apex-code 0.0.4 → 0.0.6

package/dist/core/delegation/runtime.d.ts

@@ -12,6 +12,8 @@
  * `AgentSession`/`createAgentSession` and therefore free of the import cycle that
  * would create (`sdk.ts` already imports `agent-session.ts`).
  */
+import type { AgentRunBudgetUsage } from "apex-code-agent-core";
+import { type SessionEntry } from "../session-manager.ts";
 import type { Capability } from "../tools/contract.ts";
 /** A delegatable agent's static configuration. Markdown + frontmatter in production (`agents.ts`); a plain object in tests. */
 export interface AgentDefinition {
@@ -26,12 +28,110 @@ export interface AgentDefinition {
 /** Resolve an agent type to its definition, or `undefined` if unknown. Production implements this over markdown/frontmatter (`agents.ts`); tests inject plain functions with the same shape. */
 export type AgentDefinitionResolver = (agentType: string) => AgentDefinition | undefined;
 /** A running or completed child, as far as the runtime needs to know. */
+export type ChildSessionStatus = "idle" | "running" | "interrupted" | "closed";
+/** Terminal outcome of a child's latest settled turn. */
+export type ChildTurnOutcome = "completed" | "failed" | "interrupted";
+/**
+ * Token and cost totals for one child run, rolled up from the child's OWN
+ * session transcript (the session-file reading seam; never a second transcript
+ * cache). The numbers are summed exactly as the provider reported them -- cost
+ * is provider-reported, so cache reads are NOT re-priced, re-counted, or
+ * double-counted; an entry without usage counts as zero.
+ */
+export interface ChildRunUsageTotals {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    totalTokens: number;
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        total: number;
+    };
+    /** Wall-clock time (ms) the rollup was computed at. */
+    asOf: number;
+    /** Usage-bearing transcript entries examined (assistant messages, compaction, branch summaries), including those without usage. */
+    entriesCounted: number;
+}
+/** The output and terminal outcome of a child's latest settled turn, as reported by its own handle. */
+export interface ChildTurnResult {
+    output: string;
+    outcome: ChildTurnOutcome;
+}
+/** Terminal outcome of one attempt on a child run. `cancelled` is recorded only by an explicit interrupt-with-reason. */
+export type ChildRunAttemptOutcome = "completed" | "failed" | "interrupted" | "cancelled";
+/**
+ * One launch-or-resume epoch of a child run (spec 2026-09-09, "Child
+ * lifecycle"): a launch is attempt 1; a resume closes the prior attempt with
+ * its terminal outcome and opens a new one. A live run's follow-ups and
+ * steering stay inside the active attempt. `usage` snapshots the child's own
+ * budget controller when its session exposes one (optional on the handle).
+ * `tokensAtEnd` snapshots the run-level usage/cost rollup (see
+ * `ChildRunUsageTotals`) at the attempt's settlement: these are
+ * CUMULATIVE-AT-END snapshots of the child's whole transcript, never per-attempt
+ * deltas -- range attribution between attempts is not attempted because turns
+ * that settled after the last persisted boundary are re-run on resume, so the
+ * transcript alone cannot attribute usage to an epoch.
+ */
+export interface ChildRunAttempt {
+    id: string;
+    startedAt: number;
+    endedAt?: number;
+    outcome?: ChildRunAttemptOutcome;
+    error?: string;
+    usage?: AgentRunBudgetUsage;
+    tokensAtEnd?: ChildRunUsageTotals;
+}
 export interface ChildSessionHandle {
+    readonly status: ChildSessionStatus;
     /** Run the task to completion and return the child's final output text. */
     run(task: string): Promise<{
         output: string;
     }>;
-    /** Release the child's resources. Always called, including after a failed run. */
+    /**
+     * The latest settled turn's output and terminal outcome, derived by this handle
+     * from the actual prompt resolution; `undefined` before any turn settles. This --
+     * not the registry's stored first-turn promise -- is the source of truth for
+     * background retrieval after `sendInput`/`followUp`/resume.
+     */
+    latestResult(): ChildTurnResult | undefined;
+    wait(): Promise<void>;
+    interrupt(): void;
+    close(): void;
+    sendInput(input: string): Promise<void>;
+    followUp(input: string): Promise<void>;
+    /**
+     * Point-in-time snapshot of the child's own run budget counters, when its
+     * session exposes a controller. Optional: handles whose child session does
+     * not surface a controller simply omit it, and every consumer treats
+     * attempt/status usage as optional.
+     */
+    usage?(): AgentRunBudgetUsage | undefined;
+    /**
+     * Read-only view of the child's own session entries, when the handle can
+     * reach its (possibly in-memory) session manager. Optional: fixture handles
+     * need not expose it, and the usage rollup consults it only when the child
+     * has no resolvable transcript file (an in-memory child never persisted
+     * one). Without this seam AND a transcript file, the run's usage totals are
+     * simply unreportable (`undefined`), never guessed.
+     */
+    sessionEntries?(): readonly SessionEntry[] | undefined;
+    /**
+     * The derived policy this handle's child was built with (populated by the
+     * sdk's `buildChildSession` from the request's admission projection and its
+     * own construction values). Optional: fixture handles may omit it, and the
+     * runtime relays it onto the child-run record when present.
+     */
+    policy?: ChildRunPolicySnapshot;
+    /**
+     * True when the OS-containment supervisor marker check passed at this
+     * handle's construction. Optional for the same reason as `policy`.
+     */
+    sandboxEnforced?: boolean;
+    /** Release the child's resources. Called when the child or owning parent is closed. */
     dispose(): void;
 }
 export interface BuildChildSessionRequest {
@@ -39,12 +139,110 @@ export interface BuildChildSessionRequest {
     definition: AgentDefinition;
     /** The child's tool allowlist, already ceiling-checked -- exactly `definition.tools`, never narrowed. */
     toolNames: string[];
+    /**
+     * The admitted capability set from the shared admission projection
+     * (`resolveAdmittedDefinition`). Consumers use it to describe the child;
+     * they must never re-derive it (ADR 0010).
+     */
+    capabilities: ReadonlySet<Capability>;
     /** The child's own recursion depth (the parent's depth + 1), for the runtime constructing it to record on the child's session header (task 5.3). */
     depth: number;
     /** Stable id used for the child session and its artifact directory. */
     sessionId: string;
     /** Per-child artifact root, created before the child session is constructed. */
     artifactDir?: string;
+    workspace?: ChildWorkspaceRequest;
+    /**
+     * Reattachment marker (restart reconstruction): when set, `buildChildSession`
+     * opens this existing child session transcript instead of creating a new
+     * session. The path must be the child's own session file under its recorded
+     * artifact directory. Every other field keeps its fresh-delegation meaning,
+     * so permission/model/tool wiring has exactly one construction path.
+     */
+    reattachSessionPath?: string;
+    /**
+     * Optional wall-time cap for the child's OWN run budget (spec 2026-09-09,
+     * timeouts): forwarded as `maxWallTimeMs` so the existing AgentRunBudget
+     * wall-time gate enforces it mid-run. The launch also records
+     * `deadlineMs = Date.now() + timeoutMs` on the record for lazy observation.
+     */
+    timeoutMs?: number;
+}
+/** The workspace authority requested by a child. Paths are advisory claims,
+ * never a replacement for the path-permission or sandbox enforcement. */
+export interface ChildWorkspaceRequest {
+    isolation: "shared-read" | "worktree";
+    ownedPaths: readonly string[];
+    /**
+     * The resolved isolation root a workspace owner prepared for this child
+     * (worktree isolation): absent on the raw request, present on what
+     * `prepare()` returns, and the cwd the child session runs in.
+     */
+    root?: string;
+}
+/**
+ * Lifecycle state of a worktree-isolated child's workspace, persisted on the
+ * record (spec 2026-09-09, "Workspace states and explicit recovery"). Absent
+ * means "active" -- legacy records predate the field and a live worktree is
+ * active by definition. Release outcomes write "released" / "retained-dirty" /
+ * "retained-failed"; observing a vanished root at resume writes "missing".
+ * Explicit recovery (`recoverWorkspace`) verifies and writes "active".
+ */
+export type ChildWorkspaceState = "active" | "released" | "retained-dirty" | "retained-failed" | "missing";
+/** Success payload of explicit workspace recovery (`recoverChildWorkspace`). */
+export interface ChildWorkspaceRecoveryResult {
+    /** Always "active": the workspace was verified and reactivated. */
+    workspaceState: ChildWorkspaceState;
+    /** The verified worktree holds uncommitted or untracked work. */
+    dirty: boolean;
+}
+/**
+ * Real isolation and cleanup for a child's requested workspace authority (spec
+ * 2026-09-09, "Parallel work and ownership"): the workspace subsystem owns git;
+ * delegation only negotiates the request and refuses worktree isolation when no
+ * owner is available. `prepare()` runs only for `isolation: "worktree"` -- a
+ * shared-read delegation never touches an owner and never invokes git -- and
+ * the request it returns (with `root` set) is what `buildChildSession` receives.
+ */
+/**
+ * Terminal outcome of releasing a child workspace (worktree). A kept tree is
+ * never destroyed silently: "dirty" means uncommitted/untracked child work
+ * was preserved; "failed" means the remove failed for another reason and the
+ * tree was left in place.
+ */
+export type WorkspaceReleaseOutcome = {
+    removed: true;
+} | {
+    removed: false;
+    kept: "dirty" | "failed";
+    dir: string;
+    error?: string;
+};
+export interface ChildWorkspaceOwner {
+    prepare(request: ChildWorkspaceRequest & {
+        sessionId: string;
+    }): Promise<ChildWorkspaceRequest>;
+    /**
+     * Release the child's workspace, reporting what happened instead of
+     * throwing. `options.force` is the caller's explicit escape hatch to
+     * force-remove a dirty tree; without it a dirty tree must be kept.
+     */
+    release(sessionId: string, options?: {
+        force?: boolean;
+    }): Promise<WorkspaceReleaseOutcome> | WorkspaceReleaseOutcome;
+    /**
+     * Read-only verification that a recorded worktree root is still this
+     * owner's worktree for the session in the CURRENT workspace: layout,
+     * administrative entry, and checked-out branch. Never creates, checks out,
+     * resets, or force-removes anything; a failed check throws with the check
+     * named. Optional: owners that cannot verify simply never support explicit
+     * recovery, and `recoverWorkspace` refuses rather than guessing.
+     */
+    verify?(sessionId: string, root: string): Promise<{
+        dirty: boolean;
+    }> | {
+        dirty: boolean;
+    };
 }
 export interface DelegationRuntimeOptions {
     resolveAgent: AgentDefinitionResolver;
@@ -56,9 +254,105 @@ export interface DelegationRuntimeOptions {
     getDelegationDepth: () => number;
     /** Delegation is refused once `getDelegationDepth() >= maxDelegationDepth` -- assigned by the runtime, not by the tool, so the bound applies to any future delegation entry point. */
     maxDelegationDepth: number;
+    /**
+     * Maximum simultaneously-active child runs this runtime admits (spec
+     * 2026-09-09, "Shared budgets", concurrency cap). Checked at admission --
+     * before any child session is built -- and refused with an actionable error
+     * naming the limit. An admitted run holds one slot until terminal settlement
+     * (completed/failed/interrupted), close, registry disposal, or launch
+     * failure. `undefined` (default) is unlimited.
+     */
+    maxConcurrentChildren?: number;
     /** Parent session directory. When supplied, child artifacts are rooted beneath it. */
     getParentSessionDir?: () => string;
+    /**
+     * Parent session id. When supplied, child-run records carry
+     * `parentSessionId`, tying the durable record (and every protocol payload
+     * derived from it) to the parent session's own identity.
+     */
+    getParentSessionId?: () => string;
     buildChildSession: (request: BuildChildSessionRequest) => Promise<ChildSessionHandle>;
+    childRunRegistry?: ChildRunRegistry;
+    /** Durable session owner. Records are appended to the parent session's existing log. */
+    persistChildRun?: (record: ChildRunRecord) => void;
+    /** Optional workspace owner. It is responsible for real isolation and cleanup. */
+    workspaceOwner?: ChildWorkspaceOwner;
+}
+/**
+ * Compact, derivable snapshot of the derived policy a child session was built
+ * with (spec 2026-09-09, "Derive, do not reconstruct"). Populated at child
+ * construction from the values actually used -- never re-derived by consumers.
+ * `capabilities` come from the delegation runtime's single admission projection
+ * (`resolveAdmittedDefinition`), so no surface ever re-classifies authority
+ * (ADR 0010). Persisted on `ChildRunRecord` and surfaced through status/wait
+ * payloads; legacy records without it load unchanged.
+ */
+export interface ChildRunPolicySnapshot {
+    /** The child's tool allowlist, exactly as construction received it (ceiling-checked `definition.tools`). */
+    tools: string[];
+    /** The admitted capability set from the same admission projection that gated the launch. */
+    capabilities: string[];
+    /** The sandbox contract string the child was constructed under ("required" | "external" | "none"). */
+    sandbox: string;
+    /** The delegation depth bound in force for this child's own delegations. */
+    maxDelegationDepth: number;
+    /** The child's resolved model id (its definition's model, or the parent's current model). */
+    model?: string;
+    /** The child Agent's budget scope; children are built session-scoped so follow-ups continue one controller. */
+    budgetScope: "prompt" | "session";
+    /** Whether the child answers to the tree's shared aggregate ceiling (present only when explicitly configured at the root). */
+    aggregateBudget: boolean;
+}
+export interface ChildRunRecord {
+    handleId: string;
+    agentType: string;
+    sessionId?: string;
+    task?: string;
+    parentSessionId?: string;
+    artifactDir?: string;
+    /** The derived policy this child was built with, persisted so session readers describe the child without re-deriving it. Optional: legacy records predate the field. */
+    policy?: ChildRunPolicySnapshot;
+    /**
+     * True when the SDK's OS-containment supervisor marker check passed for the
+     * parent session (always the case under the "required" contract, which
+     * refuses construction without it). Absent on legacy records; false means
+     * the contract is "external"/"none" (or no supervisor marker was present)
+     * and the SDK already allowed the run.
+     */
+    sandboxEnforced?: boolean;
+    workspace?: ChildWorkspaceRequest;
+    /**
+     * Workspace lifecycle state for worktree-isolated records (see
+     * `ChildWorkspaceState`). Written by release outcomes, by resume-time
+     * observation of a vanished root ("missing"), and by explicit recovery
+     * ("active"). Absent -- on legacy records and shared-read runs -- means
+     * "active"; the field only ever appears for worktree isolation.
+     */
+    workspaceState?: ChildWorkspaceState;
+    depth?: number;
+    latestResult?: {
+        output: string;
+        outcome: ChildTurnOutcome;
+    };
+    status: "created" | "running" | "completed" | "failed" | "interrupted" | "closed";
+    updatedAt: number;
+    /**
+     * Attempt epochs (launch = attempt 1; resume opens a new one). Optional on
+     * the wire: legacy records predate the field and are synthesized on load --
+     * one attempt derived from the record's status/updatedAt -- so every
+     * in-memory record carries at least one.
+     */
+    attempts?: ChildRunAttempt[];
+    activeAttemptId?: string;
+    /** Caller-supplied spawn dedupe key; a restarted parent rebuilds the key->handle map from records. */
+    idempotencyKey?: string;
+    /** Wall-clock deadline recorded at launch (`Date.now() + timeoutMs`); observed lazily by status/list. */
+    deadlineMs?: number;
+    /** Explicit cancellation, recorded when the run is interrupted with a reason. */
+    cancelled?: {
+        reason: string;
+        at: number;
+    };
 }
 export interface DelegationResult {
     agentType: string;
@@ -66,6 +360,380 @@ export interface DelegationResult {
     output: string;
     /** Present for background work; pass this handle to retrieveDelegationResult. */
     handleId?: string;
+    /**
+     * Terminal outcome of the latest settled turn. Present on registry retrieval
+     * once any turn has settled; the foreground result of the initial run omits it.
+     */
+    outcome?: ChildTurnOutcome;
+}
+/**
+ * Non-blocking status snapshot of one child run (`agent/status`,
+ * `AgentSession.childRunStatus`). Built from the record/entry alone -- never by
+ * awaiting a turn -- so a caller can poll without blocking on the child.
+ */
+export interface ChildRunStatus {
+    handleId: string;
+    agentType: string;
+    task: string;
+    status: ChildSessionStatus;
+    /** The active attempt's identity and its latest outcome, if any turn has settled (or a cancellation was recorded). */
+    attempt: {
+        id: string;
+        outcome?: ChildRunAttemptOutcome;
+    };
+    /** Total attempt epochs, including closed ones. */
+    attempts: number;
+    /** The latest settled turn, as persisted for retrieval. */
+    lastResult?: {
+        output: string;
+        outcome: ChildTurnOutcome;
+    };
+    /** Present when the run was interrupted with an explicit reason. */
+    cancelled?: {
+        reason: string;
+        at: number;
+    };
+    /** Wall-clock launch deadline (present when the spawn carried timeoutMs). */
+    deadlineMs?: number;
+    /** Snapshot of the child's own budget controller, when its handle exposes one. */
+    usage?: AgentRunBudgetUsage;
+    /**
+     * Cumulative token totals rolled up from the child's own session transcript
+     * (or its in-memory entries when no transcript exists), flattened from
+     * `ChildRunUsageTotals`. Present beside `cost` whenever a rollup is
+     * reachable; omitted -- never zero-filled -- when nothing is reachable.
+     */
+    tokens?: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+        totalTokens: number;
+    };
+    /** Provider-reported cost totals corresponding to `tokens`. Absent whenever `tokens` is. */
+    cost?: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        total: number;
+    };
+    /** The run's negotiated workspace authority (isolation plus a prepared root, when a workspace owner provided one). */
+    workspace?: {
+        isolation: "shared-read" | "worktree";
+        root?: string;
+    };
+    /**
+     * Workspace lifecycle state (worktree-isolated runs only). Present whenever
+     * the workspace is worktree-isolated: the record's persisted state, or
+     * "active" while the entry is live and unretained.
+     */
+    workspaceState?: ChildWorkspaceState;
+    /** The child's per-run artifact directory, when the child is file-backed. */
+    artifactDir?: string;
+    /**
+     * The child's transcript path, resolved lazily from its artifact directory
+     * per SessionManager's `<timestamp>_<sessionId>.jsonl` naming. Absent when
+     * the child is in-memory or has not persisted a transcript yet; resolution
+     * never throws.
+     */
+    sessionFile?: string;
+    /** The parent session id the run belongs to, when the runtime supplies one. */
+    parentSessionId?: string;
+    /** The derived policy the child was built with; absent on legacy records and fixture handles that never carried one. */
+    policy?: ChildRunPolicySnapshot;
+    /** True when the OS-containment supervisor marker check passed for the parent session; absent on legacy records. */
+    sandboxEnforced?: boolean;
+}
+/** The registry's record of a handle's latest settled turn. */
+type LatestTurnSettlement = {
+    outcome: "completed";
+    output: string;
+} | {
+    outcome: "interrupted";
+    output: string;
+} | {
+    outcome: "failed";
+    error: unknown;
+};
+interface BackgroundDelegation {
+    agentType: string;
+    task: string;
+    promise: Promise<DelegationResult>;
+    child?: ChildSessionHandle;
+    closed?: boolean;
+    /** The latest settled turn; `undefined` until the first settlement is recorded. */
+    latest?: LatestTurnSettlement;
+    /** The turn whose settlement has not been observed through retrieval yet, if any. */
+    pending?: Promise<unknown>;
+    /** Durable fields, persisted on every save so a restart can reattach the child session. */
+    artifactDir?: string;
+    workspace?: ChildWorkspaceRequest;
+    depth?: number;
+    /** Record linkage persisted with every save (policy snapshot, sandbox flag, parent session id). */
+    policy?: ChildRunPolicySnapshot;
+    sandboxEnforced?: boolean;
+    parentSessionId?: string;
+    /** Attempt epochs (spec 2026-09-09, "Child lifecycle"). `register()` supplies attempt 1 when the caller did not. */
+    attempts?: ChildRunAttempt[];
+    activeAttemptId?: string;
+    idempotencyKey?: string;
+    deadlineMs?: number;
+    cancelled?: {
+        reason: string;
+        at: number;
+    };
+}
+/** Default follow-up prompt for resuming an interrupted child run. */
+export declare const RESUME_CHILD_PROMPT = "Resume the interrupted task and continue from the existing session.";
+export declare class ChildRunRegistry {
+    private readonly entries;
+    private readonly workspaceClaims;
+    private readonly children;
+    /**
+     * 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()`.
+     */
+    private readonly trackedWorkspaces;
+    /** Session ids whose workspace release has already started -- release runs once, never twice. */
+    private readonly releasedWorkspaces;
+    /** Last release outcome per session id, surfaced through `workspaceReleaseOutcome()`. */
+    private readonly workspaceReleaseOutcomes;
+    private workspaceOwner?;
+    private disposed;
+    private persist?;
+    private records;
+    /**
+     * 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.
+     */
+    private readonly idempotencyKeys;
+    /**
+     * 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.
+     */
+    private readonly heldRunSlots;
+    /**
+     * 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.
+     */
+    private 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.
+     */
+    private readonly usageCache;
+    /** First attach wins: a registry is owned by one session's runtime. */
+    setRuntimeOptions(options: DelegationRuntimeOptions): void;
+    setPersistence(persist: (record: ChildRunRecord) => void): void;
+    /** Load validated historical records. This never constructs or starts a child. */
+    restore(records: readonly ChildRunRecord[]): void;
+    /** The handle a spawn dedupe key already maps to, if any. */
+    handleForIdempotencyKey(key: string): string | undefined;
+    /** True when `id` is known only as a persisted record -- no live entry in this process. */
+    isHistorical(id: string): boolean;
+    /**
+     * 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.
+     */
+    private resolveHistoricalSession;
+    /**
+     * 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.
+     */
+    resumeHistorical(id: string, input?: string): Promise<ChildSessionStatus>;
+    /**
+     * 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.
+     */
+    private rejectUnresumableWorktree;
+    /**
+     * 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.
+     */
+    recoverWorkspace(id: string): Promise<ChildWorkspaceRecoveryResult>;
+    /**
+     * The owner consulted when a tracked child's lifecycle ends. Optional:
+     * without one, close/dispose still clean claims but release nothing.
+     */
+    setWorkspaceOwner(owner: ChildWorkspaceOwner | undefined): void;
+    /** Record that a child session's workspace (worktree) must be released when its lifecycle ends. */
+    trackWorkspace(sessionId: string): void;
+    /**
+     * 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.
+     */
+    private releaseWorkspaceOnce;
+    /**
+     * 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.
+     */
+    private recordWorkspaceState;
+    /** The stored outcome of this session id's workspace release, if it has run. */
+    workspaceReleaseOutcome(sessionId: string): WorkspaceReleaseOutcome | undefined;
+    /** Awaitable variant for the delegation failure path, which must release before the throw surfaces. */
+    releaseWorkspaceNow(sessionId: string): Promise<void>;
+    releaseWorkspace(sessionId: string): void;
+    activeWorkspaceClaims(): string[];
+    claimWorkspace(sessionId: string, paths: string[]): void;
+    private save;
+    /**
+     * 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.
+     */
+    private recordCompletion;
+    private recordFailure;
+    /**
+     * 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.
+     */
+    private stampAttemptSettlement;
+    /** Persist the settlement's status. A closed run's terminal status is never overwritten by late settlement. */
+    private persistSettlement;
+    assertOpen(): void;
+    /** The configured child-run concurrency limit, if any. */
+    private concurrencyLimit;
+    /**
+     * 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: string): void;
+    /** Release a run's concurrency slot. Idempotent. */
+    releaseChildRunSlot(handleId: string): void;
+    own(child: ChildSessionHandle): void;
+    release(child: ChildSessionHandle): void;
+    register(id: string, entry: BackgroundDelegation): void;
+    retrieve(id: string, expected?: string): Promise<DelegationResult>;
+    private latestDelegationResult;
+    /**
+     * 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(): {
+        handleId: string;
+        agentType: string;
+        task: string;
+        status: ChildSessionStatus;
+        attemptCount: number;
+    }[];
+    /**
+     * 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: string): ChildRunStatus;
+    /**
+     * 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: string): ChildRunUsageTotals | undefined;
+    /**
+     * 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.
+     */
+    private usageTotalsFor;
+    /** The status payload's flattened view of the rollup, omitted when unreachable. */
+    private static usageSummaryOf;
+    private statusFromEntry;
+    private statusFromRecord;
+    /**
+     * 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.
+     */
+    private observeDeadlines;
+    private child;
+    wait(id: string): Promise<DelegationResult>;
+    sendInput(id: string, input: string): Promise<void>;
+    /**
+     * 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: string, reason?: string): void;
+    /**
+     * 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: string): void;
+    close(id: string): void;
+    /** Stop tracking handles and release any children and workspaces still owned by this registry. */
+    dispose(): void;
 }
 /**
  * Run one delegation to completion. Throws rather than returning a failure value,
@@ -87,9 +755,22 @@ export interface DelegationResult {
  * 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 declare function claimPathsOverlap(a: string, b: string): boolean;
 export declare function runDelegation(options: DelegationRuntimeOptions, agentType: string, task: string, request?: {
     background?: boolean;
+    workspace?: ChildWorkspaceRequest;
+    handleId?: string;
+    /** Spawn dedupe key (spec 2026-09-09, idempotent spawn): a known key returns the EXISTING handle without building a second child. */
+    idempotencyKey?: string;
+    /** Wall-time cap for the child's own run budget; also recorded as the record's deadlineMs for lazy observation. */
+    timeoutMs?: number;
 }): Promise<DelegationResult>;
 /** Retrieve a background delegation. Running children are awaited; unknown handles fail explicitly. */
 export declare function retrieveDelegationResult(options: DelegationRuntimeOptions, handleId: string, expectedAgentType?: string): Promise<DelegationResult>;
+export {};
 //# sourceMappingURL=runtime.d.ts.map