feat(approvals): let a session watching its own background work keep quiet (#468)

[irisitymichaelgrundberg]

Implements #468, in the shape you laid out there: the screen rather than a hook, a badge rather than a fifth state, the CLI's own string on the wire, the badge only where a state pill already is, and the acknowledgement path rather than a new suppression.

What it does

An agent that arms a monitor, backgrounds a shell or starts a background terminal is told to end its turn. The pane goes quiet, the idle notification lands a minute later, and the session shows up under NEEDS YOU with nothing to answer. The CLI says which kind of quiet it is on its own screen, so that row is now registry data and the idle probe reads it.

The signal. capabilities.workDetect.watchingLine (optional, per CLI) plus watchingLines, which says how many non-blank rows at the foot of the screen may hold it. _confirmIdle() already captures the pane when a turn ends, so the label comes off that same capture through a pure helper in session-activity.ts, lands on Session.watching and rides toLightDetailedState() out. It is cached beside _lastPaneProbeWorking and goes stale with it, never derived from a capture that did not happen.

The fix is the alert that does not fire. hook-event-routes passes the label to notePrompt(), which opens the idle item already acknowledged, with a new acknowledgedReason recording why. Nothing new suppresses anything — the prompt stays pending, answerable and Read My Mind context, so a wrong label costs a card that does not blink rather than an alert that was never created. Everything follows from that flag: the broadcast carries the reason so a live page declines to arm, the push is skipped, a reloading page reads acknowledgedAt in seedApprovals() as it always did, and classifySession() now reads it too.

Two pre-existing bugs in that same gate, fixed here as you asked. classifySession() ignored acknowledgedAt, so an alert cleared on one device stayed lit in codeman tui alone; pendingApprovalCount() had the same gap, so the header counted a session the list no longer showed. The TUI card reads the reason as well, in the drawer's own words.

The badge. watching, in the accent colour, beside the state pill on the phone overview, the desktop home rail and the rich sidebar and rail rows — never in place of the pill, because an agent can arm a monitor and ask a question in the same breath. Nothing is added to the header tab strip or the plain sidebar.

Two CLIs, and they are not equally safe

Claude writes its chip on the last row (· 1 monitor ·, also shells, cloud sessions, background tasks), so the default one-row window holds only Ink's own chrome — not even the status line above it, whose command a bypassed session can write into its own .claude/settings.json. That row was inside the window in an earlier revision of this branch, which is exactly the hole you warned about.

Codex pins 1 background terminal running · /ps to view · /stop to close above its composer, and that slot holds the last row of the transcript whenever no terminal is running. Matching the complete row raises the bar without closing it, so the entry says so rather than claiming otherwise. What contains it is hooks: 'none': no hook event from a codex session reaches notePrompt(), so a forged label costs a wrong badge and cannot quiet an alert. A CLI that gains hook signals must not keep a pattern that soft, and the registry comment, docs/cli-registry.md and a test all state it.

Both patterns were measured against live panes. A codex sub-agent started without waiting outlives its turn the same way, and codex shows nothing on screen for it, so there is no second label to add; that measurement is recorded where the next person will look for it.

What it deliberately does not do

A prose question is not a dialog. An agent that arms a monitor and then writes "which branch should I target?" is silenced along with the false alarms until the background work ends. A permission prompt or a question dialog still goes red whatever else the agent started. docs/wiki/Notifications-And-Approvals.md says so where users meet it.

Verification

npm test green (416 files, 7907 tests), typecheck, lint, format and the frontend checks clean.

test/watching-no-alert.test.ts is the negative one you asked for: a watching session with a pending idle item raises no alert on the store, the TUI classifier, the live SSE handler, the reload seed or the home-screen classifier, while the same session with a permission item still goes red. The pane fixtures elsewhere are verbatim captures.

Measured end to end on an isolated beta, not only in tests:

• a Claude session armed a monitor, took its idle prompt acknowledged with the reason attached, wore the badge, and alerted normally again once the monitor was killed;
• a Codex session reported 1 background terminal against the full-row anchor and dropped it when the terminal ended;
• with a page loaded and then left untouched, the badge appeared and later vanished within the same ten-second window the server dropped the label — before the last commit the page kept drawing it, which is what that commit fixes;
• a restart is not a hole: a session whose terminal was still running had its label back within about twenty seconds, with no input.

A two-model review (Codex CLI and Claude, same diff, same brief) raised eleven findings and all are applied — the two that mattered were the window reaching the status line and the label reaching an HTML attribute unescaped.

No changeset: CONTRIBUTING says those are yours after merge, and the summary above is there to reuse.

[Ark0N]

Merged, thanks @irisitymichaelgrundberg! This ships in 1.32.1.

This is the shape we agreed in #468 in every detail: read from the screen rather than a hook, a badge rather than a fifth state, the CLI's own string on the wire, and the acknowledgement path rather than a new suppression. The negative test and fixing the TUI's pendingApprovalCount() on the way were both welcome.

Three things at merge:

• _readWatching() now clears the label on a failed pane capture instead of keeping the last one. A stale watching could otherwise pre-acknowledge a real idle prompt at the end of a later turn, and the A session watching its own background work shows up as NEEDS YOU #468 principle is that a wrong label should fail toward a card, not toward silence. The existing watchingChanged emit tells the page, with a test.
• The web header bell counted acknowledged items while the TUI no longer did, which would have become common with every monitor-armed session. It now counts the same thing, so the bell hides when everything pending is acknowledged.
• The "Pill copy per state" JSDoc is back above the constant it describes.

I also resolved a small conflict with #469 in the Codex entry of stock.ts; both the watching fields and transcriptGutter are there.