@sema-agent/core 5.19.0 → 5.21.0

package/dist/core/protocol-table.d.ts

@@ -1,19 +1,80 @@
+/**
+ * Protocol namespace table (roadmap 2026-08-02, the non-additive precondition for a second protocol).
+ *
+ * design/108 ① established ONE namespaced family — `mcp__<server>__<tool>` — and six call sites grew
+ * their own hard-coded `"mcp__"` reads (origin projection, grouped display, permission-rule lanes,
+ * the `__` reservation message). Each new protocol would need a twin branch at every site. This table
+ * makes "which protocol owns this tool name" a lookup: a second protocol (e.g. A2A) lands by
+ * APPENDING one entry, and every table-driven site picks it up unchanged.
+ *
+ * Dependency-free by design (pure string logic) — `mcp.ts` re-exports {@link MCP_NAMESPACE}'s prefix
+ * as its public `MCP_PREFIX` face, never the other way around. The MINTING pipeline (charset
+ * normalization + the assembled-name budget, which needs a digest) lives in `protocol-naming.ts`, which
+ * imports this module's type; the dependency never runs the other way, so this file stays dependency-free.
+ */
+/** The ids of every protocol the engine speaks. Doubles as the protocol slice of the tool-manifest
+ *  `ToolOrigin` union — adding a protocol extends BOTH (tsc pairs the change). */
 export type ProtocolId = "mcp" | "a2a";
+/** The (peer, tool) pair a namespaced wire name decomposes into. */
 export interface ProtocolPeerTool {
     peer: string;
     tool: string;
 }
+/**
+ * One tool-name namespace owned by an external protocol (design/108 ① generalized).
+ *
+ * `P` carries the namespace's prefix as a LITERAL type so a public face re-exporting it (mcp.ts's
+ * `MCP_PREFIX`) keeps `"mcp__"` rather than widening to `string` — a widened prefix compiles fine
+ * here while breaking every downstream literal-typed position, and the export-surface snapshot
+ * (name → kind) cannot see that class of change at all.
+ */
 export interface ProtocolNamespace<P extends string = string> {
+    /** Stable protocol id — doubles as the tool-manifest origin tag (e.g. `"mcp"`). */
     readonly id: ProtocolId;
+    /** Global marker prefix (`mcp__`). A name in this namespace starts with it; no caller tool name may
+     *  contain the `__` separator at all (prepare-task's reservation enforces the umbrella). */
     readonly prefix: P;
+    /**
+     * Compose the wire name for a (peer, tool) pair.
+     *
+     * NAME SHAPE ONLY — this is the namespace's spelling contract (prefix + separator placement), NOT the
+     * full minting pipeline: sanitizing and length-clamping the segments is `protocol-naming.ts`'s
+     * `mintNamespacedToolName`, which every protocol registering real tools goes through. Composing a raw,
+     * unsanitized pair here yields a syntactically valid name that no mint would have produced — use this
+     * leg for a name whose segments are already known-good (a test, a display form), the mint otherwise.
+     *
+     * NAMING CONSTRAINTS (enforced by a THROW, not a silent mangle): `peer` and `tool` must be non-empty and
+     * `peer` must not contain the `__` separator. A separator inside `peer` makes the name un-round-trippable
+     * — {@link parse} splits at the FIRST separator, so `("prod__db", "query")` reads back as peer `"prod"`,
+     * tool `"db__query"` — i.e. a name that silently denotes a different peer than the caller asked for.
+     * `tool` may contain the separator (it is the trailing remainder and round-trips verbatim).
+     */
     makeName(peer: string, tool: string): string;
+    /** Parse a wire name; `undefined` when the name is not in this namespace (or malformed inside it —
+     *  empty peer segment or empty tool segment both count as malformed). */
     parse(name: string): ProtocolPeerTool | undefined;
+    /** Collapsed display key for grouped listings (`mcp__<server>__*`); identity for a malformed name. */
     displayGroupKey(name: string): string;
 }
 declare const MCP_PREFIX_NAME: "mcp__";
+/** A2A's marker prefix. `a2a__<peer>__<skill>`: `peer` is the remote agent (whatever id the deployment
+ *  knows it by), `skill` the capability that agent advertises — the same two-segment shape MCP uses, so
+ *  every table-driven site (origin projection, grouped display, the caller-name reservation) reads it
+ *  unchanged. Deliberately NOT a prefix of, nor prefixed by, `mcp__`. */
 declare const A2A_PREFIX_NAME: "a2a__";
 export declare const MCP_NAMESPACE: ProtocolNamespace<typeof MCP_PREFIX_NAME>;
+/**
+ * The A2A tool namespace (roadmap 2026-08-03, appended for the A2A client/server work).
+ *
+ * NAME LAYER ONLY: this entry decides how an A2A tool name is SPELLED and how it decomposes. Nothing
+ * materializes A2A tools yet — until the client leg lands, no name in this namespace can exist at runtime,
+ * so appending the entry changes no live behavior. It exists first because every table-driven site
+ * (`protocolOf`, the grouped display key, the `ToolOrigin` union) then needs no change when it does.
+ */
 export declare const A2A_NAMESPACE: ProtocolNamespace<typeof A2A_PREFIX_NAME>;
+/** Every protocol namespace the engine knows. APPEND-ONLY: adding a protocol must not change how any
+ *  existing name resolves — prefixes must stay pairwise non-overlapping (pinned in the table test). */
 export declare const PROTOCOL_TABLE: readonly ProtocolNamespace[];
+/** The namespace owning `name`, or `undefined` for a caller/first-party tool. */
 export declare function protocolOf(name: string): ProtocolNamespace | undefined;
 export {};

package/dist/core/push-queue.d.ts

@@ -1,3 +1,4 @@
+/** A minimal async iterable you can push values into and close. Backpressure-free (buffers). */
 export declare class PushQueue<T> implements AsyncIterable<T> {
     private buffer;
     private waiters;

package/dist/core/remote-env.d.ts

@@ -1,29 +1,124 @@
+/**
+ * Remote execution seam (design/48 §5) — the type-only contract a **remote/containerised** `ExecutionEnv`
+ * implementation (E2B/Firecracker, owned by the service control plane) must satisfy so the agent's "hand"
+ * (design/44) can act inside an isolated, *stateful*, *suspendable* workspace instead of the in-process
+ * `NodeExecutionEnv`.
+ *
+ * **This file is a SEAM, not an implementation.** The real `RemoteContainerExecutionEnv` (E2B SDK, warm
+ * pools, snapshot lifecycle, tier routing) lives in the service and is driven by real integration needs —
+ * exactly like `CheckpointStore` (design/45). Core owns the seam shape; service owns the backend.
+ *
+ * Design rulings folded in (design/48 §10/§11 DeepSeek council):
+ * - **#1 [blocker] interface extension, not capability probing**: `RemoteExecutionEnv extends ExecutionEnv`.
+ *   The base {@link ExecutionEnv} is UNCHANGED — `NodeExecutionEnv`/`StubExecutionEnv` need zero edits, and a
+ *   consumer that only needs buffered fs/shell keeps accepting the base type.
+ * - **#3 [major] do not overload `exec`**: `exec()` stays buffered; streaming is a NEW {@link execStream}.
+ * - **#4 [major] suspend × in-flight exec must not hang**: see {@link suspendVM}.
+ * - **#8 [major] post-resume consistency**: see {@link postResumeInit}.
+ * - **#10 naming**: the isolation level is `sandboxTier` (not `tier`) to avoid clashing with the existing
+ *   timeout-/degradation-"tier" in the codebase.
+ * - **#16 suspend/resume disambiguation**: the VM-lifecycle methods are `suspendVM`/`resumeVM` to keep them
+ *   distinct from the Runner gate-resume and design/45 wake/resume semantics.
+ *
+ * **Deferred (NOT modelled here — they are runtime, not seam):** actually suspending a running task and
+ * persisting the {@link WorkspaceHandle} into a design/45 `Checkpoint`; the `status:"suspended"` orchestrator
+ * mapping; tier *classification* (the static table + Tier1-safe allow-list + fail-closed routing) — all are
+ * service/design-45 implementation-time concerns. Core only declares the seam those will plug into.
+ */
 import type { ExecutionEnv } from "../internal/harness-types.js";
+/** Snapshot identifier returned by {@link RemoteExecutionEnv.suspendVM}; opaque to core, resolved by the provider. */
 export type SnapshotId = string;
+/**
+ * Token identifying a still-running remote session, used by {@link RemoteExecutionEnv.reconnect} to re-attach
+ * the control plane's transport after a control-plane replica crash/failover. The underlying VM state lives
+ * independently of any single control-plane TCP connection (a Firecracker process survives a dropped client),
+ * so reconnect re-binds rather than re-creates.
+ */
 export type SessionToken = string;
+/** Isolation routing level (design/48 §2). v1 runs everything as Tier 2; classification is DEFERRED to service. */
 export type SandboxTier = 1 | 2;
+/**
+ * Serializable identity of a remote workspace (design/48 §5 gap 1). The control plane persists this into its
+ * durable state (and design/45 `Checkpoint`) so a *different* replica can reconnect/resume the same workspace.
+ */
 export interface WorkspaceHandle {
+    /** Provider/VM/sandbox id (e.g. an E2B sandbox id). */
     sandboxId: string;
+    /** Provider identifier (e.g. `"e2b"`), so the control plane routes reconnect/destroy to the right backend. */
     provider: string;
+    /** Absolute mount path of the workspace root inside the remote env; remote paths normalize against this. */
     mountPath: string;
+    /** Set when this env was produced by resuming a snapshot ({@link RemoteExecutionEnv.resumeVM}), else undefined. */
     snapshotId?: SnapshotId;
+    /** Token for {@link RemoteExecutionEnv.reconnect} when the VM is still running (vs suspended to a snapshot). */
     sessionToken?: SessionToken;
+    /** How a checkpointed workspace is restored on resume (1.257.2 hardening, codex review of [500]②):
+     *  `"park_only"` = durable-park-only suspend degrade (non-suspendable env; workspace persists on the
+     *  target, resume skips `resumeVM`). Absent = legacy/snapshot handle — resume treats a MISSING
+     *  `snapshotId` as corruption (fail-closed) unless the resumed env is itself non-suspendable
+     *  (tolerance for park handles minted by 1.257.1 before this field existed). */
     restoreMode?: "park_only";
 }
+/**
+ * A reference to a secret injected at {@link RemoteExecutionEnv.connect}/{@link RemoteExecutionEnv.postResumeInit}
+ * time (design/48 §5 gap 7) — never baked into the image. The control plane resolves {@link ref} to a value out of
+ * band; only the reference travels through core.
+ */
 export interface SecretRef {
+    /** Logical name the secret is exposed under (an env-var name in the remote env for `destination:"remote"`). */
     name: string;
+    /** Opaque locator the control plane resolves to a value (vault path, KMS key id, …). */
     ref: string;
+    /**
+     * Where the resolved secret is consumed (design/61 §9 B, council). Default `"remote"` (the original
+     * semantics): injected **into the remote env** as `name` (E2B env-var) — visible to code running there.
+     * `"adapter"`: used by the **adapter itself** to establish/authenticate the connection (an SSH private key,
+     * an ADB token) and **MUST NOT be injected into the target machine/device** — a credential that reaches an
+     * un-isolated target's environment is the lethal trifecta (design/53 §C). An adapter MUST honor this.
+     */
     destination?: "remote" | "adapter";
 }
+/** Configuration for {@link RemoteExecutionEnv.connect}. */
 export interface RemoteConnectConfig {
+    /** Resume from this snapshot instead of provisioning a fresh workspace. */
     snapshotId?: SnapshotId;
+    /** Secrets to inject at connect time (design/48 §5 gap 7). */
     secrets?: SecretRef[];
+    /** Abort provisioning/connection. */
     abortSignal?: AbortSignal;
 }
+/**
+ * Options for the VM-lifecycle ops {@link RemoteExecutionEnv.suspendVM} / {@link RemoteExecutionEnv.resumeVM}
+ * (design/49 v1.5, code-ready council BUG#2). Parity with {@link RemoteConnectConfig.abortSignal} /
+ * {@link ExecStreamOptions.signal}: without an abort hook a hung provider pause/restore (network partition)
+ * would pin the calling worker forever. The implementation races the op against this signal + an internal
+ * timeout; on abort it returns `{ok:false}` with code `"aborted"`.
+ */
 export interface VmLifecycleOptions {
+    /** Abort a hung pause/restore. */
     abortSignal?: AbortSignal;
+    /**
+     * [1461]④a (resume workspace-root fidelity) — the CHECKPOINTED {@link WorkspaceHandle} of the workspace
+     * being restored, passed by the engine on the `resumeVM` leg. An adapter SHOULD bind the restored
+     * workspace root (cwd / mount) to `priorHandle.mountPath` rather than its CURRENT deployment
+     * configuration: across a config-knob change window (e.g. a mount-path rotation) the resumed task's
+     * execs and artifacts must land in the root the task was checkpointed under, not the new one. An
+     * adapter that cannot honor the prior root MUST still return its ACTUAL `mountPath` in the restored
+     * handle (never echo `priorHandle.mountPath` unhonored) — the engine compares the two and surfaces a
+     * divergence observation. Absent on non-resume ops and from pre-1.360 engines (adapters treat absence
+     * as the legacy current-config behavior).
+     */
     priorHandle?: WorkspaceHandle;
 }
+/**
+ * One chunk streamed from {@link RemoteExecutionEnv.execStream} (design/48 §5 gap 3, council BUG#3). A run is a
+ * sequence of `stdout`/`stderr` chunks terminated by exactly one `exit` chunk carrying the typed exit code.
+ *
+ * The async iterator THROWS a {@link RemoteExecutionError} if the stream fails before an `exit` chunk arrives
+ * (transport loss, or a {@link RemoteExecutionEnv.suspendVM} that aborts the in-flight command) — that is the
+ * streaming analogue of the base {@link ExecutionEnv}'s never-throw `Result` contract, and it guarantees a
+ * consumer is never left awaiting a chunk that will never come.
+ */
 export type OutputChunk = {
     type: "stdout";
     data: string;
@@ -34,28 +129,178 @@ export type OutputChunk = {
     type: "exit";
     exitCode: number;
 };
+/** Options for {@link RemoteExecutionEnv.execStream}. */
 export interface ExecStreamOptions {
+    /**
+     * Isolation routing hint (design/48 §2; renamed from `tier` per §11 #10). The *classification* that decides
+     * a command's tier — static tool table + Tier1-safe sub-command allow-list, fail-closed to Tier 2 — is the
+     * env/control-plane's job and is DEFERRED; this param only lets a caller pass an explicit route when known.
+     */
     sandboxTier?: SandboxTier;
+    /** Working directory; relative paths resolve against the workspace root. */
     cwd?: string;
+    /** Extra environment variables for the command. */
     env?: Record<string, string>;
+    /**
+     * Total command wall-clock timeout in seconds. **🔴 Per-command — independent of the env/sandbox lifetime.**
+     * A remote adapter MUST NOT fall back to the sandbox lifetime when this is unset (service [45]: an E2B adapter
+     * that defaulted a missing per-command timeout to `cfg.timeoutMs` = the sandbox lifetime made a seconds-long
+     * command wait the *whole sandbox lifetime*, ~30 min, on a provider RPC hang). "No `timeout`" means "no
+     * wall-clock cap on a *making-progress* command" — NOT "wait until the env dies"; liveness is still bounded by
+     * {@link readTimeoutMs} (see below). Distinct concerns: `timeout` caps a slow-but-progressing command;
+     * `readTimeoutMs` catches a *hung/unreachable* one.
+     */
     timeout?: number;
+    /** Abort the command. Aborting ends the stream with a {@link RemoteExecutionError} (code `"aborted"`, no `exit` chunk). */
     signal?: AbortSignal;
+    /**
+     * Idle/liveness read timeout (ms). If no {@link OutputChunk} arrives within this window, `execStream` ends
+     * with a {@link RemoteExecutionError} (code `"timeout"`) instead of hanging. **Needed in practice for remote
+     * backends** (design/48 §5, service [7]): E2B issue #1128 — a *streaming* call sets no read timeout (only unary
+     * does), so an unreachable sandbox hangs the worker forever. Distinct from `timeout` (total wall-clock).
+     *
+     * 🔴 **Liveness contract (service [45]/[59]):** a remote adapter SHOULD enforce a default liveness bound even
+     * when this is unset (a missing idle timeout MUST NOT mean "wait forever / until the env dies"), and that bound
+     * MUST cover the **command-creation/handshake RPC**, not only the post-first-chunk loop — a provider hang
+     * typically occurs at creation, before any chunk arrives, so an idle timer started only after the first chunk
+     * misses it. On trigger, throw {@link RemoteExecutionError} with code `"timeout"` (retryable by the caller per
+     * the command's idempotency — the adapter MUST NOT blind-retry).
+     */
     readTimeoutMs?: number;
+    /** Per-call output cap (design/48 §5 gap 8): stop streaming after this many bytes to avoid a `find /` flooding the control plane. */
     maxOutputBytes?: number;
 }
-export type RemoteExecutionErrorCode = "suspended" | "command_in_flight" | "connect_failed" | "post_resume_failed" | "aborted" | "timeout" | "unsupported" | "auth_transient" | "auth_failed" | "transport_lost" | "unknown";
+/** Stable error codes for the remote seam's lifecycle/streaming operations (design/48 §5/§11 BUG#2). */
+export type RemoteExecutionErrorCode = 
+/** A lifecycle/exec op failed because the workspace is (or became) suspended. */
+"suspended"
+/** {@link RemoteExecutionEnv.suspendVM} refused because a command was still in flight (council #4). */
+ | "command_in_flight"
+/** Connect/resume/reconnect failed to reach or provision the remote workspace. */
+ | "connect_failed"
+/** A post-resume consistency step failed (design/48 §5/#8) — caller must destroy the env. */
+ | "post_resume_failed"
+/** The command/stream was aborted via its `AbortSignal`. */
+ | "aborted"
+/**
+ * A command's wall-clock {@link ExecStreamOptions.timeout} or liveness {@link ExecStreamOptions.readTimeoutMs}
+ * was exceeded — including a provider RPC hang at command creation (service [45]/[59]). **Retryable** by the
+ * caller per the command's idempotency (the adapter MUST NOT blind-retry). Distinct from `"aborted"` (a
+ * caller-driven `AbortSignal`) and `"connect_failed"` (workspace provisioning, not a per-command hang).
+ */
+ | "timeout"
+/**
+ * The op is not supported by this adapter's capabilities (design/61 §9 A) — e.g. `suspendVM`/`resumeVM` on a
+ * non-suspendable SSH/ADB env. Permanent for this env; check {@link RemoteExecutionEnv.capabilities} first.
+ */
+ | "unsupported"
+/**
+ * A **transient** authentication step that is expected to succeed on a retry (design/61 §9 C) — e.g. an ADB
+ * device awaiting first-time authorization (connect once → user authorizes → connect again succeeds).
+ * **Retryable** (typically retry-exactly-once). Distinct from {@link "auth_failed"} so a real rejection isn't
+ * retried and a bounded ADB retry doesn't false-kill an SSH transient.
+ */
+ | "auth_transient"
+/**
+ * **Permanent** authentication failure (design/61 §9 C) — wrong/rejected SSH key, revoked token. **NEVER
+ * retry** (retrying burns the whole attempt budget and can lock accounts). The caller must surface it.
+ */
+ | "auth_failed"
+/**
+ * The transport connection dropped mid-session (TCP RST, network partition, peer close) — design/61 §9 C/#14.
+ * **Retryable** by re-establishing the connection (idempotent for a persistent SSH/ADB session). An adapter
+ * MUST map raw transport errors (DNS `ENOTFOUND`, TCP RST) onto a typed code, not leave them as `"unknown"`,
+ * else a retry whitelist misses them.
+ */
+ | "transport_lost"
+/** Unclassified provider/transport failure. */
+ | "unknown";
+/**
+ * The RETRYABLE half of {@link RemoteExecutionErrorCode} — the codes whose own contract above says a retry
+ * can succeed (`auth_transient`: retry-exactly-once after the device is authorized; `connect_failed`: the
+ * workspace could not be reached/provisioned this attempt; `timeout`: a liveness bound tripped;
+ * `transport_lost`: re-establish the connection). Every OTHER code is permanent for this attempt
+ * (`auth_failed`/`unsupported`), caller-driven (`aborted`), or unclassifiable (`unknown`) — retrying them
+ * burns budget or, worse, re-drives a rejected credential.
+ *
+ * ONE list, two consumers, so a caller's retry decision and its DISCLOSURE can never disagree: the engine
+ * retries only IDEMPOTENT ops on these codes (see {@link withRetry}'s red line — a snapshot-taking
+ * `suspendVM` is never retried), and it stamps `retryable` on the failure it reports to the caller for the
+ * ops it does NOT retry, so a deployment can decide (refresh the credential and re-resume vs give up)
+ * without parsing prose.
+ */
 export declare const RETRYABLE_REMOTE_ERROR_CODES: readonly RemoteExecutionErrorCode[];
+/** Is `code` in the {@link RETRYABLE_REMOTE_ERROR_CODES} family? */
 export declare function isRetryableRemoteErrorCode(code: RemoteExecutionErrorCode): boolean;
+/**
+ * Error surfaced by {@link RemoteExecutionEnv} lifecycle ops and by {@link RemoteExecutionEnv.execStream}'s
+ * iterator. Mirrors the vendored `ExecutionError` shape but carries the remote-specific code set; it is kept
+ * separate from the vendored `ExecutionErrorCode` union deliberately — those codes only need to widen once the
+ * design/45 suspend/resume *runtime* lands and the Runner/orchestrator layer must thread `"suspended"`.
+ */
 export declare class RemoteExecutionError extends Error {
     readonly code: RemoteExecutionErrorCode;
     constructor(code: RemoteExecutionErrorCode, message: string, cause?: Error);
 }
+/**
+ * A remote, stateful, suspendable {@link ExecutionEnv} (design/48 §5). Extends the base with workspace identity,
+ * connection lifecycle, streaming exec, and post-resume reconciliation. Every method follows the base contract:
+ * **never throw/reject** — encode failures in the returned `Result` (the one exception is {@link execStream},
+ * whose iterator may throw mid-stream; see {@link OutputChunk}).
+ *
+ * Lifecycle methods are typed but their RUNTIME wiring (task suspension, `Checkpoint` persistence of the
+ * {@link WorkspaceHandle}, cross-replica resume) is implemented with design/45 — see the file header.
+ *
+ * 🔴 **Universal liveness contract (service [45]/[59] class-fix) — applies to EVERY remote RPC**, not just
+ * `execStream`: the inherited {@link ExecutionEnv} filesystem ops (`readTextFile`/`writeFile`/`listDir`/…), the
+ * streaming/buffered exec, AND the VM-lifecycle ops below (`connect`/`reconnect`/`suspendVM`/`resumeVM`/
+ * `postResumeInit`/`destroy`). Each is a network round-trip to a provider that can hang. The contract:
+ * 1. **Every remote RPC SHOULD enforce a bounded default liveness/idle timeout** even when no `abortSignal`/
+ *    timeout is given — a hung provider call MUST NOT wait until the env/sandbox lifetime expires (the
+ *    service [45] bug, but generalized: it was found on `exec`, and `files.read`/`resumeVM`/etc. share the
+ *    exact exposure). An optional `abortSignal` (where present) composes with, but does not replace, this default.
+ * 2. **🔴 Bound on LIVENESS (no progress), not a fixed short wall-clock** — distinguish *hung* from *slow but
+ *    progressing* (search [60] / service [50] data-transfer sharpening). A **data-transfer** op — a large-workspace
+ *    `suspendVM` snapshot, a big `writeFile`/`readTextFile` — may legitimately run for minutes; a fixed short
+ *    wall-clock would false-kill the (durable-checkpoint *命门*) path. So such ops bound on an **idle/no-heartbeat**
+ *    window (reset by observable progress), not total elapsed time. Cheap control RPCs (`isRunning`, a small
+ *    `connect` handshake) may use a short wall-clock. The adapter sizes the bound per op class.
+ * 3. **A liveness breach surfaces as a typed, retryable error**: `RemoteExecutionError` code `"timeout"` for the
+ *    lifecycle/stream ops; for the inherited filesystem ops (which return the vendored `Result<_, FileError>`),
+ *    a `FileError` — but still **bounded, never an unbounded wait**. Retry is the caller's decision per the op's
+ *    idempotency; the adapter MUST NOT blind-retry.
+ */
 export interface RemoteExecutionEnv extends ExecutionEnv {
+    /**
+     * What this adapter can actually do (design/61 §9 A, council). The seam was built for E2B (a full
+     * `{isolation:true, suspendable:true}` adapter); **partial-capability** adapters (SSH/ADB: `{false, false}`
+     * — a real machine/device, not snapshotable and not isolated) declare it here. **Required + explicit** so
+     * the orchestrator never has to guess: there is no safe default (assuming isolation when there is none is a
+     * security hole; assuming suspendable crashes on `suspendVM`). Use {@link isSuspendable}/{@link isIsolated}
+     * rather than the structural {@link isRemoteExecutionEnv} (method presence ≠ semantics — a stub `suspendVM`
+     * that returns `"unsupported"` still satisfies the structural check). Extensible: add fields as new
+     * partial-capability classes appear.
+     */
     readonly capabilities: {
+        /** True iff actions are contained (E2B microVM); false for a real target (SSH host / ADB device). The
+         *  orchestrator tightens autonomy + the design/37 policy gate when this is false (design/53 zero-trust). */
         isolation: boolean;
+        /** True iff the env can be snapshot/`suspendVM`'d (E2B); false for SSH/ADB (durable suspend N/A).
+         *
+         *  ⚠️ LOAD-BEARING INVARIANT (opus review 1.257.2): `suspendable:false` on a remote env also asserts
+         *  the workspace is EXTERNALLY DURABLE — it persists on the target across the env object's lifetime
+         *  (true for SSH hosts / ADB devices). The durable-park-only suspend degrade (service [500]②) rests
+         *  on this: it skips `suspendVM` and trusts the factory to reconnect to the SAME workspace on resume.
+         *  An adapter for a non-suspendable EPHEMERAL backend (e.g. a snapshot-less container torn down with
+         *  the transport) must NOT be modeled as `suspendable:false` remote — it would silently take the
+         *  park-only branch and resume onto a fresh empty workspace. Model such a backend as a per-task env
+         *  without durable suspend instead (the human gate refuses it), or extend capabilities with an
+         *  explicit workspace-durability flag before building one. */
         suspendable: boolean;
     };
+    /** Identity of the connected workspace (design/48 §5 gap 1). Synchronous: it is data the env already holds. */
     workspaceHandle(): WorkspaceHandle;
+    /** Provision/attach the remote workspace and inject secrets. Returns the resulting {@link WorkspaceHandle}. */
     connect(config?: RemoteConnectConfig): Promise<{
         ok: true;
         value: WorkspaceHandle;
@@ -63,6 +308,26 @@ export interface RemoteExecutionEnv extends ExecutionEnv {
         ok: false;
         error: RemoteExecutionError;
     }>;
+    /**
+     * Snapshot the workspace and (provider permitting) stop billing; returns the {@link SnapshotId} to resume from.
+     *
+     * **Council #4 — must not leave an in-flight command hung.** If a {@link Shell.exec}/{@link execStream} is in
+     * flight, an implementation MUST either (a) refuse with `RemoteExecutionError("command_in_flight")`, or (b)
+     * abort the in-flight command — buffered `exec` then resolves an `Err` and an in-flight {@link execStream}
+     * iterator throws `RemoteExecutionError("suspended")`. It must NOT silently snapshot and leave the command's
+     * promise/iterator pending forever.
+     *
+     * **🔴 Atomicity contract (design/49 v1.5, code-ready council BUG#1/#13).** This is the FIRST durable side
+     * effect of a remote durable-suspend, so its all-or-nothing semantics are load-bearing for the Runner's
+     * commit ordering:
+     * - `{ok:true}` ⇒ the VM is paused at `value` (a `SnapshotId`); the caller may now persist a checkpoint.
+     * - `{ok:false}` ⇒ the VM is left in its ORIGINAL (running) state, untouched — the caller can safely fall
+     *   back to the synchronous `onAsk` gate as if no suspend was attempted (Runner: design/49 §4①).
+     * An implementation MUST NOT return `{ok:false}` after it has already paused/snapshotted the VM. The gate
+     * path means no command is in flight (the batch's prior calls are awaited, the gated call has not run), so
+     * `command_in_flight` should not arise; if it does, the Runner treats it as an ordinary `{ok:false}` and
+     * falls back to `onAsk` — see {@link RemoteExecutionErrorCode}.
+     */
     suspendVM(options?: VmLifecycleOptions): Promise<{
         ok: true;
         value: SnapshotId;
@@ -70,6 +335,9 @@ export interface RemoteExecutionEnv extends ExecutionEnv {
         ok: false;
         error: RemoteExecutionError;
     }>;
+    /** Restore the workspace from a snapshot. Idempotent + re-entrant (a replica that crashed mid-suspend can be
+     *  superseded by another resuming the same {@link SnapshotId} without corruption — aligns with design/45 resolve-CAS).
+     *  Pass `options.abortSignal` so a hung restore cannot pin the resuming worker (design/49 BUG#2). */
     resumeVM(snapshotId: SnapshotId, options?: VmLifecycleOptions): Promise<{
         ok: true;
         value: WorkspaceHandle;
@@ -77,6 +345,7 @@ export interface RemoteExecutionEnv extends ExecutionEnv {
         ok: false;
         error: RemoteExecutionError;
     }>;
+    /** Re-attach the control-plane transport to a still-running VM after a control-plane reconnect (design/48 §5 gap 4). */
     reconnect(sessionToken: SessionToken): Promise<{
         ok: true;
         value: WorkspaceHandle;
@@ -84,6 +353,18 @@ export interface RemoteExecutionEnv extends ExecutionEnv {
         ok: false;
         error: RemoteExecutionError;
     }>;
+    /**
+     * Re-establish consistency AFTER {@link resumeVM}/{@link reconnect} (design/48 §5 gap, council #8): re-fetch git
+     * remote refs + invalidate stale package/index caches, and re-inject secrets (short-lived credentials may have
+     * expired while suspended). Any failed step → `Err("post_resume_failed")` and the caller MUST destroy the env.
+     *
+     * Note: a resumed guest's network/long-lived connections (git remote / API / registry) are NOT guaranteed to
+     * survive the snapshot (clay decision 2), so this is also where the VM-internal agent rebuilds those.
+     *
+     * 🔴 Ordering red line (design/48 §5/#6): at-rest encryption of the memory snapshot must be ensured BEFORE
+     * secrets are injected — never let plaintext credentials land in an unencrypted snapshot. That encryption is a
+     * service-side property of the snapshot store; this method must fail-and-clean if it cannot be guaranteed.
+     */
     postResumeInit(): Promise<{
         ok: true;
         value: void;
@@ -91,18 +372,119 @@ export interface RemoteExecutionEnv extends ExecutionEnv {
         ok: false;
         error: RemoteExecutionError;
     }>;
+    /**
+     * Stream a command's output (design/48 §5 gap 3) — the standard path for long build/test runs. Distinct from
+     * the buffered base `exec()` (council #3: no overload). Yields `stdout`/`stderr` chunks then exactly one `exit`
+     * chunk; the iterator throws {@link RemoteExecutionError} if the stream fails before `exit` (see {@link OutputChunk}).
+     *
+     * 🔴 **Timeout/liveness contract (service [45]/[59]) — applies to BOTH `execStream` and the base `exec`:** a
+     * per-command timeout is **independent of the env/sandbox lifetime** and an adapter MUST NOT fall back to the
+     * lifetime when none is given (else a hung provider RPC pins the worker for the whole sandbox lifetime). An
+     * adapter SHOULD enforce a bounded default liveness/idle timeout that also covers the command-creation RPC, and
+     * surface a liveness/timeout breach as a typed, retryable {@link RemoteExecutionError} code `"timeout"`. See
+     * {@link ExecStreamOptions.timeout} / {@link ExecStreamOptions.readTimeoutMs}.
+     */
     execStream(command: string, options?: ExecStreamOptions): AsyncIterable<OutputChunk>;
+    /**
+     * Tear down the workspace and release provider resources. Best-effort; must never throw (like `cleanup`).
+     * **Must be idempotent** — safe to call more than once (the second call is a no-op). The Runner calls it
+     * once on task end, and `prepareTask` calls it on a prepare-time throw; a remote impl may also be reaped,
+     * so a defensive double-call must not error or double-bill.
+     *
+     * 飞轮 [519] contract note: on a NON-isolated env (no `capabilities.isolation` — host lane, SSH host),
+     * destroy() is workspace/object-level cleanup and must NOT reap still-running background processes —
+     * that is `disposeBackgroundShells`' job, which honours the timeout/session keep-alive except-list
+     * ([511]③ monitor timeout anchor). An isolated env (container/VM) naturally takes everything down;
+     * the Runner's envDying settle accounts for that with an accurate killed receipt beforehand.
+     */
     destroy(): Promise<void>;
 }
+/** Context handed to an {@link ExecutionEnvFactory} for each task (design/48 §5 / §7 Q7). Deliberately minimal:
+ *  per-task identity is enough to allocate/route a per-task container; richer routing (tenant/principal) is
+ *  captured in the factory closure by the trusted control plane that builds it. */
 export interface ExecutionEnvFactoryContext {
+    /** Resolved session id for the task — the stable identity of its per-task workspace. */
     sessionId: string;
+    /** Caller-supplied task id, when set on the `TaskSpec`. */
     taskId?: string;
+    /**
+     * design/97 CORE-6 — per-task ISOLATION request threaded from the workflow's `ctx.agent({ isolation })` via
+     * the TRUSTED `RunInternals` channel (never from the untrusted `TaskSpec`). When `"worktree"`, a
+     * control-plane factory **MUST either mint a git-worktree-rooted env for this agent (e.g. via
+     * {@link addWorktree}) WITH a `destroy()` that removes the worktree, or THROW.** It MUST NOT silently
+     * return a non-isolated env (the shared base env, or a child rooted at `parentCwd`): the spawn may be
+     * governed by a relaxed write baseline (`WorkflowGovernanceBaseline.worktreeBase`) that is safe ONLY
+     * inside a worktree — a silent degrade would point those writes at the shared working tree. A factory
+     * throw fails the spawn (fail-closed: the child never starts) — the honest outcome. The engine
+     * additionally rejects the observable degrade shapes at its consumption point (no factory configured;
+     * the shared static env returned as-is; an in-process env rooted at the base root or the parent's cwd),
+     * but full worktree verification is the factory's contract — there is no receipt field on
+     * {@link ExecutionEnv}. Unset = default (the factory's normal per-task env).
+     */
     isolation?: "worktree";
+    /**
+     * Blackboard 2026-07-03 (clay dogfood — sub-agents landing in an EMPTY sandbox): the PARENT task's
+     * effective working root, threaded (like `isolation`) via the TRUSTED `RunInternals` channel when this
+     * task is a sub-agent (workflow `ctx.agent` / Task delegation). CC parity: a Task sub-agent inherits the
+     * main session's cwd. A single-user/TOC factory SHOULD root the child env here (unless `isolation`
+     * requests a worktree — that wins); a multi-tenant/TOB factory minting isolated containers may ignore
+     * it. Absent on top-level tasks. Static shared-`executionEnv` deployments need nothing — the child
+     * already shares the parent env (and its cwd).
+     */
     parentCwd?: string;
 }
+/**
+ * A **trusted control-plane** factory that mints a per-task {@link ExecutionEnv} (design/48 §5 answers core
+ * gap-a / §7 Q7). Lives on `RunnerDeps` (deployment-level) — NOT on `TaskSpec` — so an untrusted caller can
+ * never inject its own env and escape the sandbox (design/44 §7 Q4 red line; clay decision 3: the Docker
+ * fast-lane must be control-plane-assigned, never task-selectable).
+ *
+ * The remote model is "one container per task", so the factory is invoked once per task. The Runner owns the
+ * lifetime of a factory-produced env: if it implements {@link RemoteExecutionEnv.destroy} (see {@link hasDestroy}),
+ * the Runner calls it when the task ends.
+ */
 export type ExecutionEnvFactory = (ctx: ExecutionEnvFactoryContext) => ExecutionEnv | Promise<ExecutionEnv>;
+/** True when `env` exposes a lifecycle {@link RemoteExecutionEnv.destroy} the Runner should call on task end. */
 export declare function hasDestroy(env: ExecutionEnv): env is ExecutionEnv & Pick<RemoteExecutionEnv, "destroy">;
+/** Structural check that `env` implements the remote seam (lifecycle + streaming surface + declared capabilities). */
 export declare function isRemoteExecutionEnv(env: ExecutionEnv): env is RemoteExecutionEnv;
+/**
+ * The RESTORE half of the suspend contract — the methods the RESUME leg calls after a `suspendVM`
+ * ({@link RemoteExecutionEnv.resumeVM} + {@link RemoteExecutionEnv.postResumeInit}). Returns the names an
+ * adapter is MISSING (empty = complete).
+ *
+ * Split out from {@link isRemoteExecutionEnv} deliberately: that predicate answers "can this env be driven
+ * as a remote env at all" (a park-only SSH/ADB host legitimately never restores a VM and is checked with
+ * it), while THIS one answers "if I snapshot this env now, will the resume leg find a way back". Naming the
+ * missing methods lets the suspend-time guard say WHICH part of the adapter is absent instead of failing on
+ * the resume leg — a different process, hours later — with a bare `env.resumeVM is not a function`.
+ */
 export declare function missingRestoreSurface(env: ExecutionEnv): readonly ("resumeVM" | "postResumeInit")[];
+/**
+ * Can this env be durably suspended/snapshotted (design/61 §9 A)? Use this — NOT the structural
+ * {@link isRemoteExecutionEnv} — before calling `suspendVM` (a non-suspendable SSH/ADB env declares
+ * `capabilities.suspendable: false` but still has the method, which returns `"unsupported"`). Non-remote
+ * (in-process) envs are not suspendable.
+ *
+ * A composite type guard (structural AND capability) so a `suspendVM` call site narrowed by THIS predicate
+ * gets the {@link RemoteExecutionEnv} type without a cast — `true` always implies the structural check too.
+ *
+ * RB-439-b: it also requires the RESTORE surface ({@link missingRestoreSurface}). A suspend is only durable
+ * if something can undo it; an adapter that offers `suspendVM` but no `resumeVM` used to pass this guard,
+ * take a real snapshot, commit a real checkpoint — and then blow up on the resume leg with an untyped
+ * TypeError. "Suspendable" now means the whole round trip, so a half-adapter is rejected at the suspend site
+ * where the deployment can still be told which method it owes.
+ *
+ * ⚠️ A capability-DECLARING but restore-incomplete adapter must NOT be re-routed to the durable-park-only
+ * degrade by this predicate returning false — park-only rests on the workspace being externally durable
+ * (see {@link RemoteExecutionEnv.capabilities}.suspendable), which a snapshot backend does not have. Call
+ * sites split the two cases on the DECLARED `capabilities.suspendable` flag, not on this predicate alone.
+ */
 export declare function isSuspendable(env: ExecutionEnv): env is RemoteExecutionEnv;
+/**
+ * Is this env an isolated sandbox (design/61 §9 A, design/53)? `false` for a real SSH host / ADB device AND
+ * for any in-process env (the host process is not isolated). The orchestrator tightens autonomy + the
+ * design/37 policy gate when this is `false` (zero-trust on an un-isolated target). The safe default is
+ * `false` — isolation must be explicitly declared, never assumed.
+ */
 export declare function isIsolated(env: ExecutionEnv): boolean;

package/dist/core/retention-policy.d.ts

@@ -0,0 +1,40 @@
+/**
+ * knob-hygiene #98 — one validator for every RETENTION policy a bundled store accepts.
+ *
+ * These knobs share a property nothing else in the engine does: they are the only numbers whose job is
+ * to DELETE, so an unevaluable one is not merely ignored, it decides. The shapes actually reachable:
+ *
+ *   - `keep` is consumed as `rows.slice(Math.max(0, keep))` / `i >= keep`. `Math.max(0, NaN)` is `NaN`
+ *     and `slice(NaN)` means `slice(0)` — so a policy whose `keep` arrived as NaN (the ordinary
+ *     `Number(cfg.keep)` on a missing or misspelled field) deleted EVERY terminal row instead of
+ *     keeping N of them. A negative `keep` reaches the same place by a different route.
+ *   - `maxAgeMs` on the roster feeds `now - createdAt <= maxAgeMs`, which is false for NaN — so every
+ *     row reads as expired, the next write persists the survivors, and the whole roster is gone. A
+ *     roster row is a durable ADDRESS; losing one turns a live agent unreachable.
+ *   - the remaining `*MaxAgeMs` arms fail the other way (NaN comparisons are false ⇒ nothing is
+ *     reaped), which is safe but equally silent: retention that quietly stopped running is how a disk
+ *     fills up. They are validated for the same reason — an operator deserves the same answer either way.
+ *
+ * Fail-loud rather than fall back to a default: a retention policy is the deployment saying what it
+ * wants kept, and quietly substituting a different policy is exactly the class of silence this sweep
+ * exists to remove. Every store passes its options through here BEFORE touching a row, so no
+ * implementation can drift from another (the RB-74 / RB-87 / RB-111 history in the store family is
+ * three consecutive "fixed one of the two implementations" misses).
+ */
+export interface RetentionPolicyKnobs {
+    /** Age bound in ms. */
+    maxAgeMs?: number;
+    /** Row-count bound, whole rows. */
+    keep?: number;
+    /** Age bound in ms for the stale-running flip arm. */
+    staleRunningMaxAgeMs?: number;
+    /** Row-count bound, whole rows (roster's write-time cap). */
+    maxEntries?: number;
+}
+/**
+ * Refuse a malformed retention policy at the door. `undefined` on any field keeps its documented
+ * meaning — that arm is simply not applied — so a deployment that sets nothing is untouched.
+ *
+ * @param label the caller's own name, so the error names the seam the operator configured.
+ */
+export declare function assertRetentionPolicy(label: string, opts: RetentionPolicyKnobs | undefined): void;

package/dist/core/retention-policy.js

@@ -0,0 +1,21 @@
+function invalidPolicy(label, knob, value, requirement) {
+    const e = new Error(`${label}: ${knob} must be ${requirement} (got ${String(value)}) — a retention bound that cannot be evaluated silently decides what to delete instead of bounding it`);
+    e.code = "config.retention_policy_invalid";
+    throw e;
+}
+export function assertRetentionPolicy(label, opts) {
+    if (opts === undefined)
+        return;
+    for (const knob of ["maxAgeMs", "staleRunningMaxAgeMs"]) {
+        const v = opts[knob];
+        if (v !== undefined && (!Number.isFinite(v) || v < 0)) {
+            invalidPolicy(label, knob, v, "a finite, non-negative number of milliseconds");
+        }
+    }
+    for (const knob of ["keep", "maxEntries"]) {
+        const v = opts[knob];
+        if (v !== undefined && (!Number.isInteger(v) || v < 0)) {
+            invalidPolicy(label, knob, v, "a whole number of rows, 0 or more");
+        }
+    }
+}