Honor wait_agents timeout as an Enter hatch

timeout_ms is always the max block for this call. Omit stays a
30-second hatch; the clamp is 30 minutes so an explicit wait can
cover a long check. Child shells no longer auto-extend the wait.

Author: TheGreatAxios

CHANGELOG.md

@@ -15,11 +15,10 @@ parallel copies under `docs/` or `scripts/notes/`. At cut time: rename
 
 ### Changed
 
-- wait_agents default timeout is 5 minutes (was 30 seconds) and the clamp is 30
-  minutes (was 5). While a targeted child has `run_shell` or `shell` in flight,
-  the wait extends in default-length slices until the shell ends, the worker
-  terminals, abort, or the 30-minute elapsed ceiling. Timeout, extend, and abort
-  still do not cancel workers.
+- wait_agents default timeout stays a 30-second Enter hatch. The clamp is 30
+  minutes (was 5) so an explicit `timeout_ms` can cover a long typecheck or
+  full check. Timeout and abort still do not cancel workers. The wait does
+  not auto-extend while a child shell is in flight.
 
 ## [0.3.18] - 2026-09-08
 

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

@@ -131,9 +131,8 @@ describe("skywalkerPackage", () => {
     expect(p).toContain("answer them first");
     expect(p).toContain("Enter can land");
     expect(p).toContain("do not tight-loop wait_agents");
-    expect(p).toContain("extends while a targeted child has run_shell or shell in flight");
-    expect(p).toContain("that extend ends when the last such shell ends");
-    expect(p).toContain("short timeout_ms when no child run_shell or shell is in flight");
+    expect(p).toContain("explicit large timeout_ms");
+    expect(p).toContain("does not auto-extend");
     expect(p).not.toContain("timeout_ms: 1000");
     expect(p).not.toContain("timeout_ms: MAX");
   });

src/agent/directors/skywalker/package.ts

@@ -16,7 +16,7 @@ You do not do the specialists' jobs by default. For tiny bounded product edits,
 
 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 what happens next before you block. Prefer ending that turn (or calling wait_agents with a short timeout_ms when no child run_shell or shell is in flight) so Enter can land; do not immediately fuse into a long wait_agents right after spawn. wait_agents later on the targets you need (or omit targets to wait on this session's own uncollected spawns — never a sibling's). list_agents shows that same fleet without blocking. Use mode="all" when you need every target to finish; interrupt_agent unblocks wait_agents immediately. A timeout means still running — do not tight-loop wait_agents hoping for a different answer. The wait extends while a targeted child has run_shell or shell in flight, up to the max clamp; that extend ends when the last such shell ends. A timeout is still not a kill and is not a cue to retry immediately with a short then maximum timeout. Enter mid-run delivers at the next parent tool.boundary — a long parent run_shell or awaiting wait_agents holds those steers. A bare spawn_agent does not.
+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 what happens next before you block. Prefer ending that turn, or calling wait_agents with a short timeout_ms, so Enter can land; do not immediately fuse into a long wait_agents right after spawn. If the child job is long, pass an explicit large timeout_ms (up to the clamp) or end the turn (idle-with-fleet). wait_agents later on the targets you need (or omit targets to wait on this session's own uncollected spawns — never a sibling's). list_agents shows that same fleet without blocking. Use mode="all" when you need every target to finish; interrupt_agent unblocks wait_agents immediately. A timeout means still running — do not tight-loop wait_agents hoping for a different answer. timeout_ms is the max block for this call and is always honored; the wait does not auto-extend on child shells. A timeout is still not a kill and is not a cue to retry immediately. Enter mid-run delivers at the next parent tool.boundary — a long parent run_shell or awaiting wait_agents holds those steers. A bare spawn_agent does not.
 
 # Operator updates (mandatory while fleet is live)
 

src/subagent/agent-fleet.test.ts

@@ -14,7 +14,6 @@ import {
   DEFAULT_WAIT_TIMEOUT_MS,
   MAX_WAIT_TIMEOUT_MS,
   clampWaitTimeoutMs,
-  nextWaitTimerMs,
   waitAgentsToolDefinition,
   type AgentFleetDeps,
 } from "./agent-fleet.js";
@@ -294,6 +293,29 @@ describe("spawn_agent + wait_agents", () => {
     expect(secondResults[0]!.report).toBe("finished");
   });
 
+  test("explicit short timeout_ms is honored even if a child has run_shell in flight", async () => {
+    const gate = deferred<RunSubAgentResult>();
+    const deps = makeDeps(async () => gate.promise);
+    const spawn = createSpawnAgentTool(deps);
+    const wait = createWaitAgentsTool({ sessions: deps.sessions, fleetRecords: deps.fleetRecords });
+
+    const spawned = await callTool(spawn, {
+      description: "slow job",
+      prompt: "do it",
+      intent: "explore",
+    });
+    const id = spawned.agent_id as string;
+    stampToolStart(deps.sessions, id, "run_shell", "call-shell");
+
+    const first = await callTool(wait, { targets: [id], timeout_ms: 50 });
+    expect(first.timed_out).toBe(true);
+    const firstResults = first.results as { agent_id: string; status: string }[];
+    expect(firstResults[0]!.status).toBe("running");
+    expect(deps.sessions.get(id)?.status).toBe("running");
+
+    gate.resolve({ report: "finished" });
+  });
+
   test("wait_agents with no targets waits on all uncollected agents in this fleet", async () => {
     const gates = [deferred<RunSubAgentResult>(), deferred<RunSubAgentResult>()];
     let callIndex = 0;
@@ -648,11 +670,9 @@ describe("wait mailbox session tombstone and pin", () => {
 });
 
 describe("wait timeout helpers", () => {
-  test("default is 5 minutes and clamp is 30 minutes", () => {
-    expect(DEFAULT_WAIT_TIMEOUT_MS).toBe(300_000);
+  test("default is a 30-second hatch and clamp is 30 minutes", () => {
+    expect(DEFAULT_WAIT_TIMEOUT_MS).toBe(30_000);
     expect(MAX_WAIT_TIMEOUT_MS).toBe(1_800_000);
-    expect(DEFAULT_WAIT_TIMEOUT_MS).toBeGreaterThanOrEqual(60_000);
-    expect(MAX_WAIT_TIMEOUT_MS).toBeGreaterThanOrEqual(DEFAULT_WAIT_TIMEOUT_MS);
   });
 
   test("clampWaitTimeoutMs floors at 0 and caps at MAX", () => {
@@ -662,44 +682,23 @@ describe("wait timeout helpers", () => {
     expect(clampWaitTimeoutMs(0)).toBe(0);
   });
 
-  test("nextWaitTimerMs extends only while a shell is in flight and elapsed is under max", () => {
-    const defaultMs = DEFAULT_WAIT_TIMEOUT_MS;
-    const maxMs = MAX_WAIT_TIMEOUT_MS;
-    expect(nextWaitTimerMs({ elapsed: 80, hasInFlightShell: true, defaultMs, maxMs })).toBe(
-      defaultMs,
-    );
-    expect(
-      nextWaitTimerMs({ elapsed: 80, hasInFlightShell: false, defaultMs, maxMs }),
-    ).toBeUndefined();
-    expect(
-      nextWaitTimerMs({ elapsed: maxMs, hasInFlightShell: true, defaultMs, maxMs }),
-    ).toBeUndefined();
-    expect(
-      nextWaitTimerMs({ elapsed: maxMs - 100_000, hasInFlightShell: true, defaultMs, maxMs }),
-    ).toBe(100_000);
-  });
-
-  test("wait_agents description interpolates the new default and clamp and mentions shell extend", () => {
+  test("wait_agents description interpolates the hatch default and 30-minute clamp", () => {
     expect(waitAgentsToolDefinition.description).toContain(String(DEFAULT_WAIT_TIMEOUT_MS));
     expect(waitAgentsToolDefinition.description).toContain(String(MAX_WAIT_TIMEOUT_MS));
-    expect(waitAgentsToolDefinition.description).toContain("run_shell");
     expect(waitAgentsToolDefinition.description).toContain("tight zero-progress loop");
+    expect(waitAgentsToolDefinition.description).not.toContain("extends");
     const timeoutSchema = (
       waitAgentsToolDefinition.inputSchema as {
         properties?: { timeout_ms?: { description?: string } };
       }
     ).properties?.timeout_ms;
     expect(timeoutSchema?.description).toContain(String(DEFAULT_WAIT_TIMEOUT_MS));
     expect(timeoutSchema?.description).toContain(String(MAX_WAIT_TIMEOUT_MS));
-    expect(timeoutSchema?.description).toContain("Enter hatch");
-    expect(timeoutSchema?.description).toContain("extends");
+    expect(timeoutSchema?.description).toContain("Max time to block");
+    expect(timeoutSchema?.description).not.toContain("extends");
   });
 });
 
-function delay(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
 function stampToolStart(
   sessions: ReturnType<typeof createSubAgentSessionStore>,
   id: string,
@@ -714,242 +713,6 @@ function stampToolStart(
   } as unknown as ReactorEmittedEvent);
 }
 
-function stampToolDone(
-  sessions: ReturnType<typeof createSubAgentSessionStore>,
-  id: string,
-  callId: string,
-  seq: number,
-): void {
-  sessions.appendEvent(id, {
-    type: "tool.done",
-    seq,
-    data: { result: { callId, content: "ok", isError: false } },
-  } as unknown as ReactorEmittedEvent);
-}
-
-describe("wait_agents shell-extend", () => {
-  test("extends while run_shell is in flight instead of returning a zero-progress timeout", async () => {
-    const gate = deferred<RunSubAgentResult>();
-    const deps = makeDeps(async () => gate.promise);
-    const spawn = createSpawnAgentTool(deps);
-    const wait = createWaitAgentsTool({ sessions: deps.sessions, fleetRecords: deps.fleetRecords });
-    const spawned = await callTool(spawn, {
-      description: "slow job",
-      prompt: "do it",
-      intent: "explore",
-    });
-    const id = spawned.agent_id as string;
-    stampToolStart(deps.sessions, id, "run_shell", "call-shell");
-
-    const waiting = callTool(wait, { targets: [id], timeout_ms: 80 });
-    let settled = false;
-    void waiting.then(() => {
-      settled = true;
-    });
-    await delay(150);
-    expect(settled).toBe(false);
-    expect(deps.sessions.get(id)?.status).toBe("running");
-
-    gate.resolve({ report: "done" });
-    const result = await waiting;
-    expect(result.timed_out).toBe(false);
-    const results = result.results as { status: string; report?: string }[];
-    expect(results[0]!.status).toBe("done");
-    expect(results[0]!.report).toBe("done");
-  });
-
-  test("extends while Codex shell is in flight", async () => {
-    const gate = deferred<RunSubAgentResult>();
-    const deps = makeDeps(async () => gate.promise);
-    const spawn = createSpawnAgentTool(deps);
-    const wait = createWaitAgentsTool({ sessions: deps.sessions, fleetRecords: deps.fleetRecords });
-    const spawned = await callTool(spawn, {
-      description: "slow job",
-      prompt: "do it",
-      intent: "explore",
-    });
-    const id = spawned.agent_id as string;
-    stampToolStart(deps.sessions, id, "shell", "call-codex-shell");
-
-    const waiting = callTool(wait, { targets: [id], timeout_ms: 80 });
-    let settled = false;
-    void waiting.then(() => {
-      settled = true;
-    });
-    await delay(150);
-    expect(settled).toBe(false);
-
-    gate.resolve({ report: "codex done" });
-    const result = await waiting;
-    expect(result.timed_out).toBe(false);
-    expect(deps.sessions.get(id)?.status).not.toBe("failed");
-  });
-
-  test("extends when run_shell is outstanding even if currentToolName is grep", async () => {
-    const gate = deferred<RunSubAgentResult>();
-    const deps = makeDeps(async () => gate.promise);
-    const spawn = createSpawnAgentTool(deps);
-    const wait = createWaitAgentsTool({ sessions: deps.sessions, fleetRecords: deps.fleetRecords });
-    const spawned = await callTool(spawn, {
-      description: "slow job",
-      prompt: "do it",
-      intent: "explore",
-    });
-    const id = spawned.agent_id as string;
-    stampToolStart(deps.sessions, id, "grep", "call-grep", 1);
-    stampToolStart(deps.sessions, id, "run_shell", "call-shell", 2);
-    expect(deps.sessions.get(id)?.currentToolName).toBe("grep");
-
-    const waiting = callTool(wait, { targets: [id], timeout_ms: 80 });
-    let settled = false;
-    void waiting.then(() => {
-      settled = true;
-    });
-    await delay(150);
-    expect(settled).toBe(false);
-
-    gate.resolve({ report: "done" });
-    const result = await waiting;
-    expect(result.timed_out).toBe(false);
-  });
-
-  test("grep-only outstanding tools do not extend", async () => {
-    const gate = deferred<RunSubAgentResult>();
-    const deps = makeDeps(async () => gate.promise);
-    const spawn = createSpawnAgentTool(deps);
-    const wait = createWaitAgentsTool({ sessions: deps.sessions, fleetRecords: deps.fleetRecords });
-    const spawned = await callTool(spawn, {
-      description: "slow job",
-      prompt: "do it",
-      intent: "explore",
-    });
-    const id = spawned.agent_id as string;
-    stampToolStart(deps.sessions, id, "grep", "call-grep");
-
-    const first = await callTool(wait, { targets: [id], timeout_ms: 50 });
-    expect(first.timed_out).toBe(true);
-    const firstResults = first.results as { status: string }[];
-    expect(firstResults[0]!.status).toBe("running");
-    expect(deps.sessions.get(id)?.status).toBe("running");
-
-    gate.resolve({ report: "finished" });
-    const second = await callTool(wait, { targets: [id], timeout_ms: 5000 });
-    expect(second.timed_out).toBe(false);
-  });
-
-  test("mode=all extends when any targeted live worker has run_shell in flight", async () => {
-    const gates = [deferred<RunSubAgentResult>(), deferred<RunSubAgentResult>()];
-    let callIndex = 0;
-    const deps = makeDeps(async () => gates[callIndex++]!.promise);
-    const spawn = createSpawnAgentTool(deps);
-    const wait = createWaitAgentsTool({ sessions: deps.sessions, fleetRecords: deps.fleetRecords });
-    const first = await callTool(spawn, {
-      description: "a",
-      prompt: "do it",
-      intent: "explore",
-    });
-    const second = await callTool(spawn, {
-      description: "b",
-      prompt: "do it",
-      intent: "explore",
-    });
-    const ids = [first.agent_id as string, second.agent_id as string];
-    stampToolStart(deps.sessions, ids[0]!, "run_shell", "call-shell");
-
-    const waiting = callTool(wait, { targets: ids, mode: "all", timeout_ms: 80 });
-    let settled = false;
-    void waiting.then(() => {
-      settled = true;
-    });
-    await delay(150);
-    expect(settled).toBe(false);
-
-    const afterDone = Date.now();
-    stampToolDone(deps.sessions, ids[0]!, "call-shell", 2);
-    const result = await waiting;
-    expect(Date.now() - afterDone).toBeLessThan(500);
-    expect(result.timed_out).toBe(true);
-    expect(deps.sessions.get(ids[0]!)?.status).toBe("running");
-    expect(deps.sessions.get(ids[1]!)?.status).toBe("running");
-
-    gates[0]!.resolve({ report: "a done" });
-    gates[1]!.resolve({ report: "b done" });
-  });
-
-  test("abort during a shell-extend slice returns immediately without cancelling the worker", async () => {
-    const gate = deferred<RunSubAgentResult>();
-    const deps = makeDeps(async () => gate.promise);
-    const spawn = createSpawnAgentTool(deps);
-    const wait = createWaitAgentsTool({ sessions: deps.sessions, fleetRecords: deps.fleetRecords });
-    const spawned = await callTool(spawn, {
-      description: "slow job",
-      prompt: "do it",
-      intent: "explore",
-    });
-    const id = spawned.agent_id as string;
-    stampToolStart(deps.sessions, id, "run_shell", "call-shell");
-
-    if (wait.kind !== "full") throw new Error("expected full tool");
-    const ac = new AbortController();
-    const pending = wait.handler(
-      {
-        id: "wait-extend-abort",
-        name: "wait_agents",
-        arguments: { targets: [id], timeout_ms: 80 },
-      },
-      ac.signal,
-    );
-    await delay(120);
-    ac.abort();
-    const result = await pending;
-    const content =
-      typeof result.content === "string" ? result.content : JSON.stringify(result.content);
-    const parsed = JSON.parse(content) as {
-      timed_out: boolean;
-      results: { status: string }[];
-    };
-    expect(parsed.timed_out).toBe(true);
-    expect(parsed.results[0]!.status).toBe("running");
-    expect(deps.sessions.get(id)?.status).toBe("running");
-
-    gate.resolve({ report: "done" });
-  });
-
-  test("after extend starts, tool.done on the last run_shell times out promptly while the worker still runs", async () => {
-    const gate = deferred<RunSubAgentResult>();
-    const deps = makeDeps(async () => gate.promise);
-    const spawn = createSpawnAgentTool(deps);
-    const wait = createWaitAgentsTool({ sessions: deps.sessions, fleetRecords: deps.fleetRecords });
-    const spawned = await callTool(spawn, {
-      description: "slow job",
-      prompt: "do it",
-      intent: "explore",
-    });
-    const id = spawned.agent_id as string;
-    stampToolStart(deps.sessions, id, "run_shell", "call-shell");
-
-    const waiting = callTool(wait, { targets: [id], timeout_ms: 80 });
-    let settled = false;
-    void waiting.then(() => {
-      settled = true;
-    });
-    await delay(150);
-    expect(settled).toBe(false);
-    expect(deps.sessions.get(id)?.status).toBe("running");
-
-    const afterDone = Date.now();
-    stampToolDone(deps.sessions, id, "call-shell", 2);
-    const result = await waiting;
-    expect(Date.now() - afterDone).toBeLessThan(500);
-    expect(result.timed_out).toBe(true);
-    const results = result.results as { status: string }[];
-    expect(results[0]!.status).toBe("running");
-    expect(deps.sessions.get(id)?.status).toBe("running");
-
-    gate.resolve({ report: "done" });
-  }, 2000);
-});
-
 describe("spawn_agent parentage", () => {
   test("records the caller session as parentSessionId", async () => {
     const gate = deferred<RunSubAgentResult>();