[DerekMarshall]

Fixes the bug #670's red cases pin: an agent that reports waiting mid-turn showed the hollow ○ at once, and kept showing it while it carried on working.

The bug

waiting is how a turn ends: the agent stops, and background work will wake it. I reported it when I started a background watch of the rc.2 release run, then kept working in the same turn. The dot went to ○ and stayed there for the rest of the turn. :why-status showed SELF-REPORT status=waiting with fresh pane output.

The fix

The tab follows the agent's turn. The status hooks already report each turn's start (working: UserPromptSubmit, agy's PreInvocation) and its end (done, or Claude Code's waiting). waiting::turn_open_after is the pure rule. A question (blocked) or Claude's idle nudge moves neither way.

The agent's own waiting sent while a turn is open is held (waiting::held_for_turn_end). The dot keeps showing the turn. When the turn's end arrives, the held report becomes the live one and meets that end through the unchanged waiting::meet, as if it had been reported there:

• Claude Code's Stop with pending work shows waiting, in the agent's words.
• Claude Code's Stop with nothing pending shows done.
• codex and agy, whose Stop can't say, absorb that done as before.

A held wait gives way to anything newer:

• any later report from the agent;
• Enter in the pane;
• an agent leaving a shell tab (forget_agent);
• a closed pane.

Agents without turn hooks are unchanged. An agent whose hooks report no turn start never has an open turn, so its waiting applies at once, as before.

Diagnostics: :why-status shows a held: waiting … shown once this turn ends line with the note, and the last report reads not applied: held until this turn ends. The agent's report_status reply says the same.

Tests

• test(agent-status): red cases for a waiting reported mid-turn shown at once #670's two red cases are un-ignored and pass. The mid-turn case is run for Claude Code and codex, and asserts the dot reads waiting as the turn ends, not just at the next settle.
• New: a_held_wait_gives_way_to_anything_newer, covering a turn end with nothing pending, the agent's newer report, and Enter.
• New: pure tests for turn tracking (prompt, end, question, idle nudge, agy's unnamed events) and for the hold rule.
• New: a shell_agents unit test that forget_agent drops the turn and any held wait.
• 11 mutations, one per behaviour. Each failed its test, and each run was confirmed to have run a test, not merely compiled.
• make check-ci: === GATE: PASS ===, 3,182 library tests.

Size ratchet: apply_status_report hit 101 lines, so record_hook_event was extracted. settle_agent_activity grew past its pin, so forget_closed_agent was extracted; it ends at 139, and the pin drops from 141 to 139.

Docs: docs/AGENT_ORCHESTRATION.md, FEATURES.md, AGENTS.md.

Generated with Claude Code