Queue excess spawn_agent runs instead of capping in a prompt

Workers report queued until a burst slot is free. Nested children
bypass the window so a full fleet cannot deadlock wait_agents.
Retryable 429s freeze new admits through the shared retry policy.

Author: TheGreatAxios

CHANGELOG.md

@@ -11,6 +11,16 @@ matching `## [X.Y.Z]` section (plus install instructions). Do not maintain
 parallel copies under `docs/` or `scripts/notes/`. At cut time: rename
 `## [Unreleased]` to `## [X.Y.Z] - YYYY-MM-DD`, then run the release script.
 
+## [Unreleased]
+
+### Added
+
+- Sub-agent admission queue: `spawn_agent` never refuses for worker count.
+  Excess dispatches report `queued` until a burst slot is free. Nested children
+  of an already-admitted parent bypass the cap. Capacity changes never cancel
+  in-flight work. Short provider 429s freeze new admits via the shared retry
+  remapper.
+
 ## [0.3.14] - 2026-09-03
 
 ### Changed

docs/ARCHITECTURE.md

@@ -207,7 +207,7 @@ Three distinct concepts (do not conflate them):
 | **Task**      | A checklist item owned by _one_ agent via `manage_tasks` | Local work plan — not a spawn                                    |
 | **Sub-agent** | A short-lived child agent for one self-contained job     | Spawned with **`spawn_agent`**, collected with **`wait_agents`** |
 
-The **`spawn_agent`** tool starts a sub-agent on a separate inference source (tier/profile resolved from settings) and returns immediately with an `agent_id`; **`wait_agents`** collects reports later. The dispatch brief separates durable `context`, actionable `prompt`, and optional `goals` (checklist seeds for the _child's_ own `manage_tasks` list). The child returns a structured report (`Summary` / `Findings` / `Blockers` / `Paths`) plus a tools-used footer. Parent and child never share a `manage_tasks` list.
+The **`spawn_agent`** tool starts a sub-agent on a separate inference source (tier/profile resolved from settings) and returns immediately with an `agent_id`; **`wait_agents`** collects reports later. Declared fan-out is unlimited: excess dispatches enqueue rather than fail. `run()` is admitted by `src/subagent/admission.ts` (default burst window 8 concurrent worker runs). Nested children of an already-admitted parent bypass the cap so a nested orchestrator cannot deadlock while holding a slot on `wait_agents`. Queued workers report wait/list status `queued` (live, not failed). Lowering capacity never cancels in-flight work. Short provider 429s freeze new admits via the shared retry remapper in `createCorbitsRetryPolicy`; `quota_exhausted` does not freeze. `list_agents` remains mailbox-scoped. The dispatch brief separates durable `context`, actionable `prompt`, and optional `goals` (checklist seeds for the _child's_ own `manage_tasks` list). The child returns a structured report (`Summary` / `Findings` / `Blockers` / `Paths`) plus a tools-used footer. Parent and child never share a `manage_tasks` list.
 
 When profiles exist (local `.agents/agents/` and/or enabled **`kind: "agent"`** plugins, including **data-only** markdown plugins with no `index.ts`), the chat model also receives **`search_agents`** — a lexical index over profile id, description, and role text so the model can discover ids before calling `spawn_agent(agent=...)`. Results include each match's full loaded system prompt / body so the parent can inspect plugin or Claude marketplace agents without `read_file` on paths outside the session cwd (path-escape blocks those roots by design; writes remain blocked). `spawn_agent` and `search_agents` are core tools on the primary session.
 

docs/IMPLEMENTATION.md

@@ -89,6 +89,7 @@ src/
   subagent/
     index.ts              Sub-agent run exports + SubAgentDirector
     agent-fleet.ts        spawn_agent / wait_agents fleet dispatch and mailbox tools
+    admission.ts          FIFO admission queue in front of worker run()
     session-store.ts      Retained child session transcripts for observe UI
     identity-context.ts   ALS: worker description + cwd for gate attribution
   config/

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

@@ -91,6 +91,10 @@ describe("skywalkerPackage", () => {
     expect(p).toContain("0–1 worker");
     expect(p).toContain("named, non-overlapping lanes");
     expect(p).not.toContain("2–4 workers");
+    expect(p).not.toContain("at most 4");
+    expect(p).not.toContain("Prefer synthesizing early returns");
+    expect(p).toContain("queues excess");
+    expect(p).toContain("Do not invent a numeric cap");
   });
 
   test("systemPrompt prefers spawn_agent then wait_agents (idle-orchestrator)", () => {

src/agent/directors/skywalker/package.ts

@@ -65,11 +65,10 @@ When the operator (or brief) gives an http(s) URL to read:
 
 # Effort scaling (IMPLEMENTATION / ORCHESTRATION)
 
-Scale fan-out to the ask — no numeric worker ceiling pretends to enforce itself:
+Scale fan-out to the ask — the runtime queues excess rather than refusing:
 - Simple (answer, one-path lookup, tiny fix): 0–1 worker, few tools; often answer without fleet
 - Tiny single-file / one-route asks: **DIY on the parent** with write_file/edit_file; skip spawn, skip explorer, skip critic. Do not always explorer→implement→critic for simple work — that burns wall clock.
-- Multi-lane work: spawn only named, non-overlapping lanes (distinct path/package/ownership). Width follows the ask and clear non-overlap — not a soft numeric ladder.
-Prefer synthesizing early returns over launching a second wave.
+- Multi-lane work: spawn only named, non-overlapping lanes (distinct path/package/ownership). Width follows independent lanes; the runtime queues excess rather than refusing. Do not invent a numeric cap.
 
 # Anti-cascade (stall / dig / diagnose)
 

src/agent/retry-policy.test.ts

@@ -241,4 +241,42 @@ describe("createCorbitsRetryPolicy", () => {
     current = "openai";
     expect(await policy(bare429)).toEqual({ kind: "abort" });
   });
+
+  test("retryable 429 notes admission pressure; quota_exhausted does not", async () => {
+    const notes: { provider: string; until: number }[] = [];
+    const admission = {
+      enqueue: () => "running" as const,
+      release: () => {},
+      setCapacity: () => {},
+      notePressure: (provider: string, untilMs: number) => {
+        notes.push({ provider, until: untilMs });
+      },
+      cancel: () => {},
+    };
+    const policy = createCorbitsRetryPolicy({ providerId: "xai/thegreataxios", admission });
+    const before = Date.now();
+    await policy({
+      attempt: 1,
+      elapsedMs: 0,
+      error: {
+        category: "retryable",
+        message: "Too Many Requests",
+        retryAfterMs: 2_000,
+      },
+    });
+    expect(notes).toHaveLength(1);
+    expect(notes[0]!.provider).toBe("xai/thegreataxios");
+    expect(notes[0]!.until).toBeGreaterThanOrEqual(before + 2_000);
+    notes.length = 0;
+    await policy({
+      attempt: 1,
+      elapsedMs: 0,
+      error: {
+        category: "quota_exhausted",
+        message: "monthly cap",
+        retryAfterMs: 86_400_000,
+      },
+    });
+    expect(notes).toHaveLength(0);
+  });
 });

src/agent/retry-policy.ts

@@ -4,13 +4,15 @@ import {
   normalizeInferenceErrorForRetry,
   type InferenceErrorWithGoContext,
 } from "../inference-gateway-error.js";
+import { getProcessAdmissionQueue, type AdmissionQueue } from "../subagent/admission.js";
 
 // Providers that enforce long-window quotas (e.g. monthly limits) set
 // Retry-After to days or weeks. The default policy trusts that value and
 // schedules the next attempt accordingly — silently blocking the session
 // for the full duration. Abort instead and surface the error immediately
 // so the user can switch providers or decide when to retry manually.
-const MAX_BLIND_WAIT_MS = 30_000;
+export const MAX_BLIND_WAIT_MS = 30_000;
+const DEFAULT_PRESSURE_PAUSE_MS = 1_000;
 
 export interface CorbitsRetryPolicyOptions {
   /**
@@ -19,6 +21,8 @@ export interface CorbitsRetryPolicyOptions {
    * (e.g. `/model`); it is resolved on each retry decision.
    */
   providerId?: string | (() => string | undefined);
+  /** Process admission controller. Tests inject a stub; production omits. */
+  admission?: AdmissionQueue;
 }
 
 /**
@@ -29,6 +33,7 @@ export interface CorbitsRetryPolicyOptions {
  */
 export function createCorbitsRetryPolicy(options?: CorbitsRetryPolicyOptions): RetryPolicy {
   const defaultPolicy = createDefaultRetryPolicy();
+  const admission = options?.admission ?? getProcessAdmissionQueue();
   return (situation: RetrySituation): RetryDecision | Promise<RetryDecision> => {
     const raw = options?.providerId;
     const stampedProviderId = typeof raw === "function" ? raw() : raw;
@@ -38,6 +43,11 @@ export function createCorbitsRetryPolicy(options?: CorbitsRetryPolicyOptions): R
         ? { ...incoming, providerId: stampedProviderId }
         : incoming;
     const error = normalizeInferenceErrorForRetry(withProvider);
+    if (error.category === "retryable") {
+      const pauseMs = Math.min(error.retryAfterMs ?? DEFAULT_PRESSURE_PAUSE_MS, MAX_BLIND_WAIT_MS);
+      const provider = withProvider.providerId ?? stampedProviderId ?? "unknown";
+      admission.notePressure(provider, Date.now() + pauseMs);
+    }
     if (
       error.category === "quota_exhausted" &&
       error.retryAfterMs !== undefined &&

src/subagent/agent-fleet.test.ts

@@ -11,6 +11,8 @@ import {
   MAX_FLEET_RECORDS,
   type AgentFleetDeps,
 } from "./agent-fleet.js";
+import { createAdmissionQueue } from "./admission.js";
+import { isLiveWaitStatus } from "./lifecycle.js";
 import {
   createInterruptAgentTool,
   createCloseAgentTool,
@@ -66,6 +68,7 @@ function makeDeps(
     run,
     sessions,
     fleetRecords: createFleetMailbox(sessions),
+    admission: createAdmissionQueue({ capacity: Number.POSITIVE_INFINITY }),
     ...(opts.settings !== undefined ? { settings: opts.settings } : {}),
     ...(opts.catalog !== undefined ? { catalog: opts.catalog } : {}),
     ...(opts.profiles !== undefined ? { profiles: opts.profiles } : {}),
@@ -80,7 +83,7 @@ function waitUntilMailboxTerminal(
   return new Promise((resolve) => {
     const done = (): boolean => {
       const snap = mailbox.peek(id);
-      return snap !== undefined && snap.status !== "running";
+      return snap !== undefined && !isLiveWaitStatus(snap.status);
     };
     if (done()) {
       resolve();
@@ -1390,3 +1393,211 @@ describe("spawn_agent dispatch contracts", () => {
     expect(captured[0]!.nestedDispatch).toBeUndefined();
   });
 });
+
+describe("admission queue", () => {
+  test("20 concurrent spawns admit or queue without error", async () => {
+    const gate = deferred<RunSubAgentResult>();
+    let started = 0;
+    const deps = makeDeps(async () => {
+      started += 1;
+      return gate.promise;
+    });
+    deps.admission = createAdmissionQueue({ capacity: 2 });
+    const spawn = createSpawnAgentTool(deps);
+    const results: { agent_id: string; status: string }[] = [];
+    for (let i = 0; i < 20; i++) {
+      const result = await callTool(spawn, {
+        description: `job-${i}`,
+        prompt: "do it",
+        intent: "explore",
+      });
+      results.push({ agent_id: result.agent_id as string, status: result.status as string });
+    }
+    expect(results).toHaveLength(20);
+    expect(results.every((r) => typeof r.agent_id === "string" && r.agent_id.length > 0)).toBe(
+      true,
+    );
+    expect(results.filter((r) => r.status === "running")).toHaveLength(2);
+    expect(results.filter((r) => r.status === "queued")).toHaveLength(18);
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(started).toBe(2);
+
+    const list = createListAgentsTool({
+      sessions: deps.sessions,
+      fleetRecords: deps.fleetRecords,
+    });
+    if (list.kind !== "full") throw new Error("expected full tool");
+    const raw = await list.handler(
+      { id: "list-q", name: "list_agents", arguments: {} },
+      new AbortController().signal,
+    );
+    const content = typeof raw.content === "string" ? raw.content : JSON.stringify(raw.content);
+    const parsed = JSON.parse(content) as { agents: { status: string }[] };
+    expect(parsed.agents.filter((a) => a.status === "queued")).toHaveLength(18);
+    expect(parsed.agents.filter((a) => a.status === "running")).toHaveLength(2);
+
+    const queuedId = results.find((r) => r.status === "queued")!.agent_id;
+    const wait = createWaitAgentsTool({
+      sessions: deps.sessions,
+      fleetRecords: deps.fleetRecords,
+    });
+    const waited = await callTool(wait, { targets: [queuedId], timeout_ms: 50 });
+    expect(waited.timed_out).toBe(true);
+    const waitResults = waited.results as { agent_id: string; status: string }[];
+    expect(waitResults).toEqual([{ agent_id: queuedId, status: "queued" }]);
+
+    gate.resolve({ report: "ok" });
+    await Promise.all(
+      results.map((r) => waitUntilMailboxTerminal(deps.fleetRecords, deps.sessions, r.agent_id)),
+    );
+  });
+
+  test("nested children bypass a full window", async () => {
+    let started = 0;
+    const gate = deferred<RunSubAgentResult>();
+    const deps = makeDeps(async () => {
+      started += 1;
+      return gate.promise;
+    });
+    deps.admission = createAdmissionQueue({ capacity: 0 });
+    deps.parentSessionId = "parent-1";
+    const spawn = createSpawnAgentTool(deps);
+    const result = await callTool(spawn, {
+      description: "nested",
+      prompt: "do it",
+      intent: "explore",
+    });
+    expect(result.status).toBe("running");
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(started).toBe(1);
+    gate.resolve({ report: "ok" });
+    await waitUntilMailboxTerminal(deps.fleetRecords, deps.sessions, result.agent_id as string);
+  });
+
+  test("close_agent of a queued spawn does not start the run", async () => {
+    const gate = deferred<RunSubAgentResult>();
+    let started = 0;
+    const deps = makeDeps(async () => {
+      started += 1;
+      return gate.promise;
+    });
+    deps.admission = createAdmissionQueue({ capacity: 1 });
+    const spawn = createSpawnAgentTool(deps);
+    const first = await callTool(spawn, {
+      description: "holder",
+      prompt: "hold",
+      intent: "explore",
+    });
+    const queued = await callTool(spawn, {
+      description: "queued",
+      prompt: "wait",
+      intent: "explore",
+    });
+    expect(first.status).toBe("running");
+    expect(queued.status).toBe("queued");
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(started).toBe(1);
+
+    const close = createCloseAgentTool({
+      sessions: deps.sessions,
+      fleetRecords: deps.fleetRecords,
+    });
+    if (close.kind !== "full") throw new Error("expected full tool");
+    await close.handler(
+      { id: "close-q", name: "close_agent", arguments: { target: queued.agent_id } },
+      new AbortController().signal,
+    );
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(started).toBe(1);
+    expect(deps.sessions.get(queued.agent_id as string)?.lifecycleStatus).toBe("shutdown");
+    expect(deps.fleetRecords.peek(queued.agent_id as string)?.status).toBe("interrupted");
+
+    gate.resolve({ report: "ok" });
+    await waitUntilMailboxTerminal(deps.fleetRecords, deps.sessions, first.agent_id as string);
+  });
+
+  test("sessions.cancel of a queued spawn makes wait_agents report interrupted, not queued", async () => {
+    const gate = deferred<RunSubAgentResult>();
+    let started = 0;
+    const deps = makeDeps(async () => {
+      started += 1;
+      return gate.promise;
+    });
+    deps.admission = createAdmissionQueue({ capacity: 1 });
+    const spawn = createSpawnAgentTool(deps);
+    const wait = createWaitAgentsTool({
+      sessions: deps.sessions,
+      fleetRecords: deps.fleetRecords,
+    });
+    const first = await callTool(spawn, {
+      description: "holder",
+      prompt: "hold",
+      intent: "explore",
+    });
+    const queued = await callTool(spawn, {
+      description: "queued",
+      prompt: "wait",
+      intent: "explore",
+    });
+    expect(first.status).toBe("running");
+    expect(queued.status).toBe("queued");
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(started).toBe(1);
+    const queuedId = queued.agent_id as string;
+
+    const startedAt = Date.now();
+    expect(deps.sessions.cancel(queuedId)).toBe(true);
+    const waited = await callTool(wait, { targets: [queuedId], timeout_ms: 200 });
+    const elapsed = Date.now() - startedAt;
+    expect(elapsed).toBeLessThan(200);
+    expect(waited.timed_out).toBe(false);
+    const results = waited.results as { agent_id: string; status: string }[];
+    expect(results).toEqual([{ agent_id: queuedId, status: "interrupted" }]);
+    expect(started).toBe(1);
+
+    gate.resolve({ report: "ok" });
+    await waitUntilMailboxTerminal(deps.fleetRecords, deps.sessions, first.agent_id as string);
+  });
+
+  test("start() threads fleet admission onto RunSubAgentParams", async () => {
+    let captured: RunSubAgentParams | undefined;
+    const deps = makeDeps(async (params) => {
+      captured = params;
+      return { report: "ok" };
+    });
+    const spawn = createSpawnAgentTool(deps);
+    const result = await callTool(spawn, {
+      description: "job",
+      prompt: "do it",
+      intent: "explore",
+    });
+    await waitUntilMailboxTerminal(deps.fleetRecords, deps.sessions, result.agent_id as string);
+    expect(captured?.admission).toBe(deps.admission);
+  });
+
+  test("lowering capacity does not cancel in-flight work", async () => {
+    const gate = deferred<RunSubAgentResult>();
+    let started = 0;
+    const admission = createAdmissionQueue({ capacity: 2 });
+    const deps = makeDeps(async () => {
+      started += 1;
+      return gate.promise;
+    });
+    deps.admission = admission;
+    const spawn = createSpawnAgentTool(deps);
+    const a = await callTool(spawn, { description: "a", prompt: "do it", intent: "explore" });
+    const b = await callTool(spawn, { description: "b", prompt: "do it", intent: "explore" });
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(started).toBe(2);
+    admission.setCapacity(0);
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(started).toBe(2);
+    expect(deps.sessions.get(a.agent_id as string)?.status).toBe("running");
+    expect(deps.sessions.get(b.agent_id as string)?.status).toBe("running");
+    gate.resolve({ report: "ok" });
+    await Promise.all([
+      waitUntilMailboxTerminal(deps.fleetRecords, deps.sessions, a.agent_id as string),
+      waitUntilMailboxTerminal(deps.fleetRecords, deps.sessions, b.agent_id as string),
+    ]);
+  });
+});