Issue for this PR

Related to #49842 and the closed, unmerged Monitor proposal #33806. This builds on v2’s existing shell jobs and synthetic inbox. Scheduled wakes in #52103 remain separate.

Type of change

• Bug fix
• New feature
• Refactor / code improvement
• Documentation

What does this PR do?

Problem: Agents poll and sleep to track changing work, wasting tokens and turns. Background shell already reports completion, but cannot report incremental progress.

What this adds:

The agent can call monitor({ command, description, timeoutMs?, delivery? }), receive a task ID, and end its turn. Stdout lines become clearly labelled events in the same session and wake the agent automatically. Stderr only goes to the shell log. monitor_stop({ id }) cancels a watch.

The TUI’s existing background task list shows monitor descriptions, event counts, start/deadline times, and terminal status. It includes a command-palette entry, output access, and stop progress/error feedback.

Typed monitor.started, monitor.event, and monitor.ended events and session-scoped list, output, and stop endpoints support reconnecting clients. Output stays accessible after completion and server restart without requiring live shell state.

Design:

• Tools are registered through the existing Tool.Service.transform path in packages/core/src/tool/plugin/monitor.ts, wired by plugin/internal.ts.
• packages/core/src/monitor.ts owns server-side jobs through Job.Service. A KV record stores monitor/session/shell IDs, saved PID, description, delivery mode, start/deadline/end times, event and byte counters, status, reason, and exit code.
• packages/core/src/shell.ts streams stdout separately while retaining the existing combined log. Complete lines are batched over a 200 ms window, then admitted through Session.synthetic and the durable inbox.
• Existing SessionRunCoordinator wake/busy handling delivers default steer events at safe step boundaries without cancelling tools. delivery: "queue" waits until the turn ends. Idle sessions wake automatically.
• Stop, deadline, and limit paths use the existing process handle and saved process group. Monitors force group termination, including descendants that ignore SIGTERM. No process-name matching is used.
• packages/server/src/routes.ts reconciles running records before serving requests after restart. They become ended: server_restarted; no process is resumed and no saved PID is signalled.
• Canonical schemas in packages/schema/src/monitor.ts join event-manifest.ts and flow through the existing bus/SSE and generated clients. The TUI extends its existing shell task list.

Safety:

• Shell and monitor share permission preparation: the same session directory, command scanning, external-directory checks, and approval prompt before spawn.
• Every synthetic event is labelled [background event from monitor '<description>' — not a user message]. The system prompt treats event contents as untrusted data, never authority to change the user’s request or permissions.
• Lifetime defaults to five minutes, with a thirty-minute maximum.
• At most four monitors can be active in a session.
• Retain the 25 most recently ended monitors per session. Pruning removes both KV records and owned logs; clients apply the same history cap. Session deletion cancels active monitors and removes retained records and logs.
• Monitor logs have independent ownership, so eviction from shell history does not delete them. Output pages are capped at 64 KiB, and the TUI stops monitors through the session-scoped stop endpoint while retaining output.
• Limits are 16 KiB of stdout per batch, 256 KiB cumulative stdout, and 1 MiB retained log.
• Monitors stop above thirty events in a rolling thirty-second window after the initial window.
• Tool guidance covers line-buffered pipes, matching failure states, remote API polling no faster than every thirty seconds, and choosing ordinary background shell for a single completion notification.
• Guidance includes examples for log errors, CI job progress, and local process exit.

Follow-ups out of scope: WebSocket sources and keeping live monitors running across a server restart.

How did you verify your code works?

Latest review follow-up: Fixed all three review findings: bounded terminal history and owned-log cleanup, cancellation on session deletion (including deletion during approval), and reopening completed output independently of shell cache state. Added session-scoped output and stop APIs and regenerated both clients and all OpenAPI snapshots.

Latest-head validation with Bun 1.4.2:

• 56 focused tests passed: 19 monitor lifecycle tests, 13 batching/shell/permission tests, 6 client synchronization tests, 2 server API/restart tests, and 16 TUI composer/output tests.
• bun run check passed: lint and all 36 typecheck tasks.
• bun run lint:effect-simplifications passed.
• Generated client and Protocol/website snapshots checked for consistency.
• Website bun run build passed, including link validation.
• git diff --check passed.

The complete test suite was not rerun for this follow-up. The full-suite results below describe the original submission.

Tests: Added coverage for line batching and UTF-8 boundaries, stderr exclusion, exit codes, process-group cleanup, deadlines, rate/size limits, busy queue/default steering, event labels, permission denial, startup cancellation, restart recovery, generated API access, client reconnect races, and narrow/wide TUI rendering.

Original submission validation with the repository-pinned Bun 1.4.2, without new dependencies or lockfile changes:

Focused core monitor tests: 21 passed. Shell/process tests: 103 passed, 19 existing skips. Schema, protocol, server, client reconnect, and TUI rendering/stop tests also passed.

Batching, deadline, and rate tests use the existing Effect test clock. Subprocess tests use readiness handshakes and short deadlines.

Final package results:

• Core: 5,602 passed, 34 skipped, 4 failed
• CLI: 375 passed, 9 skipped, 1 failed
• TUI: 1,437 passed, 2 skipped, 0 failed

Every other task passed. All Monitor tests passed.

Full-suite environment limitations:

• The execution sandbox denies Unix-domain socket binding (EPERM), blocking four existing persistent-pty-daemon.test.ts tests.
• Inner process IDs differ from /proc process IDs, blocking the existing ACP lifecycle test that enumerates children with pgrep -P.

No tests were skipped or modified to hide these restrictions. TZ=UTC matches CI and avoids an existing Date parity test’s timezone assumption.

OpenAPI snapshots were regenerated with the repository scripts. The generator also updates already-stale credential/pairing entries; no corresponding runtime behavior changed.

Screenshots / recordings

The TUI was checked at 100 and 48 columns, including running monitors, restart status, and stop-error feedback, in dark and light themes. Screenshot attachment is pending because the browser upload failed.

Illustrative demo—the agent writes and starts its own CI watcher:

Agent → monitor({command: "./watch-ci.sh 104", description: "CI 104"})
Tool  → Monitor started: mon_…
Agent → I'll watch the job results. [ends turn]

Wake 1 → [background event from monitor 'CI 104' — not a user message]: shard 1 success
Agent  → Shard 1 passed; I'll wait for the remaining results. [ends turn]

Wake 2 → [background event from monitor 'CI 104' — not a user message]: shard 2 failure
Agent  → I'll inspect shard 2's failure output.

Wake 3 → [background event from monitor 'CI 104' — not a user message]: run failure
         [background event from monitor 'CI 104' — not a user message]: exited with code 1, 3 events
Agent  → The run failed in shard 2. [reports the failure and next action]

Checklist

• I have tested my changes locally
• I have not included unrelated changes in this PR