Scope remaining wait-path copy to the exec primary surface

TUI and nested runs collect through mailbox mail, so every prompt,
doc, and comment that still teaches the wait path as live now says
which surface it applies to. Drops the readerless queued-steer yield
flag whose comment cited the unmounted wait.

Author: TheGreatAxios

docs/ARCHITECTURE.md

@@ -190,7 +190,7 @@ Compaction replaces older turns with a structured, workflow-aware summary rather
 - `present` — Renders structured UI from a JSON view spec instead of pasting tables into chat.
 - `submit_output` — Completes a workflow step when `step` is set. The step id is compared atomically against the current step (`complete()`); already-complete ids (behind the cursor) and not-current ids (future or unknown) are acknowledged without advancing. Always advertised so activating a workflow does not grow the tools array.
 
-Core agent tools (advertised in every chat turn) include `manage_tasks`, `tool_search`, `use_skill`, `skill_search` (catalog; callable without `tool_search`), **`spawn_agent`** (spawn fleet agents; collect through mailbox mail) and **`wait_agents`** (exec-primary collection verb; not mounted on TUI or nested runs), and **`search_agents`** when fleet-agent profiles are available — see Fleet agents below.
+Core agent tools (advertised per surface; exec-only verbs noted) include `manage_tasks`, `tool_search`, `use_skill`, `skill_search` (catalog; callable without `tool_search`), **`spawn_agent`** (spawn fleet agents; collect through mailbox mail) and **`wait_agents`** (exec-primary collection verb; not mounted on TUI or nested runs), and **`search_agents`** when fleet-agent profiles are available — see Fleet agents below.
 
 ### Workflows (`src/workflows/`)
 

docs/PRODUCT.md

@@ -41,8 +41,8 @@ The evidence is in how the product fails today: the personas already produce exc
 5. **Resume capability** — Runs persist to a git-backed store and resume from the last point after interruption.
 6. **Legible loop** — A live event log, working-tree diff panel, plan tracker, and real-time cost meter show what happened, when, and why.
 7. **Operator-in-the-loop** — The agent can call `ask_operator` to pause and ask a clarifying question; the operator answers from a modal (TUI). Headless `corbits exec` unmounts `ask_operator` when stdin/stdout are not TTYs. TTY exec still reads a single line from stdin.
-8. **Mid-run steering** — Two modes while the agent is running, keyed to **whose** idle. **Parent-idle** is when the primary Skywalker turn is not inside an in-flight parent tool; **session-idle** is parent-idle **and** no live fleet lanes. **Enter** soft-steers while the parent is busy — delivers at the next **parent** `tool.boundary` without stopping the current run; a long parent `run_shell` or an awaiting `wait_agents` is parent-busy, so Enter is a queued steer, not a new turn. An in-flight TUI-primary `wait_agents` yields as a timeout when that steer is queued so occupancy can deliver it. Idle-with-fleet is shipped: after a non-blocking `spawn_agent` dispatch the parent goes idle while workers keep running, mailbox mail arrives as inbound when a worker finishes or fails, and mid-hold Enter starts a new primary turn instead of queueing a steer. **Alt+Enter** queues a follow-up delivered only on session-idle (`run` goes idle; does not interrupt). Session-idle Alt+Enter is a no-op. **Ctrl+C** stops the run outright. The notice row shows distinct `steer N` / `follow-up M` badges; when steers are pending and a parent tool has been in flight a few seconds, the notice names that command. Shortcuts are listed in `/help` (`Enter` soft-steer · `Alt+Enter` follow-up · `Ctrl+C` stop).
-9. **Orchestrator-only (TUI + exec)** — The primary session is always the orchestrator: it can act directly and delegates via `spawn_agent` (then idle; mailbox mail inbound) / `search_agents`. Nested orchestrators still collect with `wait_agents`. Long jobs belong on workers — a parent that runs them itself stays parent-busy and holds Enter steers. Single-agent session mode, the first-run mode picker, and Settings → Session are gone (CL-5814). Legacy `sessionMode` values on disk are ignored.
+8. **Mid-run steering** — Two modes while the agent is running, keyed to **whose** idle. **Parent-idle** is when the primary Skywalker turn is not inside an in-flight parent tool; **session-idle** is parent-idle **and** no live fleet lanes. **Enter** soft-steers while the parent is busy — delivers at the next **parent** `tool.boundary` without stopping the current run; a long parent `run_shell` is parent-busy, so Enter is a queued steer, not a new turn. A queued steer delivers at the next parent `tool.boundary` so occupancy can pick it up. Idle-with-fleet is shipped: after a non-blocking `spawn_agent` dispatch the parent goes idle while workers keep running, mailbox mail arrives as inbound when a worker finishes or fails, and mid-hold Enter starts a new primary turn instead of queueing a steer. **Alt+Enter** queues a follow-up delivered only on session-idle (`run` goes idle; does not interrupt). Session-idle Alt+Enter is a no-op. **Ctrl+C** stops the run outright. The notice row shows distinct `steer N` / `follow-up M` badges; when steers are pending and a parent tool has been in flight a few seconds, the notice names that command. Shortcuts are listed in `/help` (`Enter` soft-steer · `Alt+Enter` follow-up · `Ctrl+C` stop).
+9. **Orchestrator-only (TUI + exec)** — The primary session is always the orchestrator: it can act directly and delegates via `spawn_agent` (then idle; mailbox mail inbound) / `search_agents`. Nested orchestrators collect through mailbox mail the same way. Long jobs belong on workers — a parent that runs them itself stays parent-busy and holds Enter steers. Single-agent session mode, the first-run mode picker, and Settings → Session are gone (CL-5814). Legacy `sessionMode` values on disk are ignored.
 
 ## User Experience
 
@@ -170,7 +170,7 @@ Corbits Code fans work out to short-lived **fleet agents** — workers with thei
 
 - **Agents** are runtime entities (primary session or child).
 - **Tasks** are checklist items owned by one agent via `manage_tasks`.
-- **Fleet agents** are spawned with `spawn_agent`. On the TUI primary, mailbox mail arrives as inbound when a worker finishes or fails — do not poll `wait_agents`. Nested orchestrators still collect with `wait_agents`. Workers ask the parent with `ask_director`. That parks a question while the worker stays `running`. Nested `wait_agents` returns `awaiting_director` with a question payload — that is not terminal. Once a parked ask is surfaced, `list_agents` fails closed until `send_input` answers or the ask is dropped — do not poll `list_agents`. The parent answers with `send_input` (`target` = the worker's session id). When the parent TUI is not blocked in `wait_agents`, a parked question arrives as a synthetic idle-send wake. Escalate to the human only with `ask_operator`.
+- **Fleet agents** are spawned with `spawn_agent`. On the TUI primary, mailbox mail arrives as inbound when a worker finishes or fails — spawn then idle; do not poll. Nested orchestrators collect through mailbox mail the same way. Workers ask the parent with `ask_director`. That parks a question while the worker stays `running`. On an exec-primary run, `wait_agents` returns `awaiting_director` with a question payload — that is not terminal. Once a parked ask is surfaced, `list_agents` fails closed until `send_input` answers or the ask is dropped — do not poll `list_agents`. The parent answers with `send_input` (`target` = the worker's session id). On the TUI primary, a parked question arrives as a synthetic idle-send wake. Escalate to the human only with `ask_operator`.
 
 Dispatch uses a structured brief (context / goal / optional goals seed) and returns a structured report. The TUI Agents strip and fleet board show who is running; live tool progress updates the status bar without dumping the child transcript into the parent chat. There is no turn budget. A tool-less final turn completes only with the four-heading report envelope. Printed `<tool_call>` markup in assistant text gets one corrective nudge to issue a real tool call and does not count as the wrap-up; without the envelope, one incomplete-report nudge is given and a second tool-less turn without the envelope salvages as `incomplete-report-stop`. Counsel and `intent=plan` also require plan substance in Findings (files/paths, acceptance criteria, non-goals, risks, ordered steps); headings-only or stub Findings salvage as `incomplete-report`, not an attachable plan. A silent worker (no activity for `stallTimeoutMs`, opt-in) gets one continuation nudge, then salvages as `stalled` only after a full `stallTimeoutMs` grace with still no activity — queued checks inside that window wait, they do not salvage. An opt-in `deadlineMs`, or an operator cancel, can also end a run early. Each of these returns a salvage report so a runaway or idle child cannot quietly burn a large token budget or look done after prose alone.
 

src/agent/directors/skywalker/package.ts

@@ -23,7 +23,7 @@ Idle-orchestrator: fire one or more spawn_agent calls in a turn — each returns
 You are the chat surface. Workers cannot ask_operator; they ask_director. A parked question arrives as an idle-send wake — answer with send_input using target = that worker's session id. Do not poll list_agents. Escalate with ask_operator only when you cannot resolve it. While any specialist is running:
 - After every spawn wave: short status (who, goal, what you are waiting on) then end the turn.
 - On mailbox mail or a finished report: short update — do not go silent.
-- When the operator messages mid-run: answer them first (COMMUNICATION). Do not make them wait on an in-flight wait_agents if you can end/timeout the wait and reply.
+- When the operator messages mid-run: answer them first (COMMUNICATION). Do not hold the reply on fleet collection — answer now and fold worker results in on the next turn.
 - Keep updates short; no wall of task dumps. manage_tasks is the checklist; chat is the narrative.
 
 Example chains:

src/tui/runner/exit.ts

@@ -512,8 +512,8 @@ export async function createRunLifecycle(
   // and follow-up (queued drain / deliver) must never call this — those paths
   // leave in-flight workers running. Closing the agent is the only thing that
   // aborts the reactor mid-inference (the send signal only rejects the send
-  // promise); that close cascades: operationController.abort → wait_agents parent
-  // signal → child abort. Do not add cancelAll here — fleet cancelAll is
+  // promise); that close cascades: operationController.abort → child
+  // parent-abort forwarding → child abort. Do not add cancelAll here — fleet cancelAll is
   // reserved for /clear (newSession) and shutdown.
   // Close it, drain the old stream, and rebuild a fresh agent so the next send
   // works.

src/tui/runner/state.ts

@@ -295,8 +295,6 @@ export interface RunnerState {
   stopFleetReporting?: () => void;
   stopRunHeartbeat?: () => void;
   withFleetPublicationSuspended?: (reset: () => void) => void;
-  /** TUI primary: true when a queued Enter steer should yield in-flight wait_agents. */
-  hasQueuedSteer?: () => boolean;
 }
 
 export function recordRunError(state: RunnerState, err: unknown): void {

src/tui/runner/wiring.ts

@@ -68,7 +68,6 @@ import {
   buildFleetDryContinuationMessage,
   buildMailboxMailMessage,
 } from "../../session/runtime-assembly.js";
-import { steerCount } from "../session-queue.js";
 
 const tuiLogger = getLogger([LOG_NAMESPACE_ROOT, "tui"]);
 
@@ -283,7 +282,6 @@ export function wirePostStartup(
   sessionBridge.setWaitYieldWake(() => {
     services.subAgentSessions.wake();
   });
-  state.hasQueuedSteer = () => steerCount(hostOf(state).shell.session) > 0;
   const unsubscribeFleetReport = services.subAgentSessions.subscribe(() => {
     fleetWakePublisher.publish();
     sessionBridge.flushMailboxMail();

src/workflows/coordinator.ts

@@ -16,6 +16,10 @@ export class WorkflowCoordinator {
     // When true the workflow pauses after each step for user confirmation; the
     // directive tells the agent to gate via ask_operator before advancing.
     private readonly stepThrough = false,
+    // True where the live tool surface mounted wait_agents (exec primary).
+    // Picks the collection-path copy: wait_agents vs mailbox mail. Defaults
+    // to the unmounted surface so the directive never advertises a missing tool.
+    private readonly waitAgentsMounted = false,
   ) {}
 
   isActive(): boolean {
@@ -61,7 +65,8 @@ export class WorkflowCoordinator {
       "",
     ];
     if (step.prompt !== undefined) lines.push(step.prompt, "");
-    for (const guidance of guidanceFor(step)) lines.push(guidance);
+    for (const guidance of guidanceFor(step, this.waitAgentsMounted))
+      lines.push(guidance);
     if (this.stepThrough && step.type !== "gate") {
       lines.push(
         `Step-through mode is on: when this step is done, summarize it and call` +
@@ -108,7 +113,7 @@ function stepIdOf(args: unknown): string | null {
   return typeof step === "string" && step.length > 0 ? step : null;
 }
 
-function guidanceFor(step: WorkflowStep): string[] {
+function guidanceFor(step: WorkflowStep, waitAgentsMounted: boolean): string[] {
   const out: string[] = [];
   if (step.skill !== undefined) {
     out.push(`First load the ${step.skill} skill, then follow this step.`);
@@ -118,11 +123,16 @@ function guidanceFor(step: WorkflowStep): string[] {
     if (step.parallel === true && agents.length > 1) {
       out.push(
         `Delegate this step to these sub-agents in parallel via spawn_agent: ${agents.join(", ")}.` +
-          ` Use wait_agents to collect all of them before advancing.`,
+          (waitAgentsMounted
+            ? ` Use wait_agents to collect all of them before advancing.`
+            : ` Then idle: mailbox mail arrives as inbound as each worker finishes — read it before advancing.`),
       );
     } else {
       out.push(
-        `Delegate this step to the ${agents.join(", ")} sub-agent via spawn_agent, then collect it with wait_agents.`,
+        `Delegate this step to the ${agents.join(", ")} sub-agent via spawn_agent, ` +
+          (waitAgentsMounted
+            ? `then collect it with wait_agents.`
+            : `then idle: mailbox mail arrives as inbound when it finishes — read it before advancing.`),
       );
     }
   }

src/workflows/host.ts

@@ -157,6 +157,11 @@ export class WorkflowHost {
         this.notify();
       },
       workflow.stepThrough === true,
+      // The directive's collect copy follows the live surface: wait_agents on
+      // exec primary, mailbox mail where it is unmounted (TUI, nested).
+      this.args
+        .getToolDefinitions()
+        .some((definition) => definition.name === "wait_agents"),
     );
     this.listen(runtime);
     this.runtime = runtime;

tests/unit/workflows-runtime.test.ts

@@ -61,8 +61,30 @@ const parent: Workflow = {
   ],
 };
 
+const withAgentStep: Workflow = {
+  name: "agented",
+  description: "delegates a step",
+  steps: [{ id: "a", label: "A", prompt: "do a", agent: "builder" }],
+};
+
+const withParallelAgents: Workflow = {
+  name: "parallel-agents",
+  description: "delegates a step in parallel",
+  steps: [
+    {
+      id: "a",
+      label: "A",
+      prompt: "do a",
+      agent: ["builder", "critic"],
+      parallel: true,
+    },
+  ],
+};
+
 function resolver(name: string): Workflow | undefined {
-  return [simple, withGatedStep, child, parent].find((w) => w.name === name);
+  return [simple, withGatedStep, child, parent, withAgentStep].find(
+    (w) => w.name === name,
+  );
 }
 
 function collect(runtime: WorkflowRuntime): WorkflowEvent[] {
@@ -71,6 +93,12 @@ function collect(runtime: WorkflowRuntime): WorkflowEvent[] {
   return events;
 }
 
+function coordDirective(rt: WorkflowRuntime): string {
+  const directive = new WorkflowCoordinator(rt).directive();
+  if (directive === null) throw new Error("expected an active directive");
+  return directive;
+}
+
 test("start lands on the first executable step", () => {
   const rt = new WorkflowRuntime(empty, resolver);
   rt.start(simple);
@@ -165,6 +193,34 @@ test("coordinator directive includes the ordinal, label, prompt, and completion
   expect(directive).not.toContain("advance_workflow");
 });
 
+test("coordinator directive defaults to mailbox collect when wait_agents is unmounted", () => {
+  const rt = new WorkflowRuntime(empty, resolver);
+  rt.start(withAgentStep);
+  const directive = coordDirective(rt);
+  expect(directive).toContain("mailbox mail");
+  expect(directive).not.toContain("wait_agents");
+});
+
+test("coordinator directive keeps the wait_agents collect path when mounted", () => {
+  const rt = new WorkflowRuntime(empty, resolver);
+  rt.start(withAgentStep);
+  const coord = new WorkflowCoordinator(rt, () => undefined, false, true);
+  const directive = coord.directive();
+  expect(directive).toContain("collect it with wait_agents");
+});
+
+test("coordinator parallel-agent guidance is mount-gated", () => {
+  const parallelResolver = (n: string): Workflow | undefined =>
+    n === "parallel-agents" ? withParallelAgents : undefined;
+  const unmounted = new WorkflowRuntime(empty, parallelResolver);
+  unmounted.start(withParallelAgents);
+  expect(coordDirective(unmounted)).not.toContain("wait_agents");
+  const mounted = new WorkflowRuntime(empty, parallelResolver);
+  mounted.start(withParallelAgents);
+  const coord = new WorkflowCoordinator(mounted, () => undefined, false, true);
+  expect(coord.directive()).toContain("wait_agents");
+});
+
 test("runtime complete is a compare-and-advance against the current step", () => {
   const rt = new WorkflowRuntime(empty, resolver);
   rt.start(simple);