@herbertgao/pi-subagents 0.17.0 → 0.18.0

package/src/agent-manager.ts

@@ -1,8 +1,17 @@
 /**
  * agent-manager.ts — Tracks agents, background execution, resume support.
  *
- * Background and blocking foreground agents use independent concurrency pools.
- * Nested children use neither pool, avoiding parent/child deadlocks.
+ * 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`.
  */
 
 import { randomUUID } from "node:crypto"
@@ -15,36 +24,87 @@ import type {
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent"
 import { resumeAgent, runAgent, type ToolActivity } from "./agent-runner.js"
+import { assignHandle, handleBase } from "./mention.js"
 import { describeModel } from "./model-resolver.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,
+  type WorktreeCleanupResult,
 } 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. */
+/**
+ * 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 blocking agents. 0 means unlimited. */
+
+/**
+ * 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
 
+/**
+ * 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
+
+function applyWorktreeCleanupFailure(
+  record: AgentRecord,
+  result: WorktreeCleanupResult,
+): boolean {
+  if (!result.error || !result.path) return false
+  const message = `Worktree cleanup failed: ${result.error}\nAgent worktree remains at \`${result.path}\` for recovery.`
+  record.status = "error"
+  record.error = record.error ? `${record.error}\n${message}` : message
+  return true
+}
+
 /**
  * Validate a caller-supplied SpawnOptions.cwd. `undefined`/`null` mean "unset"
  * (parent cwd). Anything else must be an absolute path to an existing
@@ -81,17 +141,57 @@ function assertValidSpawnCwd(
  * spawn costs it a turn, which is unbounded when max turns is unlimited.
  */
 function occupiesPoolSlot(
-  record: Pick<AgentRecord, "isBackground" | "parentAgentId">,
+  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.isBackground && record.parentAgentId === undefined
+  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">,
+  record: Pick<AgentRecord, "blocking" | "parentAgentId" | "workflowId">,
 ): boolean {
-  return !!record.blocking && record.parentAgentId === undefined
+  return !!record.blocking && isTopLevelAgent(record)
 }
 
+/** Which concurrency pool a spawn is charged to, if any. */
 type Pool = "background" | "foreground"
 
 interface SpawnArgs {
@@ -104,6 +204,31 @@ 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
@@ -111,13 +236,38 @@ interface SpawnOptions {
   thinkingLevel?: ThinkingLevel
   isBackground?: boolean
   /**
-   * Skip the maxConcurrent queue check for this spawn — start immediately even
-   * if the configured concurrency limit would otherwise queue it. Used by the
-   * scheduler so a fired job can't be deferred past its trigger window.
+   * 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).
    */
   bypassQueue?: boolean
-  /** Set only by spawnAndWait; detached/RPC spawns do not occupy the foreground pool. */
+  /**
+   * 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
   /**
@@ -129,13 +279,41 @@ 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
   /** Parent abort signal — when aborted, the subagent is also stopped. */
   signal?: AbortSignal
-  /** Called when this specific record has started and has a promise. */
+  /**
+   * 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 when this record enters its pool's queue. */
+  /**
+   * 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
@@ -146,7 +324,11 @@ interface SpawnOptions {
   /** Called at the end of each agentic turn with the cumulative count. */
   onTurnEnd?: (turnCount: number) => void
   /** Called once per assistant message_end with that message's usage delta. */
-  onAssistantUsage?: (usage: LifetimeUsage) => void
+  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. */
@@ -172,10 +354,12 @@ interface ResumeOptions {
   isBackground?: boolean
   /** Called on tool start/end with activity info (for streaming progress to UI). */
   onToolActivity?: (activity: ToolActivity) => void
-  /** Called at the end of each resumed agentic turn with the cumulative count. */
-  onTurnEnd?: (turnCount: number) => void
   /** Called once per assistant message_end with that message's usage delta. */
-  onAssistantUsage?: (usage: LifetimeUsage) => void
+  onAssistantUsage?: (usage: {
+    input: number
+    output: number
+    cacheWrite: number
+  }) => void
   /** Called when the session successfully compacts. */
   onCompaction?: (info: CompactionInfo) => void
   /**
@@ -189,14 +373,29 @@ interface ResumeOptions {
   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) =>
@@ -205,8 +404,9 @@ async function shutdownChildSession(
       ])
     }
   } catch {
-    /* best-effort lifecycle cleanup */
+    /* 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 {
@@ -227,14 +427,48 @@ export class AgentManager {
    *  not just the parent repo (caller-supplied cwd can target other repos). */
   private worktreeRepos = new Set<string>()
 
-  /** Agents waiting on either independent concurrency pool. */
+  /**
+   * 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: () => void
+    start: () => Promise<void>
     release: () => void
   }[] = []
+  /** Number of currently running background agents. */
   private runningBackground = 0
+  /** Number of currently running foreground (blocking) agents. */
   private runningForeground = 0
 
   constructor(
@@ -265,9 +499,12 @@ export class AgentManager {
     return this.maxConcurrent
   }
 
-  /** Update the max concurrent blocking agents limit. 0 means unlimited. */
+  /** 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()
   }
 
@@ -275,11 +512,22 @@ export class AgentManager {
     return this.maxConcurrentForeground
   }
 
+  /**
+   * 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)) {
+    if (this.maxConcurrentForeground > 0 && occupiesForegroundSlot(record))
       return "foreground"
-    }
     return undefined
   }
 
@@ -293,6 +541,11 @@ export class AgentManager {
   /**
    * 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,
@@ -311,12 +564,28 @@ 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 },
+      lifetimeUsage: { input: 0, output: 0, cacheWrite: 0, cost: 0 },
       compactionCount: 0,
       // Raw tri-state (not coerced to a boolean): true = background, false =
       // foreground (has an inline tool-result surface), undefined = caller never
@@ -324,20 +593,39 @@ 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)
+    // 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())
+    }
 
     const args: SpawnArgs = { pi, ctx, type, prompt, options }
 
     const pool = this.poolFor(record)
-    if (pool && !options.bypassQueue && !this.poolHasRoom(pool)) {
+    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) => {
@@ -346,29 +634,37 @@ export class AgentManager {
       this.queue.push({
         id,
         pool,
-        start: () => this.startAgent(id, record, args),
-        release,
+        start: () => this.launch(id, record, args, pool),
+        release: () => release(),
       })
       options.onQueued?.(
         id,
-        this.queue.filter((entry) => entry.pool === pool).length - 1,
+        this.queue.filter((e) => e.pool === pool).length - 1,
       )
       return id
     }
 
-    // startAgent can throw (e.g. strict worktree-isolation failure) — clean
-    // up the record so callers don't see an orphan in `listAgents()`.
-    try {
-      this.startAgent(id, record, args)
-    } catch (err) {
-      this.agents.delete(id)
-      throw err
-    }
+    this.launch(id, record, args, undefined)
     return 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) return true
+    if (signal === undefined) return true
     if (signal.aborted) {
       const record = this.agents.get(id)
       if (record) {
@@ -381,8 +677,71 @@ export class AgentManager {
     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.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()
+  }
+
   /** Actually start an agent (called immediately or from queue drain). */
-  private startAgent(
+  private async startAgent(
     id: string,
     record: AgentRecord,
     { pi, ctx, type, prompt, options }: SpawnArgs,
@@ -396,13 +755,42 @@ 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++
+
     // Worktree isolation: try to create a temporary git worktree. Strict —
-    // fail loud if not possible (no silent fallback to main tree). Done
-    // BEFORE state mutation so a throw doesn't leave the record half-running.
+    // 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.
     let worktreeCwd: string | undefined
     if (options.isolation === "worktree" && isWorktreeIsolationEnabled()) {
-      const wt = createWorktree(baseCwd, id)
+      const wt = await createWorktree(pi, 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`.",
@@ -417,22 +805,38 @@ 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,
+        )
+        if (applyWorktreeCleanupFailure(record, record.worktreeResult)) {
+          throw new Error(record.error)
+        }
+        this.drainQueue()
+        return
+      }
     }
 
-    record.status = "running"
-    record.startedAt = Date.now()
-    record.startGate = undefined
-    const pool = this.poolFor(record)
-    if (pool === "background") this.runningBackground++
-    else if (pool === "foreground") this.runningForeground++
     this.onStart?.(record)
 
     // Wire parent abort signal to stop the subagent when the parent is interrupted
     let detachParentSignal: (() => void) | undefined
     if (options.signal) {
-      if (options.signal.aborted) {
-        this.abort(id)
-      } else {
+      // 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 = () =>
@@ -452,12 +856,18 @@ 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),
@@ -486,11 +896,31 @@ export class AgentManager {
       },
       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) {
@@ -508,61 +938,92 @@ export class AgentManager {
         options.onSessionCreated?.(session)
       },
     })
-      .then(({ responseText, session, aborted, steered, failure }) => {
-        // Don't overwrite status if externally stopped via abort()
-        if (record.status !== "stopped") {
-          // Precedence: a hard abort keeps "aborted"; then a failed final turn
-          // (provider error that pi resolved instead of rejecting, #144) is an
-          // honest "error" — not a completion with an empty or stale result.
-          if (aborted) {
-            record.status = "aborted"
-          } else if (failure) {
-            record.status = "error"
-            record.error = failure
-          } else {
-            record.status = steered ? "steered" : "completed"
+      .then(
+        async ({
+          responseText,
+          session,
+          aborted,
+          steered,
+          failure,
+          structuredJson,
+          structuredRetried,
+        }) => {
+          // Don't overwrite status if externally stopped via abort()
+          if (record.status !== "stopped") {
+            // Precedence: a hard abort keeps "aborted"; then a failed final turn
+            // (provider error that pi resolved instead of rejecting, #144) is an
+            // honest "error" — not a completion with an empty or stale result.
+            if (aborted) {
+              record.status = "aborted"
+            } else if (failure) {
+              record.status = "error"
+              record.error = failure
+            } else {
+              record.status = steered ? "steered" : "completed"
+            }
           }
-        }
-        record.result = responseText
-        record.session = session
-        record.completedAt ??= Date.now()
-
-        detach()
-
-        // Final flush of streaming output file
-        if (record.outputCleanup) {
-          try {
-            record.outputCleanup()
-          } catch {
-            /* ignore */
+          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()
+
+          // Final flush of streaming output file
+          if (record.outputCleanup) {
+            try {
+              record.outputCleanup()
+            } catch {
+              /* ignore */
+            }
+            record.outputCleanup = undefined
           }
-          record.outputCleanup = undefined
-        }
 
-        // Clean up worktree if used
-        if (record.worktree) {
-          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}\`` : ""
-            record.result =
-              (record.result ?? "") +
-              `\n\n---\nChanges saved to branch \`${wtResult.branch}\`${repoNote}. Merge with: \`git merge ${wtResult.branch}\`${customCwd !== undefined ? ` (run in \`${baseCwd}\`)` : ""}`
+          // 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,
+            )
+            record.worktreeResult = wtResult
+            const cleanupFailed = applyWorktreeCleanupFailure(record, wtResult)
+            if (!cleanupFailed && 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.abortOwnedChildren(id)
+          this.abortOwnedChildren(id)
 
-        this.settleRun(record, true, pool)
-        return responseText
-      })
-      .catch((err) => {
+          this.settleRun(record, true, pool)
+          return responseText
+        },
+      )
+      .catch(async (err) => {
         // Don't overwrite status if externally stopped via abort()
         if (record.status !== "stopped") {
           record.status = "error"
@@ -585,12 +1046,14 @@ export class AgentManager {
         // Best-effort worktree cleanup on error
         if (record.worktree) {
           try {
-            const wtResult = cleanupWorktree(
+            const wtResult = await cleanupWorktree(
+              pi,
               baseCwd,
               record.worktree,
               options.description,
             )
             record.worktreeResult = wtResult
+            applyWorktreeCleanupFailure(record, wtResult)
           } catch {
             /* ignore cleanup errors */
           }
@@ -604,10 +1067,32 @@ export class AgentManager {
 
     record.promise = promise
 
-    // Per-call hook: safe for parallel and deferred foreground starts.
+    // 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,
@@ -626,7 +1111,14 @@ export class AgentManager {
     } else {
       this.onComplete?.(record)
     }
-    if (record.isBackground || pool) this.drainQueue()
+
+    // 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()
   }
 
   /**
@@ -641,31 +1133,46 @@ export class AgentManager {
     }
   }
 
-  /** Start the earliest queued agent whose own pool has room. */
+  /**
+   * 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.
+   */
   private drainQueue() {
     for (;;) {
-      const index = this.queue.findIndex((entry) =>
-        this.poolHasRoom(entry.pool),
-      )
-      if (index === -1) return
-      const [next] = this.queue.splice(index, 1)
+      const i = this.queue.findIndex((e) => this.poolHasRoom(e.pool))
+      if (i === -1) return
+      const [next] = this.queue.splice(i, 1)
       const record = this.agents.get(next.id)
-      try {
-        if (record?.status === "queued") next.start()
-      } catch (err) {
-        if (record) {
-          if (next.pool === "foreground") record.resultConsumed = true
-          record.status = "error"
-          record.error = err instanceof Error ? err.message : String(err)
-          record.completedAt = Date.now()
-          this.onComplete?.(record)
-        }
-      } finally {
+      // Stale entries (aborted while queued) are not started — but are still
+      // released, since nothing else will.
+      if (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) {
@@ -675,7 +1182,16 @@ export class AgentManager {
     this.queue = kept
   }
 
-  /** Spawn an agent, applying the blocking foreground pool, and await it. */
+  /**
+   * 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.
+   * 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.
+   */
   async spawnAndWait(
     pi: ExtensionAPI,
     ctx: ExtensionContext,
@@ -684,6 +1200,11 @@ 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,
@@ -691,9 +1212,32 @@ export class AgentManager {
       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
-    if (!record.promise && record.status === "error") {
+
+    // 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")
     }
     return { id, record }
@@ -739,11 +1283,24 @@ export class AgentManager {
 
       const start = () => this.startResume(id, record, prompt, signal, options)
       if (occupiesPoolSlot(record) && !this.poolHasRoom("background")) {
-        // Detached resumes remain on the background pool only.
+        // 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,
+          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 {
@@ -765,7 +1322,6 @@ export class AgentManager {
           if (activity.type === "end") record.toolUses++
           options?.onToolActivity?.(activity)
         },
-        onTurnEnd: options?.onTurnEnd,
         onAssistantUsage: (usage) => {
           addUsage(record.lifetimeUsage, usage)
           this.onUsage?.(record, usage)
@@ -870,7 +1426,6 @@ export class AgentManager {
         if (activity.type === "end") record.toolUses++
         options.onToolActivity?.(activity)
       },
-      onTurnEnd: options.onTurnEnd,
       onAssistantUsage: (usage) => {
         addUsage(record.lifetimeUsage, usage)
         this.onUsage?.(record, usage)
@@ -934,6 +1489,83 @@ 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
+  }
+
+  /**
+   * 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 }
+      }
+    }
+    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,
+    )
+  }
+
   listAgents(): AgentRecord[] {
     return [...this.agents.values()].sort((a, b) => b.startedAt - a.startedAt)
   }
@@ -942,7 +1574,9 @@ export class AgentManager {
     const record = this.agents.get(id)
     if (!record) return false
 
-    // Remove from queue if queued and release any blocking waiter.
+    // 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.
     if (record.status === "queued") {
       this.dequeue((q) => q.id === id)
       record.status = "stopped"
@@ -959,12 +1593,48 @@ export class AgentManager {
 
   /** 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 = undefined
     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() {
     const cutoff = Date.now() - 10 * 60_000
     for (const [id, record] of this.agents) {
@@ -986,6 +1656,13 @@ 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. */
@@ -1026,35 +1703,49 @@ export class AgentManager {
     // agents finish they start queued ones, which need awaiting too.
     while (true) {
       this.drainQueue()
-      const pending = [...this.agents.values()]
-        .filter((r) => r.status === "running" || r.status === "queued")
-        .map((r) => r.promise)
-        .filter(Boolean)
+      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)
+      }
       if (pending.length === 0) break
       await Promise.allSettled(pending)
     }
   }
 
-  async dispose(): Promise<void> {
+  /**
+   * @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> {
     clearInterval(this.cleanupInterval)
+    // Clear queue — via dequeue, so anyone blocked in spawnAndWait is woken
+    // rather than left awaiting a gate nothing will ever resolve.
     this.dequeue(() => true)
     const sessions = [...this.agents.values()].map((record) => record.session)
     this.agents.clear()
-    await Promise.all(sessions.map((session) => shutdownChildSession(session)))
-    // 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 */
+    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)
     }
+    // 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)))
   }
 }