apex-code 0.0.4 → 0.0.6

package/dist/core/delegation/runtime.js

@@ -13,19 +13,1220 @@
  * would create (`sdk.ts` already imports `agent-session.ts`).
  */
 import { randomUUID } from "node:crypto";
-import { mkdirSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { loadEntriesFromFile } from "../session-manager.js";
 import { computeCapabilityCeiling } from "./ceiling.js";
+/** Default follow-up prompt for resuming an interrupted child run. */
+export const RESUME_CHILD_PROMPT = "Resume the interrupted task and continue from the existing session.";
+/** The record status's terminal outcome, for closing an attempt at resume time. */
+function terminalOutcomeOfStatus(status, cancelled) {
+    if (status === "completed" || status === "failed")
+        return status;
+    if (status === "interrupted")
+        return cancelled ? "cancelled" : "interrupted";
+    return undefined;
+}
+/**
+ * Attempts for a record, synthesizing one from legacy fields when the record
+ * predates attempt tracking: one attempt, started (and, for a terminal status,
+ * ended) at the record's `updatedAt`, with the status mapped to an outcome.
+ * Older records therefore load unchanged and still report a single attempt.
+ */
+function childRunAttemptsOf(record) {
+    if (record.attempts && record.attempts.length > 0)
+        return record.attempts;
+    const attempt = { id: "attempt-1", startedAt: record.updatedAt };
+    const outcome = terminalOutcomeOfStatus(record.status, record.cancelled);
+    if (outcome !== undefined) {
+        attempt.endedAt = record.updatedAt;
+        attempt.outcome = outcome;
+    }
+    return [attempt];
+}
+/** The entry's active attempt, falling back to the most recent one. */
+function activeAttemptOf(entry) {
+    const attempts = entry.attempts ?? [];
+    return attempts.find((attempt) => attempt.id === entry.activeAttemptId) ?? attempts[attempts.length - 1];
+}
+/**
+ * Shared delegation admission: definition resolution, recursion-depth bound, and
+ * the capability ceiling. One projection for both a fresh delegation and a
+ * historical reattachment, so a resumed child can never hold authority the
+ * current parent cannot cover (no second classification, ADR 0010). The
+ * admitted capability set rides along on the result: it is what the build
+ * request carries so the child's policy snapshot describes the same projection
+ * instead of recomputing it.
+ */
+function resolveAdmittedDefinition(options, agentType) {
+    const definition = options.resolveAgent(agentType);
+    if (!definition) {
+        throw new Error(`Unknown agent type "${agentType}".`);
+    }
+    const depth = options.getDelegationDepth();
+    if (depth >= options.maxDelegationDepth) {
+        throw new Error(`Delegation depth limit (${options.maxDelegationDepth}) reached at depth ${depth}; cannot delegate to agent "${agentType}" further.`);
+    }
+    const requestedCapabilities = new Set();
+    for (const toolName of definition.tools) {
+        const capabilities = options.getToolCapabilities(toolName);
+        if (!capabilities) {
+            throw new Error(`Agent "${agentType}" requests unknown tool "${toolName}".`);
+        }
+        for (const capability of capabilities)
+            requestedCapabilities.add(capability);
+    }
+    const ceiling = computeCapabilityCeiling(options.getParentCapabilities(), requestedCapabilities);
+    if (!ceiling.allowed) {
+        throw new Error(`Delegating to agent "${agentType}" requires capability "${ceiling.deniedCapability}", which exceeds the parent's authority.`);
+    }
+    return { definition, capabilities: ceiling.capabilities };
+}
+/**
+ * Lazily resolve a child's transcript path under its artifact directory, per
+ * SessionManager's `<timestamp>_<sessionId>.jsonl` naming (the timestamp prefix
+ * is not recorded, so the directory is scanned). Never throws: an absent
+ * directory or transcript -- an in-memory child never persisted one -- simply
+ * yields `undefined`, so status payloads can resolve it lazily without
+ * becoming fallible. When several transcripts match, the newest wins (resume
+ * may have grown the file set).
+ */
+function resolveSessionFile(artifactDir, sessionId) {
+    if (!artifactDir || !sessionId)
+        return undefined;
+    if (!existsSync(artifactDir))
+        return undefined;
+    try {
+        const matches = readdirSync(artifactDir).filter((name) => name.endsWith(`_${sessionId}.jsonl`));
+        if (matches.length === 0)
+            return undefined;
+        if (matches.length === 1)
+            return join(artifactDir, matches[0]);
+        const newest = matches
+            .map((name) => ({ name, mtime: statSync(join(artifactDir, name)).mtimeMs }))
+            .sort((a, b) => b.mtime - a.mtime)[0];
+        return join(artifactDir, newest.name);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Roll provider-reported usage up over session entries (the child's OWN
+ * transcript is the source; SessionManager's reader supplies the entries).
+ * Every surface that reports child-run usage goes through here, so the numbers
+ * are summed exactly once, exactly as the provider reported them: cost is
+ * provider-reported, so cache reads are NOT re-priced or re-counted, and an
+ * entry without usage contributes zero. Assistant messages carry per-turn
+ * usage; compaction and branch-summary entries carry their summarization
+ * call's usage, which is additional real spend and therefore included.
+ * Returns `undefined` when the entries hold no usage-bearing record at all
+ * (nothing to report) -- callers omit rather than zero-fill.
+ */
+function computeUsageTotals(entries) {
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cacheReadTokens = 0;
+    let cacheWriteTokens = 0;
+    let totalTokens = 0;
+    const cost = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 };
+    let entriesCounted = 0;
+    const add = (usage) => {
+        if (!usage)
+            return; // missing/absent usage counts as zero
+        inputTokens += usage.input;
+        outputTokens += usage.output;
+        cacheReadTokens += usage.cacheRead;
+        cacheWriteTokens += usage.cacheWrite;
+        totalTokens += usage.totalTokens;
+        cost.input += usage.cost.input;
+        cost.output += usage.cost.output;
+        cost.cacheRead += usage.cost.cacheRead;
+        cost.cacheWrite += usage.cost.cacheWrite;
+        cost.total += usage.cost.total;
+    };
+    for (const entry of entries) {
+        if (entry.type === "message") {
+            if (entry.message.role !== "assistant")
+                continue;
+            entriesCounted++;
+            add(entry.message.usage);
+        }
+        else if (entry.type === "compaction" || entry.type === "branch_summary") {
+            entriesCounted++;
+            add(entry.usage);
+        }
+    }
+    if (entriesCounted === 0)
+        return undefined;
+    return {
+        inputTokens,
+        outputTokens,
+        cacheReadTokens,
+        cacheWriteTokens,
+        totalTokens,
+        cost,
+        asOf: Date.now(),
+        entriesCounted,
+    };
+}
 // Results deliberately stay available for the lifetime of their parent runtime.
 // Phase 5 promises in-process retrieval only; restart durability belongs to Phase 6.
-const backgroundByRuntime = new WeakMap();
-function background(options) {
-    let value = backgroundByRuntime.get(options);
-    if (!value) {
-        value = new Map();
-        backgroundByRuntime.set(options, value);
-    }
-    return value;
+export class ChildRunRegistry {
+    entries = new Map();
+    workspaceClaims = new Map();
+    children = new Set();
+    /**
+     * Session ids whose workspace this registry must release on close/dispose
+     * (spec 2026-09-09, "Parallel work and ownership"): populated by
+     * `trackWorkspace()` when a worktree-isolated delegation is prepared, and
+     * drained exactly once per session id by `releaseWorkspaceOnce()`.
+     */
+    trackedWorkspaces = new Set();
+    /** Session ids whose workspace release has already started -- release runs once, never twice. */
+    releasedWorkspaces = new Set();
+    /** Last release outcome per session id, surfaced through `workspaceReleaseOutcome()`. */
+    workspaceReleaseOutcomes = new Map();
+    workspaceOwner;
+    disposed = false;
+    persist;
+    records = new Map();
+    /**
+     * Spawn dedupe keys -> handle ids (spec 2026-09-09, idempotent spawn). A
+     * second spawn with a known key returns the existing handle and never builds
+     * a second child. Populated at launch and rebuilt from persisted records on
+     * `restore()`, so a restarted parent dedupes too.
+     */
+    idempotencyKeys = new Map();
+    /**
+     * Handle ids currently holding a concurrency slot (spec 2026-09-09,
+     * "Shared budgets"). Admission takes one slot per child run BEFORE any child
+     * session is built; the slot is released on terminal settlement
+     * (completed/failed/interrupted), close, registry disposal, or launch
+     * failure. Keyed by handle id, so release is idempotent.
+     */
+    heldRunSlots = new Set();
+    /**
+     * The delegation runtime this registry runs under, attached by the session
+     * that owns it (sdk wiring) or by the first `runDelegation` call. Historical
+     * resume reattaches through the SAME `buildChildSession` seam a live
+     * delegation uses; without an attached runtime, historical records are still
+     * listed and their persisted output retrievable, but they cannot reattach.
+     */
+    runtimeOptions;
+    /**
+     * Last-computed usage totals per handle id, keyed by what makes them stale
+     * (the transcript file's size+mtime, or the in-memory entry count+last id).
+     * The transcript file itself stays the one source: on every read the key is
+     * re-derived and a mismatch recomputes from the file -- this cache never
+     * becomes a second transcript.
+     */
+    usageCache = new Map();
+    /** First attach wins: a registry is owned by one session's runtime. */
+    setRuntimeOptions(options) {
+        if (!this.runtimeOptions)
+            this.runtimeOptions = options;
+    }
+    setPersistence(persist) {
+        this.persist = persist;
+    }
+    /** Load validated historical records. This never constructs or starts a child. */
+    restore(records) {
+        for (const record of records) {
+            if (!record ||
+                typeof record.handleId !== "string" ||
+                typeof record.agentType !== "string" ||
+                !Number.isFinite(record.updatedAt) ||
+                !["created", "running", "completed", "failed", "interrupted", "closed"].includes(record.status))
+                continue;
+            // Legacy records without attempts load with one synthesized attempt
+            // derived from their status/updatedAt, so every in-memory record carries
+            // at least one attempt.
+            const normalized = { ...record, attempts: childRunAttemptsOf(record) };
+            if (normalized.activeAttemptId === undefined) {
+                const openStatus = normalized.status === "running" || normalized.status === "created";
+                normalized.activeAttemptId = openStatus
+                    ? normalized.attempts[normalized.attempts.length - 1].id
+                    : undefined;
+            }
+            // Stale-running reconciliation (restart semantics): a persisted
+            // "running" record cannot be live in this fresh process, so its
+            // in-memory status becomes "interrupted" and its active attempt closes
+            // as interrupted. The historical JSONL is never rewritten here -- the
+            // corrected status persists with the record's NEXT save (e.g. a resume).
+            // This is also the honest statement of restart semantics: a resumed run
+            // continues from the last persisted transcript boundary, never
+            // exactly-once -- turns that settled after the last save are re-run.
+            if (normalized.status === "running") {
+                normalized.status = "interrupted";
+                normalized.attempts = normalized.attempts.map((attempt) => ({ ...attempt }));
+                const attempt = normalized.attempts[normalized.attempts.length - 1];
+                if (attempt) {
+                    attempt.endedAt ??= Date.now();
+                    attempt.outcome ??= "interrupted";
+                }
+            }
+            this.records.set(normalized.handleId, normalized);
+            if (typeof normalized.idempotencyKey === "string") {
+                this.idempotencyKeys.set(normalized.idempotencyKey, normalized.handleId);
+            }
+        }
+    }
+    /** The handle a spawn dedupe key already maps to, if any. */
+    handleForIdempotencyKey(key) {
+        return this.idempotencyKeys.get(key);
+    }
+    /** True when `id` is known only as a persisted record -- no live entry in this process. */
+    isHistorical(id) {
+        return !this.entries.has(id) && this.records.has(id);
+    }
+    /**
+     * Resolve a historical record's child session file. Verified against
+     * SessionManager's naming (`<timestamp>_<sessionId>.jsonl` inside the
+     * per-child artifact directory, which IS the child's session dir): the
+     * timestamp prefix is not recorded, so the directory is scanned for the file
+     * whose name ends in `_<sessionId>.jsonl`. Returns the validated triple so
+     * the reattachment request carries checked values, not optional record fields.
+     */
+    resolveHistoricalSession(record) {
+        const artifactDir = record.artifactDir ? resolve(record.artifactDir) : undefined;
+        const sessionId = typeof record.sessionId === "string" ? record.sessionId : undefined;
+        if (!sessionId || !artifactDir) {
+            throw new Error(`Child run "${record.handleId}" was never file-backed (no persisted child session directory; in-memory child), so it cannot be resumed after restart.`);
+        }
+        if (!existsSync(artifactDir)) {
+            throw new Error(`Child run "${record.handleId}" cannot be resumed: its artifact directory is missing: ${artifactDir}.`);
+        }
+        const path = resolveSessionFile(artifactDir, sessionId);
+        if (!path) {
+            throw new Error(`Child run "${record.handleId}" cannot be resumed: no child session file for session "${sessionId}" exists under ${artifactDir} (the child never persisted a transcript).`);
+        }
+        return { path, sessionId, artifactDir };
+    }
+    /**
+     * Reattach a persisted child run to its existing child session and continue
+     * it with one turn (restart reconstruction). The child session file recorded
+     * under the run's artifact directory is reopened through the same
+     * `buildChildSession` seam a live delegation uses (reattachment marker), and
+     * the run then behaves like any live entry: settlement is observed and
+     * persisted, and wait/retrieve/sendInput work on the same handle id.
+     *
+     * Never-file-backed (in-memory) children, records whose artifact directory or
+     * session file is gone, closed runs, and runs whose recorded worktree was
+     * released all refuse with an actionable error; nothing is reconstructed
+     * from nothing.
+     */
+    async resumeHistorical(id, input) {
+        this.assertOpen();
+        if (this.entries.has(id)) {
+            throw new Error(`Child run "${id}" is already live in this process; use sendInput instead of historical resume.`);
+        }
+        const record = this.records.get(id);
+        if (!record)
+            throw new Error(`Unknown delegation handle "${id}".`);
+        // The worktree gate runs BEFORE the closed check: a retained (or missing)
+        // workspace is the more actionable refusal for a released child, and it
+        // names the persisted state and the explicit-recovery way out.
+        if (record.workspace?.isolation === "worktree")
+            this.rejectUnresumableWorktree(id, record);
+        if (record.status === "closed")
+            throw new Error(`Child run "${id}" was closed and cannot be resumed.`);
+        if (typeof record.agentType !== "string" || record.agentType === "") {
+            throw new Error(`Child run "${id}" has a malformed record (no agent type) and cannot be resumed.`);
+        }
+        const { path: sessionPath, sessionId, artifactDir } = this.resolveHistoricalSession(record);
+        const runtime = this.runtimeOptions;
+        if (!runtime?.buildChildSession) {
+            throw new Error(`Child run "${id}" cannot be resumed: no delegation runtime is attached to this registry.`);
+        }
+        const { definition, capabilities } = resolveAdmittedDefinition(runtime, record.agentType);
+        const workspace = record.workspace ?? { isolation: "shared-read", ownedPaths: [] };
+        const claims = [...workspace.ownedPaths].map((p) => resolve(p));
+        for (const claim of this.activeWorkspaceClaims()) {
+            if (claims.some((path) => claimPathsOverlap(path, claim))) {
+                throw new Error(`Resuming child run "${id}" overlaps an active write ownership claim.`);
+            }
+        }
+        this.claimWorkspace(id, claims);
+        try {
+            // A resumed run counts against the concurrency limit exactly like a
+            // live delegation, from before the child is built (spec 2026-09-09,
+            // "Shared budgets").
+            this.admitChildRun(id);
+            const child = await runtime.buildChildSession({
+                agentType: record.agentType,
+                definition,
+                toolNames: definition.tools,
+                capabilities,
+                depth: typeof record.depth === "number" ? record.depth : 1,
+                sessionId,
+                artifactDir,
+                workspace,
+                reattachSessionPath: sessionPath,
+            });
+            this.own(child);
+            // Resume closes the previous attempt with its terminal outcome and opens
+            // a NEW attempt (spec 2026-09-09, "Child lifecycle"): the resumed turn
+            // is a fresh epoch of the same child session, never a continuation of
+            // the interrupted attempt.
+            const priorAttempts = childRunAttemptsOf(record).map((attempt) => ({ ...attempt }));
+            const priorOutcome = terminalOutcomeOfStatus(record.status, record.cancelled);
+            const prior = record.activeAttemptId
+                ? priorAttempts.find((attempt) => attempt.id === record.activeAttemptId)
+                : undefined;
+            const closing = prior ?? priorAttempts[priorAttempts.length - 1];
+            if (closing && closing.endedAt === undefined) {
+                closing.endedAt = Date.now();
+                closing.outcome ??= priorOutcome;
+            }
+            // The resumed epoch's predecessor gets its cumulative-at-end rollup
+            // here when the settlement before the restart never produced one: the
+            // persisted transcript is all that survived, so its current totals are
+            // the honest snapshot (see ChildRunAttempt.tokensAtEnd).
+            if (closing && closing.tokensAtEnd === undefined) {
+                const totals = this.usageTotalsFor(id, record.artifactDir);
+                if (totals)
+                    closing.tokensAtEnd = totals;
+            }
+            const attempt = { id: `attempt-${priorAttempts.length + 1}`, startedAt: Date.now() };
+            const entry = {
+                agentType: record.agentType,
+                task: record.task ?? "",
+                // No initial-turn promise: each resumed turn is tracked through
+                // sendInput's settlement observation, like any live entry.
+                promise: new Promise(() => { }),
+                child,
+                artifactDir: record.artifactDir,
+                workspace,
+                depth: record.depth,
+                // Record linkage: the reattached construction re-derives the policy
+                // through the same admission projection; the record's persisted
+                // values stand in when a fixture handle reports none.
+                policy: child.policy ?? record.policy,
+                sandboxEnforced: child.sandboxEnforced ?? record.sandboxEnforced,
+                parentSessionId: record.parentSessionId,
+                attempts: [...priorAttempts, attempt],
+                activeAttemptId: attempt.id,
+                idempotencyKey: typeof record.idempotencyKey === "string" ? record.idempotencyKey : undefined,
+            };
+            this.entries.set(id, entry);
+            this.save(id, entry, "running");
+            await this.sendInput(id, input ?? RESUME_CHILD_PROMPT);
+            return child.status;
+        }
+        catch (error) {
+            this.releaseChildRunSlot(id);
+            this.releaseWorkspace(id);
+            throw error;
+        }
+    }
+    /**
+     * Gate a worktree-isolated historical resume on the workspace's persisted
+     * state (spec 2026-09-09, "Workspace states and explicit recovery"). A
+     * vanished root classifies the record "missing" (persisted) and refuses; a
+     * retained (dirty/failed) root refuses, naming the persisted state and
+     * pointing at explicit recovery. Legacy records and recovered ("active")
+     * workspaces pass. Read-only: nothing is recreated, checked out, or reset.
+     */
+    rejectUnresumableWorktree(id, record) {
+        const workspace = record.workspace;
+        const root = workspace.root;
+        if (!root)
+            return; // never prepared: the launch failed before the owner ran
+        if (!existsSync(root)) {
+            if (record.workspaceState !== "released") {
+                record.workspaceState = "missing";
+                record.updatedAt = Date.now();
+                try {
+                    this.persist?.(record);
+                }
+                catch {
+                    // The in-memory classification stands even if persistence cannot.
+                }
+            }
+            throw new Error(`Child run "${id}" cannot be resumed: its worktree workspace "${root}" no longer exists ` +
+                `(workspace state: "${record.workspaceState ?? "missing"}"). Worktrees are released or retained when the ` +
+                `owning session closes; a missing workspace cannot be recovered -- start a new delegation instead.`);
+        }
+        if (record.workspaceState === "retained-dirty" || record.workspaceState === "retained-failed") {
+            throw new Error(`Child run "${id}" cannot be resumed: its worktree workspace "${root}" was retained at release ` +
+                `(workspace state: "${record.workspaceState}"; uncommitted work is preserved there). Recover it explicitly first -- ` +
+                `recoverChildWorkspace("${id}") verifies the worktree and reactivates it -- then resume.`);
+        }
+    }
+    /**
+     * Explicitly verify and reactivate a retained child worktree (spec
+     * 2026-09-09, "Workspace states and explicit recovery"). Read-only
+     * inspection only -- the workspace owner's verification reads the
+     * administrative entry and the checked-out branch and never creates,
+     * checks out, resets, or force-removes anything -- and on success the
+     * record's workspace state becomes "active" (persisted) so the child can be
+     * resumed in the SAME worktree. Automatic recreation stays out of scope by
+     * design: every failed check refuses with an actionable error naming the
+     * failed check, and the workspace state stays unverified.
+     */
+    async recoverWorkspace(id) {
+        this.assertOpen();
+        const record = this.records.get(id);
+        if (!record)
+            throw new Error(`Unknown delegation handle "${id}".`);
+        const workspace = record.workspace;
+        if (!workspace || workspace.isolation !== "worktree" || !workspace.root) {
+            throw new Error(`Child workspace recovery refused for run "${id}": it has no worktree workspace to recover ` +
+                `(isolation: ${workspace?.isolation ?? "none"}). Only worktree-isolated children hold a recoverable workspace; ` +
+                `nothing was verified and the record is unchanged.`);
+        }
+        const root = workspace.root;
+        if (!existsSync(root)) {
+            if (record.workspaceState !== "released") {
+                record.workspaceState = "missing";
+                record.updatedAt = Date.now();
+                try {
+                    this.persist?.(record);
+                }
+                catch {
+                    // The in-memory classification stands even if persistence cannot.
+                }
+            }
+            throw new Error(`Child workspace recovery refused for run "${id}": its recorded worktree root "${root}" does not exist ` +
+                `(workspace state: "${record.workspaceState ?? "missing"}"). A missing workspace cannot be recovered; ` +
+                `nothing was created.`);
+        }
+        const owner = this.workspaceOwner ?? this.runtimeOptions?.workspaceOwner;
+        if (!owner || typeof owner.verify !== "function") {
+            throw new Error(`Child workspace recovery refused for run "${id}": no workspace owner with verification is available for ` +
+                `this session. The workspace at "${root}" was not inspected and stays unverified.`);
+        }
+        let dirty;
+        try {
+            ({ dirty } = await owner.verify(id, root));
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new Error(`Child workspace recovery refused for run "${id}": ${detail} No recovery was performed and the ` +
+                `workspace stays unverified.`);
+        }
+        record.workspaceState = "active";
+        record.updatedAt = Date.now();
+        try {
+            this.persist?.(record);
+        }
+        catch {
+            // The in-memory record is reactivated regardless; the persisted state
+            // catches up with the next save.
+        }
+        return { workspaceState: "active", dirty };
+    }
+    /**
+     * The owner consulted when a tracked child's lifecycle ends. Optional:
+     * without one, close/dispose still clean claims but release nothing.
+     */
+    setWorkspaceOwner(owner) {
+        this.workspaceOwner = owner;
+    }
+    /** Record that a child session's workspace (worktree) must be released when its lifecycle ends. */
+    trackWorkspace(sessionId) {
+        this.trackedWorkspaces.add(sessionId);
+    }
+    /**
+     * Release a tracked child's workspace through the owner, once per session
+     * id. Best effort: a missing owner is tolerated and an owner failure never
+     * propagates -- cleanup must never break close or dispose. The outcome is
+     * stored per session id (`workspaceReleaseOutcome()`), and a kept tree is
+     * warned about loudly so silent data loss cannot hide behind best-effort
+     * cleanup.
+     */
+    releaseWorkspaceOnce(sessionId) {
+        if (this.releasedWorkspaces.has(sessionId))
+            return Promise.resolve();
+        this.releasedWorkspaces.add(sessionId);
+        this.trackedWorkspaces.delete(sessionId);
+        const owner = this.workspaceOwner;
+        if (!owner)
+            return Promise.resolve();
+        return Promise.resolve()
+            .then(() => owner.release(sessionId))
+            .catch((error) => ({
+            removed: false,
+            kept: "failed",
+            dir: "",
+            error: error instanceof Error ? error.message : String(error),
+        }))
+            .then((outcome) => {
+            this.workspaceReleaseOutcomes.set(sessionId, outcome);
+            this.recordWorkspaceState(sessionId, outcome);
+            if (!outcome.removed) {
+                if (outcome.kept === "dirty") {
+                    console.warn(`[apex-code] Child worktree for session "${sessionId}" kept at ${outcome.dir}; uncommitted child work preserved. ` +
+                        `Resume after reattach is refused for worktree children. Manual removal: git worktree remove --force ${outcome.dir}`);
+                }
+                else {
+                    console.warn(`[apex-code] Child worktree release failed for session "${sessionId}" (tree kept at ${outcome.dir}): ${outcome.error ?? "unknown error"}`);
+                }
+            }
+        })
+            .catch(() => undefined);
+    }
+    /**
+     * Classify a finished release on the record (spec 2026-09-09, "Workspace
+     * states and explicit recovery"): removed -> "released", kept dirty ->
+     * "retained-dirty", kept failed -> "retained-failed". Only worktree-isolated
+     * records carry the state. The classified record persists immediately -- even
+     * though release is fire-and-forget -- so a restarted parent sees the
+     * classification and can refuse or recover accordingly.
+     */
+    recordWorkspaceState(sessionId, outcome) {
+        const record = this.records.get(sessionId);
+        if (!record || record.workspace?.isolation !== "worktree")
+            return;
+        record.workspaceState = outcome.removed
+            ? "released"
+            : outcome.kept === "dirty"
+                ? "retained-dirty"
+                : "retained-failed";
+        record.updatedAt = Date.now();
+        try {
+            this.persist?.(record);
+        }
+        catch {
+            // The in-memory record still carries the classification even when
+            // persistence cannot run (best effort, like the release itself).
+        }
+    }
+    /** The stored outcome of this session id's workspace release, if it has run. */
+    workspaceReleaseOutcome(sessionId) {
+        return this.workspaceReleaseOutcomes.get(sessionId);
+    }
+    /** Awaitable variant for the delegation failure path, which must release before the throw surfaces. */
+    async releaseWorkspaceNow(sessionId) {
+        await this.releaseWorkspaceOnce(sessionId);
+        this.workspaceClaims.delete(sessionId);
+    }
+    releaseWorkspace(sessionId) {
+        this.workspaceClaims.delete(sessionId);
+    }
+    activeWorkspaceClaims() {
+        return [...this.workspaceClaims.values()].flat();
+    }
+    claimWorkspace(sessionId, paths) {
+        if (paths.length)
+            this.workspaceClaims.set(sessionId, paths);
+    }
+    save(handleId, entry, status) {
+        const latest = entry.latest;
+        const record = {
+            handleId,
+            agentType: entry.agentType,
+            sessionId: handleId,
+            task: entry.task,
+            artifactDir: entry.artifactDir,
+            workspace: entry.workspace,
+            depth: entry.depth,
+            status,
+            updatedAt: Date.now(),
+            // Attempts, the active attempt, and the spawn dedupe key persist with
+            // every save: a restarted parent rebuilds attempts and the key->handle
+            // map from these records alone.
+            attempts: (entry.attempts ?? []).map((attempt) => ({ ...attempt })),
+            activeAttemptId: entry.activeAttemptId,
+            // Record linkage (policy snapshot, sandbox flag, parent session id)
+            // persists with every save too, so session readers describe the child
+            // without re-deriving its policy (spec 2026-09-09, "Derive, do not
+            // reconstruct").
+            ...(entry.parentSessionId !== undefined ? { parentSessionId: entry.parentSessionId } : {}),
+            ...(entry.policy
+                ? {
+                    policy: {
+                        ...entry.policy,
+                        tools: [...entry.policy.tools],
+                        capabilities: [...entry.policy.capabilities],
+                    },
+                }
+                : {}),
+            ...(entry.sandboxEnforced !== undefined ? { sandboxEnforced: entry.sandboxEnforced } : {}),
+            ...(entry.idempotencyKey !== undefined ? { idempotencyKey: entry.idempotencyKey } : {}),
+            ...(entry.deadlineMs !== undefined ? { deadlineMs: entry.deadlineMs } : {}),
+            ...(entry.cancelled ? { cancelled: { ...entry.cancelled } } : {}),
+        };
+        // The settlement's output persists with the record so a historical run's
+        // result stays retrievable after restart without reattaching the child.
+        if (latest) {
+            record.latestResult = {
+                output: latest.outcome === "failed"
+                    ? latest.error instanceof Error
+                        ? latest.error.message
+                        : String(latest.error)
+                    : latest.output,
+                outcome: latest.outcome,
+            };
+        }
+        this.records.set(handleId, record);
+        this.persist?.(record);
+    }
+    /**
+     * Record a turn settlement from the child handle's own report, falling back to
+     * the settlement value for handles that did not report. The latest settlement
+     * wins; retrieval serves it instead of the stored first-turn promise.
+     */
+    recordCompletion(id, entry, fallbackOutput) {
+        const reported = entry.child?.latestResult?.();
+        entry.latest =
+            !reported || reported.outcome === "completed"
+                ? { outcome: "completed", output: reported?.output ?? fallbackOutput }
+                : reported.outcome === "interrupted"
+                    ? { outcome: "interrupted", output: reported.output }
+                    : { outcome: "failed", error: new Error(reported.output || "Child run failed.") };
+        this.persistSettlement(id, entry);
+    }
+    recordFailure(id, entry, error) {
+        const reported = entry.child?.latestResult?.();
+        entry.latest =
+            reported?.outcome === "interrupted" || (!reported && entry.child?.status === "interrupted")
+                ? { outcome: "interrupted", output: reported?.output ?? "" }
+                : { outcome: "failed", error };
+        this.persistSettlement(id, entry);
+    }
+    /**
+     * Stamp the active attempt with the settled turn's outcome. A cancellation
+     * recorded on the entry wins for an interrupted settlement: the attempt
+     * stays `cancelled` instead of downgrading to plain `interrupted`. Attempt
+     * usage snapshots from the child's own controller where its handle exposes
+     * one; handles without a controller leave usage unset. `tokensAtEnd`
+     * snapshots the run-level token/cost rollup at settlement time (a
+     * cumulative-at-end snapshot of the whole transcript -- see
+     * `ChildRunAttempt`); when nothing is reachable it stays unset.
+     */
+    stampAttemptSettlement(id, entry) {
+        const attempt = activeAttemptOf(entry);
+        const latest = entry.latest;
+        if (!attempt || !latest)
+            return;
+        attempt.outcome = latest.outcome === "interrupted" && entry.cancelled ? "cancelled" : latest.outcome;
+        if (latest.outcome === "failed") {
+            attempt.error = latest.error instanceof Error ? latest.error.message : String(latest.error);
+        }
+        const usage = entry.child?.usage?.();
+        if (usage)
+            attempt.usage = usage;
+        const totals = this.usageTotalsFor(id, entry.artifactDir, entry.child);
+        if (totals)
+            attempt.tokensAtEnd = totals;
+    }
+    /** Persist the settlement's status. A closed run's terminal status is never overwritten by late settlement. */
+    persistSettlement(id, entry) {
+        if (entry.closed)
+            return;
+        const latest = entry.latest;
+        if (!latest)
+            return;
+        this.stampAttemptSettlement(id, entry);
+        this.save(id, entry, latest.outcome === "completed" ? "completed" : latest.outcome === "interrupted" ? "interrupted" : "failed");
+        // Terminal settlement (completed/failed/interrupted) releases the run's
+        // concurrency slot (spec 2026-09-09, "Shared budgets").
+        this.releaseChildRunSlot(id);
+    }
+    assertOpen() {
+        if (this.disposed)
+            throw new Error("Child run registry is disposed.");
+    }
+    /** The configured child-run concurrency limit, if any. */
+    concurrencyLimit() {
+        const limit = this.runtimeOptions?.maxConcurrentChildren;
+        return typeof limit === "number" && Number.isFinite(limit) && limit > 0 ? Math.floor(limit) : undefined;
+    }
+    /**
+     * Concurrency admission (spec 2026-09-09, "Shared budgets"): refuse with an
+     * actionable error naming the limit BEFORE any child session is built when
+     * every slot is occupied. An admitted run holds one slot until terminal
+     * settlement, close, dispose, or a launch failure releases it.
+     */
+    admitChildRun(handleId) {
+        const limit = this.concurrencyLimit();
+        if (limit === undefined)
+            return;
+        if (this.heldRunSlots.size >= limit) {
+            throw new Error(`Delegation refused: maxConcurrentChildren=${limit} and ${this.heldRunSlots.size} child run(s) are still active. Wait for a child run to finish or close it, or raise maxConcurrentChildren.`);
+        }
+        this.heldRunSlots.add(handleId);
+    }
+    /** Release a run's concurrency slot. Idempotent. */
+    releaseChildRunSlot(handleId) {
+        this.heldRunSlots.delete(handleId);
+    }
+    own(child) {
+        if (this.disposed) {
+            child.dispose();
+            this.assertOpen();
+        }
+        this.children.add(child);
+    }
+    release(child) {
+        if (this.children.delete(child))
+            child.dispose();
+    }
+    register(id, entry) {
+        this.assertOpen();
+        // A launch is attempt 1: an entry without attempts starts its first epoch
+        // here (resumeHistorical supplies its own carried-over attempts).
+        if (entry.attempts === undefined || entry.attempts.length === 0) {
+            entry.attempts = [{ id: "attempt-1", startedAt: Date.now() }];
+            entry.activeAttemptId ??= entry.attempts[0].id;
+        }
+        if (entry.idempotencyKey !== undefined) {
+            this.idempotencyKeys.set(entry.idempotencyKey, id);
+        }
+        if (!this.entries.has(id)) {
+            this.entries.set(id, entry);
+            // Observe the initial turn's settlement here so the latest result is
+            // recorded even when retrieval never happens; this derived branch always
+            // resolves, so it can never become an unhandled rejection itself.
+            const settled = entry.promise.then((result) => {
+                this.recordCompletion(id, entry, result.output);
+                return result;
+            }, (error) => {
+                this.recordFailure(id, entry, error);
+                return undefined;
+            });
+            void settled.catch(() => undefined);
+            entry.pending = settled;
+        }
+        this.save(id, entry, "created");
+    }
+    retrieve(id, expected) {
+        const entry = this.entries.get(id);
+        if (!entry) {
+            const record = this.records.get(id);
+            if (!record)
+                throw new Error(`Unknown delegation handle "${id}".`);
+            if (expected !== undefined && record.agentType !== expected)
+                throw new Error(`Delegation handle "${id}" belongs to agent "${record.agentType}", not "${expected}".`);
+            const latest = record.latestResult;
+            if (!latest) {
+                throw new Error(`Child run "${id}" has no persisted output, so its result cannot be recovered after restart. Resume it with resumeChildRun("${id}") to reattach its child session.`);
+            }
+            return Promise.resolve({
+                agentType: record.agentType,
+                task: record.task ?? "",
+                output: latest.output,
+                outcome: latest.outcome,
+            });
+        }
+        if (expected !== undefined && entry.agentType !== expected)
+            throw new Error(`Delegation handle "${id}" belongs to agent "${entry.agentType}", not "${expected}".`);
+        return this.latestDelegationResult(entry);
+    }
+    /** Await any in-flight turn, then serve its settled outcome -- not the stored first-turn promise. */
+    async latestDelegationResult(entry) {
+        if (entry.pending)
+            await entry.pending.catch(() => undefined);
+        const latest = entry.latest;
+        if (!latest)
+            return entry.promise;
+        if (latest.outcome === "failed")
+            throw latest.error;
+        return { agentType: entry.agentType, task: entry.task, output: latest.output, outcome: latest.outcome };
+    }
+    /**
+     * One entry per child run -- live entries first, then historical records --
+     * each as `{handleId, agentType, task, status, attemptCount}`. Backward
+     * compatible: fields were only ever added. Observing the list lazily
+     * interrupts a live running child whose wall-clock deadline has passed.
+     */
+    list() {
+        this.observeDeadlines();
+        const historical = [...this.records]
+            .filter(([id]) => !this.entries.has(id))
+            .map(([handleId, record]) => ({
+            handleId,
+            agentType: record.agentType,
+            task: record.task ?? "",
+            status: record.status === "closed"
+                ? "closed"
+                : record.status === "interrupted"
+                    ? "interrupted"
+                    : record.status === "running"
+                        ? "running"
+                        : "idle",
+            attemptCount: childRunAttemptsOf(record).length,
+        }));
+        return [...this.entries]
+            .map(([handleId, entry]) => ({
+            handleId,
+            agentType: entry.agentType,
+            task: entry.task,
+            status: entry.closed ? "closed" : (entry.child?.status ?? "idle"),
+            attemptCount: (entry.attempts ?? []).length,
+        }))
+            .concat(historical);
+    }
+    /**
+     * Non-blocking status snapshot for one handle (spec 2026-09-09, pollable
+     * status): built from the live entry or the persisted record alone, never by
+     * awaiting a turn. Unknown ids still error. Observing the status lazily
+     * interrupts a live running child whose wall-clock deadline has passed, so a
+     * timed-out run is reported (and stopped) at observation time.
+     */
+    status(id) {
+        this.assertOpen();
+        this.observeDeadlines();
+        const entry = this.entries.get(id);
+        if (entry)
+            return this.statusFromEntry(id, entry);
+        const record = this.records.get(id);
+        if (!record)
+            throw new Error(`Unknown delegation handle "${id}".`);
+        return this.statusFromRecord(record);
+    }
+    /**
+     * The run's token/cost totals, rolled up on demand from the child's OWN
+     * session transcript (the session-file reading seam) -- or from the handle's
+     * in-memory session entries when no transcript file exists. Reads lazily and
+     * caches only the last-computed totals, keyed by transcript size/mtime or
+     * entry count, so the cache can never become a second transcript.
+     * `undefined` -- never zero-filled, never a throw -- when nothing is
+     * reachable: an in-memory child without a reachable transcript, or a
+     * historical record whose transcript is gone. Unknown ids error like
+     * `status`.
+     */
+    usageTotals(id) {
+        this.assertOpen();
+        const entry = this.entries.get(id);
+        if (entry)
+            return this.usageTotalsFor(id, entry.artifactDir, entry.child);
+        const record = this.records.get(id);
+        if (!record)
+            throw new Error(`Unknown delegation handle "${id}".`);
+        return this.usageTotalsFor(id, record.artifactDir);
+    }
+    /**
+     * One rollup read for both live entries and historical records: a
+     * resolvable transcript file wins (the persisted transcript is the source of
+     * truth, including after restart); the handle's in-memory session entries
+     * cover an in-memory child whose transcript was never written.
+     */
+    usageTotalsFor(id, artifactDir, child) {
+        const sessionFile = resolveSessionFile(artifactDir, id);
+        if (sessionFile) {
+            try {
+                const stats = statSync(sessionFile);
+                const key = `file:${stats.size}:${stats.mtimeMs}`;
+                const cached = this.usageCache.get(id);
+                if (cached && cached.key === key)
+                    return cached.totals;
+                const totals = computeUsageTotals(loadEntriesFromFile(sessionFile));
+                if (totals)
+                    this.usageCache.set(id, { key, totals });
+                return totals;
+            }
+            catch {
+                // An unreadable transcript falls through to the in-memory seam below;
+                // reporting usage must never turn a status read into a failure.
+            }
+        }
+        const entries = child?.sessionEntries?.();
+        if (entries) {
+            const last = entries[entries.length - 1];
+            const key = `mem:${entries.length}:${last?.id ?? ""}`;
+            const cached = this.usageCache.get(id);
+            if (cached && cached.key === key)
+                return cached.totals;
+            const totals = computeUsageTotals(entries);
+            if (totals)
+                this.usageCache.set(id, { key, totals });
+            return totals;
+        }
+        return undefined;
+    }
+    /** The status payload's flattened view of the rollup, omitted when unreachable. */
+    static usageSummaryOf(totals) {
+        if (!totals)
+            return {};
+        return {
+            tokens: {
+                inputTokens: totals.inputTokens,
+                outputTokens: totals.outputTokens,
+                cacheReadTokens: totals.cacheReadTokens,
+                cacheWriteTokens: totals.cacheWriteTokens,
+                totalTokens: totals.totalTokens,
+            },
+            cost: { ...totals.cost },
+        };
+    }
+    statusFromEntry(id, entry) {
+        const attempt = activeAttemptOf(entry);
+        const latest = entry.latest;
+        const usage = entry.child?.usage?.();
+        const workspace = entry.workspace;
+        // The persisted record is the authority for a worktree's lifecycle state
+        // (a closed-but-live entry's release may already have classified it);
+        // while the record has none the live workspace is simply active.
+        const workspaceState = this.records.get(id)?.workspaceState;
+        // Entries never carry their own session id: save() always records the
+        // handle id as the child session id, so transcript resolution uses it.
+        const sessionFile = resolveSessionFile(entry.artifactDir, id);
+        return {
+            handleId: id,
+            agentType: entry.agentType,
+            task: entry.task,
+            status: entry.closed ? "closed" : (entry.child?.status ?? "idle"),
+            attempt: {
+                id: attempt?.id ?? "",
+                ...(attempt?.outcome !== undefined ? { outcome: attempt.outcome } : {}),
+            },
+            attempts: (entry.attempts ?? []).length,
+            ...(latest
+                ? {
+                    lastResult: {
+                        output: latest.outcome === "failed"
+                            ? latest.error instanceof Error
+                                ? latest.error.message
+                                : String(latest.error)
+                            : latest.output,
+                        outcome: latest.outcome,
+                    },
+                }
+                : {}),
+            ...(entry.cancelled ? { cancelled: { ...entry.cancelled } } : {}),
+            ...(entry.deadlineMs !== undefined ? { deadlineMs: entry.deadlineMs } : {}),
+            ...(usage ? { usage } : {}),
+            // Token/cost rollup from the child's own transcript, on the same lazy,
+            // cached seam `usageTotals` serves; omitted when nothing is reachable.
+            ...ChildRunRegistry.usageSummaryOf(this.usageTotalsFor(id, entry.artifactDir, entry.child)),
+            ...(workspace
+                ? {
+                    workspace: {
+                        isolation: workspace.isolation,
+                        ...(workspace.root ? { root: workspace.root } : {}),
+                    },
+                    ...(workspace.isolation === "worktree" ? { workspaceState: workspaceState ?? "active" } : {}),
+                }
+                : {}),
+            // Record linkage (additive): artifact/session-file/parent identity,
+            // the derived policy, and the sandbox flag ride along when known and
+            // are simply omitted otherwise.
+            ...(entry.artifactDir !== undefined ? { artifactDir: entry.artifactDir } : {}),
+            ...(sessionFile !== undefined ? { sessionFile } : {}),
+            ...(entry.parentSessionId !== undefined ? { parentSessionId: entry.parentSessionId } : {}),
+            ...(entry.policy ? { policy: entry.policy } : {}),
+            ...(entry.sandboxEnforced !== undefined ? { sandboxEnforced: entry.sandboxEnforced } : {}),
+        };
+    }
+    statusFromRecord(record) {
+        const attempts = childRunAttemptsOf(record);
+        // The active attempt when one is open; otherwise (terminal or legacy
+        // record) the most recent attempt carries the reported outcome.
+        const attempt = record.activeAttemptId
+            ? (attempts.find((candidate) => candidate.id === record.activeAttemptId) ?? attempts[attempts.length - 1])
+            : attempts[attempts.length - 1];
+        const workspace = record.workspace;
+        const sessionFile = resolveSessionFile(record.artifactDir, record.sessionId);
+        return {
+            handleId: record.handleId,
+            agentType: record.agentType,
+            task: record.task ?? "",
+            status: record.status === "closed"
+                ? "closed"
+                : record.status === "interrupted"
+                    ? "interrupted"
+                    : record.status === "running"
+                        ? "running"
+                        : "idle",
+            attempt: {
+                id: attempt?.id ?? attempts[attempts.length - 1]?.id ?? "",
+                ...(attempt?.outcome !== undefined ? { outcome: attempt.outcome } : {}),
+            },
+            attempts: attempts.length,
+            ...(record.latestResult ? { lastResult: { ...record.latestResult } } : {}),
+            ...(record.cancelled ? { cancelled: { ...record.cancelled } } : {}),
+            ...(record.deadlineMs !== undefined ? { deadlineMs: record.deadlineMs } : {}),
+            // Token/cost rollup from the persisted transcript, so a restarted
+            // parent reports the same totals without a live child.
+            ...ChildRunRegistry.usageSummaryOf(this.usageTotalsFor(record.handleId, record.artifactDir)),
+            ...(workspace
+                ? {
+                    workspace: {
+                        isolation: workspace.isolation,
+                        ...(workspace.root ? { root: workspace.root } : {}),
+                    },
+                    // Absent means active (legacy records predate the field).
+                    ...(workspace.isolation === "worktree" ? { workspaceState: record.workspaceState ?? "active" } : {}),
+                }
+                : {}),
+            // Record linkage (additive): legacy records without the fields simply
+            // omit them (spec 2026-09-09, policy/sandbox/artifact linkage).
+            ...(record.artifactDir !== undefined ? { artifactDir: record.artifactDir } : {}),
+            ...(sessionFile !== undefined ? { sessionFile } : {}),
+            ...(record.parentSessionId !== undefined ? { parentSessionId: record.parentSessionId } : {}),
+            ...(record.policy ? { policy: record.policy } : {}),
+            ...(record.sandboxEnforced !== undefined ? { sandboxEnforced: record.sandboxEnforced } : {}),
+        };
+    }
+    /**
+     * Lazy deadline observation (spec 2026-09-09, timeouts): a live RUNNING child
+     * past its recorded wall-clock deadline is interrupted at observation time.
+     * The interrupt carries no reason -- a wall-time timeout is not a user
+     * cancellation -- so the attempt settles `interrupted`, and the child's own
+     * budget gate names "wall-time" in the settlement error path when the run's
+     * turn was refused for time. Historical records have no live child to
+     * interrupt and are left untouched.
+     */
+    observeDeadlines() {
+        const now = Date.now();
+        for (const [id, entry] of this.entries) {
+            if (entry.closed || entry.deadlineMs === undefined || now < entry.deadlineMs)
+                continue;
+            if (entry.child?.status !== "running")
+                continue;
+            try {
+                this.interrupt(id);
+            }
+            catch {
+                // The child vanished between the check and the interrupt; nothing left to observe.
+            }
+        }
+    }
+    child(id) {
+        this.assertOpen();
+        const entry = this.entries.get(id);
+        if (!entry)
+            throw new Error(`Unknown delegation handle "${id}".`);
+        if (entry.closed)
+            throw new Error(`Child session "${id}" is closed.`);
+        if (!entry.child)
+            throw new Error(`Delegation handle "${id}" has no child session.`);
+        return entry.child;
+    }
+    async wait(id) {
+        const entry = this.entries.get(id);
+        // A historical record has nothing to await: its persisted settlement (if
+        // any) is served through retrieve, which throws the actionable error when
+        // no output was persisted.
+        if (!entry)
+            return this.retrieve(id);
+        if (!entry.closed) {
+            const child = this.child(id);
+            if (entry.pending || child.status === "running")
+                this.save(id, entry, "running");
+            // A turn that ends interrupted or failed rejects here; retrieval below owns
+            // propagation, surfacing interrupted as an outcome and failed as a throw.
+            await child.wait().catch(() => undefined);
+        }
+        return this.retrieve(id);
+    }
+    sendInput(id, input) {
+        // Unknown and closed handles throw synchronously, matching close()'s contract.
+        const child = this.child(id);
+        const entry = this.entries.get(id);
+        const turn = child.sendInput(input).then(() => {
+            this.recordCompletion(id, entry, "");
+        }, (error) => {
+            this.recordFailure(id, entry, error);
+            throw error;
+        });
+        void turn.catch(() => undefined);
+        entry.pending = turn;
+        return turn;
+    }
+    /**
+     * Interrupt a live child. An optional reason turns the interrupt into an
+     * explicit cancellation: `{reason, at}` is persisted on the record
+     * immediately and the active attempt is marked `cancelled`; without a
+     * reason the attempt settles plain `interrupted` at the turn's settlement.
+     */
+    interrupt(id, reason) {
+        this.child(id).interrupt();
+        if (reason === undefined)
+            return;
+        const entry = this.entries.get(id);
+        if (!entry)
+            return; // Unreachable: child(id) already validated the handle.
+        entry.cancelled = { reason, at: Date.now() };
+        const attempt = activeAttemptOf(entry);
+        if (attempt)
+            attempt.outcome = "cancelled";
+        // The child's post-interrupt handle status maps onto the record's status
+        // vocabulary ("idle" is a handle state, not a record state).
+        const childStatus = entry.child?.status;
+        const recordStatus = childStatus === "running" ? "running" : "interrupted";
+        this.save(id, entry, recordStatus);
+    }
+    /**
+     * Close a live run's active attempt with its latest settled outcome and open
+     * a new one for the resuming turn (spec 2026-09-09, "Child lifecycle"):
+     * `AgentSession.resumeChildRun` calls this on the live path before
+     * `sendInput` so a resume is a distinct attempt epoch, while ordinary
+     * follow-ups on a live run stay inside the active attempt.
+     */
+    beginResumeAttempt(id) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            throw new Error(`Unknown delegation handle "${id}".`);
+        const prior = activeAttemptOf(entry);
+        if (prior && prior.endedAt === undefined) {
+            prior.endedAt = Date.now();
+            prior.outcome ??= entry.latest?.outcome;
+        }
+        // A resume close stamps the closed attempt's cumulative-at-end rollup
+        // when its settlement never produced one (a settlement-stamped snapshot
+        // is never overwritten with the later, larger transcript).
+        if (prior && prior.tokensAtEnd === undefined) {
+            const totals = this.usageTotalsFor(id, entry.artifactDir, entry.child);
+            if (totals)
+                prior.tokensAtEnd = totals;
+        }
+        const attempts = entry.attempts ?? [];
+        const attempt = { id: `attempt-${attempts.length + 1}`, startedAt: Date.now() };
+        attempts.push(attempt);
+        entry.attempts = attempts;
+        entry.activeAttemptId = attempt.id;
+    }
+    close(id) {
+        this.assertOpen();
+        const entry = this.entries.get(id);
+        if (!entry)
+            throw new Error(`Unknown delegation handle "${id}".`);
+        if (entry.closed)
+            return;
+        entry.closed = true;
+        this.workspaceClaims.delete(id);
+        // A closed run's slot is released with it (spec 2026-09-09, "Shared
+        // budgets"), even when its turn never settles.
+        this.releaseChildRunSlot(id);
+        // Release the child's workspace (worktree) with its lifecycle; best effort,
+        // fire-and-forget: close() is synchronous and must never throw on cleanup.
+        void this.releaseWorkspaceOnce(id);
+        this.save(id, entry, "closed");
+        if (entry.child) {
+            this.children.delete(entry.child);
+            entry.child.close();
+        }
+    }
+    /** Stop tracking handles and release any children and workspaces still owned by this registry. */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        for (const child of this.children) {
+            try {
+                child.interrupt();
+            }
+            catch { }
+            try {
+                this.release(child);
+            }
+            catch { }
+        }
+        // Release every tracked child workspace (worktree) with the registry.
+        // Best effort and fire-and-forget: dispose() is synchronous.
+        for (const sessionId of this.trackedWorkspaces) {
+            void this.releaseWorkspaceOnce(sessionId);
+        }
+        this.entries.clear();
+        this.workspaceClaims.clear();
+        this.usageCache.clear();
+        // No run holds a concurrency slot past the registry's disposal.
+        this.heldRunSlots.clear();
+    }
 }
 /**
  * Run one delegation to completion. Throws rather than returning a failure value,
@@ -47,72 +1248,144 @@ function background(options) {
  * or `buildChildSession`. `buildChildSession` receives the child's depth (parent + 1)
  * so the caller can record it on the child's own session header.
  */
+/**
+ * Whether two resolved paths denote the same directory or either contains the
+ * other. Comparison is separator-correct: forward-slash prefix matching
+ * silently never matches on platforms whose resolve() produces backslashes.
+ */
+export function claimPathsOverlap(a, b) {
+    const ab = relative(a, b);
+    if (ab !== ".." && !ab.startsWith(`..${sep}`) && !isAbsolute(ab))
+        return true;
+    const ba = relative(b, a);
+    return ba !== ".." && !ba.startsWith(`..${sep}`) && !isAbsolute(ba);
+}
 export async function runDelegation(options, agentType, task, request = {}) {
-    const definition = options.resolveAgent(agentType);
-    if (!definition) {
-        throw new Error(`Unknown agent type "${agentType}".`);
-    }
-    const depth = options.getDelegationDepth();
-    if (depth >= options.maxDelegationDepth) {
-        throw new Error(`Delegation depth limit (${options.maxDelegationDepth}) reached at depth ${depth}; cannot delegate to agent "${agentType}" further.`);
+    let registry = options.childRunRegistry;
+    if (!registry) {
+        registry = new ChildRunRegistry();
+        options.childRunRegistry = registry;
     }
-    const requestedCapabilities = new Set();
-    for (const toolName of definition.tools) {
-        const capabilities = options.getToolCapabilities(toolName);
-        if (!capabilities) {
-            throw new Error(`Agent "${agentType}" requests unknown tool "${toolName}".`);
+    registry.assertOpen();
+    registry.setRuntimeOptions(options);
+    // Idempotent spawn: a key that already maps to a handle returns that handle
+    // BEFORE any admission or child construction, so a duplicate spawn consumes
+    // no second concurrency slot. The map is rebuilt from persisted records on
+    // restore, so a restarted parent dedupes too.
+    if (request.idempotencyKey !== undefined) {
+        const existing = registry.handleForIdempotencyKey(request.idempotencyKey);
+        if (existing !== undefined) {
+            return {
+                agentType,
+                task,
+                output: `Delegation already started with handle "${existing}" (idempotency key "${request.idempotencyKey}"); retrieve it with that handle.`,
+                handleId: existing,
+            };
         }
-        for (const capability of capabilities)
-            requestedCapabilities.add(capability);
     }
-    const ceiling = computeCapabilityCeiling(options.getParentCapabilities(), requestedCapabilities);
-    if (!ceiling.allowed) {
-        throw new Error(`Delegating to agent "${agentType}" requires capability "${ceiling.deniedCapability}", which exceeds the parent's authority.`);
+    const timeoutMs = typeof request.timeoutMs === "number" && Number.isFinite(request.timeoutMs) ? request.timeoutMs : undefined;
+    const { definition, capabilities } = resolveAdmittedDefinition(options, agentType);
+    const workspace = request.workspace ?? { isolation: "shared-read", ownedPaths: [] };
+    // The owner is read only for worktree isolation, so production callers can
+    // construct it lazily: a shared-read delegation never builds an owner and
+    // never invokes git.
+    const workspaceOwner = workspace.isolation === "worktree" ? options.workspaceOwner : undefined;
+    if (workspace.isolation === "worktree" && !workspaceOwner) {
+        throw new Error(`Delegation to agent "${agentType}" requested worktree isolation, but no workspace owner is available.`);
     }
-    const sessionId = randomUUID();
-    let artifactDir;
-    const parentSessionDir = options.getParentSessionDir?.();
-    if (parentSessionDir) {
-        const parentRoot = resolve(parentSessionDir);
-        artifactDir = join(parentRoot, "delegations", sessionId);
-        mkdirSync(artifactDir, { recursive: true });
-    }
-    const child = await options.buildChildSession({
-        agentType,
-        definition,
-        toolNames: definition.tools,
-        depth: depth + 1,
-        sessionId,
-        artifactDir,
-    });
-    const execute = async () => {
-        try {
-            const { output } = await child.run(task);
-            return { agentType, task, output };
+    const claims = [...workspace.ownedPaths].map((p) => resolve(p));
+    for (const entry of registry.activeWorkspaceClaims()) {
+        if (claims.some((path) => claimPathsOverlap(path, entry))) {
+            throw new Error(`Delegation to agent "${agentType}" overlaps an active write ownership claim.`);
         }
-        finally {
-            child.dispose();
+    }
+    // The depth bound and capability ceiling are enforced inside
+    // resolveAdmittedDefinition above, shared with historical reattachment.
+    // The caller may provide the public handle so the registry identity and
+    // child session identity cannot diverge. Existing callers retain generated IDs.
+    const sessionId = request.handleId ?? randomUUID();
+    const depth = options.getDelegationDepth();
+    registry.claimWorkspace(sessionId, claims);
+    if (workspaceOwner) {
+        // Worktree isolation: the registry releases this workspace when the run
+        // closes or the registry disposes, through the same owner.
+        registry.setWorkspaceOwner(workspaceOwner);
+        registry.trackWorkspace(sessionId);
+    }
+    try {
+        // Concurrency admission (spec 2026-09-09, "Shared budgets"): over the
+        // limit this throws BEFORE any child session is built, naming the limit.
+        registry.admitChildRun(sessionId);
+        const preparedWorkspace = workspaceOwner
+            ? await workspaceOwner.prepare({ ...workspace, ownedPaths: claims, sessionId })
+            : workspace;
+        let artifactDir;
+        const parentSessionDir = options.getParentSessionDir?.();
+        if (parentSessionDir) {
+            const parentRoot = resolve(parentSessionDir);
+            artifactDir = join(parentRoot, "delegations", sessionId);
+            mkdirSync(artifactDir, { recursive: true });
         }
-    };
-    if (!request.background)
-        return execute();
-    const handleId = sessionId;
-    const promise = execute();
-    // Retrieval owns propagation of a child failure; mark the background promise
-    // observed now so a child that fails before retrieval does not become an
-    // unhandled rejection.
-    void promise.catch(() => { });
-    background(options).set(handleId, { agentType, promise });
-    return { agentType, task, output: `Delegation started. Retrieve result with handle "${handleId}".`, handleId };
+        const child = await options.buildChildSession({
+            agentType,
+            definition,
+            toolNames: definition.tools,
+            capabilities,
+            depth: depth + 1,
+            sessionId,
+            artifactDir,
+            workspace: preparedWorkspace,
+            ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        });
+        registry.own(child);
+        const handleId = sessionId;
+        const promise = child.run(task).then(({ output }) => ({ agentType, task, output }));
+        // register() observes the turn's settlement: it records the handle's latest
+        // result (retrieval follows that, not this promise) and persists the run's
+        // terminal status, so no separate settlement hook is needed here. The
+        // durable fields ride along so every save() can persist them for restart.
+        // A launch is attempt 1; timeoutMs also records the wall-clock deadline the
+        // pollable status observes lazily. The record linkage (policy snapshot,
+        // sandbox flag, parent session id) comes from the handle's own
+        // construction report -- the values buildChildSession actually used --
+        // and the runtime's parent-session seam; fixture handles that omit them
+        // simply leave the record fields absent.
+        registry.register(handleId, {
+            agentType,
+            task,
+            promise,
+            child,
+            artifactDir,
+            workspace: preparedWorkspace,
+            depth: depth + 1,
+            attempts: [{ id: "attempt-1", startedAt: Date.now() }],
+            activeAttemptId: "attempt-1",
+            ...(child.policy ? { policy: child.policy } : {}),
+            ...(child.sandboxEnforced !== undefined ? { sandboxEnforced: child.sandboxEnforced } : {}),
+            ...(options.getParentSessionId ? { parentSessionId: options.getParentSessionId() } : {}),
+            ...(request.idempotencyKey !== undefined ? { idempotencyKey: request.idempotencyKey } : {}),
+            ...(timeoutMs !== undefined ? { deadlineMs: Date.now() + timeoutMs } : {}),
+        });
+        if (!request.background)
+            return promise;
+        return { agentType, task, output: `Delegation started. Retrieve result with handle "${handleId}".`, handleId };
+    }
+    catch (error) {
+        // The delegation never started: release the workspace immediately (also
+        // marks it released, so a later close/dispose cannot double-release) and
+        // give back the concurrency slot admitted above.
+        registry.releaseChildRunSlot(sessionId);
+        await registry.releaseWorkspaceNow(sessionId);
+        throw error;
+    }
 }
 /** Retrieve a background delegation. Running children are awaited; unknown handles fail explicitly. */
 export async function retrieveDelegationResult(options, handleId, expectedAgentType) {
-    const entry = background(options).get(handleId);
-    if (!entry)
-        throw new Error(`Unknown delegation handle "${handleId}".`);
-    if (expectedAgentType !== undefined && entry.agentType !== expectedAgentType) {
-        throw new Error(`Delegation handle "${handleId}" belongs to agent "${entry.agentType}", not "${expectedAgentType}".`);
+    let registry = options.childRunRegistry;
+    if (!registry) {
+        registry = new ChildRunRegistry();
+        options.childRunRegistry = registry;
     }
-    return entry.promise;
+    return registry.retrieve(handleId, expectedAgentType);
 }
 //# sourceMappingURL=runtime.js.map