feat(web): composer bang grammar library + terminal_command receipt field plumbing

[btli]

Related issue

N/A — task T3 of the composer bang-shell-commands workstream (grammar + receipt plumbing; sibling backend PRs: runner input route #3033).

Summary

Client-side groundwork for Claude Code-style ! shell commands in the chat composer. Pure library/plumbing code — the composer submit wiring and autocomplete menu land in a follow-up PR, so nothing here is user-reachable yet:

• web/src/lib/composerBang.ts — framework-free bang grammar (mirrors composerMentions.ts): ! cmd (new default-type shell), !<running-key> cmd (send into an existing shell), !<shell-type> cmd (new shell of that type), bare ! / focus-only forms, and the \! + leading-space escape hatches. Resolution is exact-token, first match wins: running-shell session key → full resource id → declared type → inline error. Dead shells and agent panes are never targetable.
• Receipt field plumbing — the optional terminal_command receipt fields (action, terminal_id, terminal_name, session_key, status, error) plus item-level created_by thread through sse.ts → events.ts → blockStream.ts / itemsToBlocks.ts → blocks.ts → renderItems.ts → BlockRenderer.tsx. The delivery outcome rides the item-level status slot (the server flattens the data payload over the item envelope), so only "ok"/"error" surface as outcomes and lifecycle statuses stay invisible.
• TerminalCommandCard — receipts grow a muted target-shell chip (→ zsh · u-ab12cd, spawn variant → new zsh · u-ab12cd), destructive icon + message line on status="error", and an optional onFocusShell callback so the follow-up can wire click-to-focus of the shell rail. Legacy no-action items (the Claude Code TUI observer path) render byte-identically — pinned by snapshots recorded against the pre-change markup.

ELI5: we taught the web app the !command mini-language and how to display "this command was sent to that shell" receipts, but haven't plugged either into the message box yet.

composer text ──> composerBang.parse ──> {new|send|focus|error}   (wired in follow-up)

SSE / reload item ──> sse.ts / itemsToBlocks.ts ──> TerminalCommandBlock
      (+action, terminal_id, …, created_by)            │
                                                renderItems.ts
                                                       │
                                              TerminalCommandCard
                                        legacy: unchanged  │  receipt: chip/error

Test Plan

All from web/ on this branch:

• bun run lint (oxlint) — no new findings; the 10 pre-existing errors on main (unrelated files) are unchanged.
• bun run type-check (tsc -b) — passed.
• bunx vitest run src/lib/composerBang.test.ts src/lib/sse.test.ts src/lib/blockStream.test.ts src/lib/itemsToBlocks.test.ts src/lib/renderItems.test.ts src/components/blocks/TerminalCommandCard.test.tsx src/components/blocks/BlockRenderer.test.tsx — 7 files, 235 passed.
• Full bun run test — identical pass/fail profile to clean main on this machine (646 pre-existing local-env failures on both, +54 new passing tests, 0 new failures).
• pre-commit run --all-files — passed.
• Byte-identity: the legacy-markup snapshots were recorded before modifying the card, then re-run unchanged against the extended card.

Demo

N/A — non-visual plumbing behind dead code; legacy rendering is snapshot-pinned unchanged, and the new receipt variants only render once the server-side shell_command event (separate PR) starts emitting the fields.

Note on the e2e-ui gate: this touches web/** but adds no reachable UI behavior; the Playwright tests/e2e_ui coverage for the bang-command flow lands with the follow-up composer-integration task (or the maintainer skip-e2e-ui-test label applies to this plumbing-only PR).

Type of change

• Bug fix
• Feature
• UI / frontend change
• Refactor / chore
• Docs
• Test / CI
• Breaking change

Test coverage

• Unit tests added / updated
• Integration tests added / updated
• E2E tests added / updated
• Manual verification completed
• Existing tests cover this change
• Not applicable

Coverage notes

Exhaustive vitest table for every grammar row (escapes, verbatim multiline commands, precedence/collisions, dead shells, agent panes, no-shell-access) plus snapshot tests for all card variants and field-passthrough tests at each plumbing chokepoint. E2E UI coverage intentionally deferred to the follow-up task that makes the feature reachable (see Demo note).

🤖 Generated with Claude Code

[btli]

Cross-review fixes pushed in 5268910:

• B1 (whitespace-only commands) — parseBangCommand now treats only a truly empty remainder after the single separator as "no command"; whitespace remainders are verbatim command content per §3.1. The test that pinned the trimming behavior is corrected, plus new coverage: tab separators (!\tcmd, !zsh\tcmd, !u-ab12cd\t\t), NBSP/ideographic-space-only commands, the literal u- token, and the no-command running-key-vs-declared-type collision (!zsh focuses when a session is literally keyed zsh).
• B2 (status gated on action) — one shared terminalCommandStatus(action, status) rule in conversationItems.ts now feeds both the SSE parser and the reload translator; the card additionally ignores status/error entirely without action. New tests assert a no-action item carrying a flattened "ok"/"error" status renders byte-identically to plain legacy (direct innerHTML equality + snapshots), and both chokepoints drop the stray status.
• B3 (destructive border) — error receipts now draw border-destructive/50 alongside the destructive icon and message line per §6; the error-variant snapshot is updated (only that snapshot changed — the four legacy byte-identity snapshots are untouched).

Deferred as agreed: forwarding createdBy into the terminal branch of BlockRenderer lands with the T4 composer-integration task.

🤖 Generated with Claude Code

[github-actions]

@btli This PR is a Bug fix, Feature, or UI / frontend change but the Demo section is missing or only contains a placeholder.

These change types require a screenshot or screen recording so reviewers can see the new behaviour without checking out the branch. Please update the Demo section with:

• A screenshot or screen recording of the change, or
• A link to a hosted video or GIF showing the new behaviour.

Use N/A only when the change has no user-visible effect whatsoever (e.g. a pure refactor or test-only change). If that's the case, uncheck the relevant type box and check Refactor / chore or Test / CI instead.