omnirush 0.8.4 → 0.8.5

package/assets/extensions/omnirush/agents.ts

@@ -4,20 +4,33 @@
 // the SAME workspace:
 //   - role presets: code-searcher (read-only exploration),
 //     researcher-web (web_fetch research), general-worker (full tools)
-//   - parallel execution, default max 4 children at once
-//   - per-child wall-clock timeout (default 10 min): kill + keep the
-//     partial result
-//   - structured results returned to the parent model
+//   - parallel execution, every task at once unless max_parallel throttles
+//   - no wall-clock limit: a child runs until it is done. Only an explicit
+//     timeout_minutes, the inactivity watchdog (no output at all for
+//     OMNIRUSH_AGENT_INACTIVITY_MINUTES, default 30, longer while one of
+//     its tools runs), a cancel, or the session ending stop it
+//   - blocking (default) or background dispatch (`wait: false`): the call
+//     returns at once with agent ids and the parent keeps working; the
+//     results come back as a message in the conversation when the batch
+//     (or each child, notify "each") finishes — steered into the running
+//     turn, or starting a new turn when the parent is idle. In one-shot
+//     runs (print/json mode) the run does not end while background
+//     children are out: it waits for them and continues with their results
+//   - agents_status / agents_wait / agents_result / agents_cancel manage
+//     running children
 //
 // Tracing is free: every child writes its own session JSONL under
 // <agentDir>/sessions/<cwd-slug>/ (children run without --no-session)
 // under a session id the parent picks, and the parent session's
 // collector records each child's conversation as a sub-agent of the
 // turn (session.child events with parent and depth, as the desktop
-// records task sub-agents). Children get OMNIRUSH_PARENT_SESSION, so a
-// child process uploads nothing of its own.
+// records task sub-agents) — a background child that finishes in a later
+// turn is recorded as it progresses, and one the session ends under is
+// stopped and recorded as interrupted. Children get
+// OMNIRUSH_PARENT_SESSION, so a child process uploads nothing of its own.
 //
-// `/agents` lists this session's subagents (running + finished).
+// `/agents` lists this session's subagents (running + finished);
+// `/agents cancel <id|all>` stops running ones.
 
 import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -25,14 +38,26 @@ import { Type } from "typebox";
 
 import {
   AGENT_ROLES,
-  CHILD_TIMEOUT_MS,
-  mapWithConcurrency,
+  AGENTS_HOOK,
+  AgentManager,
+  type AgentRunner,
+  type AgentsHook,
+  type AgentRecord,
+  childInactivityMs,
+  renderAgentStatus,
   renderChildResults,
+  renderDelivery,
   runChildAgent,
   type ChildResult,
   type ChildTask,
 } from "./agents-lib";
 
+/** A timeout_minutes below this is taken for a placeholder, not a limit. */
+const MIN_TIMEOUT_MINUTES = 1;
+
+/** customType of the message that brings background results back. */
+export const DELIVERY_TYPE = "omnirush-agents-result";
+
 const SpawnAgentsParams = Type.Object({
   tasks: Type.Array(
     Type.Object({
@@ -41,33 +66,103 @@ const SpawnAgentsParams = Type.Object({
       }),
       task: Type.String({ description: "Self-contained task description for the child agent (it sees ONLY this, not your conversation)" }),
       model: Type.Optional(Type.String({
-        description: 'Cross-model child: gateway model id for THIS task (e.g. "muse-spark-1.3", "muse-spark-1.2-contributor" for cheap swarm workers, "meta-muse-spark", "muse-spark-1.1", "gpt-6-astra", "gpt-6-sol", "gpt-5.6-sol"). Omit to inherit this session\'s model',
+        description: 'Cross-model child: gateway model id for THIS task (e.g. "muse-spark-1.3", "muse-spark-1.2-contributor" for cheap swarm workers, "meta-muse-spark", "muse-spark-1.1", "gpt-6-astra", "gpt-6-sol", "gpt-5.6-sol"). Omit (or leave empty) to inherit this session\'s model',
       })),
     }),
     { description: "Tasks to delegate; they all run in parallel", minItems: 1 },
   ),
+  wait: Type.Optional(Type.Boolean({
+    description: "true (default): block until every child finished and return their results. false: background dispatch — return at once with agent ids and keep working; the results arrive later as a message in this conversation (no polling needed)",
+  })),
+  notify: Type.Optional(StringEnum(["batch", "each"] as const, {
+    description: 'Background dispatch only: deliver one message when the whole batch finished ("batch", default) or one per child as each finishes ("each")',
+  })),
   timeout_minutes: Type.Optional(Type.Number({
-    description: `Per-child wall-clock limit in minutes (default ${CHILD_TIMEOUT_MS / 60_000}; a timed-out child is killed and its partial result is kept)`,
-    minimum: 0.1,
-    maximum: 60,
+    description: "Leave out (or 0) unless the user asked for a hard limit: children then run until they are done, however long that takes. A value of 1 or more kills a child after that many minutes (its partial result is kept); smaller values are ignored",
   })),
   max_parallel: Type.Optional(Type.Number({
-    description: "Optional throttle: run at most this many children at once. Omit to run every task in parallel (no cap)",
-    minimum: 1,
+    description: "Leave out (or 0) to run every task in parallel (no cap, the default); a positive number throttles to that many children at once",
   })),
 });
 
-interface AgentRegistryEntry {
-  role: string;
-  task: string;
-  status: "running" | ChildResult["status"];
-  startedAt: number;
-  durationMs: number | null;
+const IdsParam = Type.Optional(Type.Array(Type.String(), {
+  description: 'Agent ids from spawn_agents (e.g. "a3"); omit (or "all") for every agent of this session',
+}));
+
+function resultOf(record: AgentRecord): ChildResult & { agent_id: string } {
+  return { ...(record.result as ChildResult), agent_id: record.id };
 }
 
-export default function (pi: ExtensionAPI) {
-  /** session id -> subagent records (this process only). */
-  const registry = new Map<string, AgentRegistryEntry[]>();
+/** Results of finished records plus a status line for the others. */
+function renderSome(records: AgentRecord[], unknown: string[] = []): string {
+  const finished = records.filter((record) => record.result);
+  const open = records.filter((record) => !record.result);
+  const parts: string[] = [];
+  if (finished.length > 0) parts.push(renderChildResults(finished.map((record) => record.result as ChildResult), finished.map((record) => record.id)));
+  if (open.length > 0) parts.push(`Still running:\n${renderAgentStatus(open)}`);
+  if (unknown.length > 0) parts.push(`Unknown agent ids: ${unknown.join(", ")}`);
+  return parts.join("\n\n") || "No matching sub-agents.";
+}
+
+export default function (pi: ExtensionAPI, options: { run?: AgentRunner } = {}) {
+  const watchdogMinutes = Math.round(childInactivityMs() / 60_000);
+  /** The session this runtime is on (deliveries go to it). */
+  let currentSession = "";
+  let cwd = process.cwd();
+  /** An agent run is under way (one-shot runs deliver through the settle loop otherwise). */
+  let busy = false;
+  let oneShot = false;
+
+  const send = (records: AgentRecord[]) => {
+    pi.sendMessage(
+      {
+        customType: DELIVERY_TYPE,
+        content: renderDelivery(records),
+        display: true,
+        details: { results: records.map(resultOf) },
+      },
+      // Busy: into the running turn at its next step. Idle: a new turn.
+      { triggerTurn: true, deliverAs: "steer" },
+    );
+  };
+
+  const deliver = () => {
+    if (!currentSession) return;
+    // One-shot and between runs: the agent_settled loop delivers.
+    if (oneShot && !busy) {
+      return;
+    }
+    for (const group of manager.takeDeliverable(currentSession)) send(group.records);
+  };
+
+  const manager = new AgentManager({
+    run: options.run ?? ((task, options) => runChildAgent(task, {
+      cwd: options.cwd ?? cwd,
+      parentSessionId: options.parentSessionId,
+      sessionId: options.sessionId,
+      signal: options.signal,
+      onActivity: options.onActivity,
+      ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+    })),
+    // After the settle's own bookkeeping (waiters took theirs).
+    onDeliverable: () => queueMicrotask(deliver),
+  });
+
+  const hook: AgentsHook = {
+    async interruptAll(parentSessionId?: string) {
+      const stopped = await manager.interruptAll(parentSessionId);
+      return stopped.map((record) => ({ sessionId: record.sessionId, id: record.id, role: record.role }));
+    },
+  };
+  (globalThis as any)[AGENTS_HOOK] = hook;
+
+  const sessionOf = (ctx: any): string => {
+    const id = String(ctx?.sessionManager?.getSessionId?.() ?? "");
+    if (id) currentSession = id;
+    if (ctx?.cwd) cwd = String(ctx.cwd);
+    if (ctx?.mode === "print" || ctx?.mode === "json") oneShot = true;
+    return id;
+  };
 
   pi.registerTool({
     name: "spawn_agents",
@@ -76,14 +171,20 @@ export default function (pi: ExtensionAPI) {
       "Delegate tasks to parallel subagents with isolated context windows.",
       "Each child is a headless agent run in this workspace with a role preset:",
       "code-searcher (read-only exploration), researcher-web (web research via web_search + web_fetch), general-worker (full tools).",
-      `Children run in parallel — every task at once unless max_parallel throttles it — and each gets its own timeout (default ${CHILD_TIMEOUT_MS / 60_000} min).`,
+      "Children run in parallel — every task at once unless max_parallel throttles it — and have no time limit: they run until done",
+      `(timeout_minutes sets one explicitly${watchdogMinutes > 0 ? `; a child that prints nothing at all for ${watchdogMinutes}+ min is stopped as hung` : ""}).`,
+      "Default (wait true) blocks until all children finish and returns their results.",
+      "wait:false dispatches them in the BACKGROUND: the call returns at once with agent ids, you keep working, and their results arrive automatically as a message in this conversation when they finish.",
+      "Manage background agents with agents_status, agents_wait, agents_result and agents_cancel.",
       'Each task can run on a DIFFERENT model via its "model" field — e.g. cheap muse workers for wide swarm sweeps under an astra parent.',
       "Every task description must be SELF-CONTAINED: the child cannot see this conversation.",
       "Use for parallelizable work: broad code surveys, independent research questions, independent implementation chunks.",
     ].join(" "),
-    promptSnippet: "spawn_agents: delegate parallel tasks to role-preset subagents",
+    promptSnippet: "spawn_agents: delegate parallel tasks to role-preset subagents (blocking, or wait:false for background work)",
     promptGuidelines: [
       "Use spawn_agents when 2+ independent sub-tasks would each take several tool calls (surveys, research, independent fixes); write each task brief as a self-contained mini-prompt with the goal, relevant paths and the expected report format.",
+      "Short fan-outs whose results you need right away (quick searches, lookups): the default blocking call.",
+      "Long work (implementation chunks, builds, test suites, long research — anything that may take many minutes) while you have other things to do: spawn_agents with wait:false, then keep working; the results arrive on their own as a message, so do not poll agents_status in a loop. Call agents_wait only when you have nothing else to do and need the results before going on.",
       "Do not use spawn_agents for a single quick action — doing it yourself is cheaper.",
     ],
     parameters: SpawnAgentsParams,
@@ -94,10 +195,8 @@ export default function (pi: ExtensionAPI) {
         if (!raw || typeof raw.task !== "string" || !raw.task.trim()) {
           throw new Error("invalid tasks: every entry needs a non-empty task string");
         }
+        // An empty model (models fill optional fields) inherits the session's.
         const model = typeof raw.model === "string" ? raw.model.trim() : "";
-        if (raw.model !== undefined && !model) {
-          throw new Error("invalid tasks: model must be a non-empty gateway model id");
-        }
         tasks.push({
           role: raw.role,
           task: raw.task.trim(),
@@ -105,78 +204,231 @@ export default function (pi: ExtensionAPI) {
         });
       }
       if (tasks.length === 0) throw new Error("no tasks given");
-      const parentSessionId = String(ctx?.sessionManager?.getSessionId?.() ?? "");
+      const parentSessionId = sessionOf(ctx);
       if (!parentSessionId) throw new Error("no parent session id — subagents cannot be traced");
-      const cwd = ctx?.cwd ? String(ctx.cwd) : process.cwd();
-      const timeoutMinutes = typeof params.timeout_minutes === "number" && params.timeout_minutes > 0
-        ? params.timeout_minutes
+      const workdir = ctx?.cwd ? String(ctx.cwd) : process.cwd();
+      // Only a deliberate limit counts: models fill optional numbers with
+      // their minimum (a 0.1-minute "limit" killed every child in 6 s).
+      const timeoutMs = typeof params.timeout_minutes === "number" && params.timeout_minutes >= MIN_TIMEOUT_MINUTES
+        ? params.timeout_minutes * 60_000
         : undefined;
       // No cap: every task runs at once unless the caller throttles.
       const concurrency = typeof params.max_parallel === "number" && params.max_parallel >= 1
         ? Math.floor(params.max_parallel)
         : tasks.length;
+      const background = params.wait === false;
 
-      const entries = registry.get(parentSessionId) ?? [];
-      registry.set(parentSessionId, entries);
-      const marks = tasks.map((task) => {
-        const entry: AgentRegistryEntry = {
-          role: task.role,
-          task: task.task,
-          status: "running",
-          startedAt: Date.now(),
-          durationMs: null,
-        };
-        entries.push(entry);
-        return entry;
-      });
-
-      // Children settled so far, for progress updates (the result array
-      // below only exists once every child settled).
-      const settled: ChildResult[] = [];
-      const results = await mapWithConcurrency<ChildTask, ChildResult>(
-        tasks,
+      let settledCount = 0;
+      const dispatched = manager.dispatch(parentSessionId, tasks, {
+        background,
         concurrency,
-        async (task, index) => {
-          const result = await runChildAgent(task, {
-            cwd,
-            parentSessionId,
-            timeoutMs: timeoutMinutes === undefined ? undefined : timeoutMinutes * 60_000,
-            signal,
-          });
-          const mark = marks[index];
-          mark.status = result.status;
-          mark.durationMs = result.durationMs;
-          settled.push(result);
+        notify: params.notify === "each" ? "each" : "batch",
+        ...(background ? {} : { signal }),
+        onSettled: (record) => {
+          settledCount += 1;
+          if (background) return;
           onUpdate?.({
-            content: [{ type: "text", text: `spawn_agents: ${settled.length}/${tasks.length} settled (latest: ${task.role})` }],
-            details: { results: [...settled] },
+            content: [{ type: "text", text: `spawn_agents: ${settledCount}/${tasks.length} settled (latest: ${record.id} ${record.role})` }],
+            details: { results: dispatched.records.filter((candidate) => candidate.result).map(resultOf) },
           });
-          return result;
         },
-      );
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        cwd: workdir,
+      });
+
+      if (background) {
+        const lines = dispatched.records.map((record) => `- ${record.id}: ${record.role}${record.model ? ` [${record.model}]` : ""} — ${record.task.length > 100 ? `${record.task.slice(0, 99)}…` : record.task}`);
+        return {
+          content: [{
+            type: "text",
+            text: [
+              `spawn_agents: dispatched ${dispatched.records.length} background sub-agent${dispatched.records.length === 1 ? "" : "s"} (batch ${dispatched.batch}):`,
+              ...lines,
+              "",
+              params.notify === "each"
+                ? "Keep working: each result arrives as a message in this conversation when that agent finishes."
+                : "Keep working: the results arrive as one message in this conversation when all of them finished.",
+              "agents_status shows progress; agents_wait blocks for them; agents_cancel stops them.",
+            ].join("\n"),
+          }],
+          details: {
+            background: true,
+            batch: dispatched.batch,
+            results: dispatched.records.map((record) => ({
+              agent_id: record.id,
+              role: record.role,
+              task: record.task,
+              session_id: record.sessionId,
+              ...(record.model ? { model: record.model } : {}),
+              status: "running",
+            })),
+          },
+        };
+      }
+
+      await dispatched.done;
+      const records = dispatched.records;
+      return {
+        content: [{ type: "text", text: renderChildResults(records.map((record) => record.result as ChildResult), records.map((record) => record.id)) }],
+        details: { results: records.map(resultOf) },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "agents_status",
+    label: "Agents Status",
+    description: "Status of this session's sub-agents (from spawn_agents): id, state, elapsed time, turns, last activity. Background results are delivered automatically — use this to check progress, not to poll in a loop.",
+    promptSnippet: "agents_status: list sub-agents and their progress",
+    parameters: Type.Object({ ids: IdsParam }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const { records, unknown } = manager.resolve(sessionOf(ctx), params.ids);
+      const text = renderAgentStatus(records) + (unknown.length ? `\nUnknown agent ids: ${unknown.join(", ")}` : "");
+      return {
+        content: [{ type: "text", text }],
+        details: { agents: records.map((record) => ({ agent_id: record.id, status: record.status, role: record.role, session_id: record.sessionId })) },
+      };
+    },
+  });
 
+  pi.registerTool({
+    name: "agents_wait",
+    label: "Wait For Agents",
+    description: "Block until the given background sub-agents finish (default: every unfinished one) and return their results. Optional timeout_minutes bounds the WAIT only — the agents keep running past it.",
+    promptSnippet: "agents_wait: block until background sub-agents finish",
+    parameters: Type.Object({
+      ids: IdsParam,
+      timeout_minutes: Type.Optional(Type.Number({ description: "Leave out (or 0) to wait until they finish; otherwise stop WAITING after this many minutes (the agents keep running)" })),
+    }),
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      const session = sessionOf(ctx);
+      const explicit = Array.isArray(params.ids) && params.ids.length > 0 && !params.ids.includes("all");
+      const { records: resolved, unknown } = manager.resolve(session, params.ids);
+      // Default: what is still out or not yet read.
+      const records = explicit ? resolved : resolved.filter((record) => !record.result || !record.delivered);
+      if (records.length === 0 && unknown.length === 0) {
+        return { content: [{ type: "text", text: "No background sub-agents to wait for." }], details: { results: [] } };
+      }
+      onUpdate?.({ content: [{ type: "text", text: `agents_wait: waiting for ${records.filter((record) => !record.result).length} sub-agent(s)` }], details: {} });
+      await manager.wait(records, {
+        signal,
+        ...(typeof params.timeout_minutes === "number" && params.timeout_minutes > 0 ? { timeoutMs: params.timeout_minutes * 60_000 } : {}),
+      });
       return {
-        content: [{ type: "text", text: renderChildResults(results) }],
-        details: { results },
+        content: [{ type: "text", text: renderSome(records, unknown) }],
+        details: { results: records.filter((record) => record.result).map(resultOf) },
       };
     },
   });
 
+  pi.registerTool({
+    name: "agents_result",
+    label: "Agent Result",
+    description: "The full result of one sub-agent by id (or its status while it still runs).",
+    promptSnippet: "agents_result: fetch a finished sub-agent's result",
+    parameters: Type.Object({ id: Type.String({ description: 'Agent id from spawn_agents (e.g. "a3")' }) }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const { records, unknown } = manager.resolve(sessionOf(ctx), [params.id]);
+      records.filter((record) => record.result).forEach((record) => { record.delivered = true; });
+      return {
+        content: [{ type: "text", text: renderSome(records, unknown) }],
+        details: { results: records.filter((record) => record.result).map(resultOf) },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "agents_cancel",
+    label: "Cancel Agents",
+    description: 'Stop running sub-agents by id ("all" for every one of this session); returns what each had produced so far.',
+    promptSnippet: "agents_cancel: stop running sub-agents",
+    parameters: Type.Object({
+      ids: Type.Array(Type.String(), { description: 'Agent ids to stop, or ["all"]', minItems: 1 }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const { records, unknown } = manager.resolve(sessionOf(ctx), params.ids);
+      const live = records.filter((record) => !record.result);
+      await manager.cancel(live, "cancelled", { delivered: true });
+      return {
+        content: [{ type: "text", text: live.length ? renderSome(live, unknown) : `Nothing to cancel${unknown.length ? ` (unknown ids: ${unknown.join(", ")})` : ""}.` }],
+        details: { results: live.map(resultOf) },
+      };
+    },
+  });
+
+  pi.on("session_start", (_event: any, ctx: any) => {
+    sessionOf(ctx);
+  });
+
+  pi.on("agent_start", (_event: any, ctx: any) => {
+    sessionOf(ctx);
+    busy = true;
+  });
+
+  /**
+   * One-shot runs (print/json mode) end when the agent settles: background
+   * children still out would be lost. The run waits for them here and
+   * continues with their results (a new run nested in this settle, whose
+   * own settle resumes this one when everything is done).
+   */
+  let resumeOuter: (() => void) | null = null;
+  pi.on("agent_settled", async (_event: any, ctx: any) => {
+    busy = false;
+    const session = sessionOf(ctx);
+    if (!oneShot) {
+      // Anything that finished right as the run ended.
+      deliver();
+      return;
+    }
+    const outer = resumeOuter;
+    resumeOuter = null;
+    try {
+      for (;;) {
+        if (typeof ctx?.isIdle === "function" && !ctx.isIdle()) {
+          // A run started (a delivery): its settle resumes this one.
+          await new Promise<void>((resolve) => { resumeOuter = resolve; });
+          break;
+        }
+        if (!session || !manager.hasPending(session)) break;
+        const groups = manager.takeDeliverable(session);
+        if (groups.length === 0) {
+          await manager.changed();
+          continue;
+        }
+        busy = true;
+        const records = groups.flatMap((group) => group.records);
+        send(records);
+        if (typeof ctx?.isIdle === "function" && ctx.isIdle()) busy = false;
+      }
+    } finally {
+      outer?.();
+    }
+  });
+
+  pi.on("session_shutdown", async () => {
+    // Children the session ends under are stopped (the collector, when it
+    // runs, already did this before its last capture).
+    await manager.interruptAll().catch(() => undefined);
+  });
+
   pi.registerCommand("agents", {
-    description: "List this session's subagents (running and finished)",
-    handler: async (_args: string, ctx: any) => {
-      const sessionId = String(ctx?.sessionManager?.getSessionId?.() ?? "");
-      const entries = registry.get(sessionId) ?? [];
-      if (entries.length === 0) {
+    description: "List this session's subagents (running and finished); /agents cancel <id|all> stops running ones",
+    handler: async (args: string, ctx: any) => {
+      const session = sessionOf(ctx);
+      const words = String(args ?? "").trim().split(/\s+/).filter(Boolean);
+      if (words[0] === "cancel") {
+        const { records } = manager.resolve(session, words.slice(1).length ? words.slice(1) : ["all"]);
+        const live = records.filter((record) => !record.result);
+        await manager.cancel(live);
+        ctx?.ui?.notify?.(live.length ? `Cancelled ${live.map((record) => record.id).join(", ")}.` : "No running subagents to cancel.");
+        return;
+      }
+      const records = manager.list(session);
+      if (records.length === 0) {
         ctx?.ui?.notify?.("No subagents have been spawned in this session yet.");
         return;
       }
-      const lines = entries.map((entry, index) => {
-        const minutes = Math.round(((entry.durationMs ?? Date.now() - entry.startedAt) / 60_000) * 10) / 10;
-        const task = entry.task.length > 60 ? `${entry.task.slice(0, 59)}…` : entry.task;
-        return `  ${index + 1}. [${entry.status}] ${entry.role} (${minutes} min) — ${task}`;
-      });
-      ctx?.ui?.notify?.(`Subagents of this session:\n${lines.join("\n")}`);
+      ctx?.ui?.notify?.(renderAgentStatus(records));
     },
   });
 }

package/assets/extensions/omnirush/collector.ts

@@ -57,6 +57,7 @@ import {
   type PiEntry,
 } from "./pi-engine";
 import { sharedRefresher } from "./refresh";
+import { AGENTS_HOOK, type AgentsHook } from "./agents-lib";
 
 /** info.agent of the root session's messages (a sub-agent's is its role). */
 export const ROOT_AGENT = "omnirush-cli";
@@ -403,6 +404,32 @@ export default function (pi: any) {
     return session;
   };
 
+  /**
+   * The sub-agent tree's messages since their checkpoints. Background
+   * sub-agents keep running past the turn that started them: each later
+   * settle (and the session's end) records what they did since.
+   */
+  const captureChildren = async (state: NonNullable<typeof session>, room: (bytes: number) => void): Promise<void> => {
+    const { id } = state;
+    try {
+      await captureChildSessions({
+        collector,
+        rootSessionId: id,
+        parentSessionId: id,
+        parentEntries: state.ctx?.sessionManager?.getBranch?.() ?? [],
+        depth: 1,
+        sessionDirs: sessionDirs(state.ctx),
+        checkpoints: await collector.childCheckpoints(id),
+        known: new Set(await collector.childSessionIds(id)),
+        visited: new Set([id]),
+        seenFiles: state.seenFiles,
+        beforeRecord: room,
+      });
+    } catch (error) {
+      collector.recordTrace(id, "session.children_failed", { error: error instanceof Error ? error.message : "unknown" });
+    }
+  };
+
   /**
    * Everything a settled run records, in the desktop observer's order:
    * messages, sub-agents, the idle event, the snapshot, the trace and the
@@ -444,23 +471,7 @@ export default function (pi: any) {
       }
       pending += bytes;
     };
-    try {
-      await captureChildSessions({
-        collector,
-        rootSessionId: id,
-        parentSessionId: id,
-        parentEntries: state.ctx?.sessionManager?.getBranch?.() ?? [],
-        depth: 1,
-        sessionDirs: sessionDirs(state.ctx),
-        checkpoints: await collector.childCheckpoints(id),
-        known: new Set(await collector.childSessionIds(id)),
-        visited: new Set([id]),
-        seenFiles: state.seenFiles,
-        beforeRecord: room,
-      });
-    } catch (error) {
-      collector.recordTrace(id, "session.children_failed", { error: error instanceof Error ? error.message : "unknown" });
-    }
+    await captureChildren(state, room);
     room(newest.bytes);
     collector.recordTrace(id, "session.idle", { status });
     // The turn snapshot runs first so the artifacts it discovers are part of
@@ -485,11 +496,34 @@ export default function (pi: any) {
    * settled too, so they reach the trace.
    */
   const settleRemaining = async (): Promise<void> => {
+    // Background sub-agents still running are stopped first (their session
+    // files are complete once they exited) and marked interrupted.
+    const hook = (globalThis as any)[AGENTS_HOOK] as AgentsHook | undefined;
+    const followed = session;
+    const interrupted = followed?.started && hook ? await hook.interruptAll(followed.id).catch(() => []) : [];
     await settleRunning("interrupted");
     const state = session;
     if (!state?.started) return;
+    for (const child of interrupted) {
+      collector.recordTrace(state.id, "session.child_interrupted", { child_session_id: child.sessionId, agent: child.role });
+    }
     const lastId = messagesOf(state).at(-1)?.info.id;
-    if (typeof lastId !== "string" || lastId === state.lastMessageId) return;
+    if (typeof lastId !== "string" || lastId === state.lastMessageId) {
+      // No new message of its own: what its sub-agents did since the last settle.
+      settling = settling.then(async () => {
+        let pending = 0;
+        await captureChildren(state, (bytes) => {
+          if (pending > 0 && pending + bytes > MAX_TURN_MESSAGE_BYTES) {
+            collector.flushTrace(state.id);
+            pending = 0;
+          }
+          pending += bytes;
+        });
+        collector.flushTrace(state.id);
+      }).catch(() => undefined);
+      await settling;
+      return;
+    }
     settling = settling.then(() => settle(state, "idle")).catch(() => undefined);
     await settling;
   };
@@ -591,6 +625,13 @@ export default function (pi: any) {
     archive.turnFollowed(state.id);
   });
 
+  // A run that no prompt started (a background sub-agent's results
+  // delivered as a message start one): it settles like any other.
+  pi.on("agent_start", (_event: any, ctx: any) => {
+    const state = follow(ctx, false);
+    if (state?.started) state.running = true;
+  });
+
   pi.on("tool_execution_start", (event: any) => {
     if (session && typeof event?.toolCallId === "string") session.toolStarts.set(event.toolCallId, Date.now());
   });