@esso0428/pi-subagents 0.17.16 → 0.17.18

package/dist/agent-manager.js

@@ -1,1572 +0,0 @@
-/**
- * agent-manager.ts — Tracks agents, background execution, resume support.
- *
- * There are two independent concurrency pools, never one:
- *
- * - Background (`maxConcurrent`, default 10) bounds detached agents.
- * - Foreground (`maxConcurrentForeground`, default 0 = unlimited) bounds
- *   agents a caller is blocking on inline — `spawnAndWait`.
- *
- * Independent by design: a foreground agent blocks the parent anyway, so
- * charging it to the background pool would let a saturated pool starve the main
- * session of work it could have done itself. Excess agents in either pool are
- * queued and auto-started as slots free up. Nested children take no slot in
- * either — see `occupiesPoolSlot` / `occupiesForegroundSlot`.
- */
-import { randomUUID } from "node:crypto";
-import { statSync } from "node:fs";
-import { isAbsolute } from "node:path";
-import { agentHistoryLocator, createAgentHistoryPath, readAgentHistory, streamAgentHistory, writeAgentHistoryInitialEntry, } from "./agent-history.js";
-import { readAgentRecoveryCheckpoints, writeAgentRecoveryCheckpoint, } from "./agent-recovery.js";
-import { resumeAgent, runAgent } from "./agent-runner.js";
-import { assignHandle, handleBase } from "./mention.js";
-import { describeModel } from "./model-resolver.js";
-import { writeInitialEntry } from "./output-file.js";
-import { addUsage } from "./usage.js";
-import { cleanupWorktree, createWorktree, isWorktreeIsolationEnabled, pruneWorktrees, } from "./worktree.js";
-/**
- * Default max concurrent background agents.
- *
- * Raised from 4 when top-level spawns started defaulting to background
- * (`backgroundByDefault`): foreground agents bypass this pool entirely, so
- * while foreground was the default a fan-out of six ran six. With background
- * as the default every top-level agent takes a slot, and a limit of 4 would
- * have silently queued the tail of exactly the parallel fan-outs the `Agent`
- * tool description tells the model to send.
- */
-const DEFAULT_MAX_CONCURRENT = 10;
-/**
- * Default max concurrent foreground (blocking) agents — `0` = unlimited, the
- * extension's existing convention for "no ceiling" (`defaultMaxTurns`).
- *
- * Off by default because nothing here ever bounded foreground work, and pi
- * dispatches a message's tool calls through `Promise.all`, so an unqualified
- * fan-out of blocking `Agent` calls has always run all at once. Users who want
- * it bounded — chiefly local models, where parallel agents thrash the prompt
- * cache (#253) — opt in; everyone else keeps today's behaviour exactly.
- */
-const DEFAULT_MAX_CONCURRENT_FOREGROUND = 0;
-/**
- * How many evicted agents stay addressable by name. Only a bound on memory —
- * a session that spawns hundreds of agents shouldn't retain every one — and
- * far above the handful anyone keeps in their head.
- */
-const MAX_TOMBSTONES = 100;
-/**
- * Validate a caller-supplied SpawnOptions.cwd. `undefined`/`null` mean "unset"
- * (parent cwd). Anything else must be an absolute path to an existing
- * directory — curated errors instead of TypeErrors from path/fs internals
- * (RPC callers send arbitrary JSON: null, numbers, file paths).
- */
-function assertValidSpawnCwd(cwd) {
-    if (cwd == null)
-        return;
-    if (typeof cwd !== "string" || !isAbsolute(cwd)) {
-        throw new Error(`SpawnOptions.cwd must be an absolute path: "${String(cwd)}"`);
-    }
-    let isDirectory = false;
-    try {
-        isDirectory = statSync(cwd).isDirectory();
-    }
-    catch {
-        throw new Error(`SpawnOptions.cwd does not exist: "${cwd}"`);
-    }
-    if (!isDirectory) {
-        throw new Error(`SpawnOptions.cwd is not a directory: "${cwd}"`);
-    }
-}
-/**
- * Whether a record occupies one of the `maxConcurrent` background slots.
- * Nested children don't: their parent already holds a slot, so counting (and
- * therefore queueing) them would deadlock a parent that waits on its own child.
- *
- * Note this bounds nothing horizontally — the depth cap limits how DEEP nesting
- * goes, not how WIDE. A parent's only limit on concurrent children is that each
- * spawn costs it a turn, which is unbounded when max turns is unlimited.
- */
-function occupiesPoolSlot(record) {
-    return !!record.isBackground && isTopLevelAgent(record);
-}
-/**
- * Whether a record is one of the session's own agents, rather than something
- * another agent or a workflow owns.
- *
- * The single definition behind every user-facing surface — the fleet list, the
- * widget, the `/agents` menus, `@handle` resolution, and the completion events
- * and session entries. An owned child reports through its owner, so surfacing
- * it separately would double-count the same work in the places a person reads.
- */
-export function isTopLevelAgent(record) {
-    return record.parentAgentId === undefined && record.workflowId === undefined;
-}
-/**
- * Whether a record occupies one of the `maxConcurrentForeground` slots.
- *
- * Keyed on `blocking` — a caller awaiting this record inline — rather than on
- * `isBackground === false`, because `spawn()` is also the funnel for DETACHED
- * starts (cross-extension RPC, `@handle` mentions, the registry) that may pass
- * `isBackground: false` and are documented to run immediately regardless. Those
- * block nobody, so bounding them buys nothing and would park a record with no
- * one waiting to release it.
- *
- * Nested children are excluded for the same reason as `occupiesPoolSlot`, and
- * more sharply: their parent is blocked *awaiting them*, so queueing a child
- * behind its own parent is a guaranteed deadlock rather than a possible one.
- * Enforced here rather than at the call site so no caller can reintroduce it.
- *
- * A workflow's children go out through `spawnAndWait` and so are `blocking`
- * too, and are excluded on the same `isTopLevelAgent` test as the background
- * pool: the run already caps how many of its agents run at once, and charging
- * them here as well would let one fan-out queue behind a limit meant for the
- * session's own work.
- *
- * Like the background pool this bounds width at the top level only — a parent's
- * own fan-out is limited by nothing but its turn budget.
- */
-function occupiesForegroundSlot(record) {
-    return !!record.blocking && isTopLevelAgent(record);
-}
-/** Best-effort ceiling on one child's shutdown handlers, so teardown can't strand a quit. */
-const CHILD_SHUTDOWN_TIMEOUT_MS = 3_000;
-/**
- * Close the extension lifecycle `runAgent` opened with `bindExtensions`, then dispose.
- *
- * `AgentSession.dispose()` only calls `ExtensionRunner.invalidate()` — pi emits the event
- * itself in `AgentSessionRuntime.dispose()` beforehand, and this is the one place that binds
- * extensions onto a session without going through that path. Without the emit, everything an
- * extension armed in `session_start` leaks once per spawn, and its next tick throws
- * `assertActive()` from a bare timer callback — an uncaughtException that kills pi (#242).
- */
-async function shutdownChildSession(session) {
-    try {
-        const runner = session?.extensionRunner;
-        // Optional all the way down: on a pi without the getter, or a stubbed session from a
-        // partial `onSessionCreated`, skip the emit — the same degrade as before this fix.
-        if (runner?.hasHandlers?.("session_shutdown")) {
-            // Raced, not awaited outright. `emit` runs every handler serially with no timeout of
-            // its own, and dispose() is reached from pi's own `session_shutdown` with the TUI
-            // already torn down — one hung handler would leave a dead terminal.
-            await Promise.race([
-                runner.emit({ type: "session_shutdown", reason: "quit" }),
-                new Promise(resolve => setTimeout(resolve, CHILD_SHUTDOWN_TIMEOUT_MS).unref()),
-            ]);
-        }
-    }
-    catch { /* a partial session must degrade, not take the teardown down with it */ }
-    // Always, even on timeout: disposal is what this function ultimately exists to do.
-    try {
-        session?.dispose?.();
-    }
-    catch { /* ignore */ }
-}
-export class AgentManager {
-    agents = new Map();
-    /** Lightweight terminal rows retained after runtime GC so durable history stays discoverable. */
-    historyRecords = new Map();
-    cleanupInterval;
-    onComplete;
-    onStart;
-    onCompact;
-    onUsage;
-    maxConcurrent;
-    maxConcurrentForeground = DEFAULT_MAX_CONCURRENT_FOREGROUND;
-    /** Base repos worktrees were created from — so dispose() can prune them all,
-     *  not just the parent repo (caller-supplied cwd can target other repos). */
-    worktreeRepos = new Set();
-    /** Project cwd for each record's durable checkpoint. */
-    recoveryCwds = new Map();
-    /**
-     * Startup phases, keyed by agent id. `spawn()` still returns synchronously,
-     * but an agent using worktree isolation is not running yet when it does —
-     * copying the repo is an awaited git call. This is what `awaitStartup` hands
-     * callers that must fail their tool call on a startup failure, and what
-     * `waitForAll` waits on while a record is "running" with no `promise` yet.
-     * Entries are dropped once the run is underway, and kept (rejected) after a
-     * startup failure so a late `awaitStartup` still sees it.
-     */
-    startups = new Map();
-    /**
-     * Evicted agents that can still be reached by name, keyed by handle. Outlives
-     * the 10-minute record cleanup — that timer exists to bound memory, not to
-     * expire a conversation the user might still want — and is cleared alongside
-     * completed records on session start/switch.
-     */
-    tombstones = new Map();
-    /**
-     * Agents waiting to start, tagged with the pool they wait on. One queue for
-     * both pools: `drainQueue` picks the earliest entry whose own pool has room,
-     * so neither can head-of-line-block the other, and every removal path
-     * (`abort`, `abortAll`, `dispose`) stays a single filter.
-     *
-     * `release` wakes a caller blocked in `spawnAndWait`, and is fired once the
-     * entry's `start` has SETTLED rather than at drain time: startup is async
-     * now, so releasing earlier would wake the caller before `record.promise`
-     * exists and it would read a still-starting agent as one that never ran.
-     * Removing an entry from this array MUST release it — a queued record has no
-     * promise to await, and pi has no tool-execution timeout to bail the caller
-     * out.
-     */
-    queue = [];
-    /** Number of currently running background agents. */
-    runningBackground = 0;
-    /** Number of currently running foreground (blocking) agents. */
-    runningForeground = 0;
-    constructor(onComplete, maxConcurrent = DEFAULT_MAX_CONCURRENT, onStart, onCompact, onUsage) {
-        this.onComplete = onComplete;
-        this.onStart = onStart;
-        this.onCompact = onCompact;
-        this.onUsage = onUsage;
-        this.maxConcurrent = maxConcurrent;
-        // Cleanup completed agents after 10 minutes (but keep sessions for resume)
-        this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
-        this.cleanupInterval.unref();
-    }
-    /** Update the max concurrent background agents limit. */
-    setMaxConcurrent(n) {
-        this.maxConcurrent = Math.max(1, n);
-        // Start queued agents if the new limit allows
-        this.drainQueue();
-    }
-    getMaxConcurrent() {
-        return this.maxConcurrent;
-    }
-    /** Update the max concurrent foreground (blocking) agents limit. 0 = unlimited. */
-    setMaxConcurrentForeground(n) {
-        // Floor 0, not 1: unlimited is a meaningful value here and the default.
-        this.maxConcurrentForeground = Math.max(0, n);
-        // Start queued agents if the new limit allows — including everything, when
-        // the limit is cleared back to unlimited mid-run.
-        this.drainQueue();
-    }
-    getMaxConcurrentForeground() {
-        return this.maxConcurrentForeground;
-    }
-    /**
-     * Which pool a spawn is charged to, or undefined for one that is charged to
-     * neither (nested children, detached non-background spawns).
-     *
-     * Nothing here queues when the limit is unset — `poolHasRoom` reports an
-     * unlimited pool as always having room, so that alone is what keeps the
-     * default path identical. The `> 0` guard is belt and braces on top: it also
-     * keeps the counter from churning and the settle path from calling a drain
-     * that would find nothing to do. Both are unobservable, which is why no test
-     * pins them; the observable half — that the default start stays synchronous —
-     * is pinned in `test/foreground-concurrency.test.ts`.
-     */
-    poolFor(record) {
-        if (occupiesPoolSlot(record))
-            return "background";
-        if (this.maxConcurrentForeground > 0 && occupiesForegroundSlot(record))
-            return "foreground";
-        return undefined;
-    }
-    poolHasRoom(pool) {
-        return pool === "background"
-            ? this.runningBackground < this.maxConcurrent
-            : this.maxConcurrentForeground === 0 || this.runningForeground < this.maxConcurrentForeground;
-    }
-    /**
-     * Spawn an agent and return its ID immediately (for background use).
-     * If the concurrency limit is reached, the agent is queued.
-     *
-     * The id comes back synchronously, but with `isolation: "worktree"` the agent
-     * is not running yet when it does — the repo copy is an awaited git call.
-     * Callers that must fail a tool call on a startup failure await
-     * `awaitStartup(id)`; everyone else sees it on the record (status "error").
-     */
-    spawn(pi, ctx, type, prompt, options) {
-        // 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);
-        const id = randomUUID().slice(0, 17);
-        const abortController = new AbortController();
-        const record = {
-            id,
-            type,
-            // Owned children — nested, or a workflow's — are filtered out of every
-            // top-level surface, so no handle: nothing can address them and they must
-            // not consume a name a top-level sibling could otherwise take.
-            handle: !isTopLevelAgent(options)
-                ? undefined
-                // A reclaimed handle is used as-is: it belongs to the conversation this
-                // spawn is reopening, and re-deriving it would lose the numbering.
-                : options.reclaim?.handle ?? assignHandle(handleBase(type), this.takenHandles()),
-            description: options.description,
-            // Reclaimed here, or filled in below from `name` — in which case it must
-            // see the handle this record just took, since both come out of the same
-            // namespace.
-            alias: isTopLevelAgent(options) ? options.reclaim?.alias : undefined,
-            // Overwritten below when the spawn is actually queued; a foreground spawn
-            // that queues flips to "queued" there rather than being guessed at here,
-            // since the pool decision needs the finished record.
-            status: options.isBackground ? "queued" : "running",
-            toolUses: 0,
-            startedAt: Date.now(),
-            abortController,
-            lifetimeUsage: { input: 0, output: 0, cacheWrite: 0, cost: 0 },
-            compactionCount: 0,
-            // Raw tri-state (not coerced to a boolean): true = background, false =
-            // foreground (has an inline tool-result surface), undefined = caller never
-            // declared it (e.g. a cross-extension RPC spawn). The widget's background-
-            // only filter excludes only explicit `false`, so undefined agents — which
-            // have no inline surface — stay visible instead of vanishing.
-            isBackground: options.isBackground,
-            // Whether anyone is awaiting this agent is a property of the agent, not
-            // of the call that made it — and both settle paths need it long after
-            // `options` has stopped being the interesting object.
-            blocking: options.blocking,
-            invocation: options.invocation,
-            depth: options.depth ?? 1,
-            parentAgentId: options.parentAgentId,
-            workflowId: options.workflowId,
-            maxSubagentDepth: options.maxSubagentDepth,
-            rootSessionId: options.rootSessionId,
-        };
-        this.agents.set(id, record);
-        this.recoveryCwds.set(id, ctx.cwd);
-        // Durable history is manager-owned so every spawn path (Agent, scheduler,
-        // RPC, mention, and Workflow) has the same recoverable seam. Attach before
-        // any caller callback can start wiring output or observe the id.
-        this.attachDurableTranscript(record, id, prompt, ctx.cwd, options.outputTranscript !== false);
-        // After the insert, so `takenHandles()` already counts this record's own
-        // handle — a spawn named after its own type gets `explore-2`, not a
-        // duplicate `explore` that would make resolution ambiguous.
-        if (record.handle !== undefined && record.alias === undefined && options.name !== undefined) {
-            record.alias = assignHandle(handleBase(options.name), this.takenHandles());
-        }
-        const args = { pi, ctx, type, prompt, options };
-        const pool = this.poolFor(record);
-        if (pool !== undefined && !options.bypassQueue && !this.poolHasRoom(pool)) {
-            // Queue it — started when a running agent in the same pool completes.
-            // Idempotent for background (already "queued"); the flip that matters is
-            // a blocking foreground spawn, optimistically marked "running" above.
-            record.status = "queued";
-            // A queued record never reaches startAgent's signal wiring, so arm the
-            // parent abort here or Esc could not release the position.
-            if (!this.armQueuedAbort(id, options.signal))
-                return id;
-            let release;
-            record.startGate = new Promise(resolve => { release = resolve; });
-            this.queue.push({
-                id,
-                pool,
-                start: () => this.launch(id, record, args, pool),
-                release: () => release(),
-            });
-            options.onQueued?.(id, this.queue.filter(e => e.pool === pool).length - 1);
-            return id;
-        }
-        this.launch(id, record, args, undefined);
-        return id;
-    }
-    /**
-     * Attach the project-local transcript once for a newly-created record.
-     * Repeated calls are harmless: deterministic paths and an existing file keep
-     * the initial user entry intact, which is important for resume and retries.
-     */
-    attachDurableTranscript(record, id, prompt, cwd, outputTranscript) {
-        try {
-            const historyFile = createAgentHistoryPath(cwd, id);
-            writeAgentHistoryInitialEntry(historyFile, id, prompt, cwd);
-            if (outputTranscript)
-                writeInitialEntry(historyFile, id, prompt, cwd);
-            record.historyFile = historyFile;
-            record.transcriptPath = agentHistoryLocator(cwd, historyFile);
-        }
-        catch (err) {
-            // A read-only project must not prevent the agent from running. The
-            // checkpoint still records the spawn metadata and the warning makes the
-            // loss of durable history visible to the host.
-            console.warn(`[pi-subagents] failed to attach durable transcript for ${id}: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        this.checkpoint(record);
-    }
-    checkpointStatus(record) {
-        return record.status;
-    }
-    makeCheckpoint(record) {
-        return {
-            version: 1,
-            id: record.id,
-            type: record.type,
-            description: record.description,
-            status: this.checkpointStatus(record),
-            startedAt: record.startedAt,
-            ...(record.completedAt !== undefined && { completedAt: record.completedAt }),
-            ...(!record.transcriptPath && record.result !== undefined && { result: record.result }),
-            ...(record.error !== undefined && { error: record.error }),
-            toolUses: record.toolUses,
-            lifetimeUsage: { ...record.lifetimeUsage },
-            compactionCount: record.compactionCount,
-            ...(record.transcriptPath !== undefined && { transcriptPath: record.transcriptPath }),
-            ...(record.invocation !== undefined && { invocation: { ...record.invocation } }),
-        };
-    }
-    checkpoint(record) {
-        const cwd = this.recoveryCwds.get(record.id);
-        if (cwd)
-            writeAgentRecoveryCheckpoint(cwd, this.makeCheckpoint(record));
-    }
-    /** Checkpoint a record after external transcript wiring. */
-    checkpointRecord(id) {
-        const record = this.agents.get(id);
-        if (record)
-            this.checkpoint(record);
-    }
-    /** Register durable transcript metadata for compatibility with callers that
-     * attach a pre-existing history (for example a restored session). */
-    setTranscript(id, historyFile, transcriptPath, cwd) {
-        const record = this.agents.get(id);
-        if (!record)
-            return;
-        record.historyFile = historyFile;
-        record.transcriptPath = transcriptPath;
-        if (cwd)
-            this.recoveryCwds.set(id, cwd);
-        this.checkpoint(record);
-    }
-    /** Restore active checkpoints as stopped partial history after a restart. */
-    restoreRecovered(cwd) {
-        for (const checkpoint of readAgentRecoveryCheckpoints(cwd)) {
-            // A session_start can fire again in the same process (resume/switch).
-            // Never replace the live in-memory record with its older checkpoint: the
-            // checkpoint may intentionally omit `result` once durable history exists.
-            if (this.agents.has(checkpoint.id))
-                continue;
-            if (!checkpoint.transcriptPath || !readAgentHistory(cwd, checkpoint.transcriptPath))
-                continue;
-            const status = checkpoint.status === "running" || checkpoint.status === "queued"
-                ? "stopped" : checkpoint.status;
-            const record = {
-                id: checkpoint.id,
-                type: checkpoint.type,
-                description: checkpoint.description,
-                status,
-                result: checkpoint.result,
-                error: checkpoint.error,
-                toolUses: checkpoint.toolUses,
-                startedAt: checkpoint.startedAt,
-                completedAt: checkpoint.completedAt ?? Date.now(),
-                transcriptPath: checkpoint.transcriptPath,
-                historyFile: undefined,
-                invocation: checkpoint.invocation,
-                lifetimeUsage: { ...checkpoint.lifetimeUsage },
-                compactionCount: checkpoint.compactionCount,
-            };
-            this.agents.set(record.id, record);
-            this.recoveryCwds.set(record.id, cwd);
-        }
-    }
-    /**
-     * Restore terminal records from durable history without creating sessions.
-     * Invalid and live records are ignored so recovery cannot replace active work.
-     */
-    restoreCompleted(records) {
-        const terminal = new Set(["completed", "steered", "stopped", "aborted", "error"]);
-        const restoredIds = new Set();
-        for (const candidate of records) {
-            const id = typeof candidate.id === "string" && candidate.id.length > 0 ? candidate.id : undefined;
-            const status = candidate.status;
-            if (!id || !status || !terminal.has(status))
-                continue;
-            if (this.agents.has(id) && !restoredIds.has(id))
-                continue;
-            this.historyRecords.delete(id);
-            const type = typeof candidate.type === "string" ? candidate.type : undefined;
-            const description = typeof candidate.description === "string" ? candidate.description : undefined;
-            const startedAt = candidate.startedAt;
-            if (!type || description === undefined || typeof startedAt !== "number" || !Number.isFinite(startedAt))
-                continue;
-            if (candidate.completedAt !== undefined && (typeof candidate.completedAt !== "number" || !Number.isFinite(candidate.completedAt)))
-                continue;
-            if (candidate.transcriptPath !== undefined && (typeof candidate.transcriptPath !== "string" || candidate.transcriptPath.includes("..") || candidate.transcriptPath.startsWith("/")))
-                continue;
-            const restored = {
-                ...candidate,
-                id,
-                type,
-                description,
-                status,
-                toolUses: typeof candidate.toolUses === "number" && Number.isFinite(candidate.toolUses) ? candidate.toolUses : 0,
-                startedAt,
-                completedAt: candidate.completedAt ?? Date.now(),
-                lifetimeUsage: candidate.lifetimeUsage ? { ...candidate.lifetimeUsage } : { input: 0, output: 0, cacheWrite: 0 },
-                compactionCount: typeof candidate.compactionCount === "number" && Number.isFinite(candidate.compactionCount) ? candidate.compactionCount : 0,
-                session: undefined,
-                abortController: undefined,
-                promise: undefined,
-                startGate: undefined,
-                outputCleanup: undefined,
-                historyCleanup: undefined,
-            };
-            this.agents.set(id, restored);
-            restoredIds.add(id);
-        }
-    }
-    /**
-     * Wire a parent abort signal for a record that is about to be QUEUED.
-     * `startAgent` does this for running agents, and a queued record never gets
-     * there, so without this Esc could not release a queue position.
-     *
-     * Returns false when the signal is ALREADY aborted, in which case the record
-     * is stopped here and must not be enqueued: `addEventListener` never fires on
-     * an aborted signal, so a `spawnAndWait` on it would wait forever — pi has no
-     * tool-execution timeout to bail it out.
-     *
-     * The listener is left in place when the agent starts. `startAgent` adds its
-     * own, so both fire on a later abort, but `abort()` on an already-stopped
-     * record is a no-op — so detaching would only be tidiness, and tidiness the
-     * `abortAll`/`dispose` paths could not offer anyway.
-     */
-    armQueuedAbort(id, signal) {
-        if (signal === undefined)
-            return true;
-        if (signal.aborted) {
-            const record = this.agents.get(id);
-            if (record) {
-                record.status = "stopped";
-                record.completedAt = Date.now();
-                this.flushOutput(record);
-                this.checkpoint(record);
-            }
-            return false;
-        }
-        signal.addEventListener("abort", () => this.abort(id), { once: true });
-        return true;
-    }
-    /**
-     * Kick off an agent's startup and register it under `startups`. The returned
-     * promise never rejects — the failure is delivered through `awaitStartup`,
-     * and to the record.
-     *
-     * @param queuedPool - The pool this start was QUEUED on, or undefined for an
-     *   immediate start. A queue drain can be minutes after `spawn()` returned,
-     *   and nobody is awaiting `awaitStartup` by then, so a failure has to live
-     *   on the record as status "error" — what drainQueue did when the throw was
-     *   still synchronous. An immediate start instead drops the record, exactly
-     *   as the throw out of `spawn()` did: no orphan in `listAgents()`, and the
-     *   handle goes back.
-     */
-    launch(id, record, args, queuedPool) {
-        const startup = this.startAgent(id, record, args).then(() => { this.startups.delete(id); }, (err) => {
-            this.startups.delete(id);
-            if (queuedPool !== undefined) {
-                // Mirrors settleRun: an inline caller gets this failure as a throw
-                // out of spawnAndWait, so an unconsumed record would ALSO nudge the
-                // session about it — the same failure reported twice.
-                if (queuedPool === "foreground")
-                    record.resultConsumed = true;
-                record.status = "error";
-                record.error = err instanceof Error ? err.message : String(err);
-                record.completedAt = Date.now();
-                this.flushOutput(record);
-                this.checkpoint(record);
-                this.onComplete?.(record);
-            }
-            else {
-                this.agents.delete(id);
-            }
-            // The agent never kept its slot (startAgent gives it back on failure),
-            // so anything queued behind it can go now.
-            this.drainQueue();
-            throw err;
-        });
-        this.startups.set(id, startup);
-        // Nothing is obliged to await `startups` — swallow the rejection once here
-        // so an unawaited startup can't take the process down, and hand callers
-        // (drainQueue) that swallowed promise.
-        return startup.catch(() => { });
-    }
-    /**
-     * Resolves once the agent is actually running, and rejects with the startup
-     * failure (strict worktree isolation) that `spawn()` used to throw before the
-     * repo copy became async. Resolves immediately for an agent that is already
-     * running, still queued, or unknown — so callers can await it unconditionally.
-     *
-     * Call it in the same tick as the `spawn()` it belongs to: a failed startup
-     * takes its record (and this entry) with it, exactly as the throw did.
-     */
-    awaitStartup(id) {
-        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 }) {
-        // 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.
-        assertValidSpawnCwd(options.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
-        const baseCwd = customCwd ?? ctx.cwd;
-        // Take the running state — and with it the concurrency slot — BEFORE the
-        // first await. Creating a worktree is an awaited git call, and drainQueue
-        // reads the pool counters synchronously in a loop: incrementing after the
-        // await would let it start every queued agent at once while the first is
-        // still copying its repo. Claiming "running" here also keeps abort() and
-        // abortAll() able to reach an agent whose worktree is still being created.
-        //
-        // The pool is resolved ONCE, here, and carried to `settleRun` below:
-        // `poolFor` reads `maxConcurrentForeground`, which the user can change from
-        // `/agents → Settings` mid-run, so recomputing it at settle time would
-        // decrement a pool this run never charged (counter underflow, limit
-        // silently lifted) or skip the decrement for one it did (leaked slot —
-        // every later blocking spawn queues forever). The two startup exits below
-        // never reach `settleRun`, so they hand the slot back themselves.
-        const pool = this.poolFor(record);
-        const releaseSlot = () => {
-            if (pool === "background")
-                this.runningBackground--;
-            else if (pool === "foreground")
-                this.runningForeground--;
-        };
-        record.status = "running";
-        record.startedAt = Date.now();
-        record.startGate = undefined;
-        if (pool === "background")
-            this.runningBackground++;
-        else if (pool === "foreground")
-            this.runningForeground++;
-        this.checkpoint(record);
-        // Worktree isolation: try to create a temporary git worktree. Strict —
-        // fail loud if not possible (no silent fallback to main tree). Done BEFORE
-        // the run is kicked off so a failure doesn't leave a half-running agent.
-        // The project switch is enforced here as well as at the tool boundary
-        // because cross-extension RPC forwards its options unvalidated — a schema
-        // that omits the field can't stop a caller that never saw the schema.
-        let worktreeCwd;
-        if (options.isolation === "worktree" && isWorktreeIsolationEnabled()) {
-            const wt = await createWorktree(pi, baseCwd, id);
-            if (!wt) {
-                releaseSlot();
-                throw new Error('Cannot run with isolation: "worktree" — not a git repo, no commits yet, or `git worktree add` failed. ' +
-                    'Initialize git and commit at least once, or omit `isolation`.');
-            }
-            record.worktree = wt;
-            // workPath preserves subdirectory scoping for caller-supplied cwds: a
-            // cwd deep in a monorepo maps to the same subdir inside the copy, not
-            // the copied repo's root. Plain worktree spawns keep the historical
-            // behavior (agent at the copy's root) — moving them to workPath would
-            // also move .pi config discovery when the parent session sits in a repo
-            // subdirectory, silently dropping extensions/skills.
-            worktreeCwd = customCwd !== undefined ? wt.workPath : wt.path;
-            this.worktreeRepos.add(baseCwd);
-            // No longer "running" means a stop landed while the copy was being made
-            // (abort(), abortAll()) — a window that did not exist when creation was
-            // synchronous. The record is already terminal, so launching the run would
-            // burn tokens on work nobody is waiting for: discard the fresh (and by
-            // definition unchanged) worktree instead.
-            if (record.status !== "running") {
-                releaseSlot();
-                record.worktreeResult = await cleanupWorktree(pi, baseCwd, wt, options.description);
-                this.drainQueue();
-                return;
-            }
-        }
-        this.onStart?.(record);
-        // 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, {
-            pi,
-            agentId: id,
-            model: options.model,
-            maxTurns: options.maxTurns,
-            isolated: options.isolated,
-            inheritContext: options.inheritContext,
-            thinkingLevel: options.thinkingLevel,
-            structuredOutput: options.structuredOutput,
-            resumeSessionFile: options.resumeSessionFile,
-            nested: options.parentAgentId !== undefined,
-            workflow: options.workflowId !== undefined,
-            // Worktree wins for the working dir (the agent must run in the copy —
-            // which, with a custom cwd, was created from that target). Config stays
-            // with the parent project when a caller-supplied cwd is in play; it must
-            // stay undefined otherwise so plain worktree runs keep resolving config
-            // (incl. relative extension paths and memory) inside the worktree copy.
-            cwd: worktreeCwd ?? customCwd,
-            // Set iff a worktree was created (see above) — names the directory the
-            // copy came from, so the prompt can tell the agent not to work there.
-            worktreeBase: worktreeCwd ? baseCwd : undefined,
-            configCwd: options.configCwd ?? (customCwd !== undefined ? ctx.cwd : undefined),
-            signal: record.abortController.signal,
-            onToolActivity: (activity) => {
-                if (activity.type === "end")
-                    record.toolUses++;
-                options.onToolActivity?.(activity);
-            },
-            onTurnEnd: options.onTurnEnd,
-            onTextDelta: options.onTextDelta,
-            onAssistantUsage: (usage) => {
-                addUsage(record.lifetimeUsage, usage);
-                this.onUsage?.(record, usage);
-                options.onAssistantUsage?.(usage);
-            },
-            onCompaction: (info) => {
-                record.compactionCount++;
-                this.onCompact?.(record, info);
-                options.onCompaction?.(info);
-            },
-            nestedRuntime: {
-                manager: this,
-                parentAgentId: id,
-                depth: record.depth ?? 1,
-                maxSubagentDepth: record.maxSubagentDepth,
-            },
-            onSessionCreated: (session) => {
-                record.session = session;
-                // Capture now, while the session object exists: after eviction this
-                // path is the only thing that can reopen the conversation, and an
-                // in-memory session reports undefined, which correctly means
-                // "nothing to come back to".
-                // Optional chaining, not defensiveness for its own sake: this is the
-                // only field read off the session at creation, so an older pi or a
-                // stubbed session must degrade to "not resumable" rather than throw
-                // and take the whole spawn down with it.
-                record.sessionFile = session.sessionManager?.getSessionFile?.();
-                // Same reason, different field: the model and thinking level are only
-                // knowable once pi has resolved its defaults and clamped the level to
-                // what the model supports. Writing them back here makes the record
-                // authoritative, so every surface reads one place instead of each
-                // re-deriving "session, else the request" for itself.
-                if (session.model) {
-                    record.invocation ??= {};
-                    // Read the kept request first: a caller's level survives being clamped
-                    // AND, one line later, being replaced by the effective one.
-                    const requested = record.invocation.requestedThinking ?? record.invocation.thinking;
-                    Object.assign(record.invocation, describeModel(session.model));
-                    // Guarded for the reason above: a session that reports no level keeps
-                    // the request rather than losing it. Overwriting unconditionally would
-                    // turn an older or stubbed session into a blank `thinking:` tag, which
-                    // is worse than the stale-but-true value it replaced.
-                    if (session.thinkingLevel) {
-                        record.invocation.thinking = session.thinkingLevel;
-                        if (requested && requested !== session.thinkingLevel) {
-                            record.invocation.requestedThinking = requested;
-                        }
-                    }
-                }
-                if (record.historyFile) {
-                    record.historyCleanup = streamAgentHistory(session, record.historyFile, record.id, ctx.cwd);
-                }
-                // Flush any steers that arrived before the session was ready
-                if (record.pendingSteers?.length) {
-                    for (const msg of record.pendingSteers) {
-                        session.steer(msg).catch(() => { });
-                    }
-                    record.pendingSteers = undefined;
-                }
-                this.checkpoint(record);
-                options.onSessionCreated?.(session);
-            },
-        })
-            .then(async ({ responseText, session, aborted, steered, failure, structuredJson, structuredRetried }) => {
-            // Don't overwrite status if externally stopped via abort()
-            if (record.status !== "stopped") {
-                // Precedence: a hard abort keeps "aborted"; then a failed final turn
-                // (provider error that pi resolved instead of rejecting, #144) is an
-                // honest "error" — not a completion with an empty or stale result.
-                if (aborted) {
-                    record.status = "aborted";
-                }
-                else if (failure) {
-                    record.status = "error";
-                    record.error = failure;
-                }
-                else {
-                    record.status = steered ? "steered" : "completed";
-                }
-            }
-            record.result = responseText;
-            // Kept beside `result`, never inside it: `result` is prose meant for a
-            // reader — it is previewed, transcribed, and appended to below — while
-            // this is a machine-readable payload one caller asked for by schema.
-            record.structuredJson = structuredJson;
-            record.structuredRetried = structuredRetried;
-            record.session = session;
-            record.completedAt ??= Date.now();
-            detach();
-            // Flush both optional output and durable history before terminal state
-            // is checkpointed or completion is observable.
-            this.flushOutput(record);
-            // Clean up worktree if used
-            if (record.worktree) {
-                // The one moment the child's tree still exists and the child is done
-                // writing to it. try/catch, not decoration: a hook that throws must
-                // not leave the worktree behind.
-                if (options.onBeforeWorktreeCleanup) {
-                    try {
-                        await options.onBeforeWorktreeCleanup(record.worktree.path);
-                    }
-                    catch { /* ignore — never block cleanup */ }
-                }
-                const wtResult = await cleanupWorktree(pi, baseCwd, record.worktree, options.description);
-                record.worktreeResult = wtResult;
-                if (wtResult.hasChanges && wtResult.branch) {
-                    // With a caller-supplied cwd the branch lives in THAT repo, not the
-                    // parent session's — say so, or the orchestrator merges in the wrong repo.
-                    const repoNote = customCwd !== undefined ? ` in \`${baseCwd}\`` : "";
-                    // Appended to the prose only. A structured child's caller parses
-                    // `structuredJson`, which stays untouched — but `result` is also
-                    // what a human reads, so the note still belongs on it.
-                    record.result = (record.result ?? "") +
-                        `\n\n---\nChanges saved to branch \`${wtResult.branch}\`${repoNote}. Merge with: \`git merge ${wtResult.branch}\`${customCwd !== undefined ? ` (run in \`${baseCwd}\`)` : ""}`;
-                }
-            }
-            this.abortOwnedChildren(id);
-            this.settleRun(record, true, pool);
-            return responseText;
-        })
-            .catch(async (err) => {
-            // Don't overwrite status if externally stopped via abort()
-            if (record.status !== "stopped") {
-                record.status = "error";
-            }
-            record.error = err instanceof Error ? err.message : String(err);
-            record.completedAt ??= Date.now();
-            detach();
-            // Preserve partial assistant/tool history before recording the error.
-            this.flushOutput(record);
-            // Best-effort worktree cleanup on error
-            if (record.worktree) {
-                try {
-                    const wtResult = await cleanupWorktree(pi, baseCwd, record.worktree, options.description);
-                    record.worktreeResult = wtResult;
-                }
-                catch { /* ignore cleanup errors */ }
-            }
-            this.abortOwnedChildren(id);
-            this.settleRun(record, false, pool);
-            return "";
-        });
-        record.promise = promise;
-        // Notify caller that spawn is complete (record is in the map, promise is set).
-        // Called synchronously — onSessionCreated fires asynchronously inside runAgent.
-        // Used by spawnAndWait to let the caller set up output files before streaming
-        // starts. Read off the options, so a spawn that started from a queue drain
-        // still reaches the caller that queued it.
-        options.onSpawned?.(id);
-    }
-    /**
-     * The shared tail of both settle paths: release whatever pool slot the run
-     * held, notify, and let the queue drain into the freed slot.
-     *
-     * The decrement lives HERE and nowhere else. `abort()` on a running record
-     * only fires its controller and leaves the run to settle normally, so
-     * decrementing there too would double-free — permanently lifting the limit.
-     *
-     * Foreground agents fire `onComplete` for lifecycle symmetry, with
-     * `resultConsumed` set so the callback skips notifications the inline result
-     * already delivered.
-     *
-     * @param guardCallback swallow a throwing `onComplete` (the success path does;
-     *   the error path historically did not, and keeps not doing so).
-     * @param pool the pool this run was CHARGED TO at start time — passed in, not
-     *   recomputed, so a mid-run change to `maxConcurrentForeground` can't make
-     *   the release disagree with the acquire.
-     */
-    settleRun(record, guardCallback, pool) {
-        // Terminal state is not durable until the stream has flushed. The
-        // checkpoint deliberately follows this call so stop/error/partial runs can
-        // be reopened after the live session is released.
-        this.flushOutput(record);
-        this.checkpoint(record);
-        if (!record.isBackground)
-            record.resultConsumed = true;
-        if (pool === "background")
-            this.runningBackground--;
-        else if (pool === "foreground")
-            this.runningForeground--;
-        if (guardCallback) {
-            try {
-                this.onComplete?.(record);
-            }
-            catch { /* ignore completion side-effect errors */ }
-        }
-        else {
-            this.onComplete?.(record);
-        }
-        // The isBackground half reproduces the pre-pool condition exactly — a
-        // background settle has always drained, even for a nested child that held
-        // no slot — so that path is unchanged whether or not the foreground pool is
-        // on. The `pool` half only adds the drain a freed FOREGROUND slot needs.
-        // A drain with nothing freed is a no-op anyway, but "no-op" is a claim
-        // about reachability, and matching the old condition needs no such claim.
-        if (record.isBackground || pool !== undefined)
-            this.drainQueue();
-    }
-    flushOutput(record) {
-        if (record.outputCleanup) {
-            try {
-                record.outputCleanup();
-            }
-            catch { /* best effort */ }
-            record.outputCleanup = undefined;
-        }
-        if (record.historyCleanup) {
-            try {
-                record.historyCleanup();
-            }
-            catch { /* best effort */ }
-            record.historyCleanup = undefined;
-        }
-    }
-    /**
-     * Stop the nested children a settled parent owns. Nested records are hidden
-     * from the UI and only their owner can consume them, so a child outliving its
-     * parent would burn tokens unseen with no way to reach it. Grandchildren are
-     * covered transitively — each abort lands in that child's own settle path.
-     */
-    abortOwnedChildren(parentId) {
-        for (const [id, record] of this.agents) {
-            if (record.parentAgentId === parentId)
-                this.abort(id);
-        }
-    }
-    /**
-     * Start queued agents up to each pool's concurrency limit.
-     *
-     * `findIndex` on the entry's OWN pool rather than `shift`: with one queue
-     * serving two independent limits, a saturated foreground pool at the head
-     * would otherwise stall every background agent behind it. Taking the earliest
-     * eligible entry keeps FIFO within each pool, which is what callers see.
-     */
-    drainQueue() {
-        for (;;) {
-            const i = this.queue.findIndex(e => this.poolHasRoom(e.pool));
-            if (i === -1)
-                return;
-            const [next] = this.queue.splice(i, 1);
-            const record = this.agents.get(next.id);
-            // Stale entries (aborted while queued) are not started — but are still
-            // released, since nothing else will.
-            if (!record || record.status !== "queued") {
-                next.release();
-                continue;
-            }
-            // Detached, and never rejects: a late failure (e.g. strict worktree
-            // isolation) lands on the record inside `launch`, exactly as the
-            // synchronous throw did here before, and draining continues either way.
-            //
-            // The release waits for that startup to SETTLE rather than firing here.
-            // Startup is async now, so a release at drain time would wake a blocked
-            // `spawnAndWait` while `record.promise` was still undefined, and it would
-            // read a perfectly healthy agent as one that never ran.
-            void next.start().then(() => next.release(), () => next.release());
-        }
-    }
-    /**
-     * Remove queued entries and wake anyone blocked on them. The single point
-     * that enforces "leaving the queue releases the waiter" — a missed release is
-     * an unbounded hang, not a failed call.
-     */
-    dequeue(pred) {
-        const kept = [];
-        for (const entry of this.queue) {
-            if (pred(entry))
-                entry.release();
-            else
-                kept.push(entry);
-        }
-        this.queue = kept;
-    }
-    /**
-     * Spawn an agent and wait for completion (foreground use).
-     * Charged to the foreground pool (`maxConcurrentForeground`), which is
-     * unlimited by default; never to the background one.
-     * Returns { id, record } so callers can access the agent ID.
-     *
-     * @param onSpawned - Called synchronously once the run is kicked off, before
-     *   onSessionCreated fires. Use this to set record.outputFile so
-     *   streamToOutputFile can pick it up.
-     */
-    async spawnAndWait(pi, ctx, type, prompt, options, onSpawned) {
-        // `blocking` is what maxConcurrentForeground bounds, and this is its only
-        // source. onSpawned rides on the options rather than on a field of this
-        // manager: a queued spawn starts at drain time, long after any install/
-        // restore pair around this call would have put the field back — and it now
-        // fires after an await (worktree creation) even on the immediate path.
-        const id = this.spawn(pi, ctx, type, prompt, {
-            ...options,
-            isBackground: false,
-            blocking: true,
-            onSpawned,
-        });
-        const record = this.agents.get(id);
-        // Queued: nothing to await yet — the promise appears when the drain starts
-        // it. The gate resolves (never rejects) on every path out of the queue,
-        // start and abort alike, so a rejection can never escape into the caller's
-        // tool `execute` and take down pi's whole Promise.all tool batch.
-        if (record.status === "queued")
-            await record.startGate;
-        // The run promise only exists once startup is past its awaited repo copy —
-        // without this the call would return before the agent had started at all.
-        // A startup failure (strict worktree isolation) rejects here, which is what
-        // the immediate path owes its caller: pi only marks a tool result failed
-        // when `execute` throws. A queued spawn's failure landed on the record
-        // instead (nobody was awaiting `startups` at drain time) and is rethrown
-        // below, so the contract is the same either way.
-        await this.awaitStartup(id);
-        // undefined when it was aborted while queued, or stopped mid-copy, and so
-        // never ran — the record is already terminal with a completedAt, which is
-        // what the caller renders.
-        if (record.promise)
-            await record.promise;
-        // A record that ended "error" without ever getting a promise never ran: the
-        // same startup failure spawn() rethrows on the immediate path (#179). Keep
-        // one contract rather than letting queue pressure decide whether a strict
-        // worktree failure throws or returns as a result.
-        if (record.promise === undefined && record.status === "error") {
-            throw new Error(record.error ?? "Agent failed to start");
-        }
-        return { id, record };
-    }
-    /**
-     * Resume an existing agent session with a new prompt.
-     */
-    async resume(id, prompt, signal, options) {
-        const record = this.agents.get(id);
-        if (!record?.session)
-            return undefined;
-        // Background resume: settle asynchronously and notify on completion exactly
-        // like a background spawn, returning immediately with the record still
-        // "running" — or "queued" when at the concurrency limit. Previously
-        // run_in_background was ignored on resume (the Agent tool's resume branch
-        // returned before its background branch, and resume() only ever awaited
-        // inline), so a resumed agent always blocked the caller until it finished.
-        if (options?.isBackground) {
-            // Never re-enter a run that is still in flight. Detaching means the caller
-            // gets control back while the record stays "running", so nothing stops the
-            // model from resuming the same agent again. Starting a second run would
-            // overwrite record.abortController — orphaning the live run beyond the
-            // reach of `/agents` stop and abortAll() — double-count the pool slot, and
-            // then reject from session.prompt() with "Agent is already processing",
-            // whose settle path would abort the LIVE run's children and report a
-            // failure for a run that is still going. Refuse instead, leaving the
-            // record untouched; the caller decides whether to wait or steer.
-            if (record.status === "running" || record.status === "queued")
-                return undefined;
-            record.isBackground = true;
-            record.resultConsumed = false;
-            record.result = undefined;
-            record.error = undefined;
-            record.completedAt = undefined;
-            record.status = "queued";
-            const start = () => this.startResume(id, record, prompt, signal, options);
-            if (occupiesPoolSlot(record) && !this.poolHasRoom("background")) {
-                // At the concurrency limit — queue it, drains when a slot frees. A
-                // detached resume has no inline caller, hence nothing to release. The
-                // queue is shared with spawns, whose startup is async, so entries are
-                // promise-shaped even though a resume starts synchronously; failures
-                // land on the record here, since drainQueue no longer catches.
-                this.queue.push({
-                    id,
-                    pool: "background",
-                    start: async () => {
-                        try {
-                            start();
-                        }
-                        catch (err) {
-                            record.status = "error";
-                            record.error = err instanceof Error ? err.message : String(err);
-                            record.completedAt = Date.now();
-                            this.onComplete?.(record);
-                        }
-                    },
-                    release: () => { },
-                });
-            }
-            else {
-                start();
-            }
-            return record;
-        }
-        // Foreground resume: run inline and return the settled record.
-        record.status = "running";
-        record.startedAt = Date.now();
-        record.completedAt = undefined;
-        record.result = undefined;
-        record.error = undefined;
-        try {
-            const { text, failure } = await resumeAgent(record.session, prompt, {
-                onToolActivity: (activity) => {
-                    if (activity.type === "end")
-                        record.toolUses++;
-                    options?.onToolActivity?.(activity);
-                },
-                onAssistantUsage: (usage) => {
-                    addUsage(record.lifetimeUsage, usage);
-                    this.onUsage?.(record, usage);
-                    options?.onAssistantUsage?.(usage);
-                },
-                onCompaction: (info) => {
-                    record.compactionCount++;
-                    this.onCompact?.(record, info);
-                    options?.onCompaction?.(info);
-                },
-                signal,
-            });
-            // Same contract as the spawn path (#144): a failed final turn is an
-            // error, not a completion — but the resumed text stays available.
-            record.status = failure ? "error" : "completed";
-            if (failure)
-                record.error = failure;
-            record.result = text;
-            record.completedAt = Date.now();
-        }
-        catch (err) {
-            record.status = "error";
-            record.error = err instanceof Error ? err.message : String(err);
-            record.completedAt = Date.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.
-        this.abortOwnedChildren(id);
-        return record;
-    }
-    /**
-     * Start a background resume run: detached, settling and notifying like
-     * startAgent's background path. Invoked immediately, or from drainQueue when
-     * a concurrency slot frees. The session already exists (resume reuses it), so
-     * there is no onSessionCreated to hang per-run wiring off — callers use
-     * `options.onStarted`, which fires on both the immediate and the drained path.
-     */
-    startResume(id, record, prompt, parentSignal, options) {
-        if (!record.session)
-            return;
-        record.status = "running";
-        record.startedAt = Date.now();
-        if (occupiesPoolSlot(record))
-            this.runningBackground++;
-        this.onStart?.(record);
-        // Fresh abort controller so /agents stop and steering target THIS run rather
-        // than the previous one's settled controller.
-        const abortController = new AbortController();
-        record.abortController = abortController;
-        // Optional, and NOT what the Agent tool passes for a detached resume: a
-        // parent signal aborts on the parent's own interrupt (user Esc), which is
-        // right for a foreground run whose result the caller is awaiting, and wrong
-        // for a detached one — background spawns omit it for exactly this reason.
-        let detachParentSignal;
-        if (parentSignal) {
-            const onParentAbort = () => this.abort(id);
-            parentSignal.addEventListener("abort", onParentAbort, { once: true });
-            detachParentSignal = () => parentSignal.removeEventListener("abort", onParentAbort);
-        }
-        // Per-run durable history starts at the existing session tail. The prompt
-        // and all messages produced by this resumed run are then flushed by the
-        // same manager-owned seam as a fresh spawn.
-        if (record.historyFile) {
-            const cwd = this.recoveryCwds.get(id);
-            if (cwd) {
-                const startIndex = Array.isArray(record.session.messages) ? record.session.messages.length : 0;
-                record.historyCleanup = streamAgentHistory(record.session, record.historyFile, id, cwd, startIndex);
-            }
-        }
-        // Per-run side effects (optional `.output` streaming) — see ResumeOptions.onStarted.
-        // After the record is in its running shape, before the run is kicked off.
-        try {
-            options.onStarted?.();
-        }
-        catch { /* ignore caller wiring errors */ }
-        const settle = () => {
-            detachParentSignal?.();
-            detachParentSignal = undefined;
-            // Final flush of streaming files. The durable history stream is owned by
-            // the manager; the optional `.output` stream is caller-wired.
-            this.flushOutput(record);
-            // Children spawned during the resumed turn must not outlive it.
-            this.abortOwnedChildren(id);
-            if (occupiesPoolSlot(record))
-                this.runningBackground--;
-            try {
-                this.onComplete?.(record);
-            }
-            catch { /* ignore completion side-effect errors */ }
-            this.drainQueue();
-        };
-        const promise = resumeAgent(record.session, prompt, {
-            onToolActivity: (activity) => {
-                if (activity.type === "end")
-                    record.toolUses++;
-                options.onToolActivity?.(activity);
-            },
-            onAssistantUsage: (usage) => {
-                addUsage(record.lifetimeUsage, usage);
-                this.onUsage?.(record, usage);
-                options.onAssistantUsage?.(usage);
-            },
-            onCompaction: (info) => {
-                record.compactionCount++;
-                this.onCompact?.(record, info);
-                options.onCompaction?.(info);
-            },
-            signal: abortController.signal,
-        })
-            .then(({ text, failure }) => {
-            // Don't overwrite status if externally stopped via abort().
-            if (record.status !== "stopped") {
-                // Same contract as the spawn path (#144): a failed final turn is an
-                // error, not a completion — but the resumed text stays available.
-                record.status = failure ? "error" : "completed";
-                if (failure)
-                    record.error = failure;
-            }
-            record.result = text;
-            record.completedAt ??= Date.now();
-            settle();
-            return text;
-        })
-            .catch((err) => {
-            if (record.status !== "stopped") {
-                record.status = "error";
-                record.error = err instanceof Error ? err.message : String(err);
-            }
-            record.completedAt ??= Date.now();
-            settle();
-            return "";
-        });
-        record.promise = promise;
-    }
-    /**
-     * Send a steering message to an agent from the UI (mirrors the steer_subagent
-     * tool). A live session delivers it now — it interrupts the agent after its
-     * current tool execution and appears as a user message. If the session isn't
-     * ready yet, the message is queued on `pendingSteers` and flushed when the
-     * session is created. Returns false if the agent can't accept steering
-     * (unknown id, or no longer running/queued).
-     */
-    steer(id, message) {
-        const record = this.agents.get(id);
-        if (!record)
-            return false;
-        if (record.status !== "running" && record.status !== "queued")
-            return false;
-        if (record.session) {
-            record.session.steer(message).catch(() => { });
-        }
-        else {
-            if (!record.pendingSteers)
-                record.pendingSteers = [];
-            record.pendingSteers.push(message);
-        }
-        return true;
-    }
-    getRecord(id) {
-        return this.agents.get(id);
-    }
-    /** Handles already in use, so a fresh spawn can pick an unclaimed one. */
-    takenHandles() {
-        const taken = new Set();
-        for (const record of this.agents.values()) {
-            if (record.handle)
-                taken.add(record.handle);
-            if (record.alias)
-                taken.add(record.alias);
-        }
-        // Tombstones hold their names too: an evicted `@explore` is still
-        // resurrectable, so a later Explore must become `explore-2` rather than
-        // shadowing a conversation the user can still reach.
-        for (const entry of this.tombstones.values()) {
-            taken.add(entry.handle);
-            if (entry.alias)
-                taken.add(entry.alias);
-        }
-        return taken;
-    }
-    /**
-     * Resolve an `@name` from the prompt. Matches a top-level agent's handle
-     * case-insensitively, preferring one that can still be steered and otherwise
-     * the most recently started (which is the one a resume should continue), then
-     * falls back to an exact agent id so `@<agentId>` works too.
-     */
-    resolveMention(name) {
-        const wanted = name.toLowerCase();
-        let fallback;
-        for (const record of this.agents.values()) {
-            if (record.parentAgentId !== undefined)
-                continue;
-            // Handle and alias share one namespace, so at most one agent answers a
-            // name and it makes no difference which of the two matched.
-            if (record.handle?.toLowerCase() !== wanted && record.alias?.toLowerCase() !== wanted)
-                continue;
-            if (record.status === "running" || record.status === "queued")
-                return { kind: "live", record };
-            if (!fallback || record.startedAt > fallback.startedAt)
-                fallback = record;
-        }
-        if (fallback)
-            return { kind: "live", record: fallback };
-        const byId = this.agents.get(name);
-        if (byId?.parentAgentId === undefined && byId !== undefined)
-            return { kind: "live", record: byId };
-        // Only once nothing live answers: a tombstone is a conversation to reopen,
-        // and reopening one while its record still exists would fork the session.
-        for (const entry of this.tombstones.values()) {
-            if (entry.handle.toLowerCase() === wanted || entry.alias?.toLowerCase() === wanted || entry.id === name) {
-                return { kind: "tombstone", entry };
-            }
-        }
-        return undefined;
-    }
-    /**
-     * Forget an evicted agent, by handle. For the case where its session file has
-     * gone: the entry can then only ever fail, while still holding the name
-     * against the type that would otherwise start a fresh agent under it.
-     *
-     * A *successful* resume does not drop its tombstone — the live record it
-     * creates already wins in `resolveMention`, and overwrites the entry in place
-     * when it is itself evicted.
-     */
-    dropTombstone(handle) {
-        this.tombstones.delete(handle);
-    }
-    /** Evicted agents whose conversation can still be reopened, newest first. */
-    listTombstones() {
-        return [...this.tombstones.values()].sort((a, b) => b.completedAt - a.completedAt);
-    }
-    listAgents() {
-        // Prefer live records when a restored transcript shares an id with a
-        // runtime record. This keeps the history archive additive without ever
-        // producing duplicate menu rows.
-        const records = new Map(this.historyRecords);
-        for (const [id, record] of this.agents)
-            records.set(id, record);
-        return [...records.values()].sort((a, b) => b.startedAt - a.startedAt);
-    }
-    abort(id) {
-        const record = this.agents.get(id);
-        if (!record)
-            return false;
-        // Remove from queue if queued. No decrement — the slot was never taken —
-        // and no onComplete, matching what a queued background abort has always
-        // done; a blocking caller learns of the stop from its own tool result.
-        if (record.status === "queued") {
-            this.dequeue(q => q.id === id);
-            record.status = "stopped";
-            record.completedAt = Date.now();
-            this.flushOutput(record);
-            this.checkpoint(record);
-            return true;
-        }
-        if (record.status !== "running")
-            return false;
-        record.abortController?.abort();
-        record.status = "stopped";
-        record.completedAt = Date.now();
-        this.flushOutput(record);
-        this.checkpoint(record);
-        return true;
-    }
-    /** Dispose a record's session and remove it from the map. */
-    removeRecord(id, record) {
-        this.tombstone(record);
-        const session = record.session;
-        // Detached before the shutdown starts, so the record leaves the map at once and
-        // nothing can observe a session that is half torn down.
-        record.session = undefined;
-        if (record.transcriptPath) {
-            // Keep a lightweight row discoverable by `/agents` and the Agents widget
-            // after runtime GC. The JSONL transcript is the source of truth; no live
-            // session, promise, or cleanup callback is retained in this archive.
-            record.abortController = undefined;
-            record.promise = undefined;
-            record.startGate = undefined;
-            record.outputCleanup = undefined;
-            record.historyCleanup = undefined;
-            record.worktree = undefined;
-            record.result = undefined;
-            this.historyRecords.set(id, record);
-        }
-        this.agents.delete(id);
-        // A failed startup keeps its (rejected) entry so a late awaitStartup still
-        // sees it; drop it with the record so the map can't grow unbounded.
-        this.startups.delete(id);
-        // Fire-and-forget is right here and only here: this runs from the 60s cleanup timer
-        // and from `clearCompleted()` on session boundaries, with the process staying alive,
-        // so handlers get their full window. The quit path awaits instead — see dispose().
-        void shutdownChildSession(session);
-    }
-    /**
-     * Preserve enough of a departing record for `@handle` to reopen its
-     * conversation later. Nothing to keep unless it has both a handle to be
-     * addressed by and a session file to reopen — an in-memory session leaves no
-     * transcript, so the mention would have nothing to continue from.
-     */
-    tombstone(record) {
-        if (!record.handle || !record.sessionFile)
-            return;
-        this.tombstones.set(record.handle, {
-            handle: record.handle,
-            alias: record.alias,
-            id: record.id,
-            type: record.type,
-            description: record.description,
-            sessionFile: record.sessionFile,
-            completedAt: record.completedAt ?? Date.now(),
-        });
-        // Bound the memory a long session can accumulate. Oldest first, since the
-        // agent someone still wants to reach is the one they used most recently.
-        while (this.tombstones.size > MAX_TOMBSTONES) {
-            const oldest = [...this.tombstones.values()].reduce((a, b) => (a.completedAt <= b.completedAt ? a : b));
-            this.tombstones.delete(oldest.handle);
-        }
-    }
-    cleanup() {
-        const cutoff = Date.now() - 10 * 60_000;
-        for (const [id, record] of this.agents) {
-            if (record.status === "running" || record.status === "queued")
-                continue;
-            if ((record.completedAt ?? 0) >= cutoff)
-                continue;
-            this.removeRecord(id, record);
-        }
-    }
-    /**
-     * Remove completed/stopped/errored runtime records immediately.
-     * Called on session start/switch so live handles from a prior session do not
-     * remain addressable. Transcript-backed rows move to `historyRecords` and
-     * stay visible to the UI; their JSONL history is the durable source of truth.
-     * Pass skipUnconsumed=true to preserve records the LLM has not read yet
-     * (resultConsumed=false) so the result remains available to the caller.
-     */
-    clearCompleted(skipUnconsumed = false) {
-        for (const [id, record] of this.agents) {
-            if (record.status === "running" || record.status === "queued")
-                continue;
-            if (skipUnconsumed && !record.resultConsumed)
-                continue;
-            this.removeRecord(id, record);
-        }
-        // Unconditional: both callers are session boundaries (`session_start` and
-        // `session_before_switch`), and `skipUnconsumed` only spares records whose
-        // results the LLM has yet to read — it does not make the sweep partial in
-        // the sense that matters here. A new session means new handles, or
-        // `@explore` would silently reach an agent the user never started. Claude
-        // Code resets its registry on `/clear` for the same reason.
-        this.tombstones.clear();
-    }
-    /** Whether any agents are still running or queued. */
-    hasRunning() {
-        return [...this.agents.values()].some(r => r.status === "running" || r.status === "queued");
-    }
-    /** Abort all running and queued agents immediately. */
-    abortAll() {
-        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 = Date.now();
-                this.flushOutput(record);
-                this.checkpoint(record);
-                count++;
-            }
-        }
-        this.dequeue(() => true);
-        // Abort running agents
-        for (const record of this.agents.values()) {
-            if (record.status === "running") {
-                record.abortController?.abort();
-                record.status = "stopped";
-                record.completedAt = Date.now();
-                this.flushOutput(record);
-                this.checkpoint(record);
-                count++;
-            }
-        }
-        return count;
-    }
-    /** Wait for all running and queued agents to complete (including queued ones). */
-    async waitForAll() {
-        // Loop because drainQueue respects the concurrency limit — as running
-        // agents finish they start queued ones, which need awaiting too.
-        while (true) {
-            this.drainQueue();
-            const pending = [];
-            for (const record of this.agents.values()) {
-                if (record.status !== "running" && record.status !== "queued")
-                    continue;
-                // An agent whose worktree is still being created is "running" with no
-                // `promise` yet — without its startup the wait would return too early.
-                const startup = this.startups.get(record.id);
-                if (startup)
-                    pending.push(startup);
-                if (record.promise)
-                    pending.push(record.promise);
-            }
-            if (pending.length === 0)
-                break;
-            await Promise.allSettled(pending);
-        }
-    }
-    /**
-     * @param pi - Needed to run `git worktree prune`, which is async now and so
-     *   cannot be reached through a stored spawn argument at shutdown. Omitting
-     *   it (tests, teardown of a manager that never spawned) skips the prune.
-     */
-    async dispose(pi) {
-        clearInterval(this.cleanupInterval);
-        // Keep the pre-shutdown active snapshot marked active in the checkpoint. A
-        // process can still be killed after dispose starts; restoreRecovered turns
-        // that stale active marker into a stopped record, while the transcript has
-        // already received the terminal abort/stop event below.
-        const activeBeforeDispose = new Set([...this.agents.values()]
-            .filter(record => record.status === "running" || record.status === "queued")
-            .map(record => record.id));
-        // Mark live work stopped and flush durable history before child sessions are
-        // shut down. The caller also invokes abortAll(), but dispose is deliberately
-        // safe and complete when used on its own.
-        this.abortAll();
-        // Clear queue — via dequeue, so anyone blocked in spawnAndWait is woken
-        // rather than left awaiting a gate nothing will ever resolve.
-        this.dequeue(() => true);
-        for (const record of this.agents.values()) {
-            this.flushOutput(record);
-            this.checkpoint(record);
-            if (activeBeforeDispose.has(record.id)) {
-                const activeSnapshot = this.makeCheckpoint(record);
-                delete activeSnapshot.completedAt;
-                activeSnapshot.status = "running";
-                const cwd = this.recoveryCwds.get(record.id);
-                if (cwd)
-                    writeAgentRecoveryCheckpoint(cwd, activeSnapshot);
-            }
-        }
-        const sessions = [...this.agents.values()].map(record => record.session);
-        this.agents.clear();
-        this.recoveryCwds.clear();
-        this.startups.clear();
-        if (pi) {
-            // Prune any orphaned git worktrees (crash recovery). Detached: dispose runs
-            // on the shutdown path, which cannot wait for git. Started before the awaited
-            // shutdown below rather than after it, so the git calls have that window to
-            // finish in instead of racing the process exit that follows.
-            const prune = (repo) => { pruneWorktrees(pi, repo).catch(() => { }); };
-            prune(process.cwd());
-            // Also prune repos that caller-supplied cwds created worktrees in — a clean
-            // exit with in-flight agents would otherwise leave stale registrations there.
-            for (const repo of this.worktreeRepos)
-                prune(repo);
-        }
-        // Awaited, unlike the eviction path: pi awaits this extension's `session_shutdown`
-        // handler and the process exits right after it returns, so anything left unawaited
-        // here never runs at all. Bounded — each call carries its own ceiling, concurrently.
-        await Promise.all(sessions.map(session => shutdownChildSession(session)));
-    }
-}
-//# sourceMappingURL=agent-manager.js.map