omnirush 0.8.6 → 0.9.1

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,
@@ -28,7 +30,16 @@ import { mkdtemp, writeFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 
+import {
+  ENV_FALLBACK_EFFORT,
+  ENV_FALLBACK_MODEL,
+  FALLBACK_MARKER,
+  fallbackNote,
+  piThinking,
+  type SubagentFallback,
+} from "./subagents-lib";
 import { childAuthEnv } from "./auth";
+import { yoloActive } from "./yolo-lib";
 
 /** childAuthEnv, never throwing (a spawn must not fail on the auth file). */
 function childAuthEnvSafe(): Record<string, string> {
@@ -62,6 +73,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];
@@ -152,6 +204,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
@@ -164,19 +235,36 @@ export function buildChildArgs(
   promptFilePath: string | null,
   model?: string,
   sessionId?: string,
+  effort?: string | null,
+  approve = false,
+  sessionDir?: string,
 ): string[] {
   const args: string[] = ["--mode", "json", "-p"];
+  if (approve) {
+    // Yolo mode: a headless child has no trust prompt, so without this it
+    // would ignore the project's settings the parent runs with.
+    args.push("--approve");
+  }
   if (sessionId) {
     // The child's session id, picked by the parent so its session file can
     // 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);
   }
   if (model && model.trim()) {
     args.push("--provider", "omnirush", "--model", model.trim());
   }
+  if (effort && effort.trim()) {
+    // The effort the sub-agent runs on (the picked one, or the main agent's
+    // mapped to the levels this model offers).
+    args.push("--thinking", piThinking(effort.trim()));
+  }
   args.push(`Task: ${task}`);
   return args;
 }
@@ -207,6 +295,25 @@ export interface ChildTask {
    *  (e.g. "muse-spark-1.3" for cheap swarm workers under an astra
    *  parent). Undefined = inherit the parent's model. */
   model?: string;
+  /** The effort the child runs on (gateway spelling); undefined = pi's default. */
+  effort?: string;
+  /** The picked sub-agent model could not be used: `model` is the main one. */
+  fallback?: SubagentFallback;
+  /** The main model the child's gateway guard moves to when the gateway refuses `model`. */
+  gatewayFallback?: { model: string; effort: string | null };
+  /** Extra environment for the child (the sub-agent setting and main model, for nested layers). */
+  env?: Record<string, string>;
+}
+
+/** A sub-agent that ran on the main model instead of the picked one. */
+export interface ChildModelFallback {
+  requested: string;
+  used: string;
+  effort?: string | null;
+  reason: string;
+  /** "selection": picked before it started; "gateway": the gateway refused the picked model mid-run. */
+  kind: "selection" | "gateway";
+  note: string;
 }
 
 export type ChildStatus = "completed" | "failed" | "timeout" | "stalled" | "cancelled" | "interrupted";
@@ -218,6 +325,10 @@ export interface ChildResult {
   session_id?: string;
   /** The gateway model the child ran on (cross-model children). */
   model?: string;
+  /** The effort it ran on. */
+  effort?: string;
+  /** It ran on the main model instead of the picked one (why, and since when). */
+  model_fallback?: ChildModelFallback;
   status: ChildStatus;
   /** Process exit code (null when killed by a signal or still unknown). */
   exitCode: number | null;
@@ -237,6 +348,33 @@ export interface ChildResultInput {
   turns: number;
   status?: ChildStatus;
   error?: string;
+  /** The gateway moved the child to the main model mid-run. */
+  gatewayFallback?: { requested: string; used: string; effort?: string | null; reason: string };
+}
+
+/** The selection or gateway fallback of a child, for its result. */
+export function childModelFallback(task: ChildTask, gateway?: ChildResultInput["gatewayFallback"]): ChildModelFallback | undefined {
+  if (task.fallback) {
+    return {
+      requested: task.fallback.requested,
+      used: task.fallback.used,
+      effort: task.effort ?? null,
+      reason: String(task.fallback.reason),
+      kind: "selection",
+      note: fallbackNote(task.fallback),
+    };
+  }
+  if (gateway) {
+    return {
+      requested: gateway.requested,
+      used: gateway.used,
+      effort: gateway.effort ?? null,
+      reason: gateway.reason,
+      kind: "gateway",
+      note: fallbackNote({ requested: gateway.requested, used: gateway.used, reason: gateway.reason }),
+    };
+  }
+  return undefined;
 }
 
 /** Final structured result for one child. */
@@ -253,11 +391,14 @@ export function buildChildResult(
     capped = output.slice(0, CHILD_OUTPUT_CAP_BYTES);
     while (Buffer.byteLength(capped, "utf8") > CHILD_OUTPUT_CAP_BYTES) capped = capped.slice(0, -1);
   }
+  const modelFallback = childModelFallback(task, input.gatewayFallback);
   return {
     role: task.role,
     task: task.task,
     ...(sessionId ? { session_id: sessionId } : {}),
     ...(task.model ? { model: task.model } : {}),
+    ...(task.effort ? { effort: task.effort } : {}),
+    ...(modelFallback ? { model_fallback: modelFallback } : {}),
     status: input.status ?? (input.exitCode === 0 ? "completed" : "failed"),
     exitCode: input.exitCode,
     output: capped,
@@ -277,38 +418,155 @@ 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;
+  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_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 {
+    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 !== "tool_execution_start" && type !== "tool_execution_end") return;
     let event: any;
     try {
       event = JSON.parse(trimmed);
     } catch {
-      continue;
+      return;
+    }
+    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_end" || !event.message) continue;
+    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;
     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 -------------------------------------------------------------
@@ -316,6 +574,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
@@ -346,6 +606,10 @@ export interface SpawnChildOptions {
   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 {
@@ -392,17 +656,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);
+    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;
@@ -411,15 +678,12 @@ export async function runChildAgent(
         cwd: options.cwd,
         shell: false,
         stdio: ["ignore", "pipe", "pipe"],
-        env: {
-          ...process.env,
-          // 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.
-          ...childAuthEnvSafe(),
-          OMNIRUSH_PARENT_SESSION: options.parentSessionId,
-        },
+        // 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(), ...(options.extraEnv ?? {}) }),
       });
+      options.onSpawn?.(child.pid);
 
       const finish = (input: ChildResultInput) => {
         if (settled) return;
@@ -429,7 +693,7 @@ export async function runChildAgent(
         if (options.signal && abortHandler) {
           options.signal.removeEventListener("abort", abortHandler);
         }
-        resolvePromise(buildChildResult(task, input, now() - startedAt, sessionId));
+        resolvePromise(buildChildResult(task, { ...input, ...(gatewayFallback ? { gatewayFallback } : {}) }, now() - startedAt, sessionId));
       };
 
       const killTree = () => {
@@ -465,7 +729,7 @@ export async function runChildAgent(
       const alive = () => {
         lastActivity = now();
         armWatchdog();
-        options.onActivity?.({ at: lastActivity, turns, toolsRunning: toolsRunning.size });
+        options.onActivity?.({ at: lastActivity, turns: events.turns, toolsRunning: toolsRunning.size });
       };
       armWatchdog();
 
@@ -482,31 +746,22 @@ 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);
+        events.push(text);
         alive();
         options.onChildStdout?.(task.role, text);
       });
+      child.stderr?.setEncoding?.("utf8");
       child.stderr?.on("data", (chunk: Buffer | string) => {
-        stderr += String(chunk);
+        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() ?? "";
+        if (pendingErrLine.length > 64 * 1024) pendingErrLine = pendingErrLine.slice(-64 * 1024);
+        for (const line of lines) gatewayFallback = parseFallbackMarker(line) ?? gatewayFallback;
+        stderr += text;
         if (stderr.length > 256 * 1024) stderr = stderr.slice(-64 * 1024);
         alive();
       });
@@ -520,7 +775,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"
@@ -551,6 +807,46 @@ function formatMinutes(ms: number): string {
   return `${Math.max(1, Math.round(ms / 1000))} s`;
 }
 
+/**
+ * A child's environment: the parent's, the parent session id (the child
+ * uploads nothing itself), the sub-agent setting and main model handed down
+ * to nested layers, and the main model its gateway guard falls back to (only
+ * for this child: a nested one gets its own or none).
+ */
+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}`;
+  delete env[ENV_FALLBACK_MODEL];
+  delete env[ENV_FALLBACK_EFFORT];
+  if (task.gatewayFallback?.model) {
+    env[ENV_FALLBACK_MODEL] = task.gatewayFallback.model;
+    if (task.gatewayFallback.effort) env[ENV_FALLBACK_EFFORT] = task.gatewayFallback.effort;
+  }
+  return env;
+}
+
+/** A child's stderr line reporting its gateway fallback (see sota.ts), or null. */
+export function parseFallbackMarker(line: string): ChildResultInput["gatewayFallback"] | null {
+  const at = line.indexOf(FALLBACK_MARKER);
+  if (at < 0) return null;
+  try {
+    const parsed = JSON.parse(line.slice(at + FALLBACK_MARKER.length));
+    if (typeof parsed?.requested !== "string" || typeof parsed?.used !== "string") return null;
+    return {
+      requested: parsed.requested,
+      used: parsed.used,
+      effort: typeof parsed.effort === "string" ? parsed.effort : null,
+      reason: typeof parsed.reason === "string" ? parsed.reason : "refused",
+    };
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Run tasks with a concurrency cap, preserving input order in the
  * results (ports the pi subagent example's mapWithConcurrencyLimit).
@@ -580,8 +876,12 @@ export function renderChildResults(results: ChildResult[], ids?: readonly string
   const succeeded = results.filter((result) => result.status === "completed").length;
   const sections = results.map((result, index) => {
     const minutes = Math.round((result.durationMs / 60_000) * 10) / 10;
-    const header = `### ${ids?.[index] ? `${ids[index]} ` : ""}${result.role}${result.model ? ` [${result.model}]` : ""} — ${result.status} (${minutes} min${result.outputTruncated ? ", output capped" : ""})`;
+    const ranOn = result.model_fallback?.kind === "gateway" ? result.model_fallback.used : result.model;
+    const effort = result.model_fallback?.kind === "gateway" ? result.model_fallback.effort ?? undefined : result.effort;
+    const label = ranOn ? ` [${ranOn}${effort ? ` · ${effort}` : ""}]` : "";
+    const header = `### ${ids?.[index] ? `${ids[index]} ` : ""}${result.role}${label} — ${result.status} (${minutes} min${result.outputTruncated ? ", output capped" : ""})`;
     const meta: string[] = [`task: ${result.task}`];
+    if (result.model_fallback) meta.push(`note: ${result.model_fallback.note}`);
     if (result.error) meta.push(`error: ${result.error}`);
     return `${header}\n${meta.join("\n")}\n\n${result.output || "(no output)"}`;
   });
@@ -604,6 +904,7 @@ export interface AgentRecord {
   role: AgentRole;
   task: string;
   model?: string;
+  effort?: string;
   /** Dispatched with wait:false: its result comes back as a message. */
   background: boolean;
   /** Null means the batch was intentionally uncapped; otherwise the batch limit. */
@@ -611,6 +912,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;
@@ -629,14 +932,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). */
@@ -652,6 +978,8 @@ export interface DispatchOptions {
   timeoutMs?: number;
   /** Workspace the children run in. */
   cwd?: string;
+  /** Where the children's session files go (subagentSessionDir). */
+  sessionDir?: string;
 }
 
 /**
@@ -671,12 +999,33 @@ export class AgentManager {
   private readonly resolvers = new Map<AgentRecord, (result: ChildResult) => void>();
   private nextAgent = 1;
   private nextBatch = 1;
+  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 }) {
+  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(
@@ -685,6 +1034,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();
@@ -699,10 +1049,12 @@ export class AgentManager {
         role: task.role,
         task: task.task,
         ...(task.model ? { model: task.model } : {}),
+        ...(task.effort ? { effort: task.effort } : {}),
         background: options.background,
         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,
@@ -726,19 +1078,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;
@@ -747,8 +1161,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;
@@ -766,7 +1182,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 {
@@ -798,6 +1219,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) ?? [])];
   }
@@ -905,6 +1338,7 @@ export class AgentManager {
         }, 0, record.sessionId));
       }
     }
+    if (live.some((record) => record.startedAt === null)) this.pump();
     await Promise.all(live.map((record) => record.done));
   }
 
@@ -927,6 +1361,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
@@ -934,7 +1369,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). */
@@ -943,8 +1379,9 @@ 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];
-    if (record.model) bits.push(`[${record.model}]`);
+    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`];
     if (!record.result && record.startedAt) {
@@ -953,6 +1390,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}`;
   });