v0.8.61: Add parent-visible worker interaction contract for agent/fleet fanout

[Hmbown]

Problem

Live QA showed the parent agent could fan out multiple workers and then appear not to know what to do with them. The sidebar showed several agents as running, with detail text clipped to queued: waiting for an intera..., while another worker was inside a long Bash call. From the user perspective this looks like total sub-agent failure: the parent keeps working or stalls, queued workers look like they need interaction, and there is no obvious way to tell whether the parent should call agent_eval, wait, cancel, or ignore the worker.

Important clarification: in code, the clipped text likely expands to queued: waiting for an interactive fanout slot (SUBAGENT_QUEUED_LAUNCH_REASON). That is a scheduler/permit state, not a request for human interaction. The wording and truncation make it look like the worker is asking for an interaction when it is actually waiting for capacity.

Current code shape

• crates/tui/src/tools/subagent/mod.rs already records richer worker statuses such as Queued, ModelWait, RunningTool, and WaitingForUser in AgentWorkerRecord.
• agent_eval can deliver a message to a running child and can continue a checkpointed interrupted child.
• The TUI/sidebar still largely presents top-level SubAgentStatus::Running, so queued/model-wait/tool-wait workers can be counted as running.
• The model-facing session context lists open sub-agents by id, role, and objective, but does not include latest worker state, latest message, whether user/parent attention is needed, or the exact next action.

Desired behavior

The parent must be able to distinguish:

1. Queued for capacity: no interaction needed; do not call agent_eval unless inspecting. This should not look like a user-input request.
2. Waiting for model: no interaction needed yet; show progress and timeout policy.
3. Running tool / long shell: inspect/cancel/wait actions should be explicit; long shell should follow the nonblocking shell policy from v0.8.61: Default independent shell and verifier work to background jobs #3212.
4. Waiting for user/parent input: parent-visible action required; show the exact agent_eval invocation shape and the agent id/name.
5. Interrupted but continuable: parent-visible action required; show agent_eval({ agent_id, continue: true, message }).
6. Completed/failed/cancelled: terminal receipt; if output is clipped, show how to read the transcript handle.

Implementation plan

1. Rename or reword queued: waiting for an interactive fanout slot to avoid confusion. Prefer queued: waiting for worker slot or queued: waiting for launch capacity.

2. Add a small worker attention model, either on AgentWorkerRecord or in the projection layer:

   • attention_required: bool
   • attention_kind: none | capacity_queue | inspect_optional | needs_parent_input | needs_continue | cancel_available | terminal_receipt
   • recommended_action: Option<{ tool, args, reason }>

3. Feed this attention model into both the TUI and parent prompt context. The parent prompt should see a compact section like:

Open workers:
- agent_123 reviewer queued for worker slot; no parent action required
- agent_456 verifier running Bash for 377s; optional actions: agent_eval inspect, agent_close cancel
- agent_789 planner waiting for parent input; action: agent_eval { agent_id: "agent_789", message: "..." }

4. Update the Agents sidebar and fanout cards to show state counts instead of a single N running bucket: 2 running / 3 queued / 1 tool / 1 needs input / 1 done, within available width.

5. Ensure WaitingForUser does not consume a running/launch slot indefinitely. A parked worker should release compute capacity and reacquire it on continue/resume if needed.

6. Make agent_eval projections more operational: include attention_required, latest_message, message_delivery, continuable, terminal, and transcript/read handles in a shape the parent can reliably use.

7. Connect this to the Fleet direction: the same attention/receipt model should apply whether the worker is a local sub-agent session or a durable Fleet worker. The user-facing term can remain agent, but the orchestration contract should be one model.

Tests / verification

• Unit test that queued launch-capacity workers render as queued/no action required, not running/waiting for interaction.
• Unit test that WaitingForUser or continuable interrupted sessions produce a parent-visible recommended_action using agent_eval.
• TUI snapshot test for mixed fanout: queued, model wait, running tool, waiting for user, completed. Header must not collapse all of them into N running.
• Engine prompt-context test proving open workers include latest actionable state and exact next actions.
• Stress smoke: spawn more workers than the interactive launch cap, include one long Bash child and one continuable child, then verify the parent stays responsive and can route a message to the correct worker.

Related

• Builds on v0.8.61: Make multi-agent fanout durable and nonblocking before shipping swarm UX #3216 and v0.8.61: Split sub-agents into a headless worker runtime with lightweight TUI projections #3096.
• Coordinates with v0.8.61: Default independent shell and verifier work to background jobs #3212 for shell/background behavior.
• Coordinates with v0.8.61: Give workers role-based tool profiles, permissions, and model routes #3217 for worker roles/tool profiles/model routes.
• Coordinates with v0.8.61: Make goal mode a real persistent work loop before adding swarm UX #3215 because goal mode needs the same worker-attention summary to keep long work moving.