Live shell output while a command runs; honest background tasks (#26, #35)

[derekhearst]

Summary

Picked up the interrupted attempt (one commit plus uncommitted work), reviewed it against the SDK 0.3.278 typings and the bundled CLI 2.1.278, then ran check, build and specs, wrote the docs and committed in logical groups. #35 is built as option A, turn-scoped and made honest. The shell tools are now named the way the CLI names them: Bash and TaskStop. The old names KillShell and KillBash still work as aliases, and BashOutput and TaskOutput are dropped from scopes. The engine now reads a backgrounded command's output file on the host once a second, through the containment helper and only after strict path checks, and sends live shell_output frames that are not persisted. task_notification settles the card through a persisted shell_task_done frame that carries the exit code and the final output. A command still running when the turn ends is marked ended_with_turn, and the turn gets one persisted notice listing what was stopped. The header chips clear on done, both tool policies tell the model that background commands end with its reply, and deleting a conversation interrupts its live run first. For #26, the card now strips all escape codes and progress-bar redraws, and opens on the last 20 lines with Show all and a copy button. It shows one status badge (live, exit N, finished, stopped, ended with turn, and so on). A failed foreground command is now distilled into the terminal card with its exit code, and the CLI's returnCodeInterpretation is shown. No migration.

After review: This pass resumed the six earlier commits on the branch and addressed every review item in four new commits. First, the task output file is now opened with O_NONBLOCK (O_RDONLY | O_NOFOLLOW | O_NONBLOCK, where the platform has the flags). A named pipe put in place of the file now opens at once, fails isFile() and is given up on, so it can no longer hang a read (src/lib/engine/task-output.server.ts). Second, the final reads in endTurn()/settle() and the reads stopped by stopAll() are now capped at 2 s, and a read that returns after its card was closed changes nothing, so the engine always closes the CLI and always sends done (src/lib/engine/background-shells.server.ts). Third, reloaded or reconnected pages now keep getting live output. At most every 5 s, and only when there is new output, the engine sends a persisted shell_output_checkpoint frame holding the output since the last save. The page applies it through applyShellOutput, which uses from/to positions to skip output it already has, add only the new part of an overlap, or mark a gap. A reattached card therefore catches up and keeps updating a few seconds behind, and the chat spec now says exactly that. Fourth, a task_notification that arrives before its call's tool_result is held, and track() (now awaited in stream.server.ts) creates the card already settled with its output and exit code, instead of later marking it 'stopped when the turn ended'. Also fixed from the minor notes: a stream clipped at 16k now drops its partial first line, so escape fragments like [31m no longer show. The docs now say the TaskStop exemption covers only the no-sandbox 'ask for every command' rule, while permission modes still apply and plan mode refuses it. The workspace-guard spec comment now says that test pins documented behaviour rather than a change. No migration.

Closes #26
Closes #35

What was addressed

Audit findings (from the 2026-09-22 subsystem audit) were re-checked against the code before any change; "not a bug" means the claim did not hold up.

#	Item	Verdict	Note
must_fix-1 task-output.server.ts:136 FIFO open blocks / unbounded finish()	must_fix-1 task-output.server.ts:136 FIFO open blocks / unbounded finish()	fixed	OPEN_FLAGS now adds O_NONBLOCK (?? 0 on Windows), the same way the bundled CLI opens these files, so a FIFO opens at once and fails isFile(). In background-shells, the final read in endTurn/settle/track goes through finishTail(), which races tail.finish() against 2 s (TAIL_FINISH_TIMEOUT_MS). stopAll() is capped the same way. applyChunk ignores chunks once a card is settled or closed. Specs: a FIFO case in tests/engine.task-output.spec.ts (the tail gives up and finish() returns in under 1 s) and in tests/engine.background-shells.spec.ts (endTurn() resolves in under 1 s). Both skip on win32, si
must_fix-2 docs/chat/spec.md:219 live output never reaches a reloaded/reconnected page	must_fix-2 docs/chat/spec.md:219 live output never reaches a reloaded/reconnected page	fixed	Fixed by making the claim true. background-shells now sends a persisted shell_output_checkpoint holding the output since the last save: the first output at once, then at most every 5 s (SHELL_CHECKPOINT_MS), only when something changed. It is emitted from the tail's new onPoll hook, in the same queue as the chunks, so it cannot arrive out of order with live frames. +page.svelte applies it with applyShellOutput (one-line change). The from/to positions let a page skip output it already has, append only the new part of an overlap, and mark a real gap. The spec.md paragraph, the applyShellOutput
should_fix background-shells.server.ts:173 notification before tool_result	should_fix background-shells.server.ts:173 notification before tool_result	fixed	settle() now holds a notification for a task not yet tracked, in a bounded Map (64 entries) keyed by task id, and can also match it by toolUseId. track() is now async and awaited in stream.server.ts before the tool_result frame is sent. When a settlement is already held, it does one bounded final read (from the result's path, or from the notification's outputFile after isTaskOutputPath) and sets details.background to the real status plus exitCode. It sends no frames, because the tool_result carries everything, and endTurn later has nothing to report. Specs cover the notification-first order th
claimed_fixes_not_actually_fixed: reloaded page 'picks the card up again'	claimed_fixes_not_actually_fixed: reloaded page 'picks the card up again'	fixed	Same fix as must_fix-2. The claim is now true, a few seconds behind, and the docs say so.
notes-minor: clipped 16k tail can start mid-escape	notes-minor: clipped 16k tail can start mid-escape	fixed	cleanTerminalText(text, { clipped }) drops the partial first line when another line follows it. ShellOutputCard passes clipped only for a stream that is truncated and at MAX_STREAM_CHARS. Spec added to tests/chat.shell-output.spec.ts.
notes-minor: docs say TaskStop is 'never held for approval'	notes-minor: docs say TaskStop is 'never held for approval'	fixed	docs/chat/spec.md, docs/tools/tools.md and the re-audit now say only the no-sandbox 'ask for every command' rule is skipped. The permission mode and per-tool approval settings still apply, and plan mode refuses TaskStop because it is classified as mutate, which I verified in permission-mode.ts.
notes-minor: workspace-guard TaskStop spec also passes on main	notes-minor: workspace-guard TaskStop spec also passes on main	partially-fixed	The test is kept as a regression pin, and its comment now says this behaviour already held before #35 and is pinned because the docs now promise it. No behaviour change was needed.

Verification

• bun run check: 0 errors
• bun run build: passes
• Specs: Run with the e2e-port patch applied and then reverted (tests/server-env.ts is clean), on both projects with --workers=3. (1) tests/engine.task-output.spec.ts, tests/engine.background-shells.spec.ts (new), tests/engine.stream-routing.spec.ts, tests/chat.shell-output.spec.ts, tests/engine.workspace-guard.spec.ts, tests/engine.sdk-notices.spec.ts, tests/engine.tool-result-details.spec.ts: 208 passed, 4 skipped. The skips are the two mkfifo specs on each project; they skip on win32 and have not run anywhere yet, so Linux CI will be their first run. (2) tests/chat.shell-output-render.spec.ts (including the new checkpoint-only card spec), tests/chat.background-commands.spec.ts, tests/chat.stop-task.spec.ts: 26 passed. bun run check: 0 errors, 0 warnings. bun run build: exit 0.
• Independent review: changes-needed (2 must-fix, 1 should-fix), addressed in a follow-up round.

Docs updated

• docs/chat/spec.md
• docs/tools/tools.md
• docs/structure/parity-reaudit-2026-09-22.md
• docs/structure/claude-desktop-parity.md
• README.md

Follow-ups / residual risk

1. The two mkfifo specs (tests/engine.task-output.spec.ts, tests/engine.background-shells.spec.ts) skip on Windows, and Docker/WSL were not available here, so they have never run. Linux CI will be their first run. 2. Checkpoints are stored in run_events for good (nothing prunes that table). A quiet dev server costs a few small rows; a very chatty command costs at most one row of up to 16k characters every 5 s for as long as the turn runs. Raise SHELL_CHECKPOINT_MS or add pruning if that becomes a problem. 3. The notification-before-tool_result order was read from the CLI's code, not reproduced live; both orders are now handled and the docs say so. 4. Still carried over from before: a live check on the Linux image that a backgrounded process really dies with session.close() (the CLI spawns detached shells). Option B, a command that outlives its turn, is not built. 5. Issues Surface shell output as a terminal, not a tool card #26 and Background work inside a chat turn #35 close through the 'Closes' trailers in 75fe76c once the PR merges; nothing was pushed or merged.

🤖 Generated with Claude Code