@esso0428/pi-subagents 0.17.16 → 0.17.18

package/src/agent-manager.ts

@@ -1,17 +1,9 @@
 /**
  * agent-manager.ts — Tracks agents, background execution, resume support.
  *
- * There are two independent concurrency pools, never one:
- *
- * - Background (`maxConcurrent`, default 10) bounds detached agents.
- * - Foreground (`maxConcurrentForeground`, default 0 = unlimited) bounds
- *   agents a caller is blocking on inline — `spawnAndWait`.
- *
- * Independent by design: a foreground agent blocks the parent anyway, so
- * charging it to the background pool would let a saturated pool starve the main
- * session of work it could have done itself. Excess agents in either pool are
- * queued and auto-started as slots free up. Nested children take no slot in
- * either — see `occupiesPoolSlot` / `occupiesForegroundSlot`.
+ * 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).
  */
 
 import { randomUUID } from "node:crypto";
@@ -19,73 +11,121 @@ import { 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 {
-  agentHistoryLocator,
-  createAgentHistoryPath,
-  readAgentHistory,
-  streamAgentHistory,
-  writeAgentHistoryInitialEntry,
-} from "./agent-history.js";
+import { readAgentHistory } from "./agent-history.js";
 import {
   type AgentRecoveryCheckpoint,
   type AgentRecoveryStatus,
   readAgentRecoveryCheckpoints,
+  removeAgentRecoveryCheckpoint,
   writeAgentRecoveryCheckpoint,
 } from "./agent-recovery.js";
 import { resumeAgent, runAgent, type ToolActivity } from "./agent-runner.js";
-import { assignHandle, handleBase } from "./mention.js";
-import { describeModel } from "./model-resolver.js";
-import { writeInitialEntry } from "./output-file.js";
-import type { AgentInvocation, AgentRecord, AgentTombstone, IsolationMode, MentionResolution, SubagentType, ThinkingLevel } from "./types.js";
-import { addUsage, type LifetimeUsage } from "./usage.js";
-import type { CompiledSchema } from "./workflow/json-schema.js";
-import { cleanupWorktree, createWorktree, isWorktreeIsolationEnabled, pruneWorktrees, } from "./worktree.js";
+import type { AgentInvocation, AgentRecord, IsolationMode, SubagentType, ThinkingLevel } from "./types.js";
+import { addUsage } from "./usage.js";
+import { cleanupWorktree, createWorktree, pruneWorktrees, } from "./worktree.js";
 
 export type OnAgentComplete = (record: AgentRecord) => void;
 export type OnAgentStart = (record: AgentRecord) => 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.
- *
- * Raised from 4 when top-level spawns started defaulting to background
- * (`backgroundByDefault`): foreground agents bypass this pool entirely, so
- * while foreground was the default a fan-out of six ran six. With background
- * as the default every top-level agent takes a slot, and a limit of 4 would
- * have silently queued the tail of exactly the parallel fan-outs the `Agent`
- * tool description tells the model to send.
- */
-const DEFAULT_MAX_CONCURRENT = 10;
+/** Default max concurrent background agents. */
+const DEFAULT_MAX_CONCURRENT = 4;
+const RESTORABLE_STATUSES = new Set(["completed", "steered", "stopped", "aborted", "error"] as const);
+const THINKING_LEVELS = new Set(["minimal", "low", "medium", "high", "xhigh", "max", "off"]);
 
-/**
- * Default max concurrent foreground (blocking) agents — `0` = unlimited, the
- * extension's existing convention for "no ceiling" (`defaultMaxTurns`).
- *
- * Off by default because nothing here ever bounded foreground work, and pi
- * dispatches a message's tool calls through `Promise.all`, so an unqualified
- * fan-out of blocking `Agent` calls has always run all at once. Users who want
- * it bounded — chiefly local models, where parallel agents thrash the prompt
- * cache (#253) — opt in; everyone else keeps today's behaviour exactly.
- */
-const DEFAULT_MAX_CONCURRENT_FOREGROUND = 0;
+type RestorableAgentStatus = "completed" | "steered" | "stopped" | "aborted" | "error";
 
-/**
- * How many evicted agents stay addressable by name. Only a bound on memory —
- * a session that spawns hundreds of agents shouldn't retain every one — and
- * far above the handful anyone keeps in their head.
- */
-const MAX_TOMBSTONES = 100;
+/** Narrow persisted strings before putting them into runtime/UI state. */
+function isSafePersistedString(value: unknown, maxLength: number): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= maxLength && !/[\0\r\n]/.test(value);
+}
+
+function isFiniteTimestamp(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) && value >= 0;
+}
+
+function isValidUsage(value: unknown): value is { input: number; output: number; cacheWrite: number } {
+  if (!value || typeof value !== "object") return false;
+  const usage = value as Record<string, unknown>;
+  return ["input", "output", "cacheWrite"].every((key) => {
+    const n = usage[key];
+    return typeof n === "number" && Number.isFinite(n) && n >= 0;
+  });
+}
+
+function isSafeTranscriptLocator(value: unknown): value is string {
+  return typeof value === "string"
+    && /^\.pi-subagents\/agent-transcripts\/[^/]+\.jsonl$/.test(value)
+    && !value.includes("..")
+    && !value.includes("\\")
+    && !value.includes("\0");
+}
+
+function isSafeInvocation(value: unknown): value is AgentInvocation {
+  if (!value || typeof value !== "object") return false;
+  const invocation = value as Record<string, unknown>;
+  for (const key of ["modelName", "effectiveModelName"]) {
+    if (invocation[key] !== undefined && !isSafePersistedString(invocation[key], 512)) return false;
+  }
+  for (const key of ["thinking", "effectiveThinking"]) {
+    if (invocation[key] !== undefined && (typeof invocation[key] !== "string" || !THINKING_LEVELS.has(invocation[key]))) return false;
+  }
+  if (invocation.maxTurns !== undefined && (!Number.isInteger(invocation.maxTurns) || (invocation.maxTurns as number) < 0)) return false;
+  for (const key of ["isolated", "inheritContext", "runInBackground"]) {
+    if (invocation[key] !== undefined && typeof invocation[key] !== "boolean") return false;
+  }
+  if (invocation.isolation !== undefined && invocation.isolation !== "worktree") return false;
+  return true;
+}
+
+function cloneInvocation(value: AgentInvocation | undefined): AgentInvocation | undefined {
+  return value ? {
+    modelName: value.modelName,
+    effectiveModelName: value.effectiveModelName,
+    thinking: value.thinking,
+    effectiveThinking: value.effectiveThinking,
+    maxTurns: value.maxTurns,
+    isolated: value.isolated,
+    inheritContext: value.inheritContext,
+    runInBackground: value.runInBackground,
+    isolation: value.isolation,
+  } : undefined;
+}
+
+/** Validate one persisted terminal record without constructing runtime handles. */
+export function isRestorableAgentRecord(value: unknown): value is {
+  id: string;
+  type: string;
+  description: string;
+  status: RestorableAgentStatus;
+  startedAt: number;
+  completedAt: number;
+  result?: string;
+  error?: string;
+  toolUses?: number;
+  lifetimeUsage?: { input: number; output: number; cacheWrite: number };
+  transcriptPath?: string;
+  invocation?: AgentInvocation;
+} {
+  if (!value || typeof value !== "object") return false;
+  const record = value as Record<string, unknown>;
+  if (!isSafePersistedString(record.id, 256)
+    || !isSafePersistedString(record.type, 256)
+    || !isSafePersistedString(record.description, 4096)
+    || typeof record.status !== "string"
+    || !RESTORABLE_STATUSES.has(record.status as RestorableAgentStatus)
+    || !isFiniteTimestamp(record.startedAt)
+    || !isFiniteTimestamp(record.completedAt)
+    || record.completedAt < record.startedAt) return false;
+  if (record.result !== undefined && !isSafePersistedString(record.result, 2_000_000)) return false;
+  if (record.error !== undefined && !isSafePersistedString(record.error, 64_000)) return false;
+  if (record.toolUses !== undefined && (!Number.isInteger(record.toolUses) || (record.toolUses as number) < 0)) return false;
+  if (record.lifetimeUsage !== undefined && !isValidUsage(record.lifetimeUsage)) return false;
+  if (record.transcriptPath !== undefined && !isSafeTranscriptLocator(record.transcriptPath)) return false;
+  if (record.invocation !== undefined && !isSafeInvocation(record.invocation)) return false;
+  return true;
+}
 
 /**
  * Validate a caller-supplied SpawnOptions.cwd. `undefined`/`null` mean "unset"
@@ -109,69 +149,6 @@ 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, "isBackground" | "parentAgentId" | "workflowId">,
-): boolean {
-  return !!record.isBackground && isTopLevelAgent(record);
-}
-
-/**
- * Whether a record is one of the session's own agents, rather than something
- * another agent or a workflow owns.
- *
- * The single definition behind every user-facing surface — the fleet list, the
- * widget, the `/agents` menus, `@handle` resolution, and the completion events
- * and session entries. An owned child reports through its owner, so surfacing
- * it separately would double-count the same work in the places a person reads.
- */
-export function isTopLevelAgent(
-  record: Pick<AgentRecord, "parentAgentId" | "workflowId">,
-): boolean {
-  return record.parentAgentId === undefined && record.workflowId === undefined;
-}
-
-/**
- * Whether a record occupies one of the `maxConcurrentForeground` slots.
- *
- * Keyed on `blocking` — a caller awaiting this record inline — rather than on
- * `isBackground === false`, because `spawn()` is also the funnel for DETACHED
- * starts (cross-extension RPC, `@handle` mentions, the registry) that may pass
- * `isBackground: false` and are documented to run immediately regardless. Those
- * block nobody, so bounding them buys nothing and would park a record with no
- * one waiting to release it.
- *
- * Nested children are excluded for the same reason as `occupiesPoolSlot`, and
- * more sharply: their parent is blocked *awaiting them*, so queueing a child
- * behind its own parent is a guaranteed deadlock rather than a possible one.
- * Enforced here rather than at the call site so no caller can reintroduce it.
- *
- * A workflow's children go out through `spawnAndWait` and so are `blocking`
- * too, and are excluded on the same `isTopLevelAgent` test as the background
- * pool: the run already caps how many of its agents run at once, and charging
- * them here as well would let one fan-out queue behind a limit meant for the
- * session's own work.
- *
- * Like the background pool this bounds width at the top level only — a parent's
- * own fan-out is limited by nothing but its turn budget.
- */
-function occupiesForegroundSlot(
-  record: Pick<AgentRecord, "blocking" | "parentAgentId" | "workflowId">,
-): boolean {
-  return !!record.blocking && isTopLevelAgent(record);
-}
-
-/** Which concurrency pool a spawn is charged to, if any. */
-type Pool = "background" | "foreground";
-
 interface SpawnArgs {
   pi: ExtensionAPI;
   ctx: ExtensionContext;
@@ -182,31 +159,6 @@ interface SpawnArgs {
 
 interface SpawnOptions {
   description: string;
-  /**
-   * Optional memorable name for this instance, becoming a second handle
-   * (`@auth-audit`) alongside the type-derived one. Slugged, not validated —
-   * anything unusable degrades via `handleBase` rather than failing the spawn.
-   */
-  name?: string;
-  /**
-   * Reopen this pi session file instead of starting a fresh conversation, so a
-   * mention of an evicted agent continues where it left off. The agent's
-   * definition is still resolved from its type, so the continuation runs under
-   * the type's CURRENT config.
-   */
-  resumeSessionFile?: string;
-  /**
-   * Take an evicted agent's names back verbatim instead of allocating fresh
-   * ones, so a resumed conversation keeps the handle the user just typed —
-   * `handleBase(type)` cannot reproduce a numbered `explore-2`. Safe without an
-   * `assignHandle` pass because tombstoned names are excluded from allocation
-   * (`takenHandles`), so nothing live can be holding them.
-   *
-   * Internal capability, like `resumeSessionFile`: a forged handle would
-   * duplicate a live agent's name and make `resolveMention` ambiguous, so
-   * `spawnTopLevel` strips it from anything a caller sends.
-   */
-  reclaim?: { handle: string; alias?: string };
   model?: Model<any>;
   maxTurns?: number;
   isolated?: boolean;
@@ -214,38 +166,11 @@ interface SpawnOptions {
   thinkingLevel?: ThinkingLevel;
   isBackground?: boolean;
   /**
-   * Skip whichever pool's queue check applies to this spawn — start immediately
-   * even if the configured concurrency limit would otherwise queue it. The slot
-   * is still COUNTED once the run starts, so a bypassing spawn transiently
-   * exceeds the limit rather than being invisible to it.
-   *
-   * Used by the scheduler, so a fired job can't be deferred past its trigger
-   * window, and by the `/agents` agent-file generator, which has no way to
-   * cancel a wait (see its call site).
+   * Skip the maxConcurrent queue check for this spawn — start immediately even
+   * if the configured concurrency limit would otherwise queue it. Used by the
+   * scheduler so a fired job can't be deferred past its trigger window.
    */
   bypassQueue?: boolean;
-  /**
-   * A caller is awaiting this record inline (`spawnAndWait`) — what
-   * `maxConcurrentForeground` bounds. Set only by `spawnAndWait`; stripped from
-   * caller-supplied options by `spawnTopLevel`, since a forged `blocking` would
-   * defer a detached start behind a queue its caller cannot see or release.
-   */
-  blocking?: boolean;
-  /**
-   * The workflow run this child belongs to, when a workflow spawned it.
-   *
-   * Ownership, not decoration. A workflow's children are the workflow's — they
-   * report through its card, its notification and its dialog, so they are
-   * filtered out of every top-level surface exactly as nested children are, and
-   * they take no `maxConcurrent` slot: the run has its own concurrency cap, and
-   * counting them twice would let one workflow starve the whole session.
-   */
-  workflowId?: string;
-  /**
-   * Make the child report through a `StructuredOutput` tool built from this
-   * compiled schema. Set only by the workflow host, for `agent({ schema })`.
-   */
-  structuredOutput?: CompiledSchema;
   /** Isolation mode — "worktree" creates a temp git worktree for the agent. */
   isolation?: IsolationMode;
   /**
@@ -257,44 +182,10 @@ interface SpawnOptions {
    * branch lands in that repo.
    */
   cwd?: string;
-  /**
-   * Last chance to look at an isolated agent's worktree, awaited immediately
-   * before it is committed to a branch and removed.
-   *
-   * Exists because that removal happens inside the settle path, before
-   * `spawnAndWait` resolves: by the time a caller has the finished record, the
-   * directory the child actually wrote in is gone. Anything that must inspect
-   * or verify that tree — a workflow `gate` is the motivating case — has to run
-   * here or it silently inspects the main tree instead.
-   *
-   * Fires only on the normal settle path, and only when a worktree was created.
-   * Not on the error path and not on the stop-during-copy guard: those are
-   * already failing, and delaying cleanup there would leak a copy for no gain.
-   * A rejection is swallowed — the hook can never keep the worktree alive.
-   */
-  onBeforeWorktreeCleanup?: (worktreePath: string) => Promise<void>;
   /** Resolved invocation snapshot captured for UI display. */
   invocation?: AgentInvocation;
-  /** Whether the optional `.output` transcript is enabled for this run. */
-  outputTranscript?: boolean;
   /** Parent abort signal — when aborted, the subagent is also stopped. */
   signal?: AbortSignal;
-  /**
-   * Called synchronously once the record is in the map and its promise is set,
-   * before `onSessionCreated` fires — where callers attach the output file.
-   *
-   * Carried on the options rather than parked on the manager for the duration
-   * of a spawn: with a foreground queue, `startAgent` can run at drain time,
-   * long after any such field would have been restored, and the callback would
-   * silently never fire (or fire into an unrelated caller's closure).
-   */
-  onSpawned?: (id: string) => void;
-  /**
-   * Called synchronously when the spawn is queued instead of started, with how
-   * many entries in its own pool are ahead of it. The foreground UI uses it to
-   * say so while it waits; nothing else needs it.
-   */
-  onQueued?: (id: string, ahead: number) => void;
   /** Called on tool start/end with activity info (for streaming progress to UI). */
   onToolActivity?: (activity: ToolActivity) => void;
   /** Called on streaming text deltas from the assistant response. */
@@ -307,142 +198,39 @@ interface SpawnOptions {
   onAssistantUsage?: (usage: { input: number; output: number; cacheWrite: number }) => void;
   /** Called when the session successfully compacts. */
   onCompaction?: (info: CompactionInfo) => void;
-  /** Nesting depth: top-level subagent = 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;
-}
-
-interface ResumeOptions {
-  /**
-   * Run the resumed turn detached in the background: return immediately with
-   * the record still "running" (or "queued" at the concurrency limit) and
-   * notify on completion via onComplete, exactly like a background spawn.
-   * Default (false/undefined) runs the resume inline and returns the settled
-   * record — the historical behavior.
-   */
-  isBackground?: boolean;
-  /** Called on tool start/end with activity info (for streaming progress to UI). */
-  onToolActivity?: (activity: ToolActivity) => void;
-  /** Called once per assistant message_end with that message's usage delta. */
-  onAssistantUsage?: (usage: { input: number; output: number; cacheWrite: number }) => void;
-  /** Called when the session successfully compacts. */
-  onCompaction?: (info: CompactionInfo) => void;
-  /**
-   * Background resume only: called synchronously when the run actually starts —
-   * immediately, or later from drainQueue. Callers wire per-run side effects
-   * (output-file streaming) here rather than at the call site, so a resume that
-   * is stopped while still queued never leaves a subscription behind: `abort()`
-   * drops a queued record without reaching `settle()`, which is what would have
-   * torn that subscription down.
-   */
-  onStarted?: () => void;
-}
-
-/** Best-effort ceiling on one child's shutdown handlers, so teardown can't strand a quit. */
-const CHILD_SHUTDOWN_TIMEOUT_MS = 3_000;
-
-/**
- * Close the extension lifecycle `runAgent` opened with `bindExtensions`, then dispose.
- *
- * `AgentSession.dispose()` only calls `ExtensionRunner.invalidate()` — pi emits the event
- * itself in `AgentSessionRuntime.dispose()` beforehand, and this is the one place that binds
- * extensions onto a session without going through that path. Without the emit, everything an
- * extension armed in `session_start` leaks once per spawn, and its next tick throws
- * `assertActive()` from a bare timer callback — an uncaughtException that kills pi (#242).
- */
-async function shutdownChildSession(session: AgentSession | undefined): Promise<void> {
-  try {
-    const runner = session?.extensionRunner;
-    // Optional all the way down: on a pi without the getter, or a stubbed session from a
-    // partial `onSessionCreated`, skip the emit — the same degrade as before this fix.
-    if (runner?.hasHandlers?.("session_shutdown")) {
-      // Raced, not awaited outright. `emit` runs every handler serially with no timeout of
-      // its own, and dispose() is reached from pi's own `session_shutdown` with the TUI
-      // already torn down — one hung handler would leave a dead terminal.
-      await Promise.race([
-        runner.emit({ type: "session_shutdown", reason: "quit" }),
-        new Promise<void>(resolve => setTimeout(resolve, CHILD_SHUTDOWN_TIMEOUT_MS).unref()),
-      ]);
-    }
-  } catch { /* a partial session must degrade, not take the teardown down with it */ }
-  // Always, even on timeout: disposal is what this function ultimately exists to do.
-  try { session?.dispose?.(); } catch { /* ignore */ }
+  /** Called synchronously after the record exists, before it is queued or started. */
+  onSpawned?: (id: string) => void;
 }
 
 export class AgentManager {
   private agents = new Map<string, AgentRecord>();
-  /** Lightweight terminal rows retained after runtime GC so durable history stays discoverable. */
-  private historyRecords = new Map<string, AgentRecord>();
   private cleanupInterval: ReturnType<typeof setInterval>;
   private onComplete?: OnAgentComplete;
   private onStart?: OnAgentStart;
   private onCompact?: OnAgentCompact;
-  private onUsage?: OnAgentUsage;
   private maxConcurrent: number;
-  private maxConcurrentForeground = DEFAULT_MAX_CONCURRENT_FOREGROUND;
   /** Base repos worktrees were created from — so dispose() can prune them all,
    *  not just the parent repo (caller-supplied cwd can target other repos). */
   private worktreeRepos = new Set<string>();
   /** Project cwd for each record's durable checkpoint. */
   private recoveryCwds = new Map<string, string>();
 
-  /**
-   * Startup phases, keyed by agent id. `spawn()` still returns synchronously,
-   * but an agent using worktree isolation is not running yet when it does —
-   * copying the repo is an awaited git call. This is what `awaitStartup` hands
-   * callers that must fail their tool call on a startup failure, and what
-   * `waitForAll` waits on while a record is "running" with no `promise` yet.
-   * Entries are dropped once the run is underway, and kept (rejected) after a
-   * startup failure so a late `awaitStartup` still sees it.
-   */
-  private startups = new Map<string, Promise<void>>();
-
-  /**
-   * Evicted agents that can still be reached by name, keyed by handle. Outlives
-   * the 10-minute record cleanup — that timer exists to bound memory, not to
-   * expire a conversation the user might still want — and is cleared alongside
-   * completed records on session start/switch.
-   */
-  private tombstones = new Map<string, AgentTombstone>();
-
-  /**
-   * Agents waiting to start, tagged with the pool they wait on. One queue for
-   * both pools: `drainQueue` picks the earliest entry whose own pool has room,
-   * so neither can head-of-line-block the other, and every removal path
-   * (`abort`, `abortAll`, `dispose`) stays a single filter.
-   *
-   * `release` wakes a caller blocked in `spawnAndWait`, and is fired once the
-   * entry's `start` has SETTLED rather than at drain time: startup is async
-   * now, so releasing earlier would wake the caller before `record.promise`
-   * exists and it would read a still-starting agent as one that never ran.
-   * Removing an entry from this array MUST release it — a queued record has no
-   * promise to await, and pi has no tool-execution timeout to bail the caller
-   * out.
-   */
-  private queue: { id: string; pool: Pool; start: () => Promise<void>; release: () => void }[] = [];
+  /** Queue of background agents waiting to start. */
+  private queue: { id: string; args: SpawnArgs }[] = [];
   /** Number of currently running background agents. */
   private runningBackground = 0;
-  /** Number of currently running foreground (blocking) agents. */
-  private runningForeground = 0;
+  /** Prevent late promise settlement from decrementing a replacement run. */
+  private runningBackgroundIds = new Set<string>();
 
   constructor(
     onComplete?: OnAgentComplete,
     maxConcurrent = DEFAULT_MAX_CONCURRENT,
     onStart?: OnAgentStart,
     onCompact?: OnAgentCompact,
-    onUsage?: OnAgentUsage,
   ) {
     this.onComplete = onComplete;
     this.onStart = onStart;
     this.onCompact = onCompact;
-    this.onUsage = onUsage;
     this.maxConcurrent = maxConcurrent;
     // Cleanup completed agents after 10 minutes (but keep sessions for resume)
     this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
@@ -460,51 +248,102 @@ export class AgentManager {
     return this.maxConcurrent;
   }
 
-  /** Update the max concurrent foreground (blocking) agents limit. 0 = unlimited. */
-  setMaxConcurrentForeground(n: number) {
-    // Floor 0, not 1: unlimited is a meaningful value here and the default.
-    this.maxConcurrentForeground = Math.max(0, n);
-    // Start queued agents if the new limit allows — including everything, when
-    // the limit is cleared back to unlimited mid-run.
-    this.drainQueue();
+  private finishBackground(id: string): void {
+    if (!this.runningBackgroundIds.delete(id)) return;
+    this.runningBackground = Math.max(0, this.runningBackground - 1);
   }
 
-  getMaxConcurrentForeground(): number {
-    return this.maxConcurrentForeground;
+  private checkpointStatus(record: AgentRecord): AgentRecoveryStatus {
+    return record.status;
   }
 
-  /**
-   * Which pool a spawn is charged to, or undefined for one that is charged to
-   * neither (nested children, detached non-background spawns).
-   *
-   * Nothing here queues when the limit is unset — `poolHasRoom` reports an
-   * unlimited pool as always having room, so that alone is what keeps the
-   * default path identical. The `> 0` guard is belt and braces on top: it also
-   * keeps the counter from churning and the settle path from calling a drain
-   * that would find nothing to do. Both are unobservable, which is why no test
-   * pins them; the observable half — that the default start stays synchronous —
-   * is pinned in `test/foreground-concurrency.test.ts`.
-   */
-  private poolFor(record: AgentRecord): Pool | undefined {
-    if (occupiesPoolSlot(record)) return "background";
-    if (this.maxConcurrentForeground > 0 && occupiesForegroundSlot(record)) return "foreground";
-    return undefined;
+  private makeCheckpoint(record: AgentRecord): AgentRecoveryCheckpoint {
+    const checkpoint: AgentRecoveryCheckpoint = {
+      version: 1,
+      id: record.id,
+      type: record.type,
+      description: record.description,
+      status: this.checkpointStatus(record),
+      startedAt: record.startedAt,
+      toolUses: record.toolUses,
+      lifetimeUsage: { ...record.lifetimeUsage },
+      compactionCount: record.compactionCount,
+      ...(record.completedAt !== undefined && { completedAt: record.completedAt }),
+      // A durable transcript is the source of truth for partial/full output.
+      // Avoid duplicating potentially sensitive or very large result text.
+      ...(!record.transcriptPath && record.result !== undefined && { result: record.result }),
+      ...(record.error !== undefined && { error: record.error }),
+      ...(record.transcriptPath !== undefined && { transcriptPath: record.transcriptPath }),
+      ...(record.invocation !== undefined && { invocation: cloneInvocation(record.invocation) }),
+    };
+    return checkpoint;
+  }
+
+  private checkpoint(record: AgentRecord): void {
+    const cwd = this.recoveryCwds.get(record.id);
+    if (!cwd) return;
+    writeAgentRecoveryCheckpoint(cwd, this.makeCheckpoint(record));
+  }
+
+  private flushOutput(record: AgentRecord): void {
+    if (!record.outputCleanup) return;
+    try { record.outputCleanup(); } catch { /* recovery must remain best effort */ }
+    record.outputCleanup = undefined;
+  }
+
+  /** Set the durable transcript locator and checkpoint the current state. */
+  setTranscript(id: string, historyFile: string, transcriptPath: string, cwd?: string): void {
+    const record = this.agents.get(id);
+    if (!record) return;
+    record.historyFile = historyFile;
+    record.transcriptPath = transcriptPath;
+    if (cwd) this.recoveryCwds.set(id, cwd);
+    this.checkpoint(record);
   }
 
-  private poolHasRoom(pool: Pool): boolean {
-    return pool === "background"
-      ? this.runningBackground < this.maxConcurrent
-      : this.maxConcurrentForeground === 0 || this.runningForeground < this.maxConcurrentForeground;
+  /** Checkpoint one record explicitly (used after transcript setup). */
+  checkpointRecord(id: string): void {
+    const record = this.agents.get(id);
+    if (record) this.checkpoint(record);
+  }
+
+  /**
+   * Reload durable records from this project's checkpoint directory. A
+   * running/queued checkpoint means the process was killed before it could
+   * write its stopped state; treat it as stopped and retain its transcript.
+   * SIGKILL cannot run a final flush/checkpoint, so this active snapshot is
+   * necessarily the last recoverable state.
+   */
+  restoreRecovered(cwd: string): void {
+    for (const checkpoint of readAgentRecoveryCheckpoints(cwd)) {
+      if (!checkpoint.transcriptPath || !readAgentHistory(cwd, checkpoint.transcriptPath)) continue;
+      const status: RestorableAgentStatus = checkpoint.status === "running" || checkpoint.status === "queued"
+        ? "stopped"
+        : checkpoint.status;
+      const completedAt = checkpoint.completedAt ?? Date.now();
+      const existing = this.agents.get(checkpoint.id);
+      if (existing) {
+        // Parent-branch records can still carry an unread in-memory result.
+        // Never replace that richer record with the checkpoint's transcript
+        // stub during the same session. Merge only durable locator metadata.
+        if (!existing.transcriptPath && checkpoint.transcriptPath) {
+          existing.transcriptPath = checkpoint.transcriptPath;
+        }
+        this.recoveryCwds.set(checkpoint.id, cwd);
+        continue;
+      }
+      this.agents.set(checkpoint.id, this.createRestoredRecord({
+        ...checkpoint,
+        status,
+        completedAt,
+      }));
+      this.recoveryCwds.set(checkpoint.id, cwd);
+    }
   }
 
   /**
    * Spawn an agent and return its ID immediately (for background use).
    * If the concurrency limit is reached, the agent is queued.
-   *
-   * The id comes back synchronously, but with `isolation: "worktree"` the agent
-   * is not running yet when it does — the repo copy is an awaited git call.
-   * Callers that must fail a tool call on a startup failure await
-   * `awaitStartup(id)`; everyone else sees it on the record (status "error").
    */
   spawn(
     pi: ExtensionAPI,
@@ -523,27 +362,12 @@ export class AgentManager {
     const record: AgentRecord = {
       id,
       type,
-      // Owned children — nested, or a workflow's — are filtered out of every
-      // top-level surface, so no handle: nothing can address them and they must
-      // not consume a name a top-level sibling could otherwise take.
-      handle: !isTopLevelAgent(options)
-        ? undefined
-        // A reclaimed handle is used as-is: it belongs to the conversation this
-        // spawn is reopening, and re-deriving it would lose the numbering.
-        : options.reclaim?.handle ?? assignHandle(handleBase(type), this.takenHandles()),
       description: options.description,
-      // Reclaimed here, or filled in below from `name` — in which case it must
-      // see the handle this record just took, since both come out of the same
-      // namespace.
-      alias: isTopLevelAgent(options) ? options.reclaim?.alias : undefined,
-      // Overwritten below when the spawn is actually queued; a foreground spawn
-      // that queues flips to "queued" there rather than being guessed at here,
-      // since the pool decision needs the finished record.
       status: options.isBackground ? "queued" : "running",
       toolUses: 0,
       startedAt: Date.now(),
       abortController,
-      lifetimeUsage: { input: 0, output: 0, cacheWrite: 0, cost: 0 },
+      lifetimeUsage: { input: 0, output: 0, cacheWrite: 0 },
       compactionCount: 0,
       // Raw tri-state (not coerced to a boolean): true = background, false =
       // foreground (has an inline tool-result surface), undefined = caller never
@@ -551,291 +375,46 @@ export class AgentManager {
       // only filter excludes only explicit `false`, so undefined agents — which
       // have no inline surface — stay visible instead of vanishing.
       isBackground: options.isBackground,
-      // Whether anyone is awaiting this agent is a property of the agent, not
-      // of the call that made it — and both settle paths need it long after
-      // `options` has stopped being the interesting object.
-      blocking: options.blocking,
       invocation: options.invocation,
-      depth: options.depth ?? 1,
-      parentAgentId: options.parentAgentId,
-      workflowId: options.workflowId,
-      maxSubagentDepth: options.maxSubagentDepth,
-      rootSessionId: options.rootSessionId,
     };
     this.agents.set(id, record);
     this.recoveryCwds.set(id, ctx.cwd);
-    // Durable history is manager-owned so every spawn path (Agent, scheduler,
-    // RPC, mention, and Workflow) has the same recoverable seam. Attach before
-    // any caller callback can start wiring output or observe the id.
-    this.attachDurableTranscript(record, id, prompt, ctx.cwd, options.outputTranscript !== false);
-    // After the insert, so `takenHandles()` already counts this record's own
-    // handle — a spawn named after its own type gets `explore-2`, not a
-    // duplicate `explore` that would make resolution ambiguous.
-    if (record.handle !== undefined && record.alias === undefined && options.name !== undefined) {
-      record.alias = assignHandle(handleBase(options.name), this.takenHandles());
+    // Give callers a chance to create the durable transcript before the first
+    // checkpoint. This closes the small spawn→attach window in which a queued
+    // or running agent could be left recoverable only as metadata.
+    try {
+      options.onSpawned?.(id);
+      this.checkpoint(record);
+    } catch (err) {
+      this.agents.delete(id);
+      this.recoveryCwds.delete(id);
+      removeAgentRecoveryCheckpoint(ctx.cwd, id);
+      throw err;
     }
 
     const args: SpawnArgs = { pi, ctx, type, prompt, options };
 
-    const pool = this.poolFor(record);
-    if (pool !== undefined && !options.bypassQueue && !this.poolHasRoom(pool)) {
-      // Queue it — started when a running agent in the same pool completes.
-      // Idempotent for background (already "queued"); the flip that matters is
-      // a blocking foreground spawn, optimistically marked "running" above.
-      record.status = "queued";
-      // A queued record never reaches startAgent's signal wiring, so arm the
-      // parent abort here or Esc could not release the position.
-      if (!this.armQueuedAbort(id, options.signal)) return id;
-      let release!: () => void;
-      record.startGate = new Promise<void>(resolve => { release = resolve; });
-      this.queue.push({
-        id,
-        pool,
-        start: () => this.launch(id, record, args, pool),
-        release: () => release(),
-      });
-      options.onQueued?.(id, this.queue.filter(e => e.pool === pool).length - 1);
+    if (options.isBackground && !options.bypassQueue && this.runningBackground >= this.maxConcurrent) {
+      // Queue it — will be started when a running agent completes
+      this.queue.push({ id, args });
       return id;
     }
 
-    this.launch(id, record, args, undefined);
-    return id;
-  }
-
-  /**
-   * Attach the project-local transcript once for a newly-created record.
-   * Repeated calls are harmless: deterministic paths and an existing file keep
-   * the initial user entry intact, which is important for resume and retries.
-   */
-  private attachDurableTranscript(record: AgentRecord, id: string, prompt: string, cwd: string, outputTranscript: boolean): void {
+    // startAgent can throw (e.g. strict worktree-isolation failure) — clean
+    // up the record so callers don't see an orphan in `listAgents()`.
     try {
-      const historyFile = createAgentHistoryPath(cwd, id);
-      writeAgentHistoryInitialEntry(historyFile, id, prompt, cwd);
-      if (outputTranscript) writeInitialEntry(historyFile, id, prompt, cwd);
-      record.historyFile = historyFile;
-      record.transcriptPath = agentHistoryLocator(cwd, historyFile);
+      this.startAgent(id, record, args);
     } catch (err) {
-      // A read-only project must not prevent the agent from running. The
-      // checkpoint still records the spawn metadata and the warning makes the
-      // loss of durable history visible to the host.
-      console.warn(`[pi-subagents] failed to attach durable transcript for ${id}: ${err instanceof Error ? err.message : String(err)}`);
+      this.agents.delete(id);
+      this.recoveryCwds.delete(id);
+      removeAgentRecoveryCheckpoint(ctx.cwd, id);
+      throw err;
     }
-    this.checkpoint(record);
-  }
-
-  private checkpointStatus(record: AgentRecord): AgentRecoveryStatus {
-    return record.status as AgentRecoveryStatus;
-  }
-
-  private makeCheckpoint(record: AgentRecord): AgentRecoveryCheckpoint {
-    return {
-      version: 1,
-      id: record.id,
-      type: record.type,
-      description: record.description,
-      status: this.checkpointStatus(record),
-      startedAt: record.startedAt,
-      ...(record.completedAt !== undefined && { completedAt: record.completedAt }),
-      ...(!record.transcriptPath && record.result !== undefined && { result: record.result }),
-      ...(record.error !== undefined && { error: record.error }),
-      toolUses: record.toolUses,
-      lifetimeUsage: { ...record.lifetimeUsage },
-      compactionCount: record.compactionCount,
-      ...(record.transcriptPath !== undefined && { transcriptPath: record.transcriptPath }),
-      ...(record.invocation !== undefined && { invocation: { ...record.invocation } }),
-    };
-  }
-
-  private checkpoint(record: AgentRecord): void {
-    const cwd = this.recoveryCwds.get(record.id);
-    if (cwd) writeAgentRecoveryCheckpoint(cwd, this.makeCheckpoint(record));
-  }
-
-  /** Checkpoint a record after external transcript wiring. */
-  checkpointRecord(id: string): void {
-    const record = this.agents.get(id);
-    if (record) this.checkpoint(record);
-  }
-
-  /** Register durable transcript metadata for compatibility with callers that
-   * attach a pre-existing history (for example a restored session). */
-  setTranscript(id: string, historyFile: string, transcriptPath: string, cwd?: string): void {
-    const record = this.agents.get(id);
-    if (!record) return;
-    record.historyFile = historyFile;
-    record.transcriptPath = transcriptPath;
-    if (cwd) this.recoveryCwds.set(id, cwd);
-    this.checkpoint(record);
-  }
-
-  /** Restore active checkpoints as stopped partial history after a restart. */
-  restoreRecovered(cwd: string): void {
-    for (const checkpoint of readAgentRecoveryCheckpoints(cwd)) {
-      // A session_start can fire again in the same process (resume/switch).
-      // Never replace the live in-memory record with its older checkpoint: the
-      // checkpoint may intentionally omit `result` once durable history exists.
-      if (this.agents.has(checkpoint.id)) continue;
-      if (!checkpoint.transcriptPath || !readAgentHistory(cwd, checkpoint.transcriptPath)) continue;
-      const status = checkpoint.status === "running" || checkpoint.status === "queued"
-        ? "stopped" as const : checkpoint.status;
-      const record: AgentRecord = {
-        id: checkpoint.id,
-        type: checkpoint.type,
-        description: checkpoint.description,
-        status,
-        result: checkpoint.result,
-        error: checkpoint.error,
-        toolUses: checkpoint.toolUses,
-        startedAt: checkpoint.startedAt,
-        completedAt: checkpoint.completedAt ?? Date.now(),
-        transcriptPath: checkpoint.transcriptPath,
-        historyFile: undefined,
-        invocation: checkpoint.invocation,
-        lifetimeUsage: { ...checkpoint.lifetimeUsage },
-        compactionCount: checkpoint.compactionCount,
-      };
-      this.agents.set(record.id, record);
-      this.recoveryCwds.set(record.id, cwd);
-    }
-  }
-
-  /**
-   * Restore terminal records from durable history without creating sessions.
-   * Invalid and live records are ignored so recovery cannot replace active work.
-   */
-  restoreCompleted(records: readonly Partial<AgentRecord>[]): void {
-    const terminal = new Set<AgentRecord["status"]>(["completed", "steered", "stopped", "aborted", "error"]);
-    const restoredIds = new Set<string>();
-    for (const candidate of records) {
-      const id = typeof candidate.id === "string" && candidate.id.length > 0 ? candidate.id : undefined;
-      const status = candidate.status;
-      if (!id || !status || !terminal.has(status)) continue;
-      if (this.agents.has(id) && !restoredIds.has(id)) continue;
-      this.historyRecords.delete(id);
-      const type = typeof candidate.type === "string" ? candidate.type : undefined;
-      const description = typeof candidate.description === "string" ? candidate.description : undefined;
-      const startedAt = candidate.startedAt;
-      if (!type || description === undefined || typeof startedAt !== "number" || !Number.isFinite(startedAt)) continue;
-      if (candidate.completedAt !== undefined && (typeof candidate.completedAt !== "number" || !Number.isFinite(candidate.completedAt))) continue;
-      if (candidate.transcriptPath !== undefined && (typeof candidate.transcriptPath !== "string" || candidate.transcriptPath.includes("..") || candidate.transcriptPath.startsWith("/"))) continue;
-      const restored: AgentRecord = {
-        ...candidate,
-        id,
-        type,
-        description,
-        status,
-        toolUses: typeof candidate.toolUses === "number" && Number.isFinite(candidate.toolUses) ? candidate.toolUses : 0,
-        startedAt,
-        completedAt: candidate.completedAt ?? Date.now(),
-        lifetimeUsage: candidate.lifetimeUsage ? { ...candidate.lifetimeUsage } : { input: 0, output: 0, cacheWrite: 0 },
-        compactionCount: typeof candidate.compactionCount === "number" && Number.isFinite(candidate.compactionCount) ? candidate.compactionCount : 0,
-        session: undefined,
-        abortController: undefined,
-        promise: undefined,
-        startGate: undefined,
-        outputCleanup: undefined,
-        historyCleanup: undefined,
-      };
-      this.agents.set(id, restored);
-      restoredIds.add(id);
-    }
-  }
-
-  /**
-   * Wire a parent abort signal for a record that is about to be QUEUED.
-   * `startAgent` does this for running agents, and a queued record never gets
-   * there, so without this Esc could not release a queue position.
-   *
-   * Returns false when the signal is ALREADY aborted, in which case the record
-   * is stopped here and must not be enqueued: `addEventListener` never fires on
-   * an aborted signal, so a `spawnAndWait` on it would wait forever — pi has no
-   * tool-execution timeout to bail it out.
-   *
-   * The listener is left in place when the agent starts. `startAgent` adds its
-   * own, so both fire on a later abort, but `abort()` on an already-stopped
-   * record is a no-op — so detaching would only be tidiness, and tidiness the
-   * `abortAll`/`dispose` paths could not offer anyway.
-   */
-  private armQueuedAbort(id: string, signal?: AbortSignal): boolean {
-    if (signal === undefined) return true;
-    if (signal.aborted) {
-      const record = this.agents.get(id);
-      if (record) {
-        record.status = "stopped";
-        record.completedAt = Date.now();
-        this.flushOutput(record);
-        this.checkpoint(record);
-      }
-      return false;
-    }
-    signal.addEventListener("abort", () => this.abort(id), { once: true });
-    return true;
-  }
-
-  /**
-   * Kick off an agent's startup and register it under `startups`. The returned
-   * promise never rejects — the failure is delivered through `awaitStartup`,
-   * and to the record.
-   *
-   * @param queuedPool - The pool this start was QUEUED on, or undefined for an
-   *   immediate start. A queue drain can be minutes after `spawn()` returned,
-   *   and nobody is awaiting `awaitStartup` by then, so a failure has to live
-   *   on the record as status "error" — what drainQueue did when the throw was
-   *   still synchronous. An immediate start instead drops the record, exactly
-   *   as the throw out of `spawn()` did: no orphan in `listAgents()`, and the
-   *   handle goes back.
-   */
-  private launch(id: string, record: AgentRecord, args: SpawnArgs, queuedPool: Pool | undefined): Promise<void> {
-    const startup = this.startAgent(id, record, args).then(
-      () => { this.startups.delete(id); },
-      (err) => {
-        this.startups.delete(id);
-        if (queuedPool !== undefined) {
-          // Mirrors settleRun: an inline caller gets this failure as a throw
-          // out of spawnAndWait, so an unconsumed record would ALSO nudge the
-          // session about it — the same failure reported twice.
-          if (queuedPool === "foreground") record.resultConsumed = true;
-          record.status = "error";
-          record.error = err instanceof Error ? err.message : String(err);
-          record.completedAt = Date.now();
-          this.flushOutput(record);
-          this.checkpoint(record);
-          this.onComplete?.(record);
-        } else {
-          this.agents.delete(id);
-        }
-        // The agent never kept its slot (startAgent gives it back on failure),
-        // so anything queued behind it can go now.
-        this.drainQueue();
-        throw err;
-      },
-    );
-    this.startups.set(id, startup);
-    // Nothing is obliged to await `startups` — swallow the rejection once here
-    // so an unawaited startup can't take the process down, and hand callers
-    // (drainQueue) that swallowed promise.
-    return startup.catch(() => {});
-  }
-
-  /**
-   * Resolves once the agent is actually running, and rejects with the startup
-   * failure (strict worktree isolation) that `spawn()` used to throw before the
-   * repo copy became async. Resolves immediately for an agent that is already
-   * running, still queued, or unknown — so callers can await it unconditionally.
-   *
-   * Call it in the same tick as the `spawn()` it belongs to: a failed startup
-   * takes its record (and this entry) with it, exactly as the throw did.
-   */
-  awaitStartup(id: string): Promise<void> {
-    return this.startups.get(id) ?? Promise.resolve();
+    return id;
   }
 
   /** Actually start an agent (called immediately or from queue drain). */
-  private async startAgent(
-    id: string,
-    record: AgentRecord,
-    { pi, ctx, type, prompt, options }: SpawnArgs,
-  ) {
+  private startAgent(id: string, record: AgentRecord, { pi, ctx, type, prompt, options }: SpawnArgs) {
     // 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.
@@ -845,43 +424,13 @@ export class AgentManager {
     const customCwd = options.cwd ?? undefined; // null (RPC "unset") → undefined
     const baseCwd = customCwd ?? ctx.cwd;
 
-    // Take the running state — and with it the concurrency slot — BEFORE the
-    // first await. Creating a worktree is an awaited git call, and drainQueue
-    // reads the pool counters synchronously in a loop: incrementing after the
-    // await would let it start every queued agent at once while the first is
-    // still copying its repo. Claiming "running" here also keeps abort() and
-    // abortAll() able to reach an agent whose worktree is still being created.
-    //
-    // The pool is resolved ONCE, here, and carried to `settleRun` below:
-    // `poolFor` reads `maxConcurrentForeground`, which the user can change from
-    // `/agents → Settings` mid-run, so recomputing it at settle time would
-    // decrement a pool this run never charged (counter underflow, limit
-    // silently lifted) or skip the decrement for one it did (leaked slot —
-    // every later blocking spawn queues forever). The two startup exits below
-    // never reach `settleRun`, so they hand the slot back themselves.
-    const pool = this.poolFor(record);
-    const releaseSlot = () => {
-      if (pool === "background") this.runningBackground--;
-      else if (pool === "foreground") this.runningForeground--;
-    };
-    record.status = "running";
-    record.startedAt = Date.now();
-    record.startGate = undefined;
-    if (pool === "background") this.runningBackground++;
-    else if (pool === "foreground") this.runningForeground++;
-    this.checkpoint(record);
-
     // Worktree isolation: try to create a temporary git worktree. Strict —
-    // fail loud if not possible (no silent fallback to main tree). Done BEFORE
-    // the run is kicked off so a failure doesn't leave a half-running agent.
-    // 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.
+    // 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.
     let worktreeCwd: string | undefined;
-    if (options.isolation === "worktree" && isWorktreeIsolationEnabled()) {
-      const wt = await createWorktree(pi, baseCwd, id);
+    if (options.isolation === "worktree") {
+      const wt = createWorktree(baseCwd, id);
       if (!wt) {
-        releaseSlot();
         throw new Error(
           'Cannot run with isolation: "worktree" — not a git repo, no commits yet, or `git worktree add` failed. ' +
           'Initialize git and commit at least once, or omit `isolation`.',
@@ -896,34 +445,23 @@ export class AgentManager {
       // subdirectory, silently dropping extensions/skills.
       worktreeCwd = customCwd !== undefined ? wt.workPath : wt.path;
       this.worktreeRepos.add(baseCwd);
-
-      // No longer "running" means a stop landed while the copy was being made
-      // (abort(), abortAll()) — a window that did not exist when creation was
-      // synchronous. The record is already terminal, so launching the run would
-      // burn tokens on work nobody is waiting for: discard the fresh (and by
-      // definition unchanged) worktree instead.
-      if (record.status !== "running") {
-        releaseSlot();
-        record.worktreeResult = await cleanupWorktree(pi, baseCwd, wt, options.description);
-        this.drainQueue();
-        return;
-      }
     }
 
+    record.status = "running";
+    record.startedAt = Date.now();
+    this.checkpoint(record);
+    if (options.isBackground) {
+      this.runningBackground++;
+      this.runningBackgroundIds.add(id);
+    }
     this.onStart?.(record);
 
     // Wire parent abort signal to stop the subagent when the parent is interrupted
     let detachParentSignal: (() => void) | undefined;
     if (options.signal) {
-      // A queued spawn can start minutes after the caller handed us its signal,
-      // by which time it may already be aborted — and `addEventListener` would
-      // never fire, leaving a child the parent can no longer reach.
-      if (options.signal.aborted) this.abort(id);
-      else {
-        const onParentAbort = () => this.abort(id);
-        options.signal.addEventListener("abort", onParentAbort, { once: true });
-        detachParentSignal = () => options.signal!.removeEventListener("abort", onParentAbort);
-      }
+      const onParentAbort = () => this.abort(id);
+      options.signal.addEventListener("abort", onParentAbort, { once: true });
+      detachParentSignal = () => options.signal!.removeEventListener("abort", onParentAbort);
     }
     const detach = () => { detachParentSignal?.(); detachParentSignal = undefined; };
 
@@ -935,20 +473,13 @@ export class AgentManager {
       isolated: options.isolated,
       inheritContext: options.inheritContext,
       thinkingLevel: options.thinkingLevel,
-      structuredOutput: options.structuredOutput,
-      resumeSessionFile: options.resumeSessionFile,
-      nested: options.parentAgentId !== undefined,
-      workflow: options.workflowId !== undefined,
       // 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
       // stay undefined otherwise so plain worktree runs keep resolving config
       // (incl. relative extension paths and memory) inside the worktree copy.
       cwd: worktreeCwd ?? customCwd,
-      // Set iff a worktree was created (see above) — names the directory the
-      // copy came from, so the prompt can tell the agent not to work there.
-      worktreeBase: worktreeCwd ? baseCwd : undefined,
-      configCwd: options.configCwd ?? (customCwd !== undefined ? ctx.cwd : undefined),
+      configCwd: customCwd !== undefined ? ctx.cwd : undefined,
       signal: record.abortController!.signal,
       onToolActivity: (activity) => {
         if (activity.type === "end") record.toolUses++;
@@ -958,7 +489,6 @@ export class AgentManager {
       onTextDelta: options.onTextDelta,
       onAssistantUsage: (usage) => {
         addUsage(record.lifetimeUsage, usage);
-        this.onUsage?.(record, usage);
         options.onAssistantUsage?.(usage);
       },
       onCompaction: (info) => {
@@ -966,48 +496,14 @@ 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;
-        // Capture now, while the session object exists: after eviction this
-        // path is the only thing that can reopen the conversation, and an
-        // in-memory session reports undefined, which correctly means
-        // "nothing to come back to".
-        // Optional chaining, not defensiveness for its own sake: this is the
-        // only field read off the session at creation, so an older pi or a
-        // stubbed session must degrade to "not resumable" rather than throw
-        // and take the whole spawn down with it.
-        record.sessionFile = session.sessionManager?.getSessionFile?.();
-        // Same reason, different field: 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.
-        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 for the reason above: a session that reports no level keeps
-          // the request rather than losing it. Overwriting unconditionally would
-          // turn an older or stubbed 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;
-            }
-          }
-        }
-        if (record.historyFile) {
-          record.historyCleanup = streamAgentHistory(session, record.historyFile, record.id, ctx.cwd);
-        }
+        const model = session.model;
+        record.invocation = {
+          ...(record.invocation ?? {}),
+          ...(model && { effectiveModelName: model.name ?? model.id }),
+          effectiveThinking: session.thinkingLevel,
+        };
         // Flush any steers that arrived before the session was ready
         if (record.pendingSteers?.length) {
           for (const msg of record.pendingSteers) {
@@ -1015,11 +511,14 @@ export class AgentManager {
           }
           record.pendingSteers = undefined;
         }
-        this.checkpoint(record);
         options.onSessionCreated?.(session);
+        this.checkpoint(record);
       },
     })
-      .then(async ({ responseText, session, aborted, steered, failure, structuredJson, structuredRetried }) => {
+      .then(({ responseText, session, aborted, steered, failure }) => {
+        // A disposed manager no longer owns this run. Avoid late callbacks
+        // mutating a dead session or emitting completion side effects.
+        if (this.agents.get(id) !== record) return responseText;
         // Don't overwrite status if externally stopped via abort()
         if (record.status !== "stopped") {
           // Precedence: a hard abort keeps "aborted"; then a failed final turn
@@ -1035,50 +534,47 @@ export class AgentManager {
           }
         }
         record.result = responseText;
-        // Kept beside `result`, never inside it: `result` is prose meant for a
-        // reader — it is previewed, transcribed, and appended to below — while
-        // this is a machine-readable payload one caller asked for by schema.
-        record.structuredJson = structuredJson;
-        record.structuredRetried = structuredRetried;
         record.session = session;
         record.completedAt ??= Date.now();
 
         detach();
 
-        // Flush both optional output and durable history before terminal state
-        // is checkpointed or completion is observable.
-        this.flushOutput(record);
+        // 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) {
-          // The one moment the child's tree still exists and the child is done
-          // writing to it. try/catch, not decoration: a hook that throws must
-          // not leave the worktree behind.
-          if (options.onBeforeWorktreeCleanup) {
-            try {
-              await options.onBeforeWorktreeCleanup(record.worktree.path);
-            } catch { /* ignore — never block cleanup */ }
-          }
-          const wtResult = await cleanupWorktree(pi, baseCwd, record.worktree, options.description);
+          const wtResult = cleanupWorktree(baseCwd, record.worktree, options.description);
           record.worktreeResult = wtResult;
           if (wtResult.hasChanges && wtResult.branch) {
             // With a caller-supplied cwd the branch lives in THAT repo, not the
             // parent session's — say so, or the orchestrator merges in the wrong repo.
             const repoNote = customCwd !== undefined ? ` in \`${baseCwd}\`` : "";
-            // Appended to the prose only. A structured child's caller parses
-            // `structuredJson`, which stays untouched — but `result` is also
-            // what a human reads, so the note still belongs on it.
             record.result = (record.result ?? "") +
               `\n\n---\nChanges saved to branch \`${wtResult.branch}\`${repoNote}. Merge with: \`git merge ${wtResult.branch}\`${customCwd !== undefined ? ` (run in \`${baseCwd}\`)` : ""}`;
           }
         }
+        this.checkpoint(record);
 
-        this.abortOwnedChildren(id);
-
-        this.settleRun(record, true, pool);
+        // 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.finishBackground(id);
+          try { this.onComplete?.(record); } catch { /* ignore completion side-effect errors */ }
+          this.drainQueue();
+        }
         return responseText;
       })
-      .catch(async (err) => {
+      .catch((err) => {
+        // A disposed manager no longer owns this run. Avoid late callbacks
+        // mutating a dead session or emitting completion side effects.
+        if (this.agents.get(id) !== record) return "";
         // Don't overwrite status if externally stopped via abort()
         if (record.status !== "stopped") {
           record.status = "error";
@@ -1088,151 +584,64 @@ export class AgentManager {
 
         detach();
 
-        // Preserve partial assistant/tool history before recording the error.
-        this.flushOutput(record);
+        // 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 {
-            const wtResult = await cleanupWorktree(pi, baseCwd, record.worktree, options.description);
+            const wtResult = cleanupWorktree(baseCwd, record.worktree, options.description);
             record.worktreeResult = wtResult;
           } catch { /* ignore cleanup errors */ }
         }
+        this.checkpoint(record);
 
-        this.abortOwnedChildren(id);
-
-        this.settleRun(record, false, pool);
+        // 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.finishBackground(id);
+          this.onComplete?.(record);
+          this.drainQueue();
+        }
         return "";
       });
 
     record.promise = promise;
-
-    // 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. Read off the options, so a spawn that started from a queue drain
-    // still reaches the caller that queued it.
-    options.onSpawned?.(id);
   }
 
-  /**
-   * The shared tail of both settle paths: release whatever pool slot the run
-   * held, notify, and let the queue drain into the freed slot.
-   *
-   * The decrement lives HERE and nowhere else. `abort()` on a running record
-   * only fires its controller and leaves the run to settle normally, so
-   * decrementing there too would double-free — permanently lifting the limit.
-   *
-   * Foreground agents fire `onComplete` for lifecycle symmetry, with
-   * `resultConsumed` set so the callback skips notifications the inline result
-   * already delivered.
-   *
-   * @param guardCallback swallow a throwing `onComplete` (the success path does;
-   *   the error path historically did not, and keeps not doing so).
-   * @param pool the pool this run was CHARGED TO at start time — passed in, not
-   *   recomputed, so a mid-run change to `maxConcurrentForeground` can't make
-   *   the release disagree with the acquire.
-   */
-  private settleRun(record: AgentRecord, guardCallback: boolean, pool: Pool | undefined): void {
-    // Terminal state is not durable until the stream has flushed. The
-    // checkpoint deliberately follows this call so stop/error/partial runs can
-    // be reopened after the live session is released.
-    this.flushOutput(record);
-    this.checkpoint(record);
-    if (!record.isBackground) record.resultConsumed = true;
-    if (pool === "background") this.runningBackground--;
-    else if (pool === "foreground") this.runningForeground--;
-
-    if (guardCallback) {
-      try { this.onComplete?.(record); } catch { /* ignore completion side-effect errors */ }
-    } else {
-      this.onComplete?.(record);
-    }
-
-    // The isBackground half reproduces the pre-pool condition exactly — a
-    // background settle has always drained, even for a nested child that held
-    // no slot — so that path is unchanged whether or not the foreground pool is
-    // on. The `pool` half only adds the drain a freed FOREGROUND slot needs.
-    // A drain with nothing freed is a no-op anyway, but "no-op" is a claim
-    // about reachability, and matching the old condition needs no such claim.
-    if (record.isBackground || pool !== undefined) this.drainQueue();
-  }
-
-  private flushOutput(record: AgentRecord): void {
-    if (record.outputCleanup) {
-      try { record.outputCleanup(); } catch { /* best effort */ }
-      record.outputCleanup = undefined;
-    }
-    if (record.historyCleanup) {
-      try { record.historyCleanup(); } catch { /* best effort */ }
-      record.historyCleanup = undefined;
-    }
-  }
-
-  /**
-   * 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 each pool's concurrency limit.
-   *
-   * `findIndex` on the entry's OWN pool rather than `shift`: with one queue
-   * serving two independent limits, a saturated foreground pool at the head
-   * would otherwise stall every background agent behind it. Taking the earliest
-   * eligible entry keeps FIFO within each pool, which is what callers see.
-   */
+  /** Start queued agents up to the concurrency limit. */
   private drainQueue() {
-    for (;;) {
-      const i = this.queue.findIndex(e => this.poolHasRoom(e.pool));
-      if (i === -1) return;
-      const [next] = this.queue.splice(i, 1);
+    while (this.queue.length > 0 && this.runningBackground < this.maxConcurrent) {
+      const next = this.queue.shift()!;
       const record = this.agents.get(next.id);
-      // Stale entries (aborted while queued) are not started — but are still
-      // released, since nothing else will.
-      if (!record || record.status !== "queued") { next.release(); continue; }
-      // Detached, and never rejects: a late failure (e.g. strict worktree
-      // isolation) lands on the record inside `launch`, exactly as the
-      // synchronous throw did here before, and draining continues either way.
-      //
-      // The release waits for that startup to SETTLE rather than firing here.
-      // Startup is async now, so a release at drain time would wake a blocked
-      // `spawnAndWait` while `record.promise` was still undefined, and it would
-      // read a perfectly healthy agent as one that never ran.
-      void next.start().then(() => next.release(), () => next.release());
-    }
-  }
-
-  /**
-   * Remove queued entries and wake anyone blocked on them. The single point
-   * that enforces "leaving the queue releases the waiter" — a missed release is
-   * an unbounded hang, not a failed call.
-   */
-  private dequeue(pred: (entry: { id: string; pool: Pool }) => boolean): void {
-    const kept: typeof this.queue = [];
-    for (const entry of this.queue) {
-      if (pred(entry)) entry.release();
-      else kept.push(entry);
+      if (!record || 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.
+        record.status = "error";
+        record.error = err instanceof Error ? err.message : String(err);
+        record.completedAt = Date.now();
+        this.checkpoint(record);
+        this.onComplete?.(record);
+      }
     }
-    this.queue = kept;
   }
 
   /**
    * Spawn an agent and wait for completion (foreground use).
-   * Charged to the foreground pool (`maxConcurrentForeground`), which is
-   * unlimited by default; never to the background one.
+   * Foreground agents bypass the concurrency queue.
    * Returns { id, record } so callers can access the agent ID.
    *
-   * @param onSpawned - Called synchronously once the run is kicked off, before
-   *   onSessionCreated fires. Use this to set record.outputFile so
-   *   streamToOutputFile can pick it up.
+   * @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,
@@ -1242,46 +651,13 @@ export class AgentManager {
     options: Omit<SpawnOptions, "isBackground">,
     onSpawned?: (id: string) => void,
   ): Promise<{ id: string; record: AgentRecord }> {
-    // `blocking` is what maxConcurrentForeground bounds, and this is its only
-    // source. onSpawned rides on the options rather than on a field of this
-    // manager: a queued spawn starts at drain time, long after any install/
-    // restore pair around this call would have put the field back — and it now
-    // fires after an await (worktree creation) even on the immediate path.
     const id = this.spawn(pi, ctx, type, prompt, {
       ...options,
       isBackground: false,
-      blocking: true,
       onSpawned,
     });
     const record = this.agents.get(id)!;
-
-    // Queued: nothing to await yet — the promise appears when the drain starts
-    // it. The gate resolves (never rejects) on every path out of the queue,
-    // start and abort alike, so a rejection can never escape into the caller's
-    // tool `execute` and take down pi's whole Promise.all tool batch.
-    if (record.status === "queued") await record.startGate;
-
-    // The run promise only exists once startup is past its awaited repo copy —
-    // without this the call would return before the agent had started at all.
-    // A startup failure (strict worktree isolation) rejects here, which is what
-    // the immediate path owes its caller: pi only marks a tool result failed
-    // when `execute` throws. A queued spawn's failure landed on the record
-    // instead (nobody was awaiting `startups` at drain time) and is rethrown
-    // below, so the contract is the same either way.
-    await this.awaitStartup(id);
-
-    // undefined when it was aborted while queued, or stopped mid-copy, and so
-    // never ran — the record is already terminal with a completedAt, which is
-    // what the caller renders.
-    if (record.promise) await record.promise;
-
-    // A record that ended "error" without ever getting a promise never ran: the
-    // same startup failure spawn() rethrows on the immediate path (#179). Keep
-    // one contract rather than letting queue pressure decide whether a strict
-    // worktree failure throws or returns as a result.
-    if (record.promise === undefined && record.status === "error") {
-      throw new Error(record.error ?? "Agent failed to start");
-    }
+    await record.promise;
     return { id, record };
   }
 
@@ -1292,86 +668,34 @@ export class AgentManager {
     id: string,
     prompt: string,
     signal?: AbortSignal,
-    options?: ResumeOptions,
   ): Promise<AgentRecord | undefined> {
     const record = this.agents.get(id);
     if (!record?.session) return undefined;
 
-    // Background resume: settle asynchronously and notify on completion exactly
-    // like a background spawn, returning immediately with the record still
-    // "running" — or "queued" when at the concurrency limit. Previously
-    // run_in_background was ignored on resume (the Agent tool's resume branch
-    // returned before its background branch, and resume() only ever awaited
-    // inline), so a resumed agent always blocked the caller until it finished.
-    if (options?.isBackground) {
-      // Never re-enter a run that is still in flight. Detaching means the caller
-      // gets control back while the record stays "running", so nothing stops the
-      // model from resuming the same agent again. Starting a second run would
-      // overwrite record.abortController — orphaning the live run beyond the
-      // reach of `/agents` stop and abortAll() — double-count the pool slot, and
-      // then reject from session.prompt() with "Agent is already processing",
-      // whose settle path would abort the LIVE run's children and report a
-      // failure for a run that is still going. Refuse instead, leaving the
-      // record untouched; the caller decides whether to wait or steer.
-      if (record.status === "running" || record.status === "queued") return undefined;
-
-      record.isBackground = true;
-      record.resultConsumed = false;
-      record.result = undefined;
-      record.error = undefined;
-      record.completedAt = undefined;
-      record.status = "queued";
-
-      const start = () => this.startResume(id, record, prompt, signal, options);
-      if (occupiesPoolSlot(record) && !this.poolHasRoom("background")) {
-        // At the concurrency limit — queue it, drains when a slot frees. A
-        // detached resume has no inline caller, hence nothing to release. The
-        // queue is shared with spawns, whose startup is async, so entries are
-        // promise-shaped even though a resume starts synchronously; failures
-        // land on the record here, since drainQueue no longer catches.
-        this.queue.push({
-          id,
-          pool: "background",
-          start: async () => {
-            try {
-              start();
-            } catch (err) {
-              record.status = "error";
-              record.error = err instanceof Error ? err.message : String(err);
-              record.completedAt = Date.now();
-              this.onComplete?.(record);
-            }
-          },
-          release: () => {},
-        });
-      } else {
-        start();
-      }
-      return record;
-    }
-
-    // Foreground resume: run inline and return the settled record.
     record.status = "running";
     record.startedAt = Date.now();
     record.completedAt = undefined;
     record.result = undefined;
     record.error = undefined;
+    const resumedModel = record.session.model;
+    record.invocation = {
+      ...(record.invocation ?? {}),
+      ...(resumedModel && { effectiveModelName: resumedModel.name ?? resumedModel.id }),
+      effectiveThinking: record.session.thinkingLevel,
+    };
+    this.checkpoint(record);
 
     try {
       const { text, failure } = await resumeAgent(record.session, prompt, {
         onToolActivity: (activity) => {
           if (activity.type === "end") record.toolUses++;
-          options?.onToolActivity?.(activity);
         },
         onAssistantUsage: (usage) => {
           addUsage(record.lifetimeUsage, usage);
-          this.onUsage?.(record, usage);
-          options?.onAssistantUsage?.(usage);
         },
         onCompaction: (info) => {
           record.compactionCount++;
           this.onCompact?.(record, info);
-          options?.onCompaction?.(info);
         },
         signal,
       });
@@ -1381,125 +705,17 @@ export class AgentManager {
       if (failure) record.error = failure;
       record.result = text;
       record.completedAt = Date.now();
+      this.checkpoint(record);
     } catch (err) {
       record.status = "error";
       record.error = err instanceof Error ? err.message : String(err);
       record.completedAt = Date.now();
+      this.checkpoint(record);
     }
 
-    // Same contract as the spawn settle paths: children spawned during the
-    // resumed turn must not outlive it — nothing else can see or reach them.
-    this.abortOwnedChildren(id);
-
     return record;
   }
 
-  /**
-   * Start a background resume run: detached, settling and notifying like
-   * startAgent's background path. Invoked immediately, or from drainQueue when
-   * a concurrency slot frees. The session already exists (resume reuses it), so
-   * there is no onSessionCreated to hang per-run wiring off — callers use
-   * `options.onStarted`, which fires on both the immediate and the drained path.
-   */
-  private startResume(
-    id: string,
-    record: AgentRecord,
-    prompt: string,
-    parentSignal: AbortSignal | undefined,
-    options: ResumeOptions,
-  ) {
-    if (!record.session) return;
-
-    record.status = "running";
-    record.startedAt = Date.now();
-    if (occupiesPoolSlot(record)) this.runningBackground++;
-    this.onStart?.(record);
-
-    // Fresh abort controller so /agents stop and steering target THIS run rather
-    // than the previous one's settled controller.
-    const abortController = new AbortController();
-    record.abortController = abortController;
-    // Optional, and NOT what the Agent tool passes for a detached resume: a
-    // parent signal aborts on the parent's own interrupt (user Esc), which is
-    // right for a foreground run whose result the caller is awaiting, and wrong
-    // for a detached one — background spawns omit it for exactly this reason.
-    let detachParentSignal: (() => void) | undefined;
-    if (parentSignal) {
-      const onParentAbort = () => this.abort(id);
-      parentSignal.addEventListener("abort", onParentAbort, { once: true });
-      detachParentSignal = () => parentSignal.removeEventListener("abort", onParentAbort);
-    }
-
-    // Per-run durable history starts at the existing session tail. The prompt
-    // and all messages produced by this resumed run are then flushed by the
-    // same manager-owned seam as a fresh spawn.
-    if (record.historyFile) {
-      const cwd = this.recoveryCwds.get(id);
-      if (cwd) {
-        const startIndex = Array.isArray(record.session.messages) ? record.session.messages.length : 0;
-        record.historyCleanup = streamAgentHistory(record.session, record.historyFile, id, cwd, startIndex);
-      }
-    }
-    // Per-run side effects (optional `.output` streaming) — see ResumeOptions.onStarted.
-    // After the record is in its running shape, before the run is kicked off.
-    try { options.onStarted?.(); } catch { /* ignore caller wiring errors */ }
-
-    const settle = () => {
-      detachParentSignal?.();
-      detachParentSignal = undefined;
-      // Final flush of streaming files. The durable history stream is owned by
-      // the manager; the optional `.output` stream is caller-wired.
-      this.flushOutput(record);
-      // Children spawned during the resumed turn must not outlive it.
-      this.abortOwnedChildren(id);
-      if (occupiesPoolSlot(record)) this.runningBackground--;
-      try { this.onComplete?.(record); } catch { /* ignore completion side-effect errors */ }
-      this.drainQueue();
-    };
-
-    const promise = resumeAgent(record.session, prompt, {
-      onToolActivity: (activity) => {
-        if (activity.type === "end") record.toolUses++;
-        options.onToolActivity?.(activity);
-      },
-      onAssistantUsage: (usage) => {
-        addUsage(record.lifetimeUsage, usage);
-        this.onUsage?.(record, usage);
-        options.onAssistantUsage?.(usage);
-      },
-      onCompaction: (info) => {
-        record.compactionCount++;
-        this.onCompact?.(record, info);
-        options.onCompaction?.(info);
-      },
-      signal: abortController.signal,
-    })
-      .then(({ text, failure }) => {
-        // Don't overwrite status if externally stopped via abort().
-        if (record.status !== "stopped") {
-          // 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();
-        settle();
-        return text;
-      })
-      .catch((err) => {
-        if (record.status !== "stopped") {
-          record.status = "error";
-          record.error = err instanceof Error ? err.message : String(err);
-        }
-        record.completedAt ??= Date.now();
-        settle();
-        return "";
-      });
-
-    record.promise = promise;
-  }
-
   /**
    * Send a steering message to an agent from the UI (mirrors the steer_subagent
    * tool). A live session delivers it now — it interrupts the agent after its
@@ -1525,92 +741,71 @@ export class AgentManager {
     return this.agents.get(id);
   }
 
-  /** Handles already in use, so a fresh spawn can pick an unclaimed one. */
-  private takenHandles(): Set<string> {
-    const taken = new Set<string>();
-    for (const record of this.agents.values()) {
-      if (record.handle) taken.add(record.handle);
-      if (record.alias) taken.add(record.alias);
-    }
-    // Tombstones hold their names too: an evicted `@explore` is still
-    // resurrectable, so a later Explore must become `explore-2` rather than
-    // shadowing a conversation the user can still reach.
-    for (const entry of this.tombstones.values()) {
-      taken.add(entry.handle);
-      if (entry.alias) taken.add(entry.alias);
-    }
-    return taken;
+  listAgents(): AgentRecord[] {
+    return [...this.agents.values()].sort(
+      (a, b) => b.startedAt - a.startedAt,
+    );
   }
 
-  /**
-   * Resolve an `@name` from the prompt. Matches a top-level agent's handle
-   * case-insensitively, preferring one that can still be steered and otherwise
-   * the most recently started (which is the one a resume should continue), then
-   * falls back to an exact agent id so `@<agentId>` works too.
-   */
-  resolveMention(name: string): MentionResolution | undefined {
-    const wanted = name.toLowerCase();
-    let fallback: AgentRecord | undefined;
-    for (const record of this.agents.values()) {
-      if (record.parentAgentId !== undefined) continue;
-      // Handle and alias share one namespace, so at most one agent answers a
-      // name and it makes no difference which of the two matched.
-      if (record.handle?.toLowerCase() !== wanted && record.alias?.toLowerCase() !== wanted) continue;
-      if (record.status === "running" || record.status === "queued") return { kind: "live", record };
-      if (!fallback || record.startedAt > fallback.startedAt) fallback = record;
-    }
-    if (fallback) return { kind: "live", record: fallback };
-    const byId = this.agents.get(name);
-    if (byId?.parentAgentId === undefined && byId !== undefined) return { kind: "live", record: byId };
-    // Only once nothing live answers: a tombstone is a conversation to reopen,
-    // and reopening one while its record still exists would fork the session.
-    for (const entry of this.tombstones.values()) {
-      if (entry.handle.toLowerCase() === wanted || entry.alias?.toLowerCase() === wanted || entry.id === name) {
-        return { kind: "tombstone", entry };
+  /** Restore terminal records persisted by a parent branch without runtime handles. */
+  restoreCompleted(records: readonly unknown[]): void {
+    const latest = new Map<string, ReturnType<typeof this.createRestoredRecord>>();
+    for (const value of records) {
+      if (isRestorableAgentRecord(value)) {
+        latest.set(value.id, this.createRestoredRecord(value));
       }
     }
-    return undefined;
-  }
 
-  /**
-   * Forget an evicted agent, by handle. For the case where its session file has
-   * gone: the entry can then only ever fail, while still holding the name
-   * against the type that would otherwise start a fresh agent under it.
-   *
-   * A *successful* resume does not drop its tombstone — the live record it
-   * creates already wins in `resolveMention`, and overwrites the entry in place
-   * when it is itself evicted.
-   */
-  dropTombstone(handle: string): void {
-    this.tombstones.delete(handle);
-  }
-
-  /** Evicted agents whose conversation can still be reopened, newest first. */
-  listTombstones(): AgentTombstone[] {
-    return [...this.tombstones.values()].sort((a, b) => b.completedAt - a.completedAt);
+    for (const [id, restored] of latest) {
+      const existing = this.agents.get(id);
+      if (existing?.status === "running" || existing?.status === "queued") continue;
+      this.agents.set(id, restored);
+    }
   }
 
-  listAgents(): AgentRecord[] {
-    // Prefer live records when a restored transcript shares an id with a
-    // runtime record. This keeps the history archive additive without ever
-    // producing duplicate menu rows.
-    const records = new Map(this.historyRecords);
-    for (const [id, record] of this.agents) records.set(id, record);
-    return [...records.values()].sort((a, b) => b.startedAt - a.startedAt);
+  private createRestoredRecord(record: {
+    id: string;
+    type: string;
+    description: string;
+    status: RestorableAgentStatus;
+    startedAt: number;
+    completedAt: number;
+    result?: string;
+    error?: string;
+    toolUses?: number;
+    lifetimeUsage?: { input: number; output: number; cacheWrite: number };
+    transcriptPath?: string;
+    invocation?: AgentInvocation;
+    compactionCount?: number;
+  }): AgentRecord {
+    return {
+      id: record.id,
+      type: record.type,
+      description: record.description,
+      status: record.status,
+      result: record.result,
+      error: record.error,
+      toolUses: record.toolUses ?? 0,
+      startedAt: record.startedAt,
+      completedAt: record.completedAt,
+      transcriptPath: record.transcriptPath,
+      invocation: cloneInvocation(record.invocation),
+      lifetimeUsage: record.lifetimeUsage
+        ? { ...record.lifetimeUsage }
+        : { input: 0, output: 0, cacheWrite: 0 },
+      compactionCount: record.compactionCount ?? 0,
+    };
   }
 
   abort(id: string): boolean {
     const record = this.agents.get(id);
     if (!record) return false;
 
-    // Remove from queue if queued. No decrement — the slot was never taken —
-    // and no onComplete, matching what a queued background abort has always
-    // done; a blocking caller learns of the stop from its own tool result.
+    // Remove from queue if queued
     if (record.status === "queued") {
-      this.dequeue(q => q.id === id);
+      this.queue = this.queue.filter(q => q.id !== id);
       record.status = "stopped";
       record.completedAt = Date.now();
-      this.flushOutput(record);
       this.checkpoint(record);
       return true;
     }
@@ -1621,62 +816,16 @@ export class AgentManager {
     record.completedAt = Date.now();
     this.flushOutput(record);
     this.checkpoint(record);
+    this.finishBackground(id);
+    this.drainQueue();
     return true;
   }
 
   /** Dispose a record's session and remove it from the map. */
   private removeRecord(id: string, record: AgentRecord): void {
-    this.tombstone(record);
-    const session = record.session;
-    // Detached before the shutdown starts, so the record leaves the map at once and
-    // nothing can observe a session that is half torn down.
+    record.session?.dispose?.();
     record.session = undefined;
-    if (record.transcriptPath) {
-      // Keep a lightweight row discoverable by `/agents` and the Agents widget
-      // after runtime GC. The JSONL transcript is the source of truth; no live
-      // session, promise, or cleanup callback is retained in this archive.
-      record.abortController = undefined;
-      record.promise = undefined;
-      record.startGate = undefined;
-      record.outputCleanup = undefined;
-      record.historyCleanup = undefined;
-      record.worktree = undefined;
-      record.result = undefined;
-      this.historyRecords.set(id, record);
-    }
     this.agents.delete(id);
-    // A failed startup keeps its (rejected) entry so a late awaitStartup still
-    // sees it; drop it with the record so the map can't grow unbounded.
-    this.startups.delete(id);
-    // Fire-and-forget is right here and only here: this runs from the 60s cleanup timer
-    // and from `clearCompleted()` on session boundaries, with the process staying alive,
-    // so handlers get their full window. The quit path awaits instead — see dispose().
-    void shutdownChildSession(session);
-  }
-
-  /**
-   * Preserve enough of a departing record for `@handle` to reopen its
-   * conversation later. Nothing to keep unless it has both a handle to be
-   * addressed by and a session file to reopen — an in-memory session leaves no
-   * transcript, so the mention would have nothing to continue from.
-   */
-  private tombstone(record: AgentRecord): void {
-    if (!record.handle || !record.sessionFile) return;
-    this.tombstones.set(record.handle, {
-      handle: record.handle,
-      alias: record.alias,
-      id: record.id,
-      type: record.type,
-      description: record.description,
-      sessionFile: record.sessionFile,
-      completedAt: record.completedAt ?? Date.now(),
-    });
-    // Bound the memory a long session can accumulate. Oldest first, since the
-    // agent someone still wants to reach is the one they used most recently.
-    while (this.tombstones.size > MAX_TOMBSTONES) {
-      const oldest = [...this.tombstones.values()].reduce((a, b) => (a.completedAt <= b.completedAt ? a : b));
-      this.tombstones.delete(oldest.handle);
-    }
   }
 
   private cleanup() {
@@ -1684,17 +833,32 @@ export class AgentManager {
     for (const [id, record] of this.agents) {
       if (record.status === "running" || record.status === "queued") continue;
       if ((record.completedAt ?? 0) >= cutoff) continue;
+      // A durable transcript is the source of truth for history. Release the
+      // live session after the TTL, but retain a lightweight record so opening
+      // history again in this session does not silently lose its identity or
+      // locator. Records without durable storage remain eligible for eviction.
+      if (record.transcriptPath) {
+        try { record.session?.dispose?.(); } catch { /* ignore cleanup failures */ }
+        record.session = undefined;
+        try { record.outputCleanup?.(); } catch { /* ignore cleanup failures */ }
+        record.outputCleanup = undefined;
+        record.outputFile = undefined;
+        record.historyFile = undefined;
+        // The durable transcript is the source of truth after the TTL. Keep
+        // only the small identity/status record in memory; get_subagent_result
+        // reloads the final answer from transcriptPath on demand.
+        record.result = undefined;
+        continue;
+      }
       this.removeRecord(id, record);
     }
   }
 
   /**
-   * Remove completed/stopped/errored runtime records immediately.
-   * Called on session start/switch so live handles from a prior session do not
-   * remain addressable. Transcript-backed rows move to `historyRecords` and
-   * stay visible to the UI; their JSONL history is the durable source of truth.
-   * Pass skipUnconsumed=true to preserve records the LLM has not read yet
-   * (resultConsumed=false) so the result remains available to the caller.
+   * Remove all completed/stopped/errored records immediately.
+   * Called on session start/switch so tasks from a prior session don't persist.
+   * Pass skipUnconsumed=true to preserve records the LLM hasn't read yet
+   * (resultConsumed=false) — they will be evicted by the 10-minute cleanup timer instead.
    */
   clearCompleted(skipUnconsumed = false): void {
     for (const [id, record] of this.agents) {
@@ -1702,13 +866,6 @@ export class AgentManager {
       if (skipUnconsumed && !record.resultConsumed) continue;
       this.removeRecord(id, record);
     }
-    // Unconditional: both callers are session boundaries (`session_start` and
-    // `session_before_switch`), and `skipUnconsumed` only spares records whose
-    // results the LLM has yet to read — it does not make the sweep partial in
-    // the sense that matters here. A new session means new handles, or
-    // `@explore` would silently reach an agent the user never started. Claude
-    // Code resets its registry on `/clear` for the same reason.
-    this.tombstones.clear();
   }
 
   /** Whether any agents are still running or queued. */
@@ -1727,19 +884,20 @@ export class AgentManager {
       if (record) {
         record.status = "stopped";
         record.completedAt = Date.now();
-        this.flushOutput(record);
         this.checkpoint(record);
         count++;
       }
     }
-    this.dequeue(() => true);
-    // Abort running agents
+    this.queue = [];
+    // Abort running agents. Flush before checkpointing so a catchable
+    // shutdown/session switch leaves the latest assistant message available.
     for (const record of this.agents.values()) {
       if (record.status === "running") {
         record.abortController?.abort();
         record.status = "stopped";
         record.completedAt = Date.now();
         this.flushOutput(record);
+        this.finishBackground(record.id);
         this.checkpoint(record);
         count++;
       }
@@ -1753,72 +911,32 @@ export class AgentManager {
     // agents finish they start queued ones, which need awaiting too.
     while (true) {
       this.drainQueue();
-      const pending: Promise<unknown>[] = [];
-      for (const record of this.agents.values()) {
-        if (record.status !== "running" && record.status !== "queued") continue;
-        // An agent whose worktree is still being created is "running" with no
-        // `promise` yet — without its startup the wait would return too early.
-        const startup = this.startups.get(record.id);
-        if (startup) pending.push(startup);
-        if (record.promise) pending.push(record.promise);
-      }
+      const pending = [...this.agents.values()]
+        .filter(r => r.status === "running" || r.status === "queued")
+        .map(r => r.promise)
+        .filter(Boolean);
       if (pending.length === 0) break;
       await Promise.allSettled(pending);
     }
   }
 
-  /**
-   * @param pi - Needed to run `git worktree prune`, which is async now and so
-   *   cannot be reached through a stored spawn argument at shutdown. Omitting
-   *   it (tests, teardown of a manager that never spawned) skips the prune.
-   */
-  async dispose(pi?: ExtensionAPI): Promise<void> {
+  dispose() {
     clearInterval(this.cleanupInterval);
-    // Keep the pre-shutdown active snapshot marked active in the checkpoint. A
-    // process can still be killed after dispose starts; restoreRecovered turns
-    // that stale active marker into a stopped record, while the transcript has
-    // already received the terminal abort/stop event below.
-    const activeBeforeDispose = new Set(
-      [...this.agents.values()]
-        .filter(record => record.status === "running" || record.status === "queued")
-        .map(record => record.id),
-    );
-    // Mark live work stopped and flush durable history before child sessions are
-    // shut down. The caller also invokes abortAll(), but dispose is deliberately
-    // safe and complete when used on its own.
-    this.abortAll();
-    // Clear queue — via dequeue, so anyone blocked in spawnAndWait is woken
-    // rather than left awaiting a gate nothing will ever resolve.
-    this.dequeue(() => true);
+    // Clear queue
+    this.queue = [];
     for (const record of this.agents.values()) {
-      this.flushOutput(record);
-      this.checkpoint(record);
-      if (activeBeforeDispose.has(record.id)) {
-        const activeSnapshot = this.makeCheckpoint(record);
-        delete activeSnapshot.completedAt;
-        activeSnapshot.status = "running";
-        const cwd = this.recoveryCwds.get(record.id);
-        if (cwd) writeAgentRecoveryCheckpoint(cwd, activeSnapshot);
-      }
+      record.session?.dispose();
     }
-    const sessions = [...this.agents.values()].map(record => record.session);
     this.agents.clear();
     this.recoveryCwds.clear();
-    this.startups.clear();
-    if (pi) {
-      // Prune any orphaned git worktrees (crash recovery). Detached: dispose runs
-      // on the shutdown path, which cannot wait for git. Started before the awaited
-      // shutdown below rather than after it, so the git calls have that window to
-      // finish in instead of racing the process exit that follows.
-      const prune = (repo: string) => { pruneWorktrees(pi, repo).catch(() => {}); };
-      prune(process.cwd());
-      // Also prune repos that caller-supplied cwds created worktrees in — a clean
-      // exit with in-flight agents would otherwise leave stale registrations there.
-      for (const repo of this.worktreeRepos) prune(repo);
+    this.runningBackgroundIds.clear();
+    this.runningBackground = 0;
+    // 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
+    // exit with in-flight agents would otherwise leave stale registrations there.
+    for (const repo of this.worktreeRepos) {
+      try { pruneWorktrees(repo); } catch { /* ignore */ }
     }
-    // Awaited, unlike the eviction path: pi awaits this extension's `session_shutdown`
-    // handler and the process exits right after it returns, so anything left unawaited
-    // here never runs at all. Bounded — each call carries its own ceiling, concurrently.
-    await Promise.all(sessions.map(session => shutdownChildSession(session)));
   }
 }