omnirush 0.9.0 → 0.10.0

package/assets/extensions/omnirush/agents-lib.ts

@@ -6,7 +6,9 @@
 // running pi entry — same runtime, same global extension/config dir)
 // in the parent's workspace, with `--mode json -p` so their output is
 // a parseable event stream. Each child writes its own session JSONL
-// under <agentDir>/sessions/<cwd-slug>/, under a session id the parent
+// under <parent's session dir>/subagents/ (subagentSessionDir: kept out
+// of the folder /resume and --continue read, so a user only ever sees
+// their own conversations there), under a session id the parent
 // picks (`--session-id`) and returns in the result (`session_id`): the
 // parent session's collector reads the child's session file from it and
 // records the child as a sub-agent of the turn (session.child events,
@@ -37,6 +39,7 @@ import {
   type SubagentFallback,
 } from "./subagents-lib";
 import { childAuthEnv } from "./auth";
+import { sanitizeToolEnvironment } from "./secret-env";
 import { yoloActive } from "./yolo-lib";
 
 /** childAuthEnv, never throwing (a spawn must not fail on the auth file). */
@@ -71,6 +74,47 @@ export function childInactivityMs(env: NodeJS.ProcessEnv = process.env): number
 export const CHILD_KILL_GRACE_MS = 5_000;
 /** Per-child output cap in the structured result (bytes, UTF-8). */
 export const CHILD_OUTPUT_CAP_BYTES = 50 * 1024;
+/**
+ * Finished sub-agents whose result reached the model keep their output (up
+ * to CHILD_OUTPUT_CAP_BYTES each) for agents_result; beyond this many per
+ * session, the oldest ones' output is let go (a swarm session runs
+ * hundreds of children).
+ */
+export const MAX_KEPT_OUTPUTS = 200;
+/** What a released output reads. */
+export const RELEASED_OUTPUT = "(output no longer kept in memory: it was delivered to the conversation earlier)";
+
+/**
+ * Sub-agent layers below the main session (the desktop app's
+ * OMNIRUSH_SUBAGENT_DEPTH): layers 1 and 2 may delegate, layer 3 may not.
+ * The session capture records exactly these layers (collector.ts).
+ */
+export const MAX_SUBAGENT_DEPTH = 3;
+/** The layer a process runs at, handed down to every child (+1 per layer). */
+export const ENV_AGENT_DEPTH = "OMNIRUSH_AGENT_DEPTH";
+
+/**
+ * This process's sub-agent layer: 0 for a main session. A child of a parent
+ * that predates the depth variable counts as layer 1.
+ */
+export function agentDepth(env: NodeJS.ProcessEnv = process.env): number {
+  const text = String(env[ENV_AGENT_DEPTH] ?? "").trim();
+  const raw = /^\d+$/.test(text) ? Number(text) : NaN;
+  if (Number.isSafeInteger(raw)) return raw;
+  return String(env.OMNIRUSH_PARENT_SESSION ?? "").trim() ? 1 : 0;
+}
+
+/** Whether a process at `depth` may start sub-agents. */
+export function canDelegate(depth: number): boolean {
+  return depth < MAX_SUBAGENT_DEPTH;
+}
+
+/** System text for a sub-agent: its layer, and whether it may delegate. */
+export function subagentLayerNote(depth: number): string {
+  return canDelegate(depth)
+    ? `You are a sub-agent: layer ${depth} of at most ${MAX_SUBAGENT_DEPTH} below the main session. You may delegate independent parts of your task with spawn_agents (your sub-agents are layer ${depth + 1}); otherwise do the work yourself.`
+    : `You are a sub-agent: layer ${depth} of at most ${MAX_SUBAGENT_DEPTH} below the main session. You cannot delegate further (there is no spawn_agents at this layer): do the work yourself.`;
+}
 
 export const AGENT_ROLES = ["code-searcher", "researcher-web", "general-worker"] as const;
 export type AgentRole = (typeof AGENT_ROLES)[number];
@@ -161,6 +205,25 @@ export function childInvocation(args: string[]): {
   return { command: "pi", args };
 }
 
+/** The folder, inside a session dir, that holds its sub-agents' sessions. */
+export const SUBAGENT_SESSIONS_DIR = "subagents";
+
+/**
+ * Where a child's session file goes: <parent's session dir>/subagents/.
+ * The core's session picker (/resume) and --continue only read the
+ * *.jsonl files directly in a session dir, so children stored one level
+ * down never show up as sessions to resume. A sub-agent's own children
+ * (nested) share its folder: a parent that is itself a sub-agent
+ * (OMNIRUSH_PARENT_SESSION set) already runs there. Undefined when the
+ * parent has no session dir (--no-session): the child keeps the core's
+ * default, and the launcher tidies such stragglers (src/sessions.js).
+ */
+export function subagentSessionDir(parentSessionDir: unknown, env: NodeJS.ProcessEnv = process.env): string | undefined {
+  if (typeof parentSessionDir !== "string" || !parentSessionDir.trim()) return undefined;
+  if (String(env.OMNIRUSH_PARENT_SESSION ?? "").trim()) return parentSessionDir;
+  return path.join(parentSessionDir, SUBAGENT_SESSIONS_DIR);
+}
+
 /**
  * Build the child's argv for one task: JSON print mode with the role's
  * system prompt appended via a temp file path (the caller writes and
@@ -175,6 +238,7 @@ export function buildChildArgs(
   sessionId?: string,
   effort?: string | null,
   approve = false,
+  sessionDir?: string,
 ): string[] {
   const args: string[] = ["--mode", "json", "-p"];
   if (approve) {
@@ -187,6 +251,10 @@ export function buildChildArgs(
     // be found and captured as this session's sub-agent.
     args.push("--session-id", sessionId);
   }
+  if (sessionDir) {
+    // Out of the user's resume list (subagentSessionDir).
+    args.push("--session-dir", sessionDir);
+  }
   if (promptFilePath) {
     args.push("--append-system-prompt", promptFilePath);
   }
@@ -351,38 +419,164 @@ export interface ParsedChildEvents {
   turns: number;
 }
 
+/** Characters of an event line read to tell its type (and role / tool call id) apart. */
+export const CHILD_EVENT_HEAD_CHARS = 512;
 /**
- * Parse the accumulated stdout of a `pi --mode json -p` run: one JSON
- * event per line; `message_end` events carry the messages. Unparseable
- * lines (banners, noise) are ignored.
+ * Longest event line kept whole for parsing (characters). Only an
+ * assistant `message_end` is ever kept; one longer than this (a huge tool
+ * call argument) still counts as a turn, its text is not read.
  */
-export function parseChildEvents(stdout: string): ParsedChildEvents {
-  let finalText = "";
-  let turns = 0;
-  for (const line of stdout.split("\n")) {
+export const MAX_CHILD_EVENT_LINE_CHARS = 4 * 1024 * 1024;
+
+const EVENT_TYPE_RE = /^\s*\{\s*"type"\s*:\s*"([A-Za-z_]+)"/;
+const TOOL_CALL_ID_RE = /"toolCallId"\s*:\s*"((?:[^"\\]|\\.)*)"/;
+const ROLE_RE = /^\s*\{\s*"type"\s*:\s*"message_end"\s*,\s*"message"\s*:\s*\{\s*"role"\s*:\s*"([A-Za-z_]+)"/;
+
+/**
+ * Streaming reader of a `pi --mode json -p` child's stdout: one JSON event
+ * per line. Only what the parent needs is kept — the last assistant text,
+ * the assistant turn count and the tool calls in flight — and every other
+ * event (streaming deltas, tool results, turn_end / agent_end, which repeat
+ * the whole conversation) is skipped as it streams by, without buffering
+ * it. A child's stream is several times its conversation (agent_end alone
+ * repeats all of it), so keeping it whole cost the parent that much memory
+ * per child. Unparseable lines (banners, noise) are ignored.
+ */
+export class ChildEventScanner {
+  finalText = "";
+  turns = 0;
+  /** Monotonic count of model/tool events that represent real progress. */
+  progressSerial = 0;
+  readonly toolsRunning = new Set<string>();
+  private line = "";
+  /** head: deciding from the first characters; keep: buffering the whole line; skip: dropping it. */
+  private mode: "head" | "keep" | "skip" = "head";
+  private lineType: string | null = null;
+  private lineRole: string | null = null;
+
+  /** Feed a decoded chunk of stdout. */
+  push(text: string): void {
+    let start = 0;
+    while (start <= text.length) {
+      const newline = text.indexOf("\n", start);
+      const end = newline < 0 ? text.length : newline;
+      if (end > start) this.feed(text.slice(start, end));
+      if (newline < 0) break;
+      this.endLine();
+      start = newline + 1;
+    }
+  }
+
+  /** The stream ended: a last line without a newline still counts. */
+  end(): void {
+    if (this.line || this.mode !== "head") this.endLine();
+  }
+
+  private feed(part: string): void {
+    if (this.mode === "skip") return;
+    this.line += part;
+    if (this.mode === "head" && this.line.length >= CHILD_EVENT_HEAD_CHARS) this.decide();
+    if (this.mode === "keep" && this.line.length > MAX_CHILD_EVENT_LINE_CHARS) {
+      // Too long to keep: an assistant message still counts as a turn.
+      if (this.lineType === "message_end" && this.lineRole === "assistant") this.turns += 1;
+      this.line = "";
+      this.mode = "skip";
+    }
+  }
+
+  /** Classify the line from its head: keep it, take what it says from the head, or skip it. */
+  private decide(): void {
+    const head = this.line.slice(0, CHILD_EVENT_HEAD_CHARS);
+    const type = EVENT_TYPE_RE.exec(head)?.[1] ?? null;
+    this.lineType = type;
+    if (type === "message_update" || type === "message_start" || type === "turn_start") this.progressSerial += 1;
+    if (type === "message_end") {
+      const role = ROLE_RE.exec(head)?.[1] ?? null;
+      this.lineRole = role;
+      // Only an assistant message carries the final text; a role further
+      // into the object than the head (not how pi writes it) is kept too.
+      if (role !== null && role !== "assistant") this.skip();
+      else this.mode = "keep";
+      return;
+    }
+    if (type === "tool_execution_start" || type === "tool_execution_end") {
+      const id = TOOL_CALL_ID_RE.exec(head)?.[1];
+      if (id !== undefined) {
+        this.tool(type, JSON.parse(`"${id}"`));
+        this.skip();
+      } else {
+        this.mode = "keep";
+      }
+      return;
+    }
+    this.skip();
+  }
+
+  private skip(): void {
+    this.line = "";
+    this.mode = "skip";
+  }
+
+  private tool(type: string, id: string): void {
+    this.progressSerial += 1;
+    if (type === "tool_execution_start") this.toolsRunning.add(id);
+    else this.toolsRunning.delete(id);
+  }
+
+  private endLine(): void {
+    const line = this.line;
+    const mode = this.mode;
+    this.line = "";
+    this.mode = "head";
+    this.lineType = null;
+    this.lineRole = null;
+    if (mode === "skip") return;
     const trimmed = line.trim();
-    if (!trimmed) continue;
+    if (!trimmed || !trimmed.includes('"type"')) return;
+    // A short line: skip the types nothing is read from without parsing them.
+    const type = mode === "head" ? EVENT_TYPE_RE.exec(trimmed)?.[1] : undefined;
+    if (type && type !== "message_end" && type !== "message_update" && type !== "message_start" && type !== "turn_start" && type !== "tool_execution_start" && type !== "tool_execution_end") return;
     let event: any;
     try {
       event = JSON.parse(trimmed);
     } catch {
-      continue;
+      return;
     }
-    if (event?.type !== "message_end" || !event.message) continue;
+    if ((event?.type === "tool_execution_start" || event?.type === "tool_execution_end") && typeof event.toolCallId === "string") {
+      this.tool(event.type, event.toolCallId);
+      return;
+    }
+    if (event?.type === "message_update" || event?.type === "message_start" || event?.type === "turn_start") {
+      this.progressSerial += 1;
+      return;
+    }
+    if (event?.type !== "message_end" || !event.message) return;
     const message = event.message;
-    if (message.role !== "assistant") continue;
-    turns += 1;
+    if (message.role !== "assistant") return;
+    this.turns += 1;
+    this.progressSerial += 1;
     const parts = Array.isArray(message.content) ? message.content : [];
     const text = parts
       .filter((part: any) => part?.type === "text" && typeof part.text === "string")
       .map((part: any) => part.text)
       .join("\n\n");
-    if (text.trim()) finalText = text;
+    if (text.trim()) this.finalText = text;
     else if (typeof message.content === "string" && message.content.trim()) {
-      finalText = message.content;
+      this.finalText = message.content;
     }
   }
-  return { finalText, turns };
+}
+
+/**
+ * Parse the stdout of a `pi --mode json -p` run: one JSON event per line;
+ * `message_end` events carry the messages (see ChildEventScanner, which
+ * the runner feeds as the output streams).
+ */
+export function parseChildEvents(stdout: string): ParsedChildEvents {
+  const scanner = new ChildEventScanner();
+  scanner.push(stdout);
+  scanner.end();
+  return { finalText: scanner.finalText, turns: scanner.turns };
 }
 
 // --- the runner -------------------------------------------------------------
@@ -390,6 +584,8 @@ export function parseChildEvents(stdout: string): ParsedChildEvents {
 export interface SpawnChildOptions {
   cwd: string;
   parentSessionId: string;
+  /** Where the child's session file goes (subagentSessionDir); the core's default when unset. */
+  sessionDir?: string;
   /**
    * Explicit wall-clock limit (the tool's `timeout_minutes`). Undefined =
    * none: a child runs until it is done, stalls (inactivityMs) or is
@@ -416,10 +612,14 @@ export interface SpawnChildOptions {
   now?: () => number;
   /** Progress callback: partial output lines as the child runs. */
   onChildStdout?: (role: AgentRole, chunk: string) => void;
-  /** Every sign of life from the child (any output), with its event types. */
+  /** Meaningful model/tool progress from the child, with its event types. */
   onActivity?: (activity: ChildActivity) => void;
   /** The child's session id (a fresh UUID by default). */
   sessionId?: string;
+  /** The child process started (its pid), for memory accounting. */
+  onSpawn?: (pid: number | undefined) => void;
+  /** Extra environment for the child (e.g. the memory tree root). */
+  extraEnv?: Record<string, string>;
 }
 
 export interface ChildActivity {
@@ -428,6 +628,7 @@ export interface ChildActivity {
   turns: number;
   /** Tool calls running right now. */
   toolsRunning: number;
+  meaningful: true;
 }
 
 /**
@@ -466,19 +667,20 @@ export async function runChildAgent(
   const sessionId = options.sessionId ?? randomUUID();
 
   return withRolePromptFile(task.role, async (promptFile) => {
-    const args = buildChildArgs(task.task, promptFile, task.model, sessionId, task.effort, yoloActive());
+    const args = buildChildArgs(task.task, promptFile, task.model, sessionId, task.effort, yoloActive(), options.sessionDir);
     const invocation = childInvocation(args);
 
     return await new Promise<ChildResult>((resolvePromise) => {
-      let stdout = "";
+      // The event stream is read as it arrives; nothing of it is kept but
+      // what the result needs (the scanner), so a long child costs the
+      // parent next to nothing.
+      const events = new ChildEventScanner();
       let stderr = "";
-      let pendingLine = "";
       let pendingErrLine = "";
       let gatewayFallback: ChildResultInput["gatewayFallback"];
       let settled = false;
       let killedFor: "timeout" | "stalled" | "cancelled" | "interrupted" | null = null;
-      let turns = 0;
-      const toolsRunning = new Set<string>();
+      const toolsRunning = events.toolsRunning;
       let lastActivity = now();
       let watchdog: ReturnType<typeof setTimeout> | null = null;
       let timer: ReturnType<typeof setTimeout> | null = null;
@@ -486,12 +688,14 @@ export async function runChildAgent(
       const child = spawnImpl(invocation.command, invocation.args, {
         cwd: options.cwd,
         shell: false,
+        detached: process.platform !== "win32",
         stdio: ["ignore", "pipe", "pipe"],
         // Shared credentials by location (OMNIRUSH_DIR), never a token
         // frozen at the parent's launch: the child re-reads auth.json for
         // every request and takes part in the refresh lock.
-        env: childEnvironment(task, options.parentSessionId, { ...process.env, ...childAuthEnvSafe() }),
+        env: childEnvironment(task, options.parentSessionId, { ...process.env, ...childAuthEnvSafe(), ...(options.extraEnv ?? {}) }),
       });
+      options.onSpawn?.(child.pid);
 
       const finish = (input: ChildResultInput) => {
         if (settled) return;
@@ -505,16 +709,33 @@ export async function runChildAgent(
       };
 
       const killTree = () => {
-        try {
-          child.kill("SIGTERM");
-        } catch {
-          /* already gone */
+        const signalGroup = (signal: NodeJS.Signals) => {
+          if (process.platform !== "win32" && typeof child.pid === "number" && child.pid > 0) {
+            try {
+              process.kill(-child.pid, signal);
+              return true;
+            } catch {
+              /* fall back to the direct child below */
+            }
+          }
+          if (process.platform === "win32" && typeof child.pid === "number" && child.pid > 0) {
+            try {
+              const args = ["/PID", String(child.pid), "/T"];
+              if (signal === "SIGKILL") args.push("/F");
+              nodeSpawn("taskkill", args, { windowsHide: true, stdio: "ignore" });
+              return true;
+            } catch {
+              /* fall back to the direct child below */
+            }
+          }
+          return false;
+        };
+        if (!signalGroup("SIGTERM")) {
+          try { child.kill("SIGTERM"); } catch { /* already gone */ }
         }
         setTimeout(() => {
-          try {
-            child.kill("SIGKILL");
-          } catch {
-            /* already gone */
+          if (!signalGroup("SIGKILL")) {
+            try { child.kill("SIGKILL"); } catch { /* already gone */ }
           }
         }, Math.max(50, options.killGraceMs ?? CHILD_KILL_GRACE_MS)).unref?.();
       };
@@ -534,10 +755,11 @@ export async function runChildAgent(
         watchdog = setTimeout(() => kill("stalled"), window);
         watchdog.unref?.();
       };
-      const alive = () => {
+      const alive = (meaningful: boolean) => {
+        if (!meaningful) return;
         lastActivity = now();
         armWatchdog();
-        options.onActivity?.({ at: lastActivity, turns, toolsRunning: toolsRunning.size });
+        options.onActivity?.({ at: lastActivity, turns: events.turns, toolsRunning: toolsRunning.size, meaningful: true });
       };
       armWatchdog();
 
@@ -554,38 +776,32 @@ export async function runChildAgent(
         else options.signal.addEventListener("abort", abortHandler, { once: true });
       }
 
-      // Tool calls in flight and finished turns, from the event lines.
-      const observe = (line: string) => {
-        if (!line.includes('"type"')) return;
-        let event: any;
-        try {
-          event = JSON.parse(line);
-        } catch {
-          return;
-        }
-        if (event?.type === "tool_execution_start" && typeof event.toolCallId === "string") toolsRunning.add(event.toolCallId);
-        else if (event?.type === "tool_execution_end" && typeof event.toolCallId === "string") toolsRunning.delete(event.toolCallId);
-        else if (event?.type === "message_end" && event.message?.role === "assistant") turns += 1;
-      };
-
+      child.stdout?.setEncoding?.("utf8");
       child.stdout?.on("data", (chunk: Buffer | string) => {
         const text = String(chunk);
-        stdout += text;
-        const lines = (pendingLine + text).split("\n");
-        pendingLine = lines.pop() ?? "";
-        for (const line of lines) observe(line);
-        alive();
+        const before = events.progressSerial;
+        events.push(text);
+        alive(events.progressSerial !== before);
         options.onChildStdout?.(task.role, text);
       });
+      child.stderr?.setEncoding?.("utf8");
       child.stderr?.on("data", (chunk: Buffer | string) => {
         const text = String(chunk);
         // The child's gateway guard reports a move to the main model here.
         const lines = (pendingErrLine + text).split("\n");
         pendingErrLine = lines.pop() ?? "";
-        for (const line of lines) gatewayFallback = parseFallbackMarker(line) ?? gatewayFallback;
+        if (pendingErrLine.length > 64 * 1024) pendingErrLine = pendingErrLine.slice(-64 * 1024);
+        let meaningful = false;
+        for (const line of lines) {
+          const fallback = parseFallbackMarker(line);
+          if (fallback) {
+            gatewayFallback = fallback;
+            meaningful = true;
+          }
+        }
         stderr += text;
         if (stderr.length > 256 * 1024) stderr = stderr.slice(-64 * 1024);
-        alive();
+        alive(meaningful);
       });
       child.on("error", (error: Error) => {
         finish({
@@ -597,7 +813,8 @@ export async function runChildAgent(
         });
       });
       child.on("close", (code: number | null) => {
-        const parsed = parseChildEvents(stdout);
+        events.end();
+        const parsed = { finalText: events.finalText, turns: events.turns };
         const partial = parsed.finalText ? " — partial result kept" : "";
         if (killedFor) {
           const error = killedFor === "timeout"
@@ -636,6 +853,8 @@ function formatMinutes(ms: number): string {
  */
 export function childEnvironment(task: ChildTask, parentSessionId: string, base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
   const env: NodeJS.ProcessEnv = { ...base, ...(task.env ?? {}), OMNIRUSH_PARENT_SESSION: parentSessionId };
+  // One layer further down than the delegating agent.
+  env[ENV_AGENT_DEPTH] = String(agentDepth(base) + 1);
   // Guarded mode: the name the parent's approval prompt shows for this child.
   const oneLine = task.task.replace(/\s+/g, " ").trim();
   env.OMNIRUSH_SUBAGENT_LABEL = `${ROLE_PRESETS[task.role]?.label ?? task.role}: ${oneLine.length > 60 ? `${oneLine.slice(0, 59)}…` : oneLine}`;
@@ -731,6 +950,8 @@ export interface AgentRecord {
   /** Background delivery: one message per child, or one per batch. */
   notify: "each" | "batch";
   status: AgentState;
+  /** Queued because memory is short (see memory-lib.ts): why, and since when. */
+  waiting: { reason: "memory"; detail: string; since: number } | null;
   queuedAt: number;
   startedAt: number | null;
   finishedAt: number | null;
@@ -749,14 +970,37 @@ export type AgentRunner = (
   options: {
     sessionId: string;
     parentSessionId: string;
+    /** Where the child's session file goes (subagentSessionDir). */
+    sessionDir?: string;
     signal: AbortSignal;
     onActivity: (activity: ChildActivity) => void;
     /** The call's explicit timeout_minutes, if any. */
     timeoutMs?: number;
     cwd?: string;
+    /** The child process started (its pid). */
+    onSpawn?: (pid: number | undefined) => void;
   },
 ) => Promise<ChildResult>;
 
+/**
+ * Memory-aware admission (memory-lib.ts MemoryAdmission): whether one more
+ * child may start, and the children it counts.
+ */
+export interface AgentAdmission {
+  check(): { ok: true } | { ok: false; reason: string; detail: string };
+  started(key: object, pid?: number | null): void;
+  spawned(key: object, pid: number | null | undefined): void;
+  finished(key: object): void;
+}
+
+/** A queued child: waits for its batch's max_parallel slot and for memory. */
+interface QueueEntry {
+  record: AgentRecord;
+  task: ChildTask;
+  options: DispatchOptions;
+  batch: { running: number; limit: number };
+}
+
 export interface DispatchOptions {
   background: boolean;
   /** Children running at once (default: all of them). */
@@ -772,6 +1016,8 @@ export interface DispatchOptions {
   timeoutMs?: number;
   /** Workspace the children run in. */
   cwd?: string;
+  /** Where the children's session files go (subagentSessionDir). */
+  sessionDir?: string;
 }
 
 /**
@@ -791,12 +1037,33 @@ export class AgentManager {
   private readonly resolvers = new Map<AgentRecord, (result: ChildResult) => void>();
   private nextAgent = 1;
   private nextBatch = 1;
-
-  constructor(options: { run: AgentRunner; now?: () => number; onDeliverable?: () => void; onChanged?: () => void }) {
+  private readonly admission: AgentAdmission | null;
+  private readonly retryMs: number;
+  private readonly onMemoryWait: (info: { critical: boolean; detail: string; queued: number } | null) => void;
+  private queue: QueueEntry[] = [];
+  private retryTimer: ReturnType<typeof setTimeout> | null = null;
+  /** The last memory wait reported (null when nothing waits for memory). */
+  private memoryWait: { critical: boolean; detail: string } | null = null;
+
+  constructor(options: {
+    run: AgentRunner;
+    now?: () => number;
+    onDeliverable?: () => void;
+    onChanged?: () => void;
+    /** Memory-aware admission; none = children start as soon as their batch allows. */
+    admission?: AgentAdmission | null;
+    /** How often a child waiting for memory checks again (ms). */
+    retryMs?: number;
+    /** Children started or stopped waiting for memory (null: nothing waits any more). */
+    onMemoryWait?: (info: { critical: boolean; detail: string; queued: number } | null) => void;
+  }) {
     this.runner = options.run;
     this.now = options.now ?? Date.now;
     this.onDeliverable = options.onDeliverable ?? (() => undefined);
     this.onChanged = options.onChanged ?? (() => undefined);
+    this.admission = options.admission ?? null;
+    this.retryMs = options.retryMs ?? 1_000;
+    this.onMemoryWait = options.onMemoryWait ?? (() => undefined);
   }
 
   dispatch(
@@ -805,6 +1072,7 @@ export class AgentManager {
     options: DispatchOptions,
   ): { batch: string; records: AgentRecord[]; done: Promise<ChildResult[]> } {
     const batch = `b${this.nextBatch++}`;
+    this.releaseOldOutputs(parentSessionId);
     const list = this.bySession.get(parentSessionId) ?? [];
     this.bySession.set(parentSessionId, list);
     const at = this.now();
@@ -824,6 +1092,7 @@ export class AgentManager {
         parallelLimit: options.concurrency === undefined ? null : Math.max(1, Math.floor(options.concurrency)),
         notify: options.notify ?? "batch",
         status: "queued",
+        waiting: null,
         queuedAt: at,
         startedAt: null,
         finishedAt: null,
@@ -847,19 +1116,81 @@ export class AgentManager {
       if (options.signal.aborted) abort();
       else options.signal.addEventListener("abort", abort, { once: true });
     }
-    const concurrency = Math.max(1, Math.floor(options.concurrency ?? records.length));
-    void mapWithConcurrency(records, concurrency, async (record, index) => {
-      // Cancelled while it waited for a slot: it never starts.
-      if (!record.result) await this.start(record, tasks[index], options);
-      options.onSettled?.(record);
-    });
+    // No count cap: every task of the batch may run at once unless the call
+    // set max_parallel; memory admission decides when each one starts.
+    const slots = { running: 0, limit: Math.max(1, Math.floor(options.concurrency ?? records.length)) };
+    records.forEach((record, index) => this.queue.push({ record, task: tasks[index], options, batch: slots }));
+    this.pump();
     return { batch, records, done: Promise.all(records.map((record) => record.done)) };
   }
 
-  private async start(record: AgentRecord, task: ChildTask, options: DispatchOptions): Promise<void> {
+  /**
+   * Start queued children, oldest first, while their batch has a free slot
+   * and memory admission allows; the rest wait for a child to finish or
+   * for the next check (every retryMs while something waits for memory).
+   */
+  private pump(): void {
+    if (this.retryTimer) {
+      clearTimeout(this.retryTimer);
+      this.retryTimer = null;
+    }
+    let blocked: { reason: string; detail: string } | null = null;
+    const still: QueueEntry[] = [];
+    let changed = false;
+    for (const entry of this.queue) {
+      const { record } = entry;
+      if (record.result) {
+        // Cancelled while it waited: it never starts.
+        entry.options.onSettled?.(record);
+        continue;
+      }
+      if (blocked || entry.batch.running >= entry.batch.limit) {
+        if (blocked && entry.batch.running < entry.batch.limit) changed = this.markWaiting(record, blocked.detail) || changed;
+        still.push(entry);
+        continue;
+      }
+      const verdict = this.admission ? this.admission.check() : { ok: true as const };
+      if (!verdict.ok) {
+        blocked = verdict;
+        changed = this.markWaiting(record, verdict.detail) || changed;
+        still.push(entry);
+        continue;
+      }
+      entry.batch.running += 1;
+      void this.start(entry);
+    }
+    this.queue = still;
+    const waiting = still.filter((entry) => entry.record.waiting);
+    if (blocked && waiting.length > 0) {
+      const info = { critical: blocked.reason === "critical", detail: blocked.detail };
+      // Once when children start waiting, and when it turns critical (or back):
+      // the figures in the detail change with every check.
+      if (!this.memoryWait || this.memoryWait.critical !== info.critical) {
+        this.memoryWait = info;
+        this.onMemoryWait({ ...info, queued: waiting.length });
+      }
+      // A ref'd timer: a one-shot run must not end while children wait.
+      this.retryTimer = setTimeout(() => this.pump(), this.retryMs);
+    } else if (this.memoryWait) {
+      this.memoryWait = null;
+      this.onMemoryWait(null);
+    }
+    if (changed) this.onChanged();
+  }
+
+  private markWaiting(record: AgentRecord, detail: string): boolean {
+    if (record.waiting?.detail === detail) return false;
+    record.waiting = { reason: "memory", detail, since: record.waiting?.since ?? this.now() };
+    return true;
+  }
+
+  private async start(entry: QueueEntry): Promise<void> {
+    const { record, task, options } = entry;
     record.status = "running";
+    record.waiting = null;
     record.startedAt = this.now();
     record.lastActivityAt = record.startedAt;
+    this.admission?.started(record);
     this.onChanged();
     options.onChanged?.();
     let result: ChildResult;
@@ -868,8 +1199,10 @@ export class AgentManager {
         sessionId: record.sessionId,
         parentSessionId: record.parentSessionId,
         signal: record.controller.signal,
+        onSpawn: (pid) => this.admission?.spawned(record, pid),
         ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
         ...(options.cwd ? { cwd: options.cwd } : {}),
+        ...(options.sessionDir ? { sessionDir: options.sessionDir } : {}),
         onActivity: (activity) => {
           record.lastActivityAt = activity.at;
           record.turns = activity.turns;
@@ -887,7 +1220,12 @@ export class AgentManager {
         error: error instanceof Error ? error.message : String(error),
       }, this.now() - (record.startedAt ?? this.now()), record.sessionId);
     }
+    this.admission?.finished(record);
+    entry.batch.running -= 1;
     this.settle(record, result);
+    options.onSettled?.(record);
+    // Its slot and its memory are free: the queue moves on.
+    this.pump();
   }
 
   private settle(record: AgentRecord, result: ChildResult): void {
@@ -919,6 +1257,18 @@ export class AgentManager {
     if (record.background && !record.delivered) this.onDeliverable();
   }
 
+  /** Memory: delivered results beyond the newest MAX_KEPT_OUTPUTS keep no output. */
+  private releaseOldOutputs(parentSessionId: string): void {
+    const list = this.bySession.get(parentSessionId) ?? [];
+    let kept = 0;
+    for (let index = list.length - 1; index >= 0; index--) {
+      const result = list[index].result;
+      if (!result || !list[index].delivered || result.output === RELEASED_OUTPUT) continue;
+      kept += 1;
+      if (kept > MAX_KEPT_OUTPUTS) list[index].result = { ...result, output: RELEASED_OUTPUT };
+    }
+  }
+
   list(parentSessionId: string): AgentRecord[] {
     return [...(this.bySession.get(parentSessionId) ?? [])];
   }
@@ -1026,6 +1376,7 @@ export class AgentManager {
         }, 0, record.sessionId));
       }
     }
+    if (live.some((record) => record.startedAt === null)) this.pump();
     await Promise.all(live.map((record) => record.done));
   }
 
@@ -1048,6 +1399,7 @@ export function agentStatusSummary(records: AgentRecord[]): string {
   if (records.length === 0) return "No sub-agents in this session.";
   const running = records.filter((record) => record.status === "running").length;
   const queued = records.filter((record) => record.status === "queued").length;
+  const forMemory = records.filter((record) => record.status === "queued" && record.waiting?.reason === "memory").length;
   const settled = records.filter((record) => Boolean(record.result)).length;
   const limits = [...new Set(records.map((record) => record.parallelLimit))];
   const parallel = limits.length === 1 && limits[0] === null
@@ -1055,7 +1407,8 @@ export function agentStatusSummary(records: AgentRecord[]): string {
     : limits.length === 1
       ? String(limits[0])
       : "per-batch";
-  return `${records.length} sub-agents: ${running} running, ${queued} queued, ${settled} settled (parallel: ${parallel})`;
+  const queuedText = forMemory > 0 ? `${queued} queued: waiting for memory` : `${queued} queued`;
+  return `${records.length} sub-agents: ${running} running, ${queuedText}, ${settled} settled (parallel: ${parallel})`;
 }
 
 /** One status line per sub-agent (agents_status, /agents). */
@@ -1064,7 +1417,8 @@ export function renderAgentStatus(records: AgentRecord[], now: number = Date.now
   const lines = records.map((record) => {
     const since = record.startedAt ?? record.queuedAt;
     const elapsed = minutesOf((record.finishedAt ?? now) - since);
-    const bits = [`${record.id}`, `[${record.status}]`, record.role];
+    const state = record.status === "queued" && record.waiting ? "queued: waiting for memory" : record.status;
+    const bits = [`${record.id}`, `[${state}]`, record.role];
     if (record.model) bits.push(`[${record.model}${record.effort ? ` · ${record.effort}` : ""}]`);
     bits.push(record.background ? "background" : "blocking");
     const detail: string[] = [`${elapsed} min`];
@@ -1074,6 +1428,7 @@ export function renderAgentStatus(records: AgentRecord[], now: number = Date.now
       detail.push(`last activity ${minutesOf(now - record.lastActivityAt)} min ago`);
     }
     if (record.result && !record.delivered) detail.push("result not yet read");
+    if (!record.result && record.waiting) detail.push(record.waiting.detail);
     const task = record.task.length > 80 ? `${record.task.slice(0, 79)}…` : record.task;
     return `- ${bits.join(" ")} (${detail.join(", ")}) — ${task}`;
   });