A session watching its own background work shows up as NEEDS YOU

[irisitymichaelgrundberg]

What happens

An agent that arms a monitor, backgrounds a shell or hands work to a cloud session is
told by its CLI to end the turn and wait to be notified. The pane falls quiet, and about
a minute later Claude Code's idle notification arrives. Codeman files that as an
approval item of kind idle, and the session joins the group Codeman calls NEEDS YOU:
the heading codeman tui prints, the Needs you section on the phone overview, and the
needs you pill on a rich sidebar row. Nothing there wants anything from me. I open the
tab, read the last message, find an agent waiting for a sleep to finish, and close it
again.

Any long wait ends a turn this way — a build, a CI run, a log tail — so those rows sit
in NEEDS YOU for as long as the work runs.

Measured

Today, on a beta instance running master (1.32.0 source) so it could not touch my live
sessions. I asked a session to arm one monitor and end its turn:

curl -s -X POST http://127.0.0.1:5000/api/v1/sessions/$SID/input \
  -d '{"input":"Call the Monitor tool once with command \"sleep 600\" … then end your turn.\r","useMux":true}'

source	what it said
the pane's last row	⏵⏵ bypass permissions on · 1 monitor · ← for agents
GET /api/sessions	status: "idle", isWorking: false, nothing further
the session's row in the UI	the yellow waiting pill, which is the NEEDS YOU tier

Killing the monitor's own process made the CLI wake, take a turn and drop the chip from
its footer. So the CLI states the difference on screen the whole time, and Codeman reads
past it.

Why it happens

Codeman's session model has idle | busy | stopped | error and nothing between them.
The pane probe reads one thing off the screen, the working line
(_probePaneWorking, src/session.ts), which answers whether a turn is running. Both
classifiers then put any pending approval, kind idle included, in the tier that means
a human is needed: classifySession at src/tui/tui-model.ts:78 and
_mobileOverviewState at src/web/public/mobile-overview.js:104.

So a quiet pane has one meaning inside Codeman, and the CLI has two meanings for it. The
last row of the screen is where Claude Code says which one this is, and it names the kind
and the count: 1 monitor, 2 shells, 1 cloud session, 4 background tasks.

Why it matters

• NEEDS YOU is the group I act on, and entries that need nothing are what teach me to
  stop trusting it.
• The Approvals Inbox counts those rows as pending items when it is on, so its bell
  carries a number that overstates what is waiting.
• Anything reading /api/sessions inherits the blind spot. My own board tool files the
  same sessions as waiting on me, because Codeman is where it gets its facts.

What I have built, and did not send

I have this working on a branch and I have not opened a PR, because CONTRIBUTING asks
for a nod on anything bigger than a small fix. It is one commit, the gate is green, and
I verified it end to end on the beta instance above. Its shape:

• The CLI registry carries the footer row as an optional
  capabilities.workDetect.watchingLine, beside the workingLine it already holds, and
  it goes through compileVersionRegex() like every other regex that comes from config.
• _confirmIdle() already captures the pane at the moment a turn ends. That same capture
  now also yields the label, through a pure helper in session-activity.ts that searches
  the last few lines only, so a session that prints the words "1 monitor" is not read as
  running one.
• The label lands on Session.watching and rides toLightDetailedState() out to every
  session payload.
• The phone overview, the desktop home rail and the rich sidebar rows wear it as a
  watching badge in the accent colour, beside the state pill rather than instead of it.
• Tests cover the pattern against verbatim pane captures, the session field through a
  real idle transition, and each surface's row model.

Questions before I send anything

1. The screen, or a hook? A PostToolUse matcher on Monitor would report the
   arming precisely, with the description and the timeout, but Claude Code fires nothing
   when a monitor ends, so the end has to be inferred. The footer row is right in both
   directions and covers backgrounded shells and cloud sessions as well. It also couples
   to a CLI's UI string, which is what the registry exists to hold, so I read it as the
   registry's kind of problem rather than a new one. Do you agree?
2. A badge, or a state of its own? I kept the state pill deciding the group, because
   an agent can arm a monitor and ask me a question in the same breath, and only the pill
   knows which. A fifth state would be tidier and would get that case wrong.
3. Should the idle alert stand down while a session is watching? That is the deeper
   version of this fix and it touches the Approvals Inbox rather than the pane probe. I
   have not written it, and I would rather ask than assume.
4. Which surfaces? The badge shows where a state pill already shows. The header tab
   strip and the plain sidebar have no pill at all, and codeman tui rows have their own
   vocabulary. Say the word and I will cover either.
5. What shape on the wire? Today watching is the CLI's own words as a string. A
   { kind, count } object would survive a CLI rewording its footer, at the cost of a
   mapping table per CLI.

Environment

• Ubuntu 22.04.5 on WSL2, Node 22.22.3, tmux 3.2a
• Codeman 1.30.0 installed with install.sh into ~/.codeman/app; measured above on
  master at 1.32.0
• Claude Code 2.1.278, browser Firefox

[Ark0N]

Send it. This is a real bug and the diagnosis is right: a quiet pane has one meaning inside Codeman and two in the CLI, and the CLI says which on screen the whole time.

Answers in your order, then two things I found while checking your reasoning that will change the shape of the PR.

1. The screen, not a hook

Agreed, and there is a third argument stronger than the two you gave. Hook signals exist for claude and deepseek only (hooksAvailableForMode(), and for dsh it is per-session), so a hook-based design can never cover codex or anything else, while a registry field can. #385 already settled the general form of this: a CLI's status row is per-CLI data, not a constant, which is exactly why workingLine lives where it does.

The latch is the other half. A hook that reports arming with no matching end event leaves you inferring the end anyway, and a latch stuck in the "still watching" direction is the same false grouping you are removing, just moved somewhere harder to see.

capabilities.workDetect.watchingLine as an optional sibling of workingLine is the right home, through compileVersionRegex() like every other config-supplied regex.

2. Badge, not a fifth state

Agreed, and your reason (an agent can arm a monitor and ask a question in the same breath) is the one that decides it. One more: the state enum feeds CodemanSessionOrder's rank, and both classifiers have to stay total. A fifth state changes the ordering contract on both home screens and needs a tiebreak direction of its own. A badge is additive and cannot break the comparator.

3. Yes, and this is the actual fix

A badge alone leaves the row in NEEDS YOU, so question 3 is not the deeper version of the fix, it is the fix. The badge is the part that is cosmetic.

Do not build a new suppression for it. Reuse acknowledge():

• ApprovalInbox.acknowledge() already does exactly what you need: the item stays pending, stays answerable, stays Read My Mind context, and only stops arming the tab alert. It is idle-kind-only by default, which is the correct narrowness here.
• The web side then needs nothing. approvals-ui.js:57 already skips re-arming for an acknowledged item when it seeds from GET /api/approvals, and :84 clears the pending hook on approval:updated, which drops idle_prompt out of the set _mobileOverviewState() reads.
• It re-arms for free when the watch ends. notePrompt() calls resolveForSession(…, 'superseded') and builds a fresh item with a new id and no acknowledgedAt, so the next idle after the monitor fires alerts normally.

So: hook-event-routes already has the session in hand when it calls notePrompt(). Pass the watching label in and create the item pre-acknowledged. One call site, no sweep, no timer.

Record why it is quiet, as an optional acknowledgedReason that only drives display. The drawer should be able to say "quiet, watching 1 monitor" rather than implying a human looked at it.

That shape also picks the right failure mode. A false watching positive degrades to "the item sits in the drawer and does not blink", never to "the alert was never created", which is why acknowledging beats skipping creation.

A pre-existing bug you will walk into. classifySession() (src/tui/tui-model.ts:78) returns 'waiting' for any non-permission, non-question approval and never looks at acknowledgedAt. So today, viewing a session on your phone clears the alert everywhere except codeman tui. Same gate, one line, please fix it in this PR.

4. Surfaces

The classifier fix in 3 covers every surface at once, codeman tui included, with no badge anywhere. So the badge is free to follow the pill and nothing else: phone overview, desktop home rail, rich sidebar and rich rail rows. Not the header tab strip, not the plain sidebar. The rule I want is that the badge never adds an affordance to a surface that deliberately has none.

5. The CLI's own string

String. { kind, count } buys a taxonomy no CLI has committed to, at the price of a mapping table per CLI, which is the branching the registry exists to prevent. If something ever needs to branch on the kind, that is the moment to add a parsed field beside the string, not instead of it.

Constraints on it: cap the length, strip ANSI, and it reaches the DOM through textContent only.

And state this at the declaration, because it is the one thing in this design that can be abused: the label is pane-derived and therefore prompt-injectable. An agent that prints · 1 monitor · into its own output would silence its own idle alert. Your "last few lines only" is the right narrowing; anchor it to the footer row as well, and write the reason next to the pattern so nobody later widens it to a whole-pane search.

One implementation trap

_probePaneWorking() caches a boolean, not the text, and returns _lastPaneProbeWorking without re-capturing for PANE_PROBE_MIN_INTERVAL_MS. So the label has to be cached beside it and go stale with it, never derived from a capture that did not happen.

Related, and worth a comment where the field is declared: once _confirmIdle() concludes, activityTimeout is null and nothing probes again until the pane produces output. The label is therefore frozen at the last capture. That is fine in practice, a monitor firing wakes the agent and produces output, but say so, or the next person "fixes" it with a polling timer.

What I want to see in verification

The whole point of this change is an alert that does not fire, so the test that matters is the negative one: a watching session with a pending idle item produces no alert on any surface, and the same session with a permission item still goes red. Plus your verbatim pane captures against the pattern.

[Ark0N]

Released in 1.32.1: https://github.com/Ark0N/Codeman/releases/tag/codeman@1.32.1 (update from Settings, System, Updates, or re-run the install line). Thanks again for reporting it and for the fix.