@kushalkhemka/opensec-pi-subagents 0.20.2 → 0.20.3

package/dist/agent-manager.js

@@ -17,11 +17,30 @@ import { randomUUID } from "node:crypto";
 import { existsSync, statSync } from "node:fs";
 import { isAbsolute } from "node:path";
 import { resumeAgent, runAgent } from "./agent-runner.js";
+import { getAgentConfig } from "./agent-types.js";
 import { assignHandle, handleBase } from "./mention.js";
 import { describeModel } from "./model-resolver.js";
 import { sessionFileProblem } from "./session-file.js";
+import { sessionFileOf, snapshotContext } from "./session-handoff.js";
 import { addUsage } from "./usage.js";
 import { cleanupWorktree, createWorktree, isWorktreeIsolationEnabled, pruneWorktrees, restoreWorktree } from "./worktree.js";
+/**
+ * This module's {@link ManagerServices}, for an instance adopting a manager
+ * built by another copy. Getters, so each import is read only when used.
+ */
+export function managerServices() {
+    return {
+        get runAgent() { return runAgent; },
+        get resumeAgent() { return resumeAgent; },
+        get createWorktree() { return createWorktree; },
+        get cleanupWorktree() { return cleanupWorktree; },
+        get restoreWorktree() { return restoreWorktree; },
+        get isWorktreeIsolationEnabled() { return isWorktreeIsolationEnabled; },
+        get pruneWorktrees() { return pruneWorktrees; },
+        get sessionFileProblem() { return sessionFileProblem; },
+        get getAgentConfig() { return getAgentConfig; },
+    };
+}
 /**
  * Default max concurrent background agents.
  *
@@ -50,6 +69,11 @@ const DEFAULT_MAX_CONCURRENT_FOREGROUND = 0;
  * far above the handful anyone keeps in their head.
  */
 const MAX_TOMBSTONES = 100;
+/**
+ * The same bound for owned children — nested agents and workflow children —
+ * counted apart, so a large workflow cannot push the session's own agents out.
+ */
+const MAX_OWNED_TOMBSTONES = 200;
 /**
  * Validate a caller-supplied SpawnOptions.cwd. `undefined`/`null` mean "unset"
  * (parent cwd). Anything else must be an absolute path to an existing
@@ -260,6 +284,7 @@ export function resumeStateOf(record) {
         maxSubagentDepth: record.maxSubagentDepth,
         rootSessionId: record.rootSessionId,
         model: record.invocation?.modelId,
+        thinking: record.invocation?.thinking,
         cwd: record.cwd,
         baseCwd: record.baseCwd,
         isolated: record.isolated,
@@ -269,16 +294,25 @@ export function resumeStateOf(record) {
         worktreeResult: record.worktreeResult ? { ...record.worktreeResult } : undefined,
     };
 }
+/** Session entry a top-level agent's final record goes into (with its resume state). */
+export const RECORD_ENTRY_TYPE = "subagents:record";
 /**
- * The resume states a session's `subagents:record` entries carry, oldest
- * first. Entries written before they carried one, or malformed ones, are
- * skipped: there is nothing to reopen them from.
+ * Session entry an owned child's resume state goes into: a nested agent's or a
+ * workflow's. Kept apart from {@link RECORD_ENTRY_TYPE}, which other extensions
+ * read as the session's own agents, while an owned child reports only through
+ * its owner. Carries the resume state alone, so it stays small.
+ */
+export const RESUME_ENTRY_TYPE = "subagents:resume";
+/**
+ * The resume states a session's `subagents:record` and `subagents:resume`
+ * entries carry, oldest first. Entries written before they carried one, or
+ * malformed ones, are skipped: there is nothing to reopen them from.
  */
 export function resumeStatesFromEntries(entries) {
     const out = [];
     for (const entry of entries) {
         const e = entry;
-        if (e?.type !== "custom" || e.customType !== "subagents:record")
+        if (e?.type !== "custom" || (e.customType !== RECORD_ENTRY_TYPE && e.customType !== RESUME_ENTRY_TYPE))
             continue;
         const state = e.data?.resume;
         if (typeof state?.id !== "string" || typeof state.type !== "string"
@@ -288,6 +322,8 @@ export function resumeStatesFromEntries(entries) {
     }
     return out;
 }
+/** The manager's own module functions, read lazily (see {@link managerServices}). */
+const DEFAULT_SERVICES = managerServices();
 export class AgentManager {
     agents = new Map();
     cleanupInterval;
@@ -347,6 +383,20 @@ export class AgentManager {
     /** Pending releases, by record. */
     releaseTimers = new Map();
     sessionReleaseMs = DEFAULT_SESSION_RELEASE_MS;
+    /** Set by an instance that adopted this manager; see {@link ManagerServices}. */
+    services;
+    /**
+     * The session whose agents the top-level surfaces show (`listAgents`,
+     * `resolveMention`, `hasRunning`, `waitForAll`). `null`: every agent — the
+     * default, and the only mode before a session has started.
+     */
+    visibleOwner = null;
+    /**
+     * Arguments of spawns that have not reached `runAgent` yet (queued, or still
+     * creating their worktree), so a session switch can swap their context for a
+     * frozen copy before Pi invalidates it.
+     */
+    pendingArgs = new Map();
     constructor(onComplete, maxConcurrent = DEFAULT_MAX_CONCURRENT, onStart, onCompact, onUsage) {
         this.onComplete = onComplete;
         this.onStart = onStart;
@@ -357,6 +407,42 @@ export class AgentManager {
         this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
         this.cleanupInterval.unref();
     }
+    /** Replace what the extension observes of this manager's agents (an adopting instance, or parking). */
+    setObservers(observers) {
+        this.onComplete = observers.onComplete;
+        this.onStart = observers.onStart;
+        this.onCompact = observers.onCompact;
+        this.onUsage = observers.onUsage;
+    }
+    /** Run new work with these module functions; see {@link ManagerServices}. */
+    useServices(services) {
+        this.services = services;
+    }
+    svc() {
+        return this.services ?? DEFAULT_SERVICES;
+    }
+    /**
+     * Show only the agents of this session (its file; undefined for one in
+     * memory) on the top-level surfaces, or every agent with `null`. Agents of
+     * other sessions keep running and are reachable by id internally — their
+     * nested tools, the workflow host — just not listed or addressable here.
+     */
+    setVisibleOwner(owner) {
+        this.visibleOwner = owner;
+    }
+    /** Whether the record belongs to the session the surfaces show. */
+    isVisible(record) {
+        return this.visibleOwner === null || record.ownerSession === this.visibleOwner;
+    }
+    /**
+     * Before a session switch: give every spawn that has not started its run yet
+     * a frozen copy of its context, since Pi invalidates the live one (every read
+     * throws) and the spawn reads it when it starts.
+     */
+    detachPendingContexts() {
+        for (const args of this.pendingArgs.values())
+            args.ctx = snapshotContext(args.ctx);
+    }
     /** Update the max concurrent background agents limit. */
     setMaxConcurrent(n) {
         this.maxConcurrent = Math.max(1, n);
@@ -478,6 +564,9 @@ export class AgentManager {
         if (run.settled)
             return;
         run.settled = true;
+        // Nobody waits on a settled run; a later foreground resume must not look
+        // like a spawn `sendToBackground` could hand off.
+        run.record.blocking = false;
         if (run.graceTimer)
             clearTimeout(run.graceTimer);
         if (this.runs.get(run.id) === run)
@@ -650,6 +739,11 @@ export class AgentManager {
             maxSubagentDepth: options.maxSubagentDepth,
             rootSessionId: options.rootSessionId,
             isolated: options.isolated,
+            // An owned child belongs where its root does: its ctx is its parent
+            // agent's own session, not the user's.
+            ownerSession: options.parentAgentId !== undefined
+                ? this.agents.get(options.parentAgentId)?.ownerSession
+                : sessionFileOf(ctx),
         };
         this.agents.set(id, record);
         // After the insert, so `takenHandles()` already counts this record's own
@@ -659,6 +753,7 @@ export class AgentManager {
             record.alias = assignHandle(handleBase(options.name), this.takenHandles());
         }
         const args = { pi, ctx, type, prompt, options };
+        this.pendingArgs.set(id, args);
         const pool = this.poolFor(record);
         if (pool !== undefined && !options.bypassQueue && !this.poolHasRoom(pool)) {
             // Queue it — started when a running agent in the same pool completes.
@@ -693,23 +788,40 @@ export class AgentManager {
      * an aborted signal, so a `spawnAndWait` on it would wait forever — pi has no
      * tool-execution timeout to bail it out.
      *
-     * The listener is left in place when the agent starts. `startAgent` adds its
-     * own, so both fire on a later abort, but `abort()` on an already-stopped
-     * record is a no-op — so detaching would only be tidiness, and tidiness the
-     * `abortAll`/`dispose` paths could not offer anyway.
+     * The listener is removable (`record.detachParentAbort`): `startAgent`
+     * 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.
      */
     armQueuedAbort(id, signal) {
         if (signal === undefined)
             return true;
+        const record = this.agents.get(id);
         if (signal.aborted) {
-            const record = this.agents.get(id);
             if (record)
                 this.stopQueued(record);
             return false;
         }
-        signal.addEventListener("abort", () => this.abort(id), { once: true });
+        if (record)
+            this.armParentAbort(record, signal);
         return true;
     }
+    /**
+     * Stop `record` when its caller's `signal` aborts, replacing any listener an
+     * earlier stage armed — at most one is live per record, so one call to
+     * `detachParentAbort` cuts the run loose from its caller.
+     */
+    armParentAbort(record, signal) {
+        this.detachParentAbort(record);
+        if (signal === undefined)
+            return;
+        const onParentAbort = () => this.abort(record.id);
+        signal.addEventListener("abort", onParentAbort, { once: true });
+        record.detachParentAbort = () => signal.removeEventListener("abort", onParentAbort);
+    }
+    detachParentAbort(record) {
+        record.detachParentAbort?.();
+        record.detachParentAbort = undefined;
+    }
     /**
      * Kick off an agent's startup and register it under `startups`. The returned
      * promise never rejects — the failure is delivered through `awaitStartup`,
@@ -724,8 +836,9 @@ export class AgentManager {
      *   handle goes back.
      */
     launch(id, record, args, queuedPool) {
-        const startup = this.startAgent(id, record, args).then(() => { this.startups.delete(id); }, (err) => {
+        const startup = this.startAgent(id, record, args).then(() => { this.startups.delete(id); this.dropPendingArgs(id, args); }, (err) => {
             this.startups.delete(id);
+            this.dropPendingArgs(id, args);
             if (queuedPool !== undefined) {
                 // Mirrors endRun: an inline caller gets this failure as a throw
                 // out of spawnAndWait, so an unconsumed record would ALSO nudge the
@@ -751,6 +864,10 @@ export class AgentManager {
         // (drainQueue) that swallowed promise.
         return startup.catch(() => { });
     }
+    dropPendingArgs(id, args) {
+        if (this.pendingArgs.get(id) === args)
+            this.pendingArgs.delete(id);
+    }
     /**
      * Resolves once the agent is actually running, and rejects with the startup
      * failure (strict worktree isolation) that `spawn()` used to throw before the
@@ -764,7 +881,13 @@ export class AgentManager {
         return this.startups.get(id) ?? Promise.resolve();
     }
     /** Actually start an agent (called immediately or from queue drain). */
-    async startAgent(id, record, { pi, ctx, type, prompt, options }) {
+    async startAgent(id, record, args) {
+        // `args.ctx` is read again where the run starts, not destructured here: a
+        // session switch during the worktree copy swaps it for a frozen copy.
+        const { pi, type, prompt, options } = args;
+        const ctx = args.ctx;
+        // The functions this run starts and settles with, fixed for its lifetime.
+        const svc = this.svc();
         // Re-validate a caller-supplied cwd: queued spawns can start minutes after
         // spawn()'s check, and the directory may be gone by then (TOCTOU). Same
         // curated errors; drainQueue parks a throw on the record as an error.
@@ -772,7 +895,8 @@ export class AgentManager {
         // 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
-        const baseCwd = customCwd ?? ctx.cwd;
+        const sessionCwd = ctx.cwd;
+        const baseCwd = customCwd ?? sessionCwd;
         // Take the running state — and with it the concurrency slot — BEFORE the
         // first await. Creating a worktree is an awaited git call, and drainQueue
         // reads the pool counters synchronously in a loop: incrementing after the
@@ -809,7 +933,7 @@ export class AgentManager {
             this.releaseRunSlot(run);
             this.drainQueue();
             try {
-                record.worktreeResult = await cleanupWorktree(pi, baseCwd, wt, options.description);
+                record.worktreeResult = await svc.cleanupWorktree(pi, baseCwd, wt, options.description);
             }
             catch { /* best effort */ }
             this.endRun(run);
@@ -820,17 +944,26 @@ export class AgentManager {
         // The project switch is enforced here as well as at the tool boundary
         // because cross-extension RPC forwards its options unvalidated — a schema
         // that omits the field can't stop a caller that never saw the schema.
+        // The agent file's `isolation:` is resolved here too, not by each caller:
+        // mentions pass none, and RPC forwards only its caller's value. Workflow
+        // children are the exception, as in Claude Code, whose workflow agent()
+        // reads only the script's option and ignores the definition's. So is an
+        // agent reopened from its session file: it continues where it ran, and a
+        // worktree it ran in comes back through `restoreWorktree` below.
+        const isolation = options.workflowId !== undefined || options.resumeSessionFile !== undefined
+            ? options.isolation
+            : svc.getAgentConfig(type)?.isolation ?? options.isolation;
         let worktreeCwd;
         // What an earlier run of a reopened agent left on its branch. A resumed
         // run that changes nothing keeps reporting that, not "no changes".
         const priorWorktreeResult = options.restoreWorktree?.prior;
         if (options.restoreWorktree) {
-            if (!isWorktreeIsolationEnabled()) {
+            if (!svc.isWorktreeIsolationEnabled()) {
                 this.discardRun(run);
                 throw new Error(`Cannot resume agent ${id}: it ran in a git worktree, and worktree isolation is turned off in this project.`);
             }
             const wt = { ...options.restoreWorktree.worktree };
-            const error = await restoreWorktree(pi, baseCwd, wt, priorWorktreeResult);
+            const error = await svc.restoreWorktree(pi, baseCwd, wt, priorWorktreeResult);
             if (error) {
                 this.discardRun(run);
                 throw new Error(`Cannot resume agent ${id} in its git worktree: ${error}. Nothing was run.`);
@@ -844,8 +977,8 @@ export class AgentManager {
                 return;
             }
         }
-        else if (options.isolation === "worktree" && isWorktreeIsolationEnabled()) {
-            const wt = await createWorktree(pi, baseCwd, id);
+        else if (isolation === "worktree" && svc.isWorktreeIsolationEnabled()) {
+            const wt = await svc.createWorktree(pi, baseCwd, id);
             if (!wt) {
                 this.discardRun(run);
                 throw new Error('Cannot run with isolation: "worktree" — not a git repo, no commits yet, or `git worktree add` failed. ' +
@@ -860,6 +993,10 @@ export class AgentManager {
             // subdirectory, silently dropping extensions/skills.
             worktreeCwd = customCwd !== undefined ? wt.workPath : wt.path;
             this.worktreeRepos.add(baseCwd);
+            // The widget's "worktree" tag reads this; only callers that resolve the
+            // agent file themselves seed it.
+            record.invocation ??= {};
+            record.invocation.isolation = "worktree";
             // No longer "running" means a stop landed while the copy was being made
             // (abort(), abortAll()) — a window that did not exist when creation was
             // synchronous. The record is already terminal, so launching the run would
@@ -875,22 +1012,16 @@ export class AgentManager {
             this.onStart?.(record);
         }
         catch { /* a start observer must not fail the run */ }
-        // Wire parent abort signal to stop the subagent when the parent is interrupted
-        let detachParentSignal;
-        if (options.signal) {
-            // A queued spawn can start minutes after the caller handed us its signal,
-            // by which time it may already be aborted — and `addEventListener` would
-            // never fire, leaving a child the parent can no longer reach.
-            if (options.signal.aborted)
-                this.abort(id);
-            else {
-                const onParentAbort = () => this.abort(id);
-                options.signal.addEventListener("abort", onParentAbort, { once: true });
-                detachParentSignal = () => options.signal.removeEventListener("abort", onParentAbort);
-            }
-        }
-        const detach = () => { detachParentSignal?.(); detachParentSignal = undefined; };
-        const promise = runAgent(ctx, type, prompt, {
+        // Wire parent abort signal to stop the subagent when the parent is interrupted.
+        // A queued spawn can start minutes after the caller handed us its signal,
+        // by which time it may already be aborted — and `addEventListener` would
+        // never fire, leaving a child the parent can no longer reach.
+        if (options.signal?.aborted)
+            this.abort(id);
+        else
+            this.armParentAbort(record, options.signal);
+        const detach = () => this.detachParentAbort(record);
+        const promise = svc.runAgent(args.ctx, type, prompt, {
             pi,
             agentId: id,
             model: options.model,
@@ -911,7 +1042,7 @@ export class AgentManager {
             // Set iff a worktree was created (see above) — names the directory the
             // copy came from, so the prompt can tell the agent not to work there.
             worktreeBase: worktreeCwd ? baseCwd : undefined,
-            configCwd: options.configCwd ?? (customCwd !== undefined ? ctx.cwd : undefined),
+            configCwd: options.configCwd ?? (customCwd !== undefined ? sessionCwd : undefined),
             signal: record.abortController.signal,
             onToolActivity: (activity) => {
                 if (activity.type === "end")
@@ -982,7 +1113,12 @@ export class AgentManager {
                     }
                     record.pendingSteers = undefined;
                 }
-                options.onSessionCreated?.(session);
+                // A caller's wiring must not fail the run (it may read a ctx a session
+                // switch has since invalidated).
+                try {
+                    options.onSessionCreated?.(session);
+                }
+                catch { /* ignore caller wiring errors */ }
             },
         })
             .then(async ({ responseText, session, aborted, steered, failure, structuredJson, structuredRetried, maxTurns }) => {
@@ -1029,7 +1165,7 @@ export class AgentManager {
                 // The hook runs inside cleanup: after the child's changes are
                 // committed and while its tree still exists; what it changes is
                 // discarded, so a gate's output never lands on the branch.
-                const wtResult = await cleanupWorktree(pi, baseCwd, record.worktree, options.description, options.onBeforeWorktreeCleanup);
+                const wtResult = await svc.cleanupWorktree(pi, baseCwd, record.worktree, options.description, options.onBeforeWorktreeCleanup);
                 record.worktreeResult = wtResult.hasChanges || !priorWorktreeResult ? wtResult : priorWorktreeResult;
                 // Appended to the prose only. A structured child's caller parses
                 // `structuredJson`, which stays untouched — but `result` is also
@@ -1065,7 +1201,7 @@ export class AgentManager {
             // Best-effort worktree cleanup on error
             if (record.worktree) {
                 try {
-                    const wtResult = await cleanupWorktree(pi, baseCwd, record.worktree, options.description);
+                    const wtResult = await svc.cleanupWorktree(pi, baseCwd, record.worktree, options.description);
                     record.worktreeResult = wtResult.hasChanges || !priorWorktreeResult ? wtResult : priorWorktreeResult;
                     // A failed run can still have changed files: say where they went,
                     // on the error every failure surface shows.
@@ -1094,7 +1230,7 @@ export class AgentManager {
             }
             if (record.worktree) {
                 try {
-                    const wtResult = await cleanupWorktree(pi, baseCwd, record.worktree, options.description);
+                    const wtResult = await svc.cleanupWorktree(pi, baseCwd, record.worktree, options.description);
                     record.worktreeResult = wtResult.hasChanges || !priorWorktreeResult ? wtResult : priorWorktreeResult;
                     const note = worktreeNote(record.worktreeResult, baseCwd, customCwd !== undefined);
                     if (note)
@@ -1227,6 +1363,50 @@ export class AgentManager {
         }
         return { id, record };
     }
+    /**
+     * Hand a live run to the background without restarting it. The session,
+     * promise, in-flight turn, transcript and worktree all continue under the
+     * same id; what changes is who answers for it. The caller's parent-abort
+     * listener comes off (its Esc no longer reaches the run — `abort()` and
+     * `/agents` still do), the slot moves to the background pool, and the run
+     * then settles through the ordinary background path: `endRun` releases the
+     * run's live pool, and the settle reads the live `isBackground`, so the
+     * result is delivered as a background completion.
+     *
+     * Releasing the caller is the caller's job — the `Agent` tool races its own
+     * wake-up against `spawnAndWait`. This only refuses what it can see: a run
+     * nobody is blocking on (a background or detached spawn, one already handed
+     * off, or a foreground resume — `blocking` is cleared when the spawned run
+     * settles), one that reports through something other than the session (a
+     * nested child, a workflow's agent), and one that is stopped or queued.
+     *
+     * The background slot is taken even when the pool is full: suspending a
+     * live run is not an option, so it runs over the limit and queued
+     * background work waits for the count to drop, as with `bypassQueue`.
+     */
+    sendToBackground(id) {
+        const record = this.agents.get(id);
+        const run = this.runs.get(id);
+        if (!record?.blocking || !isTopLevelAgent(record) || record.status !== "running" || !record.promise)
+            return false;
+        if (!run || run.settled || run.record !== record)
+            return false;
+        this.detachParentAbort(record);
+        if (!run.slotReleased) {
+            if (run.pool === "foreground")
+                this.runningForeground--;
+            else if (run.pool === "background")
+                this.runningBackground--;
+            this.runningBackground++;
+        }
+        run.pool = "background";
+        record.blocking = false;
+        record.isBackground = true;
+        record.resultConsumed = false;
+        // A freed foreground slot may have unblocked a queued blocking spawn.
+        this.drainQueue();
+        return true;
+    }
     /**
      * Resume an existing agent session with a new prompt.
      */
@@ -1375,7 +1555,7 @@ export class AgentManager {
                     this.abort(id);
                 else
                     signal?.addEventListener("abort", onParentAbort, { once: true });
-                const { text, failure, aborted, steered } = abortController.signal.aborted ? { text: "" } : await resumeAgent(session, prompt, {
+                const { text, failure, aborted, steered } = abortController.signal.aborted ? { text: "" } : await this.svc().resumeAgent(session, prompt, {
                     maxTurns: options?.maxTurns ?? record.maxTurns,
                     onTurnEnd: options?.onTurnEnd,
                     onToolActivity: (activity) => {
@@ -1445,7 +1625,7 @@ export class AgentManager {
         if (!pi || !ctx) {
             throw new Error(`Agent ${entry.id} has finished and is no longer in memory, and it cannot be reopened from here.`);
         }
-        const problem = sessionFileProblem(entry.sessionFile);
+        const problem = this.svc().sessionFileProblem(entry.sessionFile);
         if (problem) {
             // Gone for good: a row that can only ever fail is worse than none.
             if (!existsSync(entry.sessionFile))
@@ -1481,6 +1661,7 @@ export class AgentManager {
             maxSubagentDepth: entry.maxSubagentDepth,
             rootSessionId: entry.rootSessionId,
             invocation: {
+                ...(entry.thinking ? { thinking: entry.thinking } : {}),
                 ...(entry.isolated ? { isolated: true } : {}),
                 ...(entry.worktree ? { isolation: "worktree" } : {}),
             },
@@ -1525,13 +1706,13 @@ export class AgentManager {
     async prepareResume(record, options) {
         const worktree = record.worktree;
         if (worktree?.path && !existsSync(worktree.path)) {
-            if (!isWorktreeIsolationEnabled()) {
+            if (!this.svc().isWorktreeIsolationEnabled()) {
                 throw new Error(`Cannot resume agent ${record.id}: it ran in a git worktree, and worktree isolation is turned off in this project.`);
             }
             const pi = options?.pi ?? this.pi;
             const repo = record.baseCwd;
             const error = pi && repo
-                ? await restoreWorktree(pi, repo, worktree, record.worktreeResult)
+                ? await this.svc().restoreWorktree(pi, repo, worktree, record.worktreeResult)
                 : "the repository it ran in is unknown";
             if (error) {
                 throw new Error(`Cannot resume agent ${record.id} in its git worktree: ${error}. Nothing was run.`);
@@ -1553,7 +1734,7 @@ export class AgentManager {
             return;
         const prior = record.worktreeResult;
         try {
-            const wtResult = await cleanupWorktree(pi, repo, record.worktree, record.description);
+            const wtResult = await this.svc().cleanupWorktree(pi, repo, record.worktree, record.description);
             record.worktreeResult = wtResult.hasChanges || !prior ? wtResult : prior;
             const note = worktreeNote(record.worktreeResult, repo, record.cwd !== undefined);
             if (!note)
@@ -1629,7 +1810,7 @@ export class AgentManager {
             await windDown();
             this.endRun(run);
         };
-        const promise = resumeAgent(record.session, prompt, {
+        const promise = this.svc().resumeAgent(record.session, prompt, {
             maxTurns: options.maxTurns ?? record.maxTurns,
             onTurnEnd: options.onTurnEnd,
             onToolActivity: (activity) => {
@@ -1728,7 +1909,7 @@ export class AgentManager {
         const wanted = name.toLowerCase();
         let fallback;
         for (const record of this.agents.values()) {
-            if (record.parentAgentId !== undefined)
+            if (record.parentAgentId !== undefined || !this.isVisible(record))
                 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.
@@ -1742,7 +1923,7 @@ export class AgentManager {
         if (fallback)
             return { kind: "live", record: fallback };
         const byId = this.agents.get(name);
-        if (byId?.parentAgentId === undefined && byId !== undefined)
+        if (byId?.parentAgentId === undefined && byId !== undefined && this.isVisible(byId))
             return { kind: "live", record: byId };
         // Only once nothing live answers: a tombstone is a conversation to reopen,
         // and reopening one while its record still exists would fork the session.
@@ -1780,7 +1961,12 @@ export class AgentManager {
     listTombstones() {
         return [...this.tombstones.values()].filter(isTopLevelTombstone).sort((a, b) => b.completedAt - a.completedAt);
     }
+    /** The agents of the session the surfaces show (see {@link setVisibleOwner}), newest first. */
     listAgents() {
+        return this.listAllAgents().filter(record => this.isVisible(record));
+    }
+    /** Every agent this manager holds, whichever session it belongs to, newest first. */
+    listAllAgents() {
         return [...this.agents.values()].sort((a, b) => b.startedAt - a.startedAt);
     }
     abort(id) {
@@ -1810,6 +1996,7 @@ export class AgentManager {
      * off it. A blocking caller learns of the stop from its own tool result.
      */
     stopQueued(record) {
+        this.pendingArgs.delete(record.id);
         record.status = "stopped";
         record.completedAt = Date.now();
         if (record.isBackground === false)
@@ -1846,11 +2033,19 @@ export class AgentManager {
     }
     keepTombstone(state) {
         this.tombstones.set(state.id, state);
-        // Bound the memory a long session can accumulate. Oldest first, since the
-        // agent someone still wants to reach is the one they used most recently.
-        while (this.tombstones.size > MAX_TOMBSTONES) {
-            const oldest = [...this.tombstones.values()].reduce((a, b) => (a.completedAt <= b.completedAt ? a : b));
-            this.tombstones.delete(oldest.id);
+        // Bound the memory a long session can accumulate, per kind (top-level or
+        // owned). Oldest first, since the agent someone still wants to reach is the
+        // one they used most recently.
+        const topLevel = isTopLevelAgent(state);
+        const sameKind = [...this.tombstones.values()].filter(entry => isTopLevelAgent(entry) === topLevel);
+        let excess = sameKind.length - (topLevel ? MAX_TOMBSTONES : MAX_OWNED_TOMBSTONES);
+        if (excess <= 0)
+            return;
+        sameKind.sort((a, b) => a.completedAt - b.completedAt);
+        for (const entry of sameKind) {
+            if (excess-- <= 0)
+                break;
+            this.tombstones.delete(entry.id);
         }
     }
     /**
@@ -1891,6 +2086,8 @@ export class AgentManager {
         for (const [id, record] of this.agents) {
             if (this.isRunActive(id))
                 continue;
+            // Kept too: another session's agent that finished while that session was
+            // closed, until it is opened again and told (or the cleanup evicts it).
             if (skipUnconsumed && !record.resultConsumed)
                 continue;
             this.removeRecord(id, record);
@@ -1908,7 +2105,10 @@ export class AgentManager {
      * whose run has not settled yet, which still holds its slot.
      */
     hasRunning() {
-        return this.runs.size > 0 || [...this.agents.values()].some(isBusy);
+        for (const run of this.runs.values())
+            if (this.isVisible(run.record))
+                return true;
+        return [...this.agents.values()].some(record => isBusy(record) && this.isVisible(record));
     }
     /** Abort all running and queued agents immediately. */
     abortAll() {
@@ -1940,9 +2140,11 @@ export class AgentManager {
      * commit and branch that preserve the agent's changes — finishes before the
      * process exits instead of racing it.
      */
-    async awaitWorktreeCleanup(timeoutMs) {
+    async awaitWorktreeCleanup(timeoutMs, ids) {
         const pending = [];
         for (const record of this.agents.values()) {
+            if (ids !== undefined && !ids.has(record.id))
+                continue;
             const startup = this.startups.get(record.id);
             if (!record.worktree && !startup)
                 continue;
@@ -1969,6 +2171,9 @@ export class AgentManager {
             for (const record of this.agents.values()) {
                 if (record.status !== "running" && record.status !== "queued")
                     continue;
+                // Another session's agents keep running; this session does not wait on them.
+                if (!this.isVisible(record))
+                    continue;
                 // An agent whose worktree is still being created is "running" with no
                 // `promise` yet — without its startup the wait would return too early.
                 const startup = this.startups.get(record.id);
@@ -1980,7 +2185,8 @@ export class AgentManager {
             // A stopped run still winding down holds its slot, and whatever is queued
             // behind it starts only once it settles (or is abandoned).
             for (const run of this.runs.values())
-                pending.push(run.done);
+                if (this.isVisible(run.record))
+                    pending.push(run.done);
             if (pending.length === 0)
                 break;
             await Promise.allSettled(pending);
@@ -2011,12 +2217,13 @@ export class AgentManager {
         const sessions = [...this.agents.values()].filter(record => !this.released.has(record)).map(record => record.session);
         this.agents.clear();
         this.startups.clear();
+        this.pendingArgs.clear();
         if (pi) {
             // Prune any orphaned git worktrees (crash recovery). Detached: dispose runs
             // on the shutdown path, which cannot wait for git. Started before the awaited
             // shutdown below rather than after it, so the git calls have that window to
             // finish in instead of racing the process exit that follows.
-            const prune = (repo) => { pruneWorktrees(pi, repo).catch(() => { }); };
+            const prune = (repo) => { this.svc().pruneWorktrees(pi, repo).catch(() => { }); };
             prune(process.cwd());
             // Also prune repos that caller-supplied cwds created worktrees in — a clean
             // exit with in-flight agents would otherwise leave stale registrations there.