Unmount wait_agents on TUI primary and nested orchestrators

Author: TheGreatAxios

CHANGELOG.md

@@ -15,6 +15,11 @@ parallel copies under `docs/` or `scripts/notes/`. At cut time: rename
 
 ### Changed
 
+- `wait_agents` is now exec-primary opt-in (`mountWaitAgents` in
+  `createAgentToolset`; CL-7678). The TUI primary and nested orchestrators no
+  longer mount it and collect fleet results through mailbox mail instead:
+  spawn then idle, do not poll. Headless `corbits exec` keeps it mounted with
+  an advertised allow.
 - Headless `corbits exec` unmounts `ask_operator` when stdin/stdout are not
   TTYs instead of advertising a cancel stub. TUI Skywalker still mounts it;
   TTY exec still prompts on stdin.

README.md

@@ -154,8 +154,8 @@ Details live in `docs/PRODUCT.md` (safety model) and `docs/ARCHITECTURE.md`
 Corbits Code is a single-process CLI built on Interchange primitives. The primary
 session is always the **orchestrator** (Skywalker): it can act directly and
 delegates substantial work through a closed director fleet via `spawn_agent`
-then idle (mailbox mail inbound), `search_agents`, and optional `wait_agents`
-for nested orchestrators.
+then idle (mailbox mail inbound) and `search_agents`. `wait_agents` stays
+mounted only on headless `corbits exec` primary runs.
 
 ```
 CLI (src/index.ts)

docs/ARCHITECTURE.md

@@ -686,6 +686,8 @@ export async function buildEvalDiagnostics(
       // Capability evals run through exec; they are non-TTY, so ask_operator
       // is unmounted the same way the runner does when interactive is false.
       operatorAvailable: false,
+      // ...and wait_agents stays mounted the way the exec runner mounts it.
+      waitAgentsMounted: true,
     });
   return {
     advertisedTools,

scripts/eval-capability.ts

@@ -111,7 +111,7 @@ export function formatAgentSearchResults(
       "",
       ...entries.flatMap((entry, i) => (i === 0 ? [entry] : ["", entry])),
       "",
-      "Spawn with spawn_agent(description, prompt, agent=<id>). For a team, call spawn_agent once per member (parallel in one turn when independent), then reply and idle — mailbox mail arrives as inbound. Nested orchestrators still collect with wait_agents.",
+      "Spawn with spawn_agent(description, prompt, agent=<id>). For a team, call spawn_agent once per member (parallel in one turn when independent), then reply and idle — mailbox mail arrives as inbound. wait_agents is mounted on exec-primary runs only.",
     ].join("\n"),
   );
 }

src/agent/agent-search.ts

@@ -104,7 +104,9 @@ describe("greybeardPackage", () => {
     const allow = greybeardPackage.tools?.allow ?? [];
     expect(allow).not.toContain("task");
     expect(allow).toContain("spawn_agent");
-    expect(allow).toContain("wait_agents");
+    // CL-7678: nested orchestrators collect through mailbox mail; wait_agents
+    // is exec-primary opt-in, so it stays off the Greybeard allow.
+    expect(allow).not.toContain("wait_agents");
     // CL-7051: search_agents is Skywalker-only — nested directors spawn from allowlist.
     expect(allow).not.toContain("search_agents");
     expect(allow).toContain("write_file");

src/agent/directors/greybeard/package.test.ts

@@ -33,7 +33,7 @@ Judge the approach:
 4. Rank risks for long-term maintainability and backward compatibility.
 5. Report a clear verdict: hold / revise / block — with the why, not a checklist theater.
 
-Spawn only when a concrete unknown blocks that judgment. Package spawn rules allow intern (mechanical shell), explorer (map/read), and critic (code evidence). When spawning critic, pass non-empty success_criteria (runtime fail-closes without it). intern and explorer remain optional. Prefer doing the review yourself with mounted read/search tools. Do not invent numeric spawn caps or act as a scheduler — width follows the unknown, not a soft ladder. Nested orchestrators collect with wait_agents — mailbox mail is the primary parent path.
+Spawn only when a concrete unknown blocks that judgment. Package spawn rules allow intern (mechanical shell), explorer (map/read), and critic (code evidence). When spawning critic, pass non-empty success_criteria (runtime fail-closes without it). intern and explorer remain optional. Prefer doing the review yourself with mounted read/search tools. Do not invent numeric spawn caps or act as a scheduler — width follows the unknown, not a soft ladder. Spawn then idle; reports arrive as mailbox mail — do not poll.
 
 Blinders: do not call search_agents to discover the fleet (even when nested). You already know the limited spawn set; stay inside it. Do not spawn builder, counsel, skywalker, or other directors outside the allowlist.
 

src/agent/directors/greybeard/package.ts

@@ -188,7 +188,9 @@ describe("director registry", () => {
     expect(s.systemPrompt).toMatch(/No catch-all worker/i);
     expect(s.tools?.allow).not.toContain("task");
     expect(s.tools?.allow).toContain("spawn_agent");
-    expect(s.tools?.allow).toContain("wait_agents");
+    // CL-7678: wait_agents is exec-primary opt-in, off the Skywalker allow —
+    // TUI primary collects through mailbox mail.
+    expect(s.tools?.allow).not.toContain("wait_agents");
     expect(s.tools?.allow).toContain("write_file");
     expect(s.tools?.allow).toContain("edit_file");
     expect(s.tools?.allow).toContain("delete_file");

src/agent/directors/registry.test.ts

@@ -52,7 +52,9 @@ describe("skywalkerPackage", () => {
     const allow = skywalkerPackage.tools?.allow ?? [];
     expect(allow).not.toContain("task");
     expect(allow).toContain("spawn_agent");
-    expect(allow).toContain("wait_agents");
+    // CL-7678: TUI primary collects through mailbox mail; wait_agents is
+    // exec-primary opt-in, so it stays off the Skywalker allow.
+    expect(allow).not.toContain("wait_agents");
     expect(allow).toContain("search_agents");
     expect(allow).toContain("write_file");
     expect(allow).toContain("edit_file");
@@ -123,7 +125,9 @@ describe("skywalkerPackage", () => {
     expect(p).toContain("wait_agents");
     expect(p).toContain("Idle-orchestrator");
     expect(p).not.toContain("task()");
-    expect(p).toContain("do not poll wait_agents");
+    expect(p).toContain("Spawn then idle; do not poll");
+    expect(p).not.toContain("do not poll wait_agents");
+    expect(p).toContain("wait_agents is mounted on exec-primary runs only");
     expect(p).toContain("mailbox mail arrives as inbound");
     expect(p).toContain(
       "When the fleet goes dry the runtime re-enters with collected reports",

src/agent/directors/skywalker/package.test.ts

@@ -6,17 +6,17 @@ import { SKYWALKER_TOOLS } from "../tool-sets.js";
 const SKYWALKER_SYSTEM_PROMPT = `You are Skywalker — the primary orchestrator for Corbits Code.
 
 When asked your name, answer: Skywalker.
-Agent id: skywalker (primary session; not a spawned worker). Prefer spawn_agent for specialists (parallel OK), then idle. Mailbox mail arrives as inbound when workers finish — do not poll wait_agents.
+Agent id: skywalker (primary session; not a spawned worker). Prefer spawn_agent for specialists (parallel OK), then idle. Mailbox mail arrives as inbound when workers finish — spawn then idle; do not poll.
 
 PRIMARY INTENT: run the workflow. Classify every request. DIY tiny/single-file/one-route product edits. Delegate substantial work. Chain specialists into a sequence of actions. Track who is running. You are the only surface that talks to the operator — give frequent short status updates while work is in flight. Synthesize for the operator. Do not become the reviewer or explorer by default.
 
-You do not do the specialists' jobs by default. For tiny bounded product edits, use write_file/edit_file/delete_file yourself. For substantial work you start specialists with spawn_agent, give the operator a short status, then idle so mailbox mail can wake you. Do not poll wait_agents.
+You do not do the specialists' jobs by default. For tiny bounded product edits, use write_file/edit_file/delete_file yourself. For substantial work you start specialists with spawn_agent, give the operator a short status, then idle so mailbox mail can wake you; do not poll.
 
 # Parent tools
 
 Do not run long-blocking jobs on the parent (evals, full test suites, long installs, long-running implementation). Dispatch intern (mechanical shell), tester (suite / repro), or builder (substantial code). Path tools (write_file/edit_file/delete_file) are the DIY surface; shell file-writes stay denied.
 
-Idle-orchestrator: fire one or more spawn_agent calls in a turn — each returns immediately with an agent_id and does not hold the parent. Then **reply to the operator** with who is running and **end the turn**. Workers keep running while you are idle; mailbox mail arrives as inbound when a worker finishes or fails — read it and decide the next action. Do not poll wait_agents. wait_agents is optional/deprecated on this primary parent (nested orchestrators such as greybeard still collect with it). list_agents shows the fleet without blocking; do not poll list_agents. interrupt_agent unblocks an in-flight wait immediately. Enter mid-run delivers at the next parent tool.boundary — a long parent foreground run_shell or awaiting wait_agents holds those steers (start long commands with run_shell background:true instead). A bare spawn_agent does not. When the fleet goes dry the runtime re-enters with collected reports.
+Idle-orchestrator: fire one or more spawn_agent calls in a turn — each returns immediately with an agent_id and does not hold the parent. Then **reply to the operator** with who is running and **end the turn**. Workers keep running while you are idle; mailbox mail arrives as inbound when a worker finishes or fails — read it and decide the next action. Spawn then idle; do not poll. wait_agents is mounted on exec-primary runs only. list_agents shows the fleet without blocking; do not poll list_agents. interrupt_agent unblocks an in-flight wait immediately. Enter mid-run delivers at the next parent tool.boundary — a long parent foreground run_shell holds those steers (start long commands with run_shell background:true instead). A bare spawn_agent does not. When the fleet goes dry the runtime re-enters with collected reports.
 
 # Operator updates (mandatory while fleet is live)