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

package/src/agent-manager.ts

@@ -21,19 +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, 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,
@@ -49,7 +51,7 @@ 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
@@ -70,8 +72,26 @@ function relabelFromResponse(record: AgentRecord, message: AssistantMessageInfo
   }
 }
 
+/** 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
@@ -175,6 +195,8 @@ export interface EvictedNote {
   /** 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. */
@@ -214,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
@@ -277,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>;
@@ -331,6 +399,8 @@ interface SpawnOptions {
   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;
@@ -401,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,
@@ -553,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;
@@ -583,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
@@ -616,9 +692,13 @@ export class AgentManager {
     onSteered?: OnAgentSteered,
     private readonly clock: Clock = realClock,
     private readonly homeDir?: string,
+    onQueuedStop?: OnAgentQueuedStop,
+    onReaped?: OnAgentReaped,
   ) {
     this.onComplete = onComplete;
     this.onStart = onStart;
+    this.onQueuedStop = guardObserver("queued stop", onQueuedStop);
+    this.onReaped = guardObserver("reaped", onReaped);
     this.onCompact = guardObserver("compaction", onCompact);
     this.onUsage = guardObserver("usage", onUsage);
     this.onSteered = onSteered;
@@ -632,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);
@@ -699,7 +804,7 @@ 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,
@@ -740,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
@@ -757,18 +863,22 @@ export class AgentManager {
       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 };
@@ -784,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.
@@ -792,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,
@@ -822,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;
   }
 
@@ -863,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;
   }
@@ -893,6 +1006,7 @@ export class AgentManager {
     const left = new Promise<void>(resolve => { markLeft = resolve; });
     const entry: QueueEntry = {
       id,
+      record,
       pool,
       start,
       release: () => {
@@ -902,7 +1016,7 @@ export class AgentManager {
       // 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 ?? 1,
+        depth: record.depth,
         ready: () => pool === undefined || this.poolHasRoom(pool),
         grant: (lease) => {
           this.queue = this.queue.filter(e => e !== entry);
@@ -957,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 {
@@ -998,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
@@ -1032,7 +1146,8 @@ export class AgentManager {
     try {
       if (options.modelSelection?.tierBinding && !options.modelSelection.tierAdmitted) {
         const block = await admitModelSelection(options.modelSelection, ctx.modelRegistry, pi.events);
-        record.modelTier = options.modelSelection.tier ? tierDisclosure(options.modelSelection.tier) : undefined;
+        // 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.");
@@ -1059,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;
@@ -1066,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`."
@@ -1094,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();
@@ -1111,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;
     }
@@ -1125,8 +1253,10 @@ 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.modelSelection?.model,
@@ -1136,6 +1266,7 @@ export class AgentManager {
       inheritContext: options.inheritContext,
       thinkingLevel: options.thinkingLevel,
       structuredOutput: options.structuredOutput,
+      planGate: record.planGate,
       resumeSessionFile: options.resumeSessionFile,
       nested: options.parentAgentId !== undefined,
       workflow: options.workflowId !== undefined,
@@ -1172,7 +1303,7 @@ export class AgentManager {
       nestedRuntime: {
         manager: this,
         parentAgentId: id,
-        depth: record.depth ?? 1,
+        depth: record.depth,
         maxSubagentDepth: record.maxSubagentDepth,
       },
       onSessionCreated: (session) => {
@@ -1254,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.
@@ -1264,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}\`)` : ""}`;
           }
         }
@@ -1279,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();
@@ -1294,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 */ }
         }
 
@@ -1339,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 {
@@ -1361,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();
     }
   }
 
@@ -1412,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,
@@ -1461,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 };
   }
@@ -1527,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
@@ -1542,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;
@@ -1558,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;
@@ -1589,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();
@@ -1631,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,
@@ -1664,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.
@@ -1704,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();
   }
@@ -1769,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,
@@ -1835,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);
@@ -1853,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,
@@ -1906,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;
 
@@ -1915,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;
@@ -1951,19 +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) {
@@ -1973,26 +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,
       ...(record.modelTier ? { modelTier: record.modelTier } : {}),
       ...(record.modelFallback ? { modelFallback: record.modelFallback } : {}),
-    });
-    while (this.evictedNotes.size > MAX_EVICTED_NOTES) {
-      const oldest = this.evictedNotes.keys().next().value;
-      if (oldest === undefined) break;
+    };
+  }
+
+  /**
+   * 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);
@@ -2007,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);
     }
   }
 
@@ -2024,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);
     }
@@ -2037,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. */
@@ -2046,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:
@@ -2059,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;
@@ -2091,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") {