@cad0p/pi-subagents-tintinweb 0.14.2 → 0.22.0

package/src/agent-manager.ts

@@ -3,23 +3,46 @@
  *
  * Background agents are subject to a configurable concurrency limit (default: 4).
  * Excess agents are queued and auto-started as running agents complete.
- * Foreground agents bypass the queue (they block the parent anyway).
+ * Nested children are exempt from that pool — see `occupiesPoolSlot`.
+ * Resumes are exempt from the admission gate: they start immediately and are
+ * counted while they run, so a parent-visible continuation is never silently
+ * deferred behind fresh spawns — a burst of resumes can therefore exceed the
+ * limit by design.
  */
 
 import { randomUUID } from "node:crypto";
-import { statSync } from "node:fs";
+import { rmSync, statSync } from "node:fs";
 import { isAbsolute } from "node:path";
 import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getDefaultMaxTurns, normalizeMaxTurns, resumeAgent, runAgent, type ToolActivity } from "./agent-runner.js";
 import { getAgentConfig } from "./agent-types.js";
-import type { AgentInvocation, AgentRecord, IsolationMode, SubagentType, ThinkingLevel } from "./types.js";
-import { addUsage } from "./usage.js";
-import { cleanupWorktree, createWorktree, pruneWorktrees, } from "./worktree.js";
+import { describeModel } from "./model-resolver.js";
+import type { AgentConfig, AgentInvocation, AgentRecord, IsolationMode, SubagentType, ThinkingLevel } from "./types.js";
+import { addUsage, type LifetimeUsage } from "./usage.js";
+import { cleanupWorktree, createWorktree, isWorktreeIsolationEnabled, pruneWorktrees, } from "./worktree.js";
 
 export type OnAgentComplete = (record: AgentRecord) => void;
 export type OnAgentStart = (record: AgentRecord) => void;
+/**
+ * Fired by `steer()` once a message is delivered or queued. Every steer path
+ * that goes through the manager reports through it — the widget, the fleet
+ * list, the conversation viewer, and the cross-extension RPC. The steer tools
+ * (`steer_subagent` in index.ts and its nested twin) bypass this method because
+ * they await the session directly, so they emit on their own.
+ */
+export type OnAgentSteered = (record: AgentRecord, message: string) => void;
 export type OnAgentCompact = (record: AgentRecord, info: CompactionInfo) => void;
+/**
+ * Fired once per assistant `message_end`, for EVERY agent this manager owns —
+ * top-level and nested alike, spawns and resumes. The one place where each
+ * message is seen exactly once: `AgentRecord.lifetimeUsage` is deliberately
+ * double-booked into ancestors (see `nested-tools.ts`) so a hidden child's spend
+ * shows up on the record a human can see, which makes those records useless as
+ * a basis for anything that must not count a message twice — parent-session
+ * accounting above all.
+ */
+export type OnAgentUsage = (record: AgentRecord, usage: LifetimeUsage) => void;
 export type CompactionInfo = { reason: "manual" | "threshold" | "overflow"; tokensBefore: number };
 
 /** Default max concurrent background agents. */
@@ -47,6 +70,19 @@ function assertValidSpawnCwd(cwd: unknown): asserts cwd is string | undefined |
   }
 }
 
+/**
+ * Whether a record occupies one of the `maxConcurrent` background slots.
+ * Nested children don't: their parent already holds a slot, so counting (and
+ * therefore queueing) them would deadlock a parent that waits on its own child.
+ *
+ * Note this bounds nothing horizontally — the depth cap limits how DEEP nesting
+ * goes, not how WIDE. A parent's only limit on concurrent children is that each
+ * spawn costs it a turn, which is unbounded when max turns is unlimited.
+ */
+function occupiesPoolSlot(record: Pick<AgentRecord, "parentAgentId">): boolean {
+  return record.parentAgentId === undefined;
+}
+
 interface SpawnArgs {
   pi: ExtensionAPI;
   ctx: ExtensionContext;
@@ -55,14 +91,13 @@ interface SpawnArgs {
   options: SpawnOptions;
 }
 
-interface SpawnOptions {
+export interface SpawnOptions {
   description: string;
   model?: Model<any>;
   maxTurns?: number;
   isolated?: boolean;
   inheritContext?: boolean;
   thinkingLevel?: ThinkingLevel;
-  isBackground?: boolean;
   /**
    * Skip the maxConcurrent queue check for this spawn — start immediately even
    * if the configured concurrency limit would otherwise queue it. Used by the
@@ -82,7 +117,14 @@ interface SpawnOptions {
   cwd?: string;
   /** Resolved invocation snapshot captured for UI display. */
   invocation?: AgentInvocation;
-  /** Parent abort signal — when aborted, the subagent is also stopped. */
+  /**
+   * Parent abort signal — when aborted, the subagent is also stopped.
+   * Intended for in-process callers holding the manager directly (e.g. through
+   * the manager registry). Cross-extension RPC callers should pass serializable
+   * option values: `signal` is not part of the documented RPC surface and may
+   * not survive a serialized boundary. The `Agent` tool no longer forwards its
+   * tool-call signal to child runs.
+   */
   signal?: AbortSignal;
   /** Called on tool start/end with activity info (for streaming progress to UI). */
   onToolActivity?: (activity: ToolActivity) => void;
@@ -96,14 +138,39 @@ interface SpawnOptions {
   onAssistantUsage?: (usage: { input: number; output: number; cacheWrite: number }) => void;
   /** Called when the session successfully compacts. */
   onCompaction?: (info: CompactionInfo) => void;
+  /** Nesting depth: a top-level subagent is 1. */
+  depth?: number;
+  /** Parent agent ID for ownership-scoped nested controls. */
+  parentAgentId?: string;
+  /** Effective inherited nesting cap for this branch. */
+  maxSubagentDepth?: number;
+  /** Config-discovery root inherited by nested launches when it differs from the working directory. */
+  configCwd?: string;
+  /** Root session id, inherited by nested launches so transcripts stay grouped. */
+  rootSessionId?: string;
+  /**
+   * Config already resolved by the caller's own registry. A nested spawn reads
+   * its branch's config root, which may differ from the process-global registry
+   * `getAgentConfig` reads; without this the run would resolve the type again
+   * and could fall back to the unknown-type default.
+   */
+  agentConfig?: AgentConfig;
 }
 
+/** The five activity callbacks a resumed run forwards to its caller. */
+type ResumeCallbacks = Pick<
+  SpawnOptions,
+  "onToolActivity" | "onTextDelta" | "onTurnEnd" | "onAssistantUsage" | "onCompaction"
+>;
+
 export class AgentManager {
   private agents = new Map<string, AgentRecord>();
   private cleanupInterval: ReturnType<typeof setInterval>;
   private onComplete?: OnAgentComplete;
   private onStart?: OnAgentStart;
   private onCompact?: OnAgentCompact;
+  private onUsage?: OnAgentUsage;
+  private onSteered?: OnAgentSteered;
   private maxConcurrent: number;
   /** Base repos worktrees were created from — so dispose() can prune them all,
    *  not just the parent repo (caller-supplied cwd can target other repos). */
@@ -119,10 +186,14 @@ export class AgentManager {
     maxConcurrent = DEFAULT_MAX_CONCURRENT,
     onStart?: OnAgentStart,
     onCompact?: OnAgentCompact,
+    onUsage?: OnAgentUsage,
+    onSteered?: OnAgentSteered,
   ) {
     this.onComplete = onComplete;
     this.onStart = onStart;
     this.onCompact = onCompact;
+    this.onUsage = onUsage;
+    this.onSteered = onSteered;
     this.maxConcurrent = maxConcurrent;
     // Cleanup completed agents after 10 minutes (but keep sessions for resume)
     this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
@@ -162,7 +233,7 @@ export class AgentManager {
       id,
       type,
       description: options.description,
-      status: options.isBackground ? "queued" : "running",
+      status: "queued",
       toolUses: 0,
       startedAt: Date.now(),
       abortController,
@@ -172,30 +243,37 @@ export class AgentManager {
       turnCount: 1,
       // max_turns: 0 (unlimited) maps to undefined; the full fallback chain
       // is resolved here so every spawn path agrees. See AgentRecord.effectiveMaxTurns.
-      effectiveMaxTurns: normalizeMaxTurns(options.maxTurns ?? getAgentConfig(type)?.maxTurns ?? getDefaultMaxTurns()),
-      // Raw tri-state (not coerced to a boolean): true = background, false =
-      // foreground (has an inline tool-result surface), undefined = caller never
-      // declared it (e.g. a cross-extension RPC spawn). The widget's background-
-      // only filter excludes only explicit `false`, so undefined agents — which
-      // have no inline surface — stay visible instead of vanishing.
-      isBackground: options.isBackground,
+      effectiveMaxTurns: normalizeMaxTurns(
+        options.maxTurns ?? (options.agentConfig ?? getAgentConfig(type))?.maxTurns ?? getDefaultMaxTurns(),
+      ),
+      // Retention is read from the resolved agent config here, at spawn, so the
+      // removal path never re-resolves the registry. A resume reuses the record
+      // and therefore the decision its first run made.
+      persistSession: (options.agentConfig ?? getAgentConfig(type))?.persistSession === true,
       invocation: options.invocation,
+      depth: options.depth ?? 1,
+      parentAgentId: options.parentAgentId,
+      maxSubagentDepth: options.maxSubagentDepth,
+      rootSessionId: options.rootSessionId,
     };
     this.agents.set(id, record);
 
     const args: SpawnArgs = { pi, ctx, type, prompt, options };
 
-    if (options.isBackground && !options.bypassQueue && this.runningBackground >= this.maxConcurrent) {
+    if (occupiesPoolSlot(record) && !options.bypassQueue && this.runningBackground >= this.maxConcurrent) {
       // Queue it — will be started when a running agent completes
       this.queue.push({ id, args });
       return id;
     }
 
-    // startAgent can throw (e.g. strict worktree-isolation failure) — clean
-    // up the record so callers don't see an orphan in `listAgents()`.
+    // startAgent can throw (strict worktree-isolation failure, or a throwing
+    // `subagents:started` listener after the worktree was created) — reclaim
+    // any prologue worktree and drop the record so callers don't see an
+    // orphan in `listAgents()`.
     try {
       this.startAgent(id, record, args);
     } catch (err) {
+      this.reclaimWorktree(record, options.cwd ?? ctx.cwd);
       this.agents.delete(id);
       throw err;
     }
@@ -204,6 +282,14 @@ export class AgentManager {
 
   /** Actually start an agent (called immediately or from queue drain). */
   private startAgent(id: string, record: AgentRecord, { pi, ctx, type, prompt, options }: SpawnArgs) {
+    // An already-aborted parent signal never fires "abort" again — wiring it
+    // alone would start a run under a signal its owner considers dead. Settle
+    // through the stopped tail before anything is created: no cwd/worktree
+    // validation, no started event, no runner call, no slot, one report.
+    if (options.signal?.aborted) {
+      this.settleStoppedWithoutRun(record);
+      return;
+    }
     // Re-validate a caller-supplied cwd: queued spawns can start minutes after
     // spawn()'s check, and the directory may be gone by then (TOCTOU). Same
     // curated errors; drainQueue parks a throw on the record as an error.
@@ -216,9 +302,12 @@ export class AgentManager {
     // Worktree isolation: try to create a temporary git worktree. Strict —
     // fail loud if not possible (no silent fallback to main tree). Done
     // BEFORE state mutation so a throw doesn't leave the record half-running.
+    // The project switch is enforced here as well as at the tool boundary
+    // because cross-extension RPC forwards its options unvalidated — a schema
+    // that omits the field can't stop a caller that never saw the schema.
     let worktreeCwd: string | undefined;
     let worktreePromptInfo: { path: string; parentCwd: string } | undefined;
-    if (options.isolation === "worktree") {
+    if (options.isolation === "worktree" && isWorktreeIsolationEnabled()) {
       const wt = createWorktree(baseCwd, id);
       if (!wt) {
         throw new Error(
@@ -240,9 +329,16 @@ export class AgentManager {
 
     record.status = "running";
     record.startedAt = Date.now();
-    if (options.isBackground) this.runningBackground++;
     this.onStart?.(record);
 
+    // A started listener can stop the record synchronously (an extension
+    // reacting to `subagents:started`). Settle it through the stopped tail
+    // instead of starting — and counting — a run the user already stopped.
+    if (this.stoppedInStartPrologue(record)) {
+      this.settleStoppedWithoutRun(record, baseCwd);
+      return;
+    }
+
     // Wire parent abort signal to stop the subagent when the parent is interrupted
     let detachParentSignal: (() => void) | undefined;
     if (options.signal) {
@@ -252,6 +348,11 @@ export class AgentManager {
     }
     const detach = () => { detachParentSignal?.(); detachParentSignal = undefined; };
 
+    // Increment only after every synchronous throw site (cwd/worktree
+    // validation, onStart) — the runner calls are async, so any later throw
+    // arrives as a rejection through .catch/.finally and cannot leak the slot.
+    if (occupiesPoolSlot(record)) this.runningBackground++;
+    record.settled = false;
     const promise = runAgent(ctx, type, prompt, {
       pi,
       agentId: id,
@@ -260,6 +361,9 @@ export class AgentManager {
       isolated: options.isolated,
       inheritContext: options.inheritContext,
       thinkingLevel: options.thinkingLevel,
+      // Resolved by the caller's own registry (a nested spawn reads its branch's
+      // config root), so the run does not re-resolve it against the global one.
+      agentConfig: options.agentConfig,
       // Worktree wins for the working dir (the agent must run in the copy —
       // which, with a custom cwd, was created from that target). Config stays
       // with the parent project when a caller-supplied cwd is in play; it must
@@ -267,7 +371,7 @@ export class AgentManager {
       // (incl. relative extension paths and memory) inside the worktree copy.
       cwd: worktreeCwd ?? customCwd,
       worktree: worktreePromptInfo,
-      configCwd: customCwd !== undefined ? ctx.cwd : undefined,
+      configCwd: options.configCwd ?? (customCwd !== undefined ? ctx.cwd : undefined),
       signal: record.abortController!.signal,
       onToolActivity: (activity) => {
         if (activity.type === "end") record.toolUses++;
@@ -280,6 +384,7 @@ export class AgentManager {
       onTextDelta: options.onTextDelta,
       onAssistantUsage: (usage) => {
         addUsage(record.lifetimeUsage, usage);
+        this.onUsage?.(record, usage);
         options.onAssistantUsage?.(usage);
       },
       onCompaction: (info) => {
@@ -287,9 +392,38 @@ export class AgentManager {
         this.onCompact?.(record, info);
         options.onCompaction?.(info);
       },
+      nestedRuntime: {
+        manager: this,
+        parentAgentId: id,
+        depth: record.depth ?? 1,
+        maxSubagentDepth: record.maxSubagentDepth,
+      },
       onSessionCreated: (session) => {
         record.session = session;
         record.sessionId = session.sessionId;
+        // The model and thinking level are only knowable once pi has resolved
+        // its defaults and clamped the level to what the model supports. Writing
+        // them back here makes the record authoritative, so every surface reads
+        // one place instead of each re-deriving "session, else the request" for
+        // itself. An agent started outside the Agent tool (RPC, scheduler) has
+        // no invocation yet and gains one here.
+        if (session.model) {
+          record.invocation ??= {};
+          // Read the kept request first: a caller's level survives being clamped
+          // AND, one line later, being replaced by the effective one.
+          const requested = record.invocation.requestedThinking ?? record.invocation.thinking;
+          Object.assign(record.invocation, describeModel(session.model));
+          // Guarded: a session that reports no level keeps the request rather
+          // than losing it. Overwriting unconditionally would turn a stubbed or
+          // older session into a blank `thinking:` tag, which is worse than the
+          // stale-but-true value it replaced.
+          if (session.thinkingLevel) {
+            record.invocation.thinking = session.thinkingLevel;
+            if (requested && requested !== session.thinkingLevel) {
+              record.invocation.requestedThinking = requested;
+            }
+          }
+        }
         // Flush any steers that arrived before the session was ready
         if (record.pendingSteers?.length) {
           for (const msg of record.pendingSteers) {
@@ -321,12 +455,6 @@ export class AgentManager {
 
         detach();
 
-        // Final flush of streaming output file
-        if (record.outputCleanup) {
-          try { record.outputCleanup(); } catch { /* ignore */ }
-          record.outputCleanup = undefined;
-        }
-
         // Clean up worktree if used
         if (record.worktree) {
           const wtResult = cleanupWorktree(baseCwd, record.worktree, options.description);
@@ -340,16 +468,6 @@ export class AgentManager {
           }
         }
 
-        // Fire onComplete for foreground agents too — lifecycle symmetry.
-        // Mark resultConsumed so the callback skips notifications (result returned inline).
-        if (!options.isBackground) {
-          record.resultConsumed = true;
-          try { this.onComplete?.(record); } catch { /* ignore completion side-effect errors */ }
-        } else {
-          this.runningBackground--;
-          try { this.onComplete?.(record); } catch { /* ignore completion side-effect errors */ }
-          this.drainQueue();
-        }
         return responseText;
       })
       .catch((err) => {
@@ -362,12 +480,6 @@ export class AgentManager {
 
         detach();
 
-        // Final flush of streaming output file on error
-        if (record.outputCleanup) {
-          try { record.outputCleanup(); } catch { /* ignore */ }
-          record.outputCleanup = undefined;
-        }
-
         // Best-effort worktree cleanup on error
         if (record.worktree) {
           try {
@@ -376,25 +488,96 @@ export class AgentManager {
           } catch { /* ignore cleanup errors */ }
         }
 
-        // Fire onComplete for foreground agents too — lifecycle symmetry.
-        // Mark resultConsumed so the callback skips notifications (result returned inline).
-        if (!options.isBackground) {
-          record.resultConsumed = true;
-          this.onComplete?.(record);
-        } else {
-          this.runningBackground--;
-          this.onComplete?.(record);
-          this.drainQueue();
-        }
         return "";
-      });
+      })
+      .finally(() => this.afterRun(record));
 
     record.promise = promise;
+  }
+
+  /** Shared completion tail: release the slot, stop orphaned children, flush the transcript, notify, drain. */
+  private afterRun(record: AgentRecord): void {
+    if (occupiesPoolSlot(record)) this.runningBackground--;
+    // Children spawned by this run must not outlive it — they are hidden from
+    // every surface and reachable only through this agent, so an orphan would
+    // burn tokens unseen. Runs on every settle path, which is what also covers
+    // a resumed turn: grandchildren follow transitively, each through its own
+    // settle tail.
+    this.abortOwnedChildren(record.id);
+    try { record.outputCleanup?.(); } catch { /* ignore */ }
+    record.outputCleanup = undefined;
+    try { this.onComplete?.(record); } catch { /* ignore completion side-effect errors */ }
+    // A drain escape must not reject an already-fulfilled run promise or strand
+    // `settled` — a stuck `settled = false` would refuse every later resume and
+    // leave the queued records behind the freed slot unstarted.
+    try { this.drainQueue(); } catch { /* keep the completion tail failure-safe */ }
+    record.settled = true;
+  }
+
+  /**
+   * Settle a record whose run never started — stopped while queued, or stopped
+   * by a `subagents:started` listener before the runner was wired. Reports the
+   * stop through the completion surface exactly once and marks the record fully
+   * unwound. No counter change: a never-started record never held a slot.
+   *
+   * `baseCwd` is the repo a prologue-created worktree came from; omit it on
+   * paths where this run's prologue created none (a record stopped while
+   * queued, an already-aborted parent signal, or a resume stopped during its
+   * start prologue). A resumed record can still carry the prior run's worktree
+   * reference — a resume never creates one, and reclaiming that stale path
+   * would clobber the prior run's `worktreeResult`.
+   */
+  private settleStoppedWithoutRun(record: AgentRecord, baseCwd?: string): void {
+    record.status = "stopped";
+    record.completedAt ??= Date.now();
+    // No turn ever executed — zero the run-local counter so the completion
+    // report cannot claim the presumed first turn.
+    record.turnCount = 0;
+    // Reclaim a worktree created by the start prologue (a stop issued during
+    // the `subagents:started` emit): the run never made changes, so this
+    // removes the copy and its git registration outright. `baseCwd` is absent
+    // on the queued-abort, already-aborted-signal, and resume start-prologue
+    // paths, where this run's prologue created no worktree.
+    if (baseCwd) {
+      this.reclaimWorktree(record, baseCwd);
+    }
+    try { this.onComplete?.(record); } catch { /* ignore completion side-effect errors */ }
+    record.settled = true;
+  }
 
-    // Notify caller that spawn is complete (record is in the map, promise is set).
-    // Called synchronously — onSessionCreated fires asynchronously inside runAgent.
-    // Used by spawnAndWait to let the caller set up output files before streaming starts.
-    this.onSpawned?.(id);
+  /**
+   * Best-effort reclamation of a worktree the start prologue created when the
+   * run never executed: a throwing started listener on the spawn or queue
+   * path, or a stop issued during the `subagents:started` emit. Removes the
+   * copy and its git registration from `baseCwd`'s repo, records the cleanup
+   * outcome, and clears the record's reference so no later path retries it.
+   * Cleanup errors are ignored — the failure or stop that triggered the
+   * reclaim is the actionable signal.
+   */
+  private reclaimWorktree(record: AgentRecord, baseCwd: string): void {
+    if (!record.worktree) return;
+    try {
+      record.worktreeResult = cleanupWorktree(baseCwd, record.worktree, record.description);
+    } catch { /* ignore cleanup errors */ }
+    record.worktree = undefined;
+  }
+
+  /** True when a started listener stopped the record or aborted its controller
+   *  during the synchronous `onStart` emit. */
+  private stoppedInStartPrologue(record: AgentRecord): boolean {
+    return record.status === "stopped" || record.abortController?.signal.aborted === true;
+  }
+
+  /**
+   * Stop the nested children a settled parent owns. Nested records are hidden
+   * from the UI and only their owner can consume them, so a child outliving its
+   * parent would burn tokens unseen with no way to reach it. Grandchildren are
+   * covered transitively — each abort lands in that child's own settle path.
+   */
+  private abortOwnedChildren(parentId: string): void {
+    for (const [id, record] of this.agents) {
+      if (record.parentAgentId === parentId) this.abort(id);
+    }
   }
 
   /** Start queued agents up to the concurrency limit. */
@@ -402,99 +585,137 @@ export class AgentManager {
     while (this.queue.length > 0 && this.runningBackground < this.maxConcurrent) {
       const next = this.queue.shift()!;
       const record = this.agents.get(next.id);
-      if (!record || record.status !== "queued") continue;
+      if (record?.status !== "queued") continue;
       try {
         this.startAgent(next.id, record, next.args);
       } catch (err) {
-        // Late failure (e.g. strict worktree-isolation) — surface on the record
-        // so the user/agent can see it via /agents, then keep draining.
+        // Only pre-increment throws reach here (cwd re-validation, worktree
+        // creation, onStart) — the counter needs no rollback. Surface the failure
+        // on the record so the user/agent can see it via /agents, then keep draining.
         record.status = "error";
         record.error = err instanceof Error ? err.message : String(err);
         record.completedAt = Date.now();
-        this.onComplete?.(record);
+        // No turn ever executed — zero the run-local counter so the completion
+        // report cannot claim the presumed first turn.
+        record.turnCount = 0;
+        // A throwing onStart can follow worktree creation: reclaim the copy
+        // and its registration (best-effort, like the run handlers' cleanup).
+        this.reclaimWorktree(record, next.args.options.cwd ?? next.args.ctx.cwd);
+        try { this.onComplete?.(record); } catch { /* ignore completion side-effect errors */ }
       }
     }
   }
 
   /**
-   * Called synchronously right after spawn, before onSessionCreated fires.
-   * Lets the caller set up the output file path on the record.
-   * The record is guaranteed to be in this.agents at this point.
-   */
-  private onSpawned?: (id: string) => void;
-
-  /**
-   * Spawn an agent and wait for completion (foreground use).
-   * Foreground agents bypass the concurrency queue.
-   * Returns { id, record } so callers can access the agent ID.
+   * Kick off a resume of an existing agent session with a new prompt.
    *
-   * @param onSpawned - Called synchronously after spawn(), before onSessionCreated fires.
-   *   Use this to set record.outputFile so streamToOutputFile can pick it up.
-   */
-  async spawnAndWait(
-    pi: ExtensionAPI,
-    ctx: ExtensionContext,
-    type: SubagentType,
-    prompt: string,
-    options: Omit<SpawnOptions, "isBackground">,
-    onSpawned?: (id: string) => void,
-  ): Promise<{ id: string; record: AgentRecord }> {
-    // Temporarily register the onSpawned hook so startAgent can call it.
-    const prevOnSpawned = this.onSpawned;
-    this.onSpawned = onSpawned;
-    try {
-      const id = this.spawn(pi, ctx, type, prompt, { ...options, isBackground: false });
-      const record = this.agents.get(id)!;
-      await record.promise;
-      return { id, record };
-    } finally {
-      this.onSpawned = prevOnSpawned;
-    }
-  }
-
-  /**
-   * Resume an existing agent session with a new prompt.
+   * Returns the record synchronously; the run settles through `record.promise`
+   * and the shared completion tail. Returns `undefined` when the record is
+   * unknown, has no session, is already active or winding down, when the
+   * started listener throws, or when it stops the record during the
+   * `subagents:started` emit.
+   *
+   * Resumes bypass the maxConcurrent admission gate by design: a continuation
+   * of a parent-visible run must start immediately rather than queue behind
+   * fresh spawns. It still occupies a pool slot while running, so a burst of
+   * resumes can push the actual concurrency above the limit.
    */
-  async resume(
-    id: string,
-    prompt: string,
-    signal?: AbortSignal,
-  ): Promise<AgentRecord | undefined> {
+  resume(id: string, prompt: string, callbacks?: ResumeCallbacks): AgentRecord | undefined {
     const record = this.agents.get(id);
     if (!record?.session) return undefined;
+    // A record in the start prologue is already `running` while `settled` may
+    // still hold the prior run's `true`, so the running arm is load-bearing.
+    // A queued record has no session yet and is refused by the queued arm.
+    if (record.status === "running" || record.status === "queued" || record.settled === false) {
+      return undefined;
+    }
 
+    const prior = {
+      status: record.status,
+      startedAt: record.startedAt,
+      completedAt: record.completedAt,
+      result: record.result,
+      error: record.error,
+      resultConsumed: record.resultConsumed,
+      abortController: record.abortController,
+      turnCount: record.turnCount,
+      lastCheckpoint: record.lastCheckpoint,
+    };
     record.status = "running";
     record.startedAt = Date.now();
     record.completedAt = undefined;
     record.result = undefined;
     record.error = undefined;
-
+    record.resultConsumed = undefined; // a prior pull must not swallow the resume report
+    // Run-local, mirroring a fresh spawn's initial turn count.
+    record.turnCount = 1;
+    // Run-local too: the prior run's latest checkpoint must not surface as the
+    // resumed run's state. The .checkpoints.md history stays cumulative.
+    record.lastCheckpoint = undefined;
+    record.abortController = new AbortController();
     try {
-      const { text, failure } = await resumeAgent(record.session, prompt, {
-        onToolActivity: (activity) => {
-          if (activity.type === "end") record.toolUses++;
-        },
-        onAssistantUsage: (usage) => {
-          addUsage(record.lifetimeUsage, usage);
-        },
-        onCompaction: (info) => {
-          record.compactionCount++;
-          this.onCompact?.(record, info);
-        },
-        signal,
-      });
-      // Same contract as the spawn path (#144): a failed final turn is an
-      // error, not a completion — but the resumed text stays available.
-      record.status = failure ? "error" : "completed";
-      if (failure) record.error = failure;
-      record.result = text;
-      record.completedAt = Date.now();
-    } catch (err) {
-      record.status = "error";
-      record.error = err instanceof Error ? err.message : String(err);
-      record.completedAt = Date.now();
+      this.onStart?.(record);
+    } catch {
+      // A listener threw (stale extension context). Restore the pre-resume
+      // state and refuse: the tool reports failure and the counter is untouched.
+      Object.assign(record, prior);
+      return undefined;
     }
-
+    // A started listener can stop the record synchronously; settle it through
+    // the stopped tail instead of starting — and counting — a run that was
+    // already stopped.
+    if (this.stoppedInStartPrologue(record)) {
+      this.settleStoppedWithoutRun(record);
+      return undefined;
+    }
+    record.settled = false;
+    // Occupies a slot but is never gated by maxConcurrent — a burst of resumes
+    // can exceed the cap by design. They share the pool counter, so queued
+    // fresh spawns wait for these resumes to settle before drainQueue admits them.
+    // A nested child is not in the pool (`occupiesPoolSlot`), and afterRun only
+    // decrements for records that are: counting it here leaked a slot per nested
+    // resume until every top-level spawn queued forever.
+    if (occupiesPoolSlot(record)) this.runningBackground++;
+    const promise = resumeAgent(record.session, prompt, {
+      onToolActivity: (activity) => {
+        if (activity.type === "end") record.toolUses++;
+        callbacks?.onToolActivity?.(activity);
+      },
+      onTextDelta: callbacks?.onTextDelta,
+      onTurnEnd: (turnCount) => {
+        record.turnCount = turnCount;
+        callbacks?.onTurnEnd?.(turnCount);
+      },
+      onAssistantUsage: (usage) => {
+        addUsage(record.lifetimeUsage, usage);
+        this.onUsage?.(record, usage);
+        callbacks?.onAssistantUsage?.(usage);
+      },
+      onCompaction: (info) => {
+        record.compactionCount++;
+        this.onCompact?.(record, info);
+        callbacks?.onCompaction?.(info);
+      },
+      signal: record.abortController.signal,
+    })
+      .then(({ text, failure }) => {
+        // Stop wins; a stopped resume is never overwritten with completed.
+        if (record.status !== "stopped") {
+          record.status = failure ? "error" : "completed";
+          if (failure) record.error = failure;
+        }
+        record.result = text;
+        record.completedAt ??= Date.now();
+        return text;
+      })
+      .catch((err) => {
+        if (record.status !== "stopped") record.status = "error";
+        record.error = err instanceof Error ? err.message : String(err);
+        record.completedAt ??= Date.now();
+        return "";
+      })
+      .finally(() => this.afterRun(record));
+    record.promise = promise;
     return record;
   }
 
@@ -504,7 +725,10 @@ export class AgentManager {
    * current tool execution and appears as a user message. If the session isn't
    * ready yet, the message is queued on `pendingSteers` and flushed when the
    * session is created. Returns false if the agent can't accept steering
-   * (unknown id, or no longer running/queued).
+   * (unknown id, or no longer running/queued). Fires `onSteered` on either
+   * accepted path, so the viewers and the cross-extension RPC report the steer
+   * the same way without each emitting by hand. The steer tools bypass this
+   * method because they await delivery.
    */
   steer(id: string, message: string): boolean {
     const record = this.agents.get(id);
@@ -516,6 +740,7 @@ export class AgentManager {
       if (!record.pendingSteers) record.pendingSteers = [];
       record.pendingSteers.push(message);
     }
+    this.onSteered?.(record, message);
     return true;
   }
 
@@ -536,8 +761,7 @@ export class AgentManager {
     // Remove from queue if queued
     if (record.status === "queued") {
       this.queue = this.queue.filter(q => q.id !== id);
-      record.status = "stopped";
-      record.completedAt = Date.now();
+      this.settleStoppedWithoutRun(record);
       return true;
     }
 
@@ -548,17 +772,47 @@ export class AgentManager {
     return true;
   }
 
-  /** Dispose a record's session and remove it from the map. */
+  /**
+   * Dispose a record's session and remove it from the map.
+   *
+   * The record's removal is also the child session file's disposal point: the
+   * 10-minute eviction and `clearCompleted()` on session switch are the grace
+   * window in which a live record can still resume the agent, so nothing may
+   * delete the file earlier. A `persist_session` agent keeps its file
+   * indefinitely; every other settled agent's file goes here.
+   *
+   * A run still in flight keeps its file even at removal: deleting the file a
+   * live child is still appending to loses the transcript the crash-recovery
+   * case exists for. The callers that could reach one — eviction and the session
+   * switch — skip it for the same reason, so this is the second line of defence,
+   * not the only one.
+   *
+   * Best-effort: a missing file, a permission error or a Windows lock must not
+   * throw into the completion/eviction path.
+   */
   private removeRecord(id: string, record: AgentRecord): void {
+    // Read from the session, not a copy taken at creation: pi moves the file on
+    // `ctx.newSession()`/`fork()`, and deleting the path it started with would
+    // leak the one it actually wrote.
+    const sessionFile = record.session?.sessionManager.getSessionFile();
     record.session?.dispose?.();
     record.session = undefined;
     this.agents.delete(id);
+    // After dispose, so the file handle is closed — Windows will not unlink an
+    // open file.
+    if (record.settled === false || record.persistSession || !sessionFile) return;
+    try {
+      rmSync(sessionFile, { force: true });
+    } catch { /* retention is best-effort — never fail a turn over it */ }
   }
 
   private cleanup() {
     const cutoff = Date.now() - 10 * 60_000;
     for (const [id, record] of this.agents) {
       if (record.status === "running" || record.status === "queued") continue;
+      // Stopped but still unwinding: removing it would dispose a session a live
+      // run is still writing to, and the file has to outlive the run.
+      if (record.settled === false) continue;
       if ((record.completedAt ?? 0) >= cutoff) continue;
       this.removeRecord(id, record);
     }
@@ -573,6 +827,8 @@ export class AgentManager {
   clearCompleted(skipUnconsumed = false): void {
     for (const [id, record] of this.agents) {
       if (record.status === "running" || record.status === "queued") continue;
+      // See cleanup(): an unwinding run keeps its record until it settles.
+      if (record.settled === false) continue;
       if (skipUnconsumed && !record.resultConsumed) continue;
       this.removeRecord(id, record);
     }
@@ -592,8 +848,7 @@ export class AgentManager {
     for (const queued of this.queue) {
       const record = this.agents.get(queued.id);
       if (record) {
-        record.status = "stopped";
-        record.completedAt = Date.now();
+        this.settleStoppedWithoutRun(record);
         count++;
       }
     }
@@ -610,14 +865,21 @@ export class AgentManager {
     return count;
   }
 
-  /** Wait for all running and queued agents to complete (including queued ones). */
+  /**
+   * Wait for all running and queued agents to complete (including queued ones).
+   *
+   * A stopped run is still unwinding when its `settled` flag is `false`: it no
+   * longer counts as `running` but still holds its slot, so its promise is part
+   * of the pending set — the queued records behind it start only once it
+   * settles.
+   */
   async waitForAll(): Promise<void> {
     // Loop because drainQueue respects the concurrency limit — as running
     // agents finish they start queued ones, which need awaiting too.
     while (true) {
       this.drainQueue();
       const pending = [...this.agents.values()]
-        .filter(r => r.status === "running" || r.status === "queued")
+        .filter(r => r.status === "running" || r.status === "queued" || r.settled === false)
         .map(r => r.promise)
         .filter(Boolean);
       if (pending.length === 0) break;
@@ -629,10 +891,12 @@ export class AgentManager {
     clearInterval(this.cleanupInterval);
     // Clear queue
     this.queue = [];
-    for (const record of this.agents.values()) {
-      record.session?.dispose();
+    // An in-flight run keeps its session file for the crash-recovery follow-up;
+    // a settled one is deleted here, because the manager's map is discarded and
+    // nothing would ever revisit it.
+    for (const [id, record] of this.agents) {
+      this.removeRecord(id, record);
     }
-    this.agents.clear();
     // Prune any orphaned git worktrees (crash recovery)
     try { pruneWorktrees(process.cwd()); } catch { /* ignore */ }
     // Also prune repos that caller-supplied cwds created worktrees in — a clean