@nredd/pi-subagents 0.22.0-nredd.7 → 0.22.0-nredd.9

package/src/agent-manager.ts

@@ -21,16 +21,21 @@
  */
 
 import { randomUUID } from "node:crypto";
-import { statSync } from "node:fs";
+import { accessSync, constants, opendirSync, 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 { type AssistantMessageInfo, resumeAgent, runAgent, type ToolActivity } from "./agent-runner.js";
 import { getAgentConfig } from "./agent-types.js";
 import { type Clock, realClock, type TimerHandle } from "./clock.js";
+import { errorMessage } from "./error-message.js";
 import { assignHandle, handleBase } from "./mention.js";
 import type { ModelCallEvent } from "./model-call.js";
-import { describeModel, describePhysicalModel, describeVirtualModel, isVirtualModel } from "./model-resolver.js";
+import { describeModel, describePhysicalModel, describeVirtualModel, isVirtualModel, type ModelFallback } from "./model-resolver.js";
+import { admitModelSelection, describeSelection, type ModelSelection, modelSelectionNote, selectModel } from "./model-selection.js";
+import { type TierDisclosure, tierDisclosure } from "./model-tiers.js";
+import { appendModelFallbackEntry, appendModelTierEntry } from "./output-file.js";
+import { type PlanToolPolicy, queryPlanPolicy } from "./plan-mode-children.js";
 import {
   assertWithinBudgetDepth,
   BUDGET_QUEUE_FULL_ERROR,
@@ -41,10 +46,12 @@ import {
   releaseBudget,
   tryAcquireBudget,
 } from "./process-budget.js";
+import { describeBlock } from "./quota-admission.js";
+import { isStaleCtxError } from "./stale-ctx.js";
 import type { AgentInvocation, AgentRecord, AgentTombstone, IsolationMode, MentionResolution, Pool, 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 WorktreeInfo } from "./worktree.js";
+import { cleanupWorktree, createWorktree, isWorktreeIsolationEnabled, pruneWorktrees, type WorktreeCleanupResult, type WorktreeInfo } from "./worktree.js";
 
 /**
  * Relabel a record's model from the response that just finished. A virtual
@@ -59,10 +66,32 @@ function relabelFromResponse(record: AgentRecord, message: AssistantMessageInfo
   if (!physical) return;
   record.invocation ??= {};
   Object.assign(record.invocation, physical);
+  if ((record.modelTier?.kind === "routed" || record.modelTier?.kind === "static") && record.modelTier.answered !== physical.modelId) {
+    record.modelTier = { ...record.modelTier, answered: physical.modelId };
+    if (record.outputFile) appendModelTierEntry(record.outputFile, record.id, record.modelTier);
+  }
+}
+
+/** Keep a cleanup failure visible on every result, including errors and stopped workflows. */
+function recordWorktreeCleanup(record: AgentRecord, result: WorktreeCleanupResult): void {
+  record.worktreeResult = result;
+  if (!result.error) return;
+  const note = `Worktree cleanup failed: ${result.error}. Worktree retained at \`${result.path}\`${result.branch ? `; branch \`${result.branch}\` was created` : ""}. Inspect and recover it before removing it.`;
+  record.error = record.error ? `${record.error}\n${note}` : note;
+  record.result = record.result ? `${record.result}\n\n${note}` : note;
+  if (record.status !== "stopped") record.status = "error";
 }
 
 export type OnAgentComplete = (record: AgentRecord) => void;
 export type OnAgentStart = (record: AgentRecord) => void;
+/**
+ * Fired when `abort`, `detach` or `abortAll` stops a record that was still queued. Such a record
+ * never reaches `onComplete` (it never ran, so there is no result to announce), but a listener
+ * that heard it spawn needs to learn it ended.
+ */
+export type OnAgentQueuedStop = (record: AgentRecord) => void;
+/** Fired when the retention sweep evicts a top-level agent whose result was never read (#330). */
+export type OnAgentReaped = (note: EvictedNote) => void;
 /**
  * Fired by `steer()` once a message is delivered or queued. Every steer path
  * goes through it except the steer tools (`steer_subagent` in index.ts, and its
@@ -163,12 +192,19 @@ export interface EvictedNote {
   evictedAfterMin: number;
   /** The `.output` transcript when one was written, else the session file. */
   transcript?: string;
+  /** The run's model fallback, so even an evicted agent's id still discloses it. */
+  modelFallback?: ModelFallback;
+  modelTier?: TierDisclosure;
+  /** Set when a saved session exists but its name now belongs to another agent, so it was not kept reopenable. */
+  nameTaken?: string;
 }
 
 /** The text a tool returns for an id whose record was evicted. */
 export function describeEvicted(note: EvictedNote): string {
   const where = note.transcript ? `; transcript: ${note.transcript}` : "";
-  return `Agent "${note.id}" (${note.description}) ${note.status}, evicted after ${note.evictedAfterMin} min${where}`;
+  const disclosure = modelSelectionNote(note);
+  const fallback = disclosure ? `\n${disclosure}` : "";
+  return `Agent "${note.id}" (${note.description}) ${note.status}, evicted after ${note.evictedAfterMin} min${where}${fallback}`;
 }
 
 /**
@@ -200,6 +236,50 @@ function assertValidSpawnCwd(cwd: unknown): asserts cwd is string | undefined |
   }
 }
 
+/**
+ * Fail fast when a working directory exists but cannot be opened (#436).
+ * `stat` succeeds on such a directory (POSIX `chmod 000`, or a macOS privacy
+ * denial of an external volume), so without this the child starts and every
+ * read fails with a bare EPERM/EACCES. Only those two codes are rejected: a
+ * missing directory stays the caller's concern (`assertValidSpawnCwd`).
+ */
+function assertReadableCwd(cwd: string, label: string): void {
+  try {
+    opendirSync(cwd).closeSync();
+    // opendir needs only the read bit; children also need search (x) to reach anything inside.
+    accessSync(cwd, constants.R_OK | constants.X_OK);
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== "EACCES" && code !== "EPERM") return;
+    throw new Error(
+      `${label} is not readable (${code}): "${cwd}". Check its permissions; on macOS also check Privacy & Security -> Files & Folders / Full Disk Access for the terminal app (external volumes need it).`,
+    );
+  }
+}
+
+/** Validate the cwd a child will run in: caller-supplied `SpawnOptions.cwd`, else the session cwd. */
+function assertSpawnCwd(cwd: unknown, sessionCwd: string): void {
+  assertValidSpawnCwd(cwd);
+  if (cwd == null) assertReadableCwd(sessionCwd, "The session cwd");
+  else assertReadableCwd(cwd, "SpawnOptions.cwd");
+}
+
+/** The session's own pending agents, split by whether their completion wakes the parent. */
+export interface OwnedPending {
+  /** Background agents (Agent tool, `@handle`, scheduler, background resume) whose completion notice starts a parent turn. */
+  notifying: number;
+  /** Foreground agents and RPC spawns without `isBackground`, whose settle notifies nobody. */
+  silent: number;
+}
+
+/** A record whose run is over. Every settle and stop stamps `completedAt`; only a (re)start clears it. */
+type SettledRecord = AgentRecord & { completedAt: number };
+
+/** Whether `record` is past its run (neither running nor queued), and so carries `completedAt`. */
+function isSettled(record: AgentRecord): record is SettledRecord {
+  return record.status !== "running" && record.status !== "queued";
+}
+
 /**
  * Whether a record occupies one of the `maxConcurrent` background slots.
  * Nested children don't: their parent already holds a slot, so counting (and
@@ -263,6 +343,8 @@ function occupiesForegroundSlot(
 /** A start waiting in `AgentManager.queue`; see there. */
 interface QueueEntry {
   id: string;
+  /** The queued record; it stays in `agents` while queued, since only settled records are evicted. */
+  record: AgentRecord;
   /** The pool it needs room in, or undefined when it waits on the budget alone. */
   pool?: Pool;
   start: () => Promise<void>;
@@ -282,6 +364,8 @@ interface SpawnArgs {
 }
 
 interface SpawnOptions {
+  /** Home inherited by nested callers; the manager's home is the default. */
+  homeDir?: string;
   description: string;
   /**
    * Optional memorable name for this instance, becoming a second handle
@@ -308,7 +392,16 @@ interface SpawnOptions {
    * `spawnTopLevel` strips it from anything a caller sends.
    */
   reclaim?: { handle: string; alias?: string };
-  model?: Model<any>;
+  model?: Model<any> | string;
+  /** Internal preflight outcome, stored on the record without resolving again. */
+  modelSelection?: ModelSelection;
+  /** Historical outcome only, never used to label the continuation. */
+  previousModelTier?: TierDisclosure;
+  /** Historical fallback only, never used to label the continuation. */
+  previousModelFallback?: ModelFallback;
+  /** Internal, like `reclaim`: the evicted id a reopen continues. */
+  previousId?: string;
+
   maxTurns?: number;
   isolated?: boolean;
   inheritContext?: boolean;
@@ -378,9 +471,11 @@ interface SpawnOptions {
   invocation?: AgentInvocation;
   /** Parent abort signal — when aborted, the subagent is also stopped. */
   signal?: AbortSignal;
+  /** Prepare the record before it can be queued or started. A throw rejects the spawn. */
+  onPrepare?: (id: string) => void;
   /**
    * Called synchronously once the record is in the map and its promise is set,
-   * before `onSessionCreated` fires — where callers attach the output file.
+   * before `onSessionCreated` fires.
    *
    * 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,
@@ -472,6 +567,7 @@ const CHILD_SHUTDOWN_TIMEOUT_MS = 3_000;
  * `assertActive()` from a bare timer callback — an uncaughtException that kills pi (#242).
  */
 async function shutdownChildSession(session: AgentSession | undefined): Promise<void> {
+  let deadline: ReturnType<typeof setTimeout> | undefined;
   try {
     const runner = session?.extensionRunner;
     // Optional all the way down: on a pi without the getter, or a stubbed session from a
@@ -482,14 +578,44 @@ async function shutdownChildSession(session: AgentSession | undefined): Promise<
       // 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()),
+        new Promise<void>(resolve => {
+          deadline = setTimeout(resolve, CHILD_SHUTDOWN_TIMEOUT_MS);
+          deadline.unref();
+        }),
       ]);
     }
   } catch { /* a partial session must degrade, not take the teardown down with it */ }
+  finally {
+    // Promise.race does not cancel its loser, even when a handler rejects.
+    if (deadline !== undefined) clearTimeout(deadline);
+  }
   // Always, even on timeout: disposal is what this function ultimately exists to do.
   try { session?.dispose?.(); } catch { /* ignore */ }
 }
 
+/**
+ * Wrap an observer the child's own agent loop calls (usage, compaction) so a
+ * throw cannot reach that loop. pi records a throw from a session listener as
+ * the turn's failure, so an observer closed over a replaced session's `pi`
+ * ("This extension ctx is stale ...") used to end a detached child with an
+ * empty error turn and "No output" (#145). That failure is expected after a
+ * reload and dropped silently. Any other throw is a real observer defect: it
+ * is logged once per observer and also kept from killing the run.
+ */
+function guardObserver<A extends unknown[]>(name: string, observer: ((...args: A) => void) | undefined): ((...args: A) => void) | undefined {
+  if (!observer) return undefined;
+  let logged = false;
+  return (...args: A) => {
+    try {
+      observer(...args);
+    } catch (error) {
+      if (isStaleCtxError(error) || logged) return;
+      logged = true;
+      console.error(`pi-subagents: ${name} observer failed; further failures are not logged`, error);
+    }
+  };
+}
+
 export class AgentManager {
   private agents = new Map<string, AgentRecord>();
   private cleanupInterval: TimerHandle;
@@ -499,6 +625,8 @@ export class AgentManager {
   private readonly unreadTtlMs = retentionMs("PI_SUBAGENTS_UNREAD_TTL_MIN", UNCONSUMED_RECORD_TTL_MS);
   private onComplete?: OnAgentComplete;
   private onStart?: OnAgentStart;
+  private onQueuedStop?: OnAgentQueuedStop;
+  private onReaped?: OnAgentReaped;
   private onCompact?: OnAgentCompact;
   private onUsage?: OnAgentUsage;
   private onSteered?: OnAgentSteered;
@@ -529,6 +657,8 @@ export class AgentManager {
 
   /** Evicted records by id, oldest first (insertion order). */
   private evictedNotes = new Map<string, EvictedNote>();
+  /** Evicted id -> the id its reopened conversation runs under, so the old id keeps resolving (#330). */
+  private successors = new Map<string, string>();
 
   /**
    * Agents waiting to start, tagged with the pool they wait on (none for a
@@ -561,11 +691,16 @@ export class AgentManager {
     onUsage?: OnAgentUsage,
     onSteered?: OnAgentSteered,
     private readonly clock: Clock = realClock,
+    private readonly homeDir?: string,
+    onQueuedStop?: OnAgentQueuedStop,
+    onReaped?: OnAgentReaped,
   ) {
     this.onComplete = onComplete;
     this.onStart = onStart;
-    this.onCompact = onCompact;
-    this.onUsage = onUsage;
+    this.onQueuedStop = guardObserver("queued stop", onQueuedStop);
+    this.onReaped = guardObserver("reaped", onReaped);
+    this.onCompact = guardObserver("compaction", onCompact);
+    this.onUsage = guardObserver("usage", onUsage);
     this.onSteered = onSteered;
     this.maxConcurrent = maxConcurrent;
     // Sweep finished records past their retention window (see cleanup()).
@@ -577,6 +712,31 @@ export class AgentManager {
     this.cleanupInterval.unref?.();
   }
 
+  /**
+   * Put a run under Plan mode's policy when its owning agent's run is (a nested
+   * child) or the parent session is planning right now (everything else, a
+   * workflow stage included). The gate object is kept, since the child's hooks
+   * hold it.
+   */
+  private decidePlanGate(record: AgentRecord, query: () => PlanToolPolicy | undefined): void {
+    const owner = record.parentAgentId === undefined ? undefined : this.agents.get(record.parentAgentId);
+    const policy = owner?.planGate?.policy ?? query();
+    record.planGate ??= {};
+    record.planGate.policy = policy;
+    if (policy || record.invocation?.planMode) {
+      record.invocation ??= {};
+      record.invocation.planMode = policy ? true : undefined;
+    }
+  }
+
+  /** Spawns and settles, in order: `spawnSeq` / `settleSeq` on lifecycle events. */
+  private lifecycleSequence = 0;
+
+  /** The next lifecycle sequence number; the host stamps `settleSeq` with it at settle. */
+  nextSequence(): number {
+    return ++this.lifecycleSequence;
+  }
+
   /** Update the max concurrent background agents limit. */
   setMaxConcurrent(n: number) {
     this.maxConcurrent = Math.max(1, n);
@@ -644,7 +804,20 @@ export class AgentManager {
     // Validate before the queue branch — a queued spawn should fail at the
     // call, not minutes later at drain. Throw (not warn): programmatic callers
     // can fix and retry; the RPC layer converts throws into error envelopes.
-    assertValidSpawnCwd(options.cwd);
+    assertSpawnCwd(options.cwd, ctx.cwd);
+    const selection = options.modelSelection ?? selectModel({
+      homeDir: options.homeDir ?? this.homeDir,
+      agentType: type,
+      definitionModel: getAgentConfig(type)?.model,
+      paramModel: options.model,
+      parentModel: ctx.model,
+      registry: ctx.modelRegistry,
+      cwd: options.configCwd ?? ctx.cwd,
+      agentLabel: getAgentConfig(type)?.displayName,
+    });
+    if (typeof selection === "string") throw new Error(selection);
+    if (selection.scopeWarning && !options.modelSelection) ctx.ui.notify(selection.scopeWarning, "warning");
+    options = { ...options, model: selection.model, modelSelection: selection };
 
     const id = randomUUID().slice(0, 17);
     const abortController = new AbortController();
@@ -672,6 +845,7 @@ export class AgentManager {
       startedAt: this.clock.now(),
       abortController,
       lifetimeUsage: { input: 0, output: 0, cacheWrite: 0, cost: 0 },
+      spawnSeq: this.nextSequence(),
       compactionCount: 0,
       // Raw tri-state (not coerced to a boolean): true = background, false =
       // foreground (has an inline tool-result surface), undefined = caller never
@@ -684,18 +858,27 @@ export class AgentManager {
       // `options` has stopped being the interesting object.
       blocking: options.blocking,
       invocation: options.invocation,
+      modelFallback: selection.fallback,
+      modelSelection: selection,
+      modelTier: selection.tier ? tierDisclosure(selection.tier) : undefined,
+      previousModelTier: options.previousModelTier,
+      previousModelFallback: options.previousModelFallback,
+      previousId: options.previousId,
       depth: options.depth ?? 1,
       parentAgentId: options.parentAgentId,
       workflowId: options.workflowId,
       maxSubagentDepth: options.maxSubagentDepth,
       rootSessionId: options.rootSessionId,
     };
+    this.decidePlanGate(record, () => queryPlanPolicy(pi.events));
+    record.planQuery = () => queryPlanPolicy(pi.events, "restrict");
     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());
+      record.nameBase = handleBase(options.name);
+      record.alias = assignHandle(record.nameBase, this.takenHandles());
     }
 
     const args: SpawnArgs = { pi, ctx, type, prompt, options };
@@ -711,6 +894,14 @@ export class AgentManager {
       this.agents.delete(id);
       throw err;
     }
+    try {
+      options.onPrepare?.(id);
+    } catch (err) {
+      this.agents.delete(id);
+      releaseBudget(lease);
+      this.drainQueue();
+      throw err;
+    }
     if (lease === undefined) {
       // Queue it — started once its pool has room and the process budget a
       // lease, whichever was missing.
@@ -719,7 +910,7 @@ export class AgentManager {
       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;
+      if (!this.armQueuedAbort(record, options.signal)) return id;
       let release!: () => void;
       record.startGate = new Promise<void>(resolve => { release = resolve; });
       // Failure bookkeeping keys on whether an inline caller gets the throw,
@@ -749,18 +940,14 @@ export class AgentManager {
    * replaces it with its own, and `sendToBackground` must be able to take it
    * off, or the caller that armed it could stop a run it no longer owns.
    */
-  private armQueuedAbort(id: string, signal?: AbortSignal): boolean {
+  private armQueuedAbort(record: AgentRecord, signal?: AbortSignal): boolean {
     if (signal === undefined) return true;
     if (signal.aborted) {
-      const record = this.agents.get(id);
-      if (record) {
-        record.status = "stopped";
-        record.completedAt = this.clock.now();
-      }
+      record.status = "stopped";
+      record.completedAt = this.clock.now();
       return false;
     }
-    const record = this.agents.get(id);
-    if (record) this.armParentAbort(record, signal);
+    this.armParentAbort(record, signal);
     return true;
   }
 
@@ -790,9 +977,8 @@ export class AgentManager {
    * budget's wait queue is full.
    */
   private admit(record: AgentRecord, pool: Pool | undefined): BudgetLease | undefined {
-    const depth = record.depth ?? 1;
-    assertWithinBudgetDepth(depth);
-    const lease = pool === undefined || this.poolHasRoom(pool) ? tryAcquireBudget(depth) : undefined;
+    assertWithinBudgetDepth(record.depth);
+    const lease = pool === undefined || this.poolHasRoom(pool) ? tryAcquireBudget(record.depth) : undefined;
     if (lease === undefined && !budgetHasPendingRoom()) throw new Error(BUDGET_QUEUE_FULL_ERROR);
     return lease;
   }
@@ -820,34 +1006,36 @@ export class AgentManager {
     const left = new Promise<void>(resolve => { markLeft = resolve; });
     const entry: QueueEntry = {
       id,
+      record,
       pool,
       start,
       release: () => {
         release();
         markLeft();
       },
-      cancel: () => {},
+      // enqueueBudget only registers; grant cannot run until the next pump,
+      // after this entry has been initialized and published in the queue.
+      cancel: enqueueBudget({
+        depth: record.depth,
+        ready: () => pool === undefined || this.poolHasRoom(pool),
+        grant: (lease) => {
+          this.queue = this.queue.filter(e => e !== entry);
+          if (this.agents.get(id) !== record || record.status !== "queued") {
+            releaseBudget(lease);
+            entry.release();
+            return;
+          }
+          record.budgetLease = lease;
+          // Detached, and never rejects: a late failure (e.g. strict worktree
+          // isolation) lands on the record inside `launch`. The release waits
+          // for that startup to SETTLE: a release at grant time would wake a
+          // blocked `spawnAndWait` while `record.promise` was still undefined,
+          // and it would read a healthy agent as one that never ran.
+          void entry.start().then(() => entry.release(), () => entry.release());
+        },
+      }),
       left,
     };
-    entry.cancel = enqueueBudget({
-      depth: record.depth ?? 1,
-      ready: () => pool === undefined || this.poolHasRoom(pool),
-      grant: (lease) => {
-        this.queue = this.queue.filter(e => e !== entry);
-        if (this.agents.get(id) !== record || record.status !== "queued") {
-          releaseBudget(lease);
-          entry.release();
-          return;
-        }
-        record.budgetLease = lease;
-        // Detached, and never rejects: a late failure (e.g. strict worktree
-        // isolation) lands on the record inside `launch`. The release waits
-        // for that startup to SETTLE: a release at grant time would wake a
-        // blocked `spawnAndWait` while `record.promise` was still undefined,
-        // and it would read a healthy agent as one that never ran.
-        void entry.start().then(() => entry.release(), () => entry.release());
-      },
-    });
     this.queue.push(entry);
   }
 
@@ -883,7 +1071,7 @@ export class AgentManager {
             // session about it — the same failure reported twice.
             if (failAs === "foreground") markConsumed(record, this.clock.now());
             record.status = "error";
-            record.error = err instanceof Error ? err.message : String(err);
+            record.error = errorMessage(err);
             record.completedAt = this.clock.now();
             try { this.onComplete?.(record); } catch { /* the startup failure is the error worth reporting */ }
           } else {
@@ -924,10 +1112,10 @@ export class AgentManager {
     record: AgentRecord,
     { pi, ctx, type, prompt, options }: SpawnArgs,
   ) {
-    // Re-validate a caller-supplied cwd: queued spawns can start minutes after
+    // Re-validate the cwd (caller-supplied, else the session's): 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.
-    assertValidSpawnCwd(options.cwd);
+    assertSpawnCwd(options.cwd, ctx.cwd);
     // Single resolution point for the caller-supplied cwd — the worktree base
     // repo and both cleanup calls below MUST agree on this value forever.
     const customCwd = options.cwd ?? undefined; // null (RPC "unset") → undefined
@@ -954,6 +1142,25 @@ export class AgentManager {
     record.startGate = undefined;
     this.chargePool(record.chargedPool, 1);
 
+    // Hold the pool slot BEFORE awaiting admission, just as for worktree creation.
+    try {
+      if (options.modelSelection?.tierBinding && !options.modelSelection.tierAdmitted) {
+        const block = await admitModelSelection(options.modelSelection, ctx.modelRegistry, pi.events);
+        // Admitting an unadmitted binding always resolves its `tier`.
+        record.modelTier = tierDisclosure(options.modelSelection.tier!);
+        record.modelFallback = options.modelSelection.fallback;
+        if (block) throw new Error(`${modelSelectionNote(record)} ${describeBlock(block)} The agent was not started.`);
+        if (record.abortController?.signal.aborted || options.signal?.aborted) throw new Error("Agent aborted during model admission.");
+      }
+      if (record.modelTier) {
+        record.invocation ??= {};
+        Object.assign(record.invocation, describeSelection(options.modelSelection, ctx.modelRegistry));
+      }
+    } catch (error) {
+      this.chargePool(record.chargedPool, -1);
+      throw error;
+    }
+
     // 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.
@@ -967,6 +1174,11 @@ export class AgentManager {
     const isolation = options.workflowId !== undefined
       ? options.isolation
       : getAgentConfig(type)?.isolation ?? options.isolation;
+    // A worktree exists to make edits, which a child started while planning may not.
+    if (isolation === "worktree" && record.planGate?.policy) {
+      this.chargePool(record.chargedPool, -1);
+      throw new Error('Cannot run with isolation: "worktree" while Plan mode is active: a worktree exists to make edits. Omit `isolation`, or leave Plan mode first.');
+    }
     let worktreeCwd: string | undefined;
     if (isolation === "worktree" && isWorktreeIsolationEnabled()) {
       let wt: WorktreeInfo;
@@ -974,7 +1186,7 @@ export class AgentManager {
         wt = await createWorktree(pi, baseCwd, id);
       } catch (err) {
         this.chargePool(record.chargedPool, -1);
-        const cause = err instanceof Error ? err.message : String(err);
+        const cause = errorMessage(err);
         // Only a parent-cwd spawn can be fixed by pointing `cwd` elsewhere.
         const hint = customCwd === undefined
           ? " To isolate another repo, pass its path as the `Agent` tool's `cwd`; or omit `isolation`."
@@ -1002,7 +1214,11 @@ export class AgentManager {
       // definition unchanged) worktree instead.
       if (record.status !== "running") {
         this.chargePool(record.chargedPool, -1);
-        record.worktreeResult = await cleanupWorktree(pi, baseCwd, wt, options.description);
+        recordWorktreeCleanup(record, await cleanupWorktree(pi, baseCwd, wt, options.description));
+        if (record.worktreeResult?.error) {
+          if (!record.isBackground) markConsumed(record, this.clock.now());
+          try { this.onComplete?.(record); } catch { /* do not strand the lease */ }
+        }
         // After the cleanup, not before: the copy is still being removed until here.
         this.releaseLease(record);
         this.drainQueue();
@@ -1019,8 +1235,12 @@ export class AgentManager {
       this.chargePool(record.chargedPool, -1);
       if (record.worktree) {
         try {
-          record.worktreeResult = await cleanupWorktree(pi, baseCwd, record.worktree, options.description);
-        } catch { /* ignore cleanup errors */ }
+          recordWorktreeCleanup(record, await cleanupWorktree(pi, baseCwd, record.worktree, options.description));
+        } catch { /* ignore unexpected cleanup errors */ }
+      }
+      if (record.worktreeResult?.error) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`${message}\n${record.error}`);
       }
       throw err;
     }
@@ -1033,15 +1253,20 @@ export class AgentManager {
     else this.armParentAbort(record, options.signal);
     const detach = () => this.detachParentAbort(record);
 
+    record.ranThisRun = record.status === "running";
     const promise = runAgent(ctx, type, prompt, {
       pi,
+      clock: this.clock,
+      homeDir: options.homeDir ?? this.homeDir,
       agentId: id,
-      model: options.model,
+      model: options.modelSelection?.model,
+      modelSelection: record.modelSelection!,
       maxTurns: options.maxTurns,
       isolated: options.isolated,
       inheritContext: options.inheritContext,
       thinkingLevel: options.thinkingLevel,
       structuredOutput: options.structuredOutput,
+      planGate: record.planGate,
       resumeSessionFile: options.resumeSessionFile,
       nested: options.parentAgentId !== undefined,
       workflow: options.workflowId !== undefined,
@@ -1078,7 +1303,7 @@ export class AgentManager {
       nestedRuntime: {
         manager: this,
         parentAgentId: id,
-        depth: record.depth ?? 1,
+        depth: record.depth,
         maxSubagentDepth: record.maxSubagentDepth,
       },
       onSessionCreated: (session) => {
@@ -1104,7 +1329,9 @@ export class AgentManager {
           const requested = record.invocation.requestedThinking ?? record.invocation.thinking;
           Object.assign(
             record.invocation,
-            isVirtualModel(session.model) ? describeVirtualModel(session.model) : describeModel(session.model),
+            record.modelTier?.kind === "routed" && record.modelTier.admitted
+              ? describeSelection(options.modelSelection, ctx.modelRegistry)
+              : isVirtualModel(session.model) ? describeVirtualModel(session.model) : describeModel(session.model),
           );
           // Guarded for the reason above: a session that reports no level keeps
           // the request rather than losing it. Overwriting unconditionally would
@@ -1117,6 +1344,9 @@ export class AgentManager {
             }
           }
         }
+        // The transcript says it too: it is what someone opens to find out what ran.
+        if (record.modelFallback && record.outputFile) appendModelFallbackEntry(record.outputFile, record.id, record.modelFallback);
+        if (record.modelTier && record.outputFile) appendModelTierEntry(record.outputFile, record.id, record.modelTier);
         // Flush any steers that arrived before the session was ready
         if (record.pendingSteers?.length) {
           for (const msg of record.pendingSteers) {
@@ -1155,8 +1385,8 @@ export class AgentManager {
             } catch { /* ignore — never block cleanup */ }
           }
           const wtResult = await cleanupWorktree(pi, baseCwd, record.worktree, options.description);
-          record.worktreeResult = wtResult;
-          if (wtResult.hasChanges && wtResult.branch) {
+          recordWorktreeCleanup(record, wtResult);
+          if (!wtResult.error && 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.
             // Named by its toplevel: the cwd may be a subdirectory of it.
@@ -1165,7 +1395,7 @@ export class AgentManager {
             // 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 ?? "") +
+            record.result = responseText +
               `\n\n---\nChanges saved to branch \`${wtResult.branch}\`${repoNote}. Merge with: \`git merge ${wtResult.branch}\`${customCwd !== undefined ? ` (run in \`${repo}\`)` : ""}`;
           }
         }
@@ -1180,7 +1410,7 @@ export class AgentManager {
         if (record.status !== "stopped") {
           record.status = "error";
         }
-        record.error = err instanceof Error ? err.message : String(err);
+        record.error = errorMessage(err);
         record.completedAt ??= this.clock.now();
 
         detach();
@@ -1195,7 +1425,7 @@ export class AgentManager {
         if (record.worktree) {
           try {
             const wtResult = await cleanupWorktree(pi, baseCwd, record.worktree, options.description);
-            record.worktreeResult = wtResult;
+            recordWorktreeCleanup(record, wtResult);
           } catch { /* ignore cleanup errors */ }
         }
 
@@ -1240,16 +1470,9 @@ export class AgentManager {
     // Nobody waits on a settled run; a later foreground resume must not look
     // like a spawn `sendToBackground` could hand off.
     record.blocking = false;
-    const pool = record.chargedPool;
-    this.chargePool(pool, -1);
-    // 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.
-    // The lease half: a freed budget slot may start work in any manager.
-    const drain = record.isBackground || pool !== undefined || record.budgetLease !== undefined;
+    this.chargePool(record.chargedPool, -1);
+    // Every run that reaches here holds a budget lease (each start takes one),
+    // so every settle frees a slot some queued start, in any manager, may need.
     this.releaseLease(record);
 
     try {
@@ -1262,7 +1485,7 @@ export class AgentManager {
       // Drained even when an unguarded `onComplete` throws: the slot and lease
       // are already free, and a waiter that misses this drain may be the child
       // a running parent is blocked on, with nothing else left to pump.
-      if (drain) this.drainQueue();
+      this.drainQueue();
     }
   }
 
@@ -1313,8 +1536,7 @@ export class AgentManager {
    * 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.
+   *   onSessionCreated fires.
    */
   async spawnAndWait(
     pi: ExtensionAPI,
@@ -1362,7 +1584,7 @@ export class AgentManager {
     // 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");
+      throw new Error(record.error);
     }
     return { id, record };
   }
@@ -1428,6 +1650,9 @@ export class AgentManager {
     // both paths flip the status synchronously, so a second call made in the
     // same tick is refused too. The caller decides whether to wait or steer.
     if (record.status === "running" || record.status === "queued") return undefined;
+    // Decided per run: a resume after the parent left Plan gets its full surface back.
+    // `spawn` sets `planQuery` on every record this manager holds.
+    this.decidePlanGate(record, record.planQuery!);
 
     // Background resume: settle asynchronously and notify on completion exactly
     // like a background spawn, returning immediately with the record still
@@ -1443,6 +1668,8 @@ export class AgentManager {
 
       record.isBackground = true;
       record.resultConsumed = false;
+      record.noticeDelivered = undefined;
+      record.ranThisRun = false;
       record.consumedAt = undefined;
       record.result = undefined;
       record.error = undefined;
@@ -1459,7 +1686,7 @@ export class AgentManager {
           if (occupiesPoolSlot(record)) this.runningBackground--;
           this.releaseLease(record);
           record.status = "error";
-          record.error = err instanceof Error ? err.message : String(err);
+          record.error = errorMessage(err);
           record.completedAt = this.clock.now();
           this.drainQueue();
           throw err;
@@ -1490,6 +1717,8 @@ export class AgentManager {
     // its limit; the caller's signal (or `/agents` stop) releases the wait.
     // No pool: the foreground pool does not cover resumes (see the README).
     const lease = this.admit(record, undefined);
+    record.ranThisRun = false;
+    record.noticeDelivered = undefined;
     record.status = lease === undefined ? "queued" : "running";
     record.budgetLease = lease;
     record.startedAt = this.clock.now();
@@ -1532,13 +1761,17 @@ export class AgentManager {
           record.status = "stopped";
           record.completedAt = this.clock.now();
         }
+        markConsumed(record, this.clock.now());
         this.detachParentAbort(record);
         return record;
       }
     }
 
     try {
+      // Positive evidence for the reap notice: only a live signal means the prompt runs.
+      record.ranThisRun = record.status === "running";
       this.settleOutcome(record, await resumeAgent(record.session, prompt, {
+        clock: this.clock,
         type: record.type,
         maxTurns: options?.maxTurns ?? record.invocation?.maxTurns,
         onTurnEnd: options?.onTurnEnd,
@@ -1565,6 +1798,8 @@ export class AgentManager {
       this.failResume(record, err);
     }
     this.detachParentAbort(record);
+    // The caller gets the settled record inline, whatever the outcome.
+    markConsumed(record, this.clock.now());
 
     // Same contract as the spawn settle paths: children spawned during the
     // resumed turn must not outlive it — nothing else can see or reach them.
@@ -1605,7 +1840,7 @@ export class AgentManager {
   private failResume(record: AgentRecord, err: unknown): void {
     if (record.status !== "stopped") {
       record.status = "error";
-      record.error = err instanceof Error ? err.message : String(err);
+      record.error = errorMessage(err);
     }
     record.completedAt ??= this.clock.now();
   }
@@ -1670,7 +1905,9 @@ export class AgentManager {
       this.drainQueue();
     };
 
+    record.ranThisRun = true;
     const promise = resumeAgent(record.session, prompt, {
+      clock: this.clock,
       type: record.type,
       maxTurns: options.maxTurns ?? record.invocation?.maxTurns,
       onTurnEnd: options.onTurnEnd,
@@ -1736,9 +1973,15 @@ export class AgentManager {
     return this.agents.get(id);
   }
 
+  /**
+   * Handles held outside this manager, e.g. by live survivors of an orphaned one, which a fresh
+   * spawn must not reuse: a listener keys lifecycle events by handle, so a twin would mix the two up.
+   */
+  reservedHandles: () => Iterable<string> = () => [];
+
   /** Handles already in use, so a fresh spawn can pick an unclaimed one. */
   private takenHandles(): Set<string> {
-    const taken = new Set<string>();
+    const taken = new Set<string>(this.reservedHandles());
     for (const record of this.agents.values()) {
       if (record.handle) taken.add(record.handle);
       if (record.alias) taken.add(record.alias);
@@ -1754,23 +1997,19 @@ export class AgentManager {
   }
 
   /**
-   * 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.
+   * Resolve an `@name` from the prompt. Matches a top-level agent's handle or
+   * alias case-insensitively, 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;
+      // Handle and alias share one lowercase namespace (`takenHandles`, and a
+      // reopen reclaims the evicted record's own names), so at most one agent
+      // answers a name and it makes no difference which of the two matched.
+      if (record.handle === wanted || record.alias === wanted) return { kind: "live", 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,
@@ -1807,7 +2046,14 @@ export class AgentManager {
     );
   }
 
-  abort(id: string): boolean {
+  /**
+   * Stop a running or queued agent; false when it was neither.
+   *
+   * @param by `"parent"` when the agent that spawned it asked (`stop_subagent`);
+   *   omitted for a human stop. Written on every stop, so a resumed record never
+   *   carries an earlier run's answer.
+   */
+  abort(id: string, by?: AgentRecord["stoppedBy"]): boolean {
     const record = this.agents.get(id);
     if (!record) return false;
 
@@ -1816,20 +2062,29 @@ export class AgentManager {
     // 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";
-      record.completedAt = this.clock.now();
+      record.stoppedBy = by;
+      this.stopQueued(record);
       return true;
     }
 
     if (record.status !== "running") return false;
+    // Before the abort: the run settles asynchronously and its notice reads this.
+    record.stoppedBy = by;
     record.abortController?.abort();
     record.status = "stopped";
     record.completedAt = this.clock.now();
     return true;
   }
 
+  /** Mark a dequeued record stopped and tell `onQueuedStop`; the queue entry is already gone. */
+  private stopQueued(record: AgentRecord): void {
+    record.status = "stopped";
+    record.completedAt = this.clock.now();
+    this.onQueuedStop?.(record);
+  }
+
   /** Dispose a record's session and remove it from the map. */
-  private removeRecord(id: string, record: AgentRecord): void {
+  private removeRecord(id: string, record: SettledRecord): void {
     this.tombstone(record);
     this.noteEviction(record);
     const session = record.session;
@@ -1852,17 +2107,63 @@ export class AgentManager {
    * 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, {
+  private tombstone(record: SettledRecord): void {
+    const entry = this.tombstoneOf(record);
+    if (entry) this.storeTombstone(entry);
+  }
+
+  /** What `@handle` needs to reopen `record`'s conversation; undefined without a handle and a session file. */
+  private tombstoneOf(record: SettledRecord): AgentTombstone | undefined {
+    if (!record.handle || !record.sessionFile) return undefined;
+    return {
       handle: record.handle,
       alias: record.alias,
       id: record.id,
       type: record.type,
       description: record.description,
       sessionFile: record.sessionFile,
-      completedAt: record.completedAt ?? this.clock.now(),
-    });
+      completedAt: record.completedAt,
+      ...(record.modelTier ? { modelTier: record.modelTier } : {}),
+      ...(record.modelFallback ? { modelFallback: record.modelFallback } : {}),
+    };
+  }
+
+  /** Tombstones for whichever of `ids` are settled here and reopenable, to hand to a session that will never see these records. */
+  evictionTombstones(ids: readonly string[]): AgentTombstone[] {
+    return [...this.agents.values()]
+      .filter(isSettled)
+      .filter(record => isTopLevelAgent(record) && ids.includes(record.id))
+      .flatMap(record => this.tombstoneOf(record) ?? []);
+  }
+
+  /**
+   * Keep `entry` reopenable by handle, alias and id. Also how an agent that settled in an
+   * orphaned manager (`/new`, `/reload`) stays reopenable here (#330). A name already held
+   * by another live agent, an evicted conversation or a handle reserved for another manager's
+   * survivor stays with its holder (as `takenHandles` has it): two conversations must not
+   * answer to one `@name`. The entry is then not kept and its note says why.
+   */
+  rememberTombstone(entry: AgentTombstone): void {
+    const names = [entry.handle, ...(entry.alias ? [entry.alias] : [])];
+    const reserved = new Set<string>(this.reservedHandles());
+    const owns = (own: { id: string; handle?: string; alias?: string }, name: string) =>
+      own.id !== entry.id && (name === own.handle || name === own.alias);
+    const taken = names.find(
+      name =>
+        reserved.has(name) ||
+        [...this.agents.values()].some(own => owns(own, name)) ||
+        [...this.tombstones.values()].some(own => owns(own, name)),
+    );
+    if (taken !== undefined) {
+      const note = this.evictedNotes.get(entry.id);
+      if (note) note.nameTaken = taken;
+      return;
+    }
+    this.storeTombstone(entry);
+  }
+
+  private storeTombstone(entry: AgentTombstone): void {
+    this.tombstones.set(entry.handle, entry);
     // 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) {
@@ -1872,24 +2173,68 @@ export class AgentManager {
   }
 
   /** Remember that `record` existed, so its id still answers with something better than "not found". */
-  private noteEviction(record: AgentRecord): void {
-    const completedAt = record.completedAt ?? this.clock.now();
-    this.evictedNotes.delete(record.id);
-    this.evictedNotes.set(record.id, {
+  private noteEviction(record: SettledRecord): void {
+    // Only the top-level tools read notes, and an owned child (nested or a
+    // workflow's) must stay unreachable from them after eviction as before it.
+    if (!isTopLevelAgent(record)) return;
+    this.rememberEvicted(this.evictionNote(record));
+  }
+
+  /** Notes for whichever of `ids` are settled here, to hand to a session that will never see these records. */
+  evictionNotes(ids: readonly string[]): EvictedNote[] {
+    return [...this.agents.values()].filter(isSettled).filter(record => isTopLevelAgent(record) && ids.includes(record.id)).map(record => this.evictionNote(record));
+  }
+
+  /** What a settled record leaves behind once it is gone from this manager. */
+  private evictionNote(record: SettledRecord): EvictedNote {
+    return {
       id: record.id,
       type: record.type,
       description: record.description,
       status: record.status,
-      evictedAfterMin: Math.max(0, Math.round((this.clock.now() - completedAt) / 60_000)),
+      evictedAfterMin: Math.max(0, Math.round((this.clock.now() - record.completedAt) / 60_000)),
       transcript: record.outputFile ?? record.sessionFile,
-    });
-    while (this.evictedNotes.size > MAX_EVICTED_NOTES) {
-      const oldest = this.evictedNotes.keys().next().value;
-      if (oldest === undefined) break;
+      ...(record.modelTier ? { modelTier: record.modelTier } : {}),
+      ...(record.modelFallback ? { modelFallback: record.modelFallback } : {}),
+    };
+  }
+
+  /**
+   * Keep `note` addressable by its id, bounded by age. Also how a result handed
+   * over by an orphaned manager (`/new`, `/reload`) stays answerable here: the
+   * record settled in a manager this one never saw (#330).
+   */
+  rememberEvicted(note: EvictedNote): void {
+    this.evictedNotes.delete(note.id);
+    this.evictedNotes.set(note.id, note);
+    // Insertion order is age order (the note was just re-inserted above).
+    for (const oldest of this.evictedNotes.keys()) {
+      if (this.evictedNotes.size <= MAX_EVICTED_NOTES) break;
       this.evictedNotes.delete(oldest);
     }
   }
 
+  /** Record that evicted `id` was reopened as `next`; bounded like the eviction notes. */
+  linkSuccessor(id: string, next: string): void {
+    this.successors.delete(id);
+    this.successors.set(id, next);
+    // One link per call, so at most one over the bound: drop the oldest.
+    if (this.successors.size > MAX_EVICTED_NOTES) this.successors.delete(this.successors.keys().next().value as string);
+  }
+
+  /** Forget a reopen that never started, so `id` resolves to its tombstone again. */
+  unlinkSuccessor(id: string): void {
+    this.successors.delete(id);
+  }
+
+  /** The newest id `id` continues under, following every reopen; `id` itself when never reopened. */
+  latestId(id: string): string {
+    // Acyclic: every successor is a freshly generated id.
+    let current = id;
+    for (let next = this.successors.get(current); next !== undefined; next = this.successors.get(current)) current = next;
+    return current;
+  }
+
   /** What became of an evicted agent, by id; undefined for an id this session never evicted. */
   getEvictedNote(id: string): EvictedNote | undefined {
     return this.evictedNotes.get(id);
@@ -1904,12 +2249,21 @@ export class AgentManager {
   private cleanup() {
     const now = this.clock.now();
     for (const [id, record] of this.agents) {
-      if (record.status === "running" || record.status === "queued") continue;
-      const completedAt = record.completedAt ?? 0;
+      if (!isSettled(record)) continue;
+      const { completedAt } = record;
       const expired = record.resultConsumed
         ? now - (record.consumedAt ?? completedAt) >= this.consumedTtlMs
         : now - completedAt >= this.unreadTtlMs;
-      if (expired) this.removeRecord(id, record);
+      if (!expired) continue;
+      const ran = record.ranThisRun === true && (record.result !== undefined || record.error !== undefined);
+      this.removeRecord(id, record);
+      // Evicting a result nobody read is a loss the parent must hear about. Owned
+      // children never leave a note, and only their owner could have read them.
+      // Nothing was lost when the parent saw the completion notice (a failure's
+      // stays unread in FleetView), or when no run produced a result (stopped in
+      // the queue, refused, or failed before the runner started).
+      const note = record.resultConsumed || record.noticeDelivered || !ran ? undefined : this.evictedNotes.get(id);
+      if (note) this.onReaped?.(note);
     }
   }
 
@@ -1921,7 +2275,7 @@ export class AgentManager {
    */
   clearCompleted(skipUnconsumed = false): void {
     for (const [id, record] of this.agents) {
-      if (record.status === "running" || record.status === "queued") continue;
+      if (!isSettled(record)) continue;
       if (skipUnconsumed && !record.resultConsumed) continue;
       this.removeRecord(id, record);
     }
@@ -1934,6 +2288,7 @@ export class AgentManager {
     this.tombstones.clear();
     // Ids are only meaningful within the session that issued them.
     this.evictedNotes.clear();
+    this.successors.clear();
   }
 
   /** Whether any agents are still running or queued. */
@@ -1943,6 +2298,22 @@ export class AgentManager {
     );
   }
 
+  /**
+   * The session's own agents (see `isTopLevelAgent`) still running or queued,
+   * split by whether their completion wakes the parent. A background agent's
+   * settle sends a completion notice that starts a turn, in every join mode;
+   * a foreground one, or an RPC spawn that omits `isBackground`, is marked
+   * consumed at settle and notifies nobody. Owned children report through their owner, so counting
+   * them would double-count the same work.
+   */
+  ownedPending(): OwnedPending {
+    const pending = [...this.agents.values()].filter(
+      r => isTopLevelAgent(r) && (r.status === "running" || r.status === "queued"),
+    );
+    const notifying = pending.filter(r => r.isBackground).length;
+    return { notifying, silent: pending.length - notifying };
+  }
+
   /**
    * Abort everything that cannot outlive its session and let the rest finish.
    * Survivors are running top-level background agents and their nested children:
@@ -1956,19 +2327,11 @@ export class AgentManager {
    * @returns how many agents keep running.
    */
   detach(): number {
-    const keepQueued = (id: string): boolean => {
-      const record = this.agents.get(id);
-      return record !== undefined && record.parentAgentId !== undefined && record.workflowId === undefined;
-    };
-    for (const queued of this.queue) {
-      if (keepQueued(queued.id)) continue;
-      const record = this.agents.get(queued.id);
-      if (record) {
-        record.status = "stopped";
-        record.completedAt = this.clock.now();
-      }
-    }
-    this.dequeue(entry => !keepQueued(entry.id));
+    const keepQueued = ({ record }: QueueEntry): boolean =>
+      record.parentAgentId !== undefined && record.workflowId === undefined;
+    const dropped = this.queue.filter(entry => !keepQueued(entry)).map(({ record }) => record);
+    this.dequeue(entry => !keepQueued(entry));
+    for (const record of dropped) this.stopQueued(record);
     let survivors = 0;
     for (const record of this.agents.values()) {
       if (record.status !== "running") continue;
@@ -1988,15 +2351,12 @@ export class AgentManager {
   abortAll(): number {
     let count = 0;
     // Clear queued agents first
-    for (const queued of this.queue) {
-      const record = this.agents.get(queued.id);
-      if (record) {
-        record.status = "stopped";
-        record.completedAt = this.clock.now();
-        count++;
-      }
-    }
+    const dropped = this.queue.map(({ record }) => record);
     this.dequeue(() => true);
+    for (const record of dropped) {
+      this.stopQueued(record);
+      count++;
+    }
     // Abort running agents
     for (const record of this.agents.values()) {
       if (record.status === "running") {