@sema-agent/core 5.20.0 → 5.21.0

package/dist/core/compliance.d.ts

@@ -1,11 +1,41 @@
+/** Closed compliance profile set (CC 2.1.221 policy-limits profiles). */
 export type ComplianceProfile = "hipaa" | "zdr";
+/** Closed capability set the ENGINE can veto end-to-end (see the module header for the entry-point
+ *  map — a capability is admitted here only with its full interception story). */
 export type ComplianceCapability = "mcp_servers" | "workflows" | "web_fetch" | "org_memory_mount";
+/** Every member of {@link ComplianceCapability} — the fail-closed "deny everything managed" set used
+ *  when the posture resolver itself fails. `satisfies` keeps it in lockstep with the union. */
 export declare const COMPLIANCE_CAPABILITIES: readonly ["mcp_servers", "workflows", "web_fetch", "org_memory_mount"];
+/**
+ * A principal's resolved compliance posture, supplied by the trusted deployment resolver. The
+ * effective deny set is `BUILTIN_COMPLIANCE_DENIES[profile] ∪ additionalDenies` — supply can only
+ * TIGHTEN a profile's builtin floor, never carve a builtin deny back out.
+ */
 export interface CompliancePosture {
     profile: ComplianceProfile;
+    /** Extra denies on top of the profile's builtin floor (closed set; unknown values are refused). */
     additionalDenies?: readonly ComplianceCapability[];
 }
+/**
+ * Builtin per-profile deny floors, mapped from the CC 2.1.221 policy-limits pair table onto the
+ * capabilities this engine manages: hipaa denies `allow_web_fetch` ⇒ `web_fetch`. (CC's
+ * `allow_memory_sync` row maps onto the org-memory plane and joins this table together with the
+ * memory-admission seam; CC has no MCP/workflow rows — those stay reachable via `additionalDenies`.)
+ */
 export declare const BUILTIN_COMPLIANCE_DENIES: Record<ComplianceProfile, readonly ComplianceCapability[]>;
+/**
+ * Resolve a posture into its effective deny set. Fail-loud on any value outside the closed sets
+ * (`config.compliance_posture`): a posture that does not parse must be treated by the caller as a
+ * resolver FAULT (deny every managed capability), never as a partially-applied profile.
+ */
 export declare function resolveComplianceDenies(posture: CompliancePosture): ReadonlySet<ComplianceCapability>;
+/** The core web-fetch tool face's canonical mounted name (`createWebFetchTool` in tools/web.ts). */
 export declare const WEB_FETCH_TOOL_NAME = "WebFetch";
+/**
+ * The CALL-TIME half of the `web_fetch` double point (CC form — mount check + call guard): given the
+ * run's frozen deny set and a tool-call name, return the refusal text when the call must be blocked,
+ * else `undefined`. Kept as a pure exported decision so the gate wiring and the tests hold ONE
+ * predicate; today every roster lane that can mint a `WebFetch`-named tool is already refused at
+ * prepare, so this is the standing second lock for any future dynamic roster lane.
+ */
 export declare function complianceCallDenial(denies: ReadonlySet<ComplianceCapability>, toolName: string): string | undefined;

package/dist/core/consolidate-scope.d.ts

@@ -1,18 +1,93 @@
 import type { MemoryStore } from "./memory.js";
 import { type ConsolidationLLM, type ConsolidationStats } from "./runner/memory-consolidation.js";
+/**
+ * design/84 Seam B (M6+M10) — **cursor-incremental scope consolidation**. A thin function over the pure
+ * {@link runMemoryConsolidation}: it reads the scope's persisted cursor, feeds ONLY the notes appended
+ * AFTER it (the incremental batch) into one reconcile pass, then — IFF the whole pass succeeds — advances
+ * the cursor to the high-water mark it observed. This is the externally-triggerable periodic path (a
+ * deployment's timer / N-session gate fires it); the TRIGGER and any cross-process LOCK live OUTSIDE this
+ * function (the deployment shell's exec/persist axes — see {@link ConsolidateScopeOptions.acquire}).
+ *
+ * **Cursor marker semantics (no-miss / no-dup):** the cursor is an OPAQUE ordering marker the STORE defines
+ * (this core never parses it). In the three reference stores it is a note **id** — `uuidv7`, which is
+ * lexicographically time-sortable, so "after the cursor" is a string `>` comparison and the high-water mark
+ * is the lexicographic MAX. Each pass:
+ *  - reads `cursor = getConsolidationCursor(scope)` (undefined ⇒ whole scope pending),
+ *  - lists the scope's note headers (stable store ordering) and keeps those with `id > cursor` AND not
+ *    already `consolidationGenerated` (a prior pass's own output — excluded so it is never re-merged),
+ *  - reconciles that incremental batch via `runMemoryConsolidation` (which itself re-excludes
+ *    `consolidationGenerated` + this-batch ids from each note's candidate set),
+ *  - advances the cursor to the high-water mark of the fed batch ∪ `stats.addedIds`, but capped STRICTLY
+ *    BELOW the smallest note this pass FAILED to process (`stats.failedIds`) — a contiguous successful-prefix
+ *    marker, not the plain max (the MAJOR1 BLOCKER: a single max marker cannot keep a sub-max failed note
+ *    pending; see {@link cappedHighWater}).
+ * No-dup: a note with `id <= cursor` is never re-fed. No-miss: a note appended after the advance, or one at/
+ * above a failure floor this pass, keeps `id > cursor` (uuidv7 monotonic) and is picked up by a later pass. A
+ * pass's own ADDs carry `consolidationGenerated:true` AND (when below the failure floor) are folded into the
+ * high-water mark, so they are excluded twice over.
+ *
+ * **Whole-pass advance (decision 3):** the cursor advances (up to the success boundary) ONLY when the pass
+ * returns (no throw). A pass that THROWS (LLM hard failure) does NOT advance at all — the batch is fully
+ * retried next time. A pass that returns with per-note failures advances only past the contiguous successful
+ * prefix below the smallest failure (fail-open: at worst a near-duplicate survives an extra pass, never data
+ * loss; consistent with the memory-store contract).
+ *
+ * **No-op safety (the BLOCKER §2 closes):** when the store lacks the cursor pair
+ * ({@link supportsPeriodicConsolidation} false) this is a NO-OP that calls `onWarn` — it NEVER degrades into a
+ * full re-consolidation of the whole scope (which would re-merge already-consolidated notes forever). It is
+ * also a no-op when the store can't consolidate at all ({@link supportsConsolidation} false) or the manifest
+ * read pair ({@link MemoryStore.listStructuredNotes} / {@link MemoryStore.getByIds}) is incomplete.
+ */
 export interface ConsolidateScopeDeps {
     store: MemoryStore;
     llm: ConsolidationLLM;
+    /** Routes diagnostics (skipped decisions, no-op-because-unsupported, lock-busy) — same sink as the Runner's
+     *  `onError(phase:"memory")`. Never throws back into this function. */
     onWarn?: (err: unknown) => void;
+    /**
+     * design/84 Seam B (TOC profile) — OPTIONAL cross-process consolidation lock. When provided,
+     * {@link consolidateScope} acquires it for `scope` before the pass and releases it after; a `release` of
+     * `undefined` (lock busy) makes the pass a NO-OP (another process is already consolidating this scope).
+     * The implementation (writeThenLink + stale-PID prune) lives in the deployment shell (`stores/file`), NOT
+     * core — core only DEFINES the injection point (the constitutional persist/exec-axis split).
+     */
     acquire?: (scope: string) => Promise<(() => void) | undefined> | (() => void) | undefined;
 }
+/** Tuning for one {@link consolidateScope} pass (mirrors the inline consolidation settings; all optional). */
 export interface ConsolidateScopeOptions {
     band?: {
         lo: number;
         hi: number;
     };
     searchLimit?: number;
+    /** Cap on notes fed into ONE pass (token bound). The cursor advances only past the contiguous SUCCESSFUL
+     *  prefix of the FED batch (the first `maxNotes` pending) — never past the un-fed tail beyond the cap, and
+     *  never past a note this pass FAILED to process — so a backlog larger than `maxNotes`, and any failed note,
+     *  keep `id > cursor` and drain over successive passes without ever re-feeding the notes already handled. */
     maxNotes?: number;
 }
+/**
+ * Run ONE cursor-incremental consolidation pass for `scope` (design/84 Seam B). Returns the pass stats
+ * (or `undefined` when it was a no-op: unsupported store, empty incremental batch, or lock busy). Never
+ * throws for a no-op reason; a hard LLM failure inside `runMemoryConsolidation` propagates (the caller's
+ * fire-and-forget envelope catches it) and the cursor is left UN-advanced (the batch retries next pass).
+ */
 export declare function consolidateScope(scope: string, deps: ConsolidateScopeDeps, opts?: ConsolidateScopeOptions): Promise<ConsolidationStats | undefined>;
+/**
+ * design/84 Seam B (切片 4) — advance ONLY the cursor after an INLINE (task-end) consolidation pass has
+ * already run, so a later periodic {@link consolidateScope} starts from the inline-processed high-water mark
+ * (it does NOT re-consolidate the notes the inline pass just handled). The inline path consolidates the
+ * notes the model saved THIS task (the newest, highest-id notes); advancing the cursor over the PROCESSED
+ * ids ∪ addedIds makes inline and periodic share ONE cursor.
+ *
+ * **MAJOR1 BLOCKER:** the advance caps STRICTLY BELOW the smallest FAILED note (`failedIds`). A single
+ * max-marker cursor cannot keep a sub-max failed note pending, so a low-id note whose handling failed must
+ * stop the cursor below it even when a higher-id sibling succeeded — otherwise the failed note (id <= the
+ * plain max) would lose `id > cursor` and be exiled from consolidation forever. Pass the pass's
+ * `stats.consolidatedIds` (processed), `stats.addedIds`, and `stats.failedIds`.
+ *
+ * No-op when the store lacks the cursor pair (back-compat: an old store keeps the pure-inline behavior).
+ * Never throws — a cursor-advance failure routes to `onWarn` (the inline notes are already durable; the
+ * worst case is the next periodic pass re-sees them, which `runMemoryConsolidation` handles idempotently).
+ */
 export declare function advanceCursorAfterInline(store: MemoryStore, scope: string, seenNoteIds: ReadonlyArray<string | undefined>, addedIds: ReadonlyArray<string>, failedIds?: ReadonlyArray<string>, onWarn?: (err: unknown) => void): Promise<void>;

package/dist/core/context-edit.d.ts

@@ -1,20 +1,119 @@
 import type { AgentMessage } from "../internal/harness.js";
 import type { Model } from "../internal/llm.js";
+/**
+ * Small-window FLOOR fraction of the clearStale/compaction frontier (see {@link contextEditFrontier},
+ * which is the single source for both the clearStale budget and the compaction-threshold clamp).
+ * CC's fixed-deduction trigger geometry only exists for ≥100k autocompact windows (its configured-
+ * window floor is 100000), and `W − 33000` goes degenerate below ~47k — small windows keep the
+ * historical fractional trigger instead.
+ */
 export declare const EDIT_FRACTION = 0.7;
+/**
+ * CC-parity trigger geometry (verified against CC 2.1.207): the reactive autocompact trigger sits a
+ * FIXED DISTANCE below the window, not at a fixed fraction —
+ *   effectiveWindow = autocompactWindow − min(maxOutputTokens, 20000)   (CC `Nye`, cap `uMd`)
+ *   trigger         = effectiveWindow − 13000                           (CC `dSo`, buffer `rMd`)
+ * i.e. trigger = W − 33000 for every model whose max output is ≥ 20k: a 200k window triggers at
+ * 167000 (83.5% of nominal), a 1M window at 967000. (CC additionally ships a sonnet-5-only 1M
+ * autocompact-window special of 967000 via dynamic config, making ITS 1M trigger 934000; that is a
+ * per-model config delivery, not geometry — an embedder reproduces it EXACTLY via
+ * `model.autoCompactTokens = 967000`, which lowers only this trigger-side window while the guard
+ * and physical request budgeting stay on the 1M window — CC's dual-window shape.) We take the
+ * 20000 cap branch unconditionally (flat 33000), i.e. the `min(maxOutputTokens, 20000)` branch is
+ * deliberately NOT ported: the deduction is exact parity only for models with max output ≥ 20k. A
+ * model with a smaller max output would deduct less in CC (trigger LATER); we deduct the full
+ * 20000 and so trigger EARLIER there — the conservative direction (early compaction is bounded
+ * cost; a late trigger risks the window). It also keeps the frontier a pure function of the
+ * window — single source for the death-band clamp below.
+ */
 export declare const CONTEXT_OUTPUT_RESERVE_TOKENS = 20000;
 export declare const COMPACTION_TRIGGER_BUFFER_TOKENS = 13000;
+/**
+ * The clearStale/compaction frontier for a window — SINGLE SOURCE for two coupled points
+ * (design/64 §26.4 fix 2): the budget at which the request-layer stale-result clearing engages
+ * ({@link editBudget}) AND the ceiling the compaction threshold is clamped to
+ * (`sanitizeCompactionSettings`). Deriving both from one function keeps `compaction ≡ clearStale`
+ * an invariant: a threshold above the clearing frontier would put every request between the two
+ * points on a moving clearing frontier that breaks the prefix cache (~frontier re-prefilled PER
+ * REQUEST — the "death band"). `max()` keeps the frontier monotonic in the window; exact
+ * crossover (integer domain, pinned by test): the fractional floor strictly wins through
+ * W = 109996, the two legs are EQUAL for W = 109997…110000 (floor(0.7W) meets W − 33000 there),
+ * and the fixed deduction strictly wins from W = 110001 up.
+ */
 export declare function contextEditFrontier(window: number): number;
+/**
+ * checklist #54 (CC microCompact.ts:41-50 `COMPACTABLE_TOOLS` parity): the INCLUSION whitelist of
+ * tools whose results may be content-cleared by the stale-result pass. CC's set is exactly
+ * { Read, Bash, PowerShell (SHELL_TOOL_NAMES), Grep, Glob, WebSearch, WebFetch, Edit, Write } —
+ * cheap-to-regenerate I/O. Everything else is PRESERVED: expensive/decision-bearing results
+ * (Agent subagent reports, Task* registry state, TodoWrite acks, Monitor, MCP tools, custom
+ * ToolSpecs) survive to the harder defenses (compaction summarizes them instead of blanking them).
+ * PowerShell is kept for CC fidelity even though sema does not mount it. Overridable per call via
+ * {@link ContextEditOptions.compactableTools} for custom-tool-heavy embedders.
+ */
 export declare const COMPACTABLE_TOOLS: ReadonlySet<string>;
 export interface ContextEditOptions {
+    /** Start clearing once estimated context tokens exceed this. */
     budgetTokens: number;
+    /** Always keep the content of this many most-recent tool results. Default 3. */
     keepRecentToolResults?: number;
+    /**
+     * roadmap #6② (CC contentReplacementState parity): when set, a result's FULL TEXT is offloaded to
+     * the store before its content is cleared, and the marker carries the ReadToolResult ref — a
+     * cleared result becomes pageable instead of gone-from-view. `persist` must be idempotent per ref
+     * (the store's write-once put) because clearing re-runs on every request build. Absent ⇒ the bare
+     * marker (pre-#6 behavior; the durable session still holds the full result either way).
+     */
     offload?: {
+        /** Write-once persist; the returned ref goes into the marker. Sync (in-memory) or async stores both fit. */
         persist: (toolCallId: string, fullText: string) => string;
     };
+    /**
+     * design/123 D3 (codex-B1 = fable-M5) — ANCHORED accounting start: `estimateContextTokens(messages,
+     * charsPerToken).tokens` for the SAME message array. When set, the trigger gate AND the internal
+     * bookkeeping start from this usage-anchored value instead of the pure structural sum (which
+     * underestimates code by ~25% and CJK by 60–75% — the defense would self-certify and pass
+     * over-window requests). Bookkeeping semantics (pinned): clearing a message AFTER the usage anchor
+     * decrements by its structural delta; clearing a message AT/BEFORE the anchor decrements ZERO —
+     * the anchor usage was billed with that content included and does not shrink on a request-view
+     * edit (the clear only pays off on the NEXT request, after a fresh anchor lands), so the defense
+     * keeps clearing deeper until the anchored total is met or nothing clearable remains.
+     * Absent ⇒ legacy structural gate + accounting (byte-identical behavior).
+     */
     anchoredTotalTokens?: number;
+    /** design/123 D2 — structural coefficient (`Model.charsPerToken`); default 4. */
     charsPerToken?: number;
+    /**
+     * checklist #54 — which tools' results are clearable. Defaults to {@link COMPACTABLE_TOOLS}
+     * (CC microCompact.ts:41-50). A result whose `toolName` is not in the set is NEVER cleared by
+     * this pass, no matter how far over budget the request is — expensive subagent reports and
+     * registry state are compaction's job, not a blanking marker's.
+     */
     compactableTools?: ReadonlySet<string>;
 }
+/**
+ * Context-editing (the lightest, safest compaction; Anthropic reports ~29% improvement alone):
+ * when context exceeds the budget, replace the CONTENT of older tool-result messages with a short
+ * marker, keeping the turn structure (tool_call/tool_result pairing) intact. The most recent
+ * `keepRecentToolResults` results are preserved.
+ *
+ * Request-only and non-destructive: returns a new array; the durable session keeps the full results.
+ * Older results are cleared first, stopping as soon as the budget is met.
+ */
+/**
+ * audit A-1 (view-level heal for HISTORICAL pollution): drop synthetic EMPTY failure assistants —
+ * stopReason aborted/error with no tool calls and no non-whitespace text/thinking. Sessions persisted
+ * before 1.92.0 may carry one parked between an interrupted tool batch and its reconcile tool_results
+ * (`A(tu×3), TR1, TR2, A(aborted,""), TR3`) — an API-invalid sequence on strict providers, and
+ * append-only sessions cannot be rewritten. Dropping the junk from the REQUEST VIEW restores a legal
+ * transcript (TR3 rejoins its batch). Deterministic ⇒ byte-stable per request ⇒ prefix-cache safe.
+ * New sessions never contain these (the loop exits cleanly on abort; the harness skips persisting them).
+ */
 export declare function dropEmptyFailureAssistants(messages: AgentMessage[]): AgentMessage[];
 export declare function clearStaleToolResults(messages: AgentMessage[], opts: ContextEditOptions): AgentMessage[];
+/** The token budget at which context-editing begins for a model (below the harder guard trim).
+ *  = {@link contextEditFrontier} of the model's AUTOCOMPACT window (CC-parity fixed deduction with
+ *  a 0.7 small-window floor) — the same point the compaction threshold is clamped to. Dual-window
+ *  semantics: `autoCompactTokens` (when declared) feeds this trigger-side geometry only; the guard
+ *  trim (`guardBudget`) stays on the physical window. */
 export declare function editBudget(model: Model): number;

package/dist/core/context-guard.d.ts

@@ -1,8 +1,49 @@
 import type { AgentMessage } from "../internal/harness.js";
 import type { Model } from "../internal/llm.js";
+/**
+ * Last-resort, in-task context trim. Proper compaction (LLM summary) runs *between* tasks;
+ * this prevents a single task whose internal tool-loop balloons from overflowing the window.
+ *
+ * Keeps all summary messages (compaction/branch) and the most recent messages that fit the
+ * budget, dropping older regular messages at a safe boundary (never starting on an orphan
+ * toolResult). Returns the original array when already within budget.
+ *
+ * design/123 D3 (codex-B1 = fable-M5) — anchored accounting: when `anchoredTotalTokens`
+ * (= `estimateContextTokens(messages, charsPerToken).tokens` for the SAME array) is provided, the
+ * trigger gate and the internal bookkeeping start from the usage-anchored value instead of the
+ * structural sum (which underestimates code/CJK and lets over-window requests through). Dropping a
+ * message AFTER the usage anchor reduces the accounted total by its structural estimate; dropping a
+ * message AT/BEFORE the anchor reduces it by ZERO (the anchor usage was billed with that content —
+ * a request-view drop only pays off on the NEXT request), so the trim keeps cutting deeper until
+ * the anchored total meets the budget or only the minimal tail is left. Absent ⇒ legacy structural
+ * behavior, byte-identical. `charsPerToken` (design/123 D2): structural coefficient, default 4.
+ */
 export declare function trimToBudget(messages: AgentMessage[], budgetTokens: number, anchoredTotalTokens?: number, charsPerToken?: number): AgentMessage[];
+/**
+ * In-band notice for a request view whose oldest messages were dropped by the guard trim. Every
+ * other history-reducing pass in the pipeline announces itself to the model (compaction injects a
+ * summary); a silent trim leaves the model unaware that earlier instructions or constraints are no
+ * longer visible. MUST remain a single static string: the notice is re-inserted on every trimmed
+ * request, and a byte-identical prefix keeps provider prefix caching effective.
+ */
 export declare const CONTEXT_TRIM_NOTICE: string;
+/**
+ * Insert the static trim notice ahead of the kept tail of a trimmed request view (after any
+ * always-kept summary messages, which lead the rebuilt array). Call ONLY when the trim actually
+ * dropped messages. Request-view only — the synthetic message is never persisted to the session
+ * (fixed timestamp keeps it fully deterministic).
+ */
 export declare function insertTrimNotice(trimmed: AgentMessage[]): AgentMessage[];
+/**
+ * design/123 D3 belt (invariant-level, live-caught 16k 400s): the FINAL request view must never
+ * contain a toolResult whose tool-call assistant is absent — strict gateways hard-400 on it
+ * ("Messages with role 'tool' must be a response to a preceding message with 'tool_calls'"). Every
+ * individual producer is turn-aligned (findCutPoint never cuts on a toolResult; trimToBudget
+ * turn-aligns its floor), but NO pipeline combination may ship an orphan, so the prepare-task
+ * context hook sweeps its output through this last. Deterministic ⇒ byte-stable per request ⇒
+ * prefix-cache safe. Returns the SAME array when clean (zero-cost fast path); `dropped` carries a
+ * diagnostic per removed orphan (toolCallId + neighbor roles) for onError attribution.
+ */
 export declare function dropOrphanToolResults(messages: AgentMessage[]): {
     messages: AgentMessage[];
     dropped: Array<{
@@ -12,4 +53,9 @@ export declare function dropOrphanToolResults(messages: AgentMessage[]): {
         nextRole: string;
     }>;
 };
+/** Budget the in-task guard targets for a model — CC-aligned headroom numbers with a 0.85
+ *  small-window floor, sema-owned drop-oldest action (see {@link GUARD_HEADROOM_TOKENS}); always
+ *  above the compaction/clearStale frontier. Dual-window semantics: deliberately the PHYSICAL
+ *  window (`contextTokens ?? contextWindow`), NOT `autoCompactTokens` — the guard protects the
+ *  real request limit; a lowered autocompact window only moves the trigger-side geometry. */
 export declare function guardBudget(model: Model): number;

package/dist/core/exec-gate.d.ts

@@ -1,29 +1,73 @@
+/**
+ * L2 mechanical verification gate (design/54) — the "verifiable outputs" exit oracle.
+ *
+ * Runs a TRUSTED, spec-derived suite of commands (build / type-check / test) in an {@link ExecutionEnv}
+ * and gates on the **real exit codes**: pass = every step exited 0. This is the mechanical half of
+ * verifiable outputs (design/54 §2); the de-correlated LLM-judge half is {@link runWithVerification}
+ * (L3). It catches what tests cover; service[33] measured L2 alone misses 50-100% of semantic/edge
+ * defects, which is why L3 runs on what passes L2.
+ *
+ * **It is a thin exit oracle, not a framework** — no model, no Runner, no agents dependency. It just runs
+ * commands and reports their exit truthfully, choosing the streaming `execStream` on a remote env (long
+ * builds, read-timeout, output cap) or the buffered `exec` on a base env. Which commands to run, and how
+ * to compose L2 with L3 / per-module sub-gates, is the caller's (profile's) job (design/54 §4).
+ *
+ * 🔴 SECURITY (design/53 §2.B, threat BUG8 — "L2 can be gamed"): `steps` MUST be a trusted, spec-derived
+ * suite — NOT test files an **untrusted worker** authored (a worker can write `assert(true)` / happy-path
+ * tests that pass while the code is broken, pushing all pressure onto an uncalibrated L3). This helper does
+ * not and cannot know which commands are trustworthy; the caller owns that. The gate's guarantee is narrow:
+ * "did these exact commands all exit 0 in this env" — nothing about whether the commands are meaningful,
+ * whether the env is isolated (design/53 §E = deployment), or the semantics of the change (that is L3).
+ */
 import type { ExecutionEnv } from "../internal/harness-types.js";
+/** One command in an L2 suite. */
 export interface ExecStep {
+    /** Shell command to run (e.g. `"npm test"`, `"tsc --noEmit"`, `"git diff"`). */
     command: string;
+    /** Human label for reporting. Default: the command string. */
     label?: string;
+    /** Working directory; relative paths resolve against the env root. Default: the env's cwd. */
     cwd?: string;
+    /** Extra environment variables for this command. */
     env?: Record<string, string>;
+    /** Per-step timeout (seconds). Default: none. */
     timeoutSec?: number;
 }
+/** The outcome of a single {@link ExecStep}. */
 export interface ExecStepResult {
     label: string;
     command: string;
+    /** The real exit code, or `null` when the command never produced one (transport error / timeout / abort). */
     exitCode: number | null;
     stdout: string;
     stderr: string;
+    /** `exitCode === 0`. A `null` exit is **never** `ok` (we can't confirm success, so we don't pass it). */
     ok: boolean;
+    /** Set when the step failed to RUN (an `ExecutionError`/`RemoteExecutionError` code) — distinct from a non-zero exit. */
     errorCode?: string;
+    /** True when captured output was truncated at {@link ExecGateOptions.maxOutputBytes}. */
     truncated?: boolean;
 }
+/** The L2 verdict over a whole suite. */
 export interface ExecGateResult {
+    /** True iff there was ≥1 step AND every step ran and exited 0. An EMPTY suite is `false` (nothing was verified — not a vacuous pass). */
     passed: boolean;
+    /** Per-step detail, in order. With `stopOnFailure` (default), steps after the first failure are absent. */
     steps: ExecStepResult[];
 }
+/** Options for {@link runExecGate}. */
 export interface ExecGateOptions {
+    /** Stop at the first failed/non-zero step (default `true` — a cheap CI-style short-circuit). */
     stopOnFailure?: boolean;
+    /** Cap captured output **per step** in UTF-8 bytes (default 64 KiB) so a `find /` can't flood memory. */
     maxOutputBytes?: number;
+    /** Idle read timeout (ms) for the streaming (remote) path; ignored on the buffered path. */
     readTimeoutMs?: number;
+    /** Abort the whole gate (also forwarded to each command). */
     signal?: AbortSignal;
 }
+/**
+ * Run an L2 mechanical gate: execute `steps` in `env` and gate on real exit codes. See the file header for
+ * the security contract — `steps` must be a trusted, spec-derived suite, not worker-authored tests.
+ */
 export declare function runExecGate(env: ExecutionEnv, steps: ExecStep[], options?: ExecGateOptions): Promise<ExecGateResult>;

package/dist/core/exec-output-tail.d.ts

@@ -1,5 +1,21 @@
+/**
+ * Bounded rolling-TAIL accumulator for streaming exec output (sema D2) — FIRST-PARTY, vendor-independent.
+ *
+ * A model-driven `yes` / `cat big.bin` over a 120s/600s shell can emit gigabytes; accumulating it unbounded OOMs
+ * a durable worker. We keep only the LAST `maxBytes` — the tail (errors + the exit code are at the end, which is
+ * what the model needs) — dropping the head as it overflows, plus a count of dropped bytes for a visible marker.
+ *
+ * This lives in `src/core/` — NOT `src/vendor/` — on purpose: it is OUR robustness invariant, shared by the
+ * (currently-vendored) NodeExecutionEnv AND a downstream exec adapter (service host/ssh/adb/docker/k8s, [267]).
+ * One implementation + ONE model-facing marker text = zero drift, and the public export points at a STABLE path
+ * that survives the planned de-vendoring (when NodeExecutionEnv is naturalized out of `src/vendor/`, nothing rebinds).
+ */
 import { StringDecoder } from "node:string_decoder";
 export declare const MAX_EXEC_OUTPUT_BYTES: number;
+/**
+ * Push-based bounded tail: feed it raw output chunks (Buffers); it retains only the last `maxBytes`, dropping the
+ * head incrementally so memory is O(maxBytes) regardless of total output. Byte-precise (the OOM bound is bytes).
+ */
 export declare class RollingTailBuffer {
     private readonly maxBytes;
     private readonly chunks;
@@ -7,26 +23,71 @@ export declare class RollingTailBuffer {
     private headDropped;
     private sourceSkipped;
     constructor(maxBytes?: number);
+    /** Append a chunk; evict head bytes (whole or partial chunks) until within `maxBytes`. */
     push(chunk: Buffer): void;
+    /** Account bytes that were dropped BEFORE ever reaching the buffer (e.g. a spool reader skipping
+     *  un-retainable backlog at the source). They join `droppedBytes` so `markTruncated` discloses the
+     *  TRUE number of missing bytes — recording them here instead of pushing keeps the drop O(1). */
     recordSkippedBytes(n: number): void;
+    /** The retained tail decoded as UTF-8, plus how many bytes are missing in total (head evictions +
+     *  source skips — the foreground `markTruncated` disclosure keeps the combined figure). */
     result(): {
         text: string;
         droppedBytes: number;
     };
+    /** RB-234 ([1937]): the retained window's RAW bytes — cursor slicing must happen in the byte domain
+     *  (re-encoding a lossily-decoded string inflates every invalid byte to a 3-byte U+FFFD and lands
+     *  byte cursors on the wrong offsets). */
     bytes(): Buffer;
+    /** RB-234 ([1937]): head-eviction count ALONE — the retention window is [headDroppedBytes, pushed-total)
+     *  in the accepted-byte domain; source skips must not shift this origin. */
     headDroppedBytes(): number;
+    /** RB-234 ([1937]): source-skip count alone (see {@link recordSkippedBytes}) — poll disclosure reports
+     *  the per-poll increment of this figure instead of silently absorbing it into the window origin. */
     sourceSkippedBytes(): number;
 }
+/** RB-234 ([1937]): per-stream cursor state for incremental (poll-style) consumption of a
+ *  {@link RollingTailBuffer}. All counters live in the ACCEPTED-byte domain (bytes actually pushed);
+ *  source skips are tracked separately for disclosure. Module-level export (not on the package
+ *  surface) so the slice arithmetic is unit-pinnable without an 8MB integration harness. */
 export interface StreamCursorState {
     tail: RollingTailBuffer;
+    /** Consumer position in the accepted-byte domain (bytes already delivered). */
     cursorBytes: number;
+    /** Bytes actually pushed into `tail` (excludes source skips — those never had content to deliver). */
     acceptedBytes: number;
+    /** `tail.sourceSkippedBytes()` as of the last slice — the delta is disclosed exactly once. */
     disclosedSkippedBytes: number;
+    /** Incremental UTF-8 decoder (CC 2.1.220 shape: StringDecoder holds a split multi-byte char across
+     *  reads instead of emitting replacement chars at every read boundary). */
     decoder: StringDecoder;
 }
+/** Fresh cursor state over a new tail. */
 export declare function newStreamCursorState(tail?: RollingTailBuffer): StreamCursorState;
+/**
+ * RB-234 ([1937]): slice the undelivered increment out of a rolling tail — in the BYTE domain, decoded
+ * incrementally. Replaces the former decode→re-encode→byte-offset-subarray shape, which mixed two
+ * domains: byte cursors landed inside a re-encoded string whose length differs from the raw stream as
+ * soon as any invalid-UTF-8 byte sits in the window (each inflates to a 3-byte U+FFFD), making every
+ * later poll re-deliver the same trailing garbage forever (a sleeping process "producing" output).
+ *
+ *  - Continuity: a multi-byte char split across two slices is held by the decoder and completed on the
+ *    next slice — zero replacement chars, zero duplication.
+ *  - Discontinuity (`droppedBeforeCursor > 0`): the decoder is rebuilt, so bytes on either side of a
+ *    hole are never joined into a fake character.
+ *  - `terminal`: flush the decoder (a trailing split char becomes one honest U+FFFD) — without this
+ *    the last 1–3 bytes of a finished stream would never surface.
+ *
+ * `droppedBeforeCursor` = head-evicted bytes the cursor never got to + the NEW source-skip increment
+ * since the previous slice (formerly silent: skips shifted the window origin instead, re-delivering
+ * already-served bytes with `truncated` unset).
+ */
 export declare function sliceStreamIncrement(s: StreamCursorState, terminal: boolean): {
     inc: string;
     droppedBeforeCursor: number;
 };
+/**
+ * Prepend a model-visible marker when `droppedBytes > 0` (only the TAIL was kept). The SINGLE source of the
+ * marker wording so the engine and any downstream adapter show the model the SAME thing.
+ */
 export declare function markTruncated(text: string, droppedBytes: number): string;

package/dist/core/file-snapshot-store.d.ts

@@ -1,7 +1,14 @@
+/** rel path of `child` under `root` in "/" form (win root) / verbatim form (posix root); null when not under.
+ *  codex 1.237 F7: fold "\" only under a WIN-family root ({@link isWinFormPath}); a POSIX tree may legally
+ *  contain literal backslashes in FILE NAMES, and folding them corrupted both the manifest key and the
+ *  restore target. */
 declare function relUnder(root: string, child: string): string | null;
+/** Join root + a "/"-form relPath using the ROOT's native separator (keys stay family-consistent). */
 declare function joinUnder(root: string, rel: string): string;
 import type { ExecutionEnv } from "../internal/harness-types.js";
 export interface FileSnapshotError {
+    /** `too_large` = the tree exceeded a bound (fail-CLOSED, NOT a silent partial snapshot); `not_found` = no
+     *  snapshot for that key; `aborted` = the signal fired; the rest = an underlying fs op failed. */
     code: "too_large" | "enumerate_failed" | "read_failed" | "restore_failed" | "not_found" | "aborted";
     message: string;
 }
@@ -11,23 +18,106 @@ export type FileSnapshotResult = {
     ok: false;
     error: FileSnapshotError;
 };
+/**
+ * Capture/restore a working-tree file set keyed by `(scope, key)` — `scope` = sessionId, `key` =
+ * `SessionTreeEntry.id` (same anchor as E18 resume-at). All methods are best-effort and NEVER throw — failures
+ * are encoded in the returned {@link FileSnapshotResult} (mirrors the ExecutionEnv FileSystem contract).
+ *
+ * **v1 fidelity bounds (design/101 §defer):** files only — symlinks are NOT captured and are REMOVED by
+ * `restore` (they are a path-escape vector); empty directories are not tracked; `restore` re-enumerates under
+ * the SAME bounds, so a tree that grew past a bound since the snapshot cannot be rewound (fail-closed).
+ */
 export interface FileSnapshotStore {
+    /** Capture the tree under `root` for `(scope, key)`. CREATE-ONCE: a second call for an existing key is a
+     *  no-op `{ok:true}` (a session entry id is immutable, so its tree state is too). */
     snapshot(scope: string, key: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileSnapshotResult>;
+    /** Converge the tree under `root` back to the snapshot for `(scope, key)`: remove obstructions/strays
+     *  (symlinks + files created since), then write every captured file — so the tree MATCHES the snapshot. */
     restore(scope: string, key: string, env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<FileSnapshotResult>;
+    /** Whether a snapshot exists for `(scope, key)`. */
     has(scope: string, key: string): Promise<boolean>;
+    /** GC: drop every snapshot in `scope` whose key is NOT in `keepKeys` (e.g. unreachable branches). Returns the
+     *  number of snapshots removed. */
     reap(scope: string, keepKeys: string[]): Promise<number>;
+    /** Every snapshot key in `scope` (order unspecified). The enumeration counterpart of {@link reap} (which
+     *  already iterates the same set internally) — exposed for a cross-backend session EXPORT (service 2c
+     *  session-sync, [266]): list a session's snapshot keys to move its {entries + file snapshots} to another
+     *  backend. A durable backend implements it as a `SELECT key WHERE scope = ?`. */
     listKeys(scope: string): Promise<string[]>;
+    /**
+     * 2c session-sync ([271]): the manifest (`relPath → blobHash`) for `(scope, key)`, or `null` if absent — to
+     * EXPORT a snapshot's content to another backend. Pairs with {@link getBlob} for CONTENT-ADDRESSED (deduped)
+     * blob transfer: the caller fetches each distinct hash ONCE across all of a session's snapshots. Optional — a
+     * backend that supports cross-backend snapshot export implements it.
+     */
     exportManifest?(scope: string, key: string): Promise<Map<string, string> | null>;
+    /** 2c session-sync ([271]): the content-addressed bytes for `hash` (undefined if absent). */
     getBlob?(hash: string): Promise<Uint8Array | undefined>;
+    /**
+     * 2c session-sync ([273]): STORE a snapshot INTO this store from another store's {@link exportManifest} +
+     * {@link getBlob} output — the import-side mirror that closes the cross-backend transfer loop. For each DISTINCT
+     * blob hash in `manifest`, fetch its bytes via `srcGetBlob`, VERIFY content-address integrity
+     * (`sha256(bytes) === hash`), and store it (content-addressed dedup); THEN record `(scope, key) → manifest`.
+     *
+     * - CREATE-ONCE: a second import for an existing key is a no-op `{ok:true}` (an entry id is immutable).
+     * - FAIL-CLOSED: a missing OR hash-mismatched source blob → `read_failed` and NO manifest is committed (never a
+     *   partial snapshot that a later {@link restore} would silently truncate). The manifest's relPaths are NOT
+     *   re-validated here — `restore` remains the path-escape gate (it already neutralizes unsafe relPaths).
+     * - Pure store→store: does NOT touch an `ExecutionEnv` (unlike `applyManifest`, which converges ONE snapshot to a
+     *   working tree; import preserves ALL historical snapshots in the dst store so a later rewind-to-past finds them).
+     *
+     * Optional — a backend that supports cross-backend snapshot import implements it.
+     */
     importManifest?(scope: string, key: string, manifest: Map<string, string>, srcGetBlob: (hash: string) => Promise<Uint8Array | undefined>): Promise<FileSnapshotResult>;
+    /**
+     * 2c session-sync ([277]): STORE a single content-addressed blob — the symmetric WRITE side of {@link getBlob},
+     * for a two-phase PUSH (upload blobs, THEN import the manifest that references them). VERIFIES content-address
+     * integrity (`sha256(bytes) === hash`) so a corrupt/mismatched upload can never poison the store (a later
+     * getBlob/restore would otherwise return wrong content); a mismatch → `read_failed`, nothing stored. IMMUTABLE +
+     * content-addressed: a repeat putBlob for the same hash is a no-op (the bytes are identical by definition).
+     * Returns a {@link FileSnapshotResult} (NOT void) so the integrity failure is encodable under the never-throw
+     * contract. Optional — a backend that supports a two-phase push implements it.
+     *
+     * ⚠️ ORCHESTRATION CAVEAT: a pushed blob is NOT yet referenced by any manifest (the matching
+     * {@link importManifest} runs LATER), so — unlike `snapshot`/`importManifest`, which hold their blobs in an
+     * `inFlight` live-set across the whole store-then-commit — a `putBlob`'d blob is reap-ELIGIBLE in the window
+     * before its manifest is imported. The two-phase pusher MUST NOT `reap` the scope between PUT and import (a
+     * grace-window). This is fail-closed, not corrupting: blobs are content-addressed (re-push is always safe) and
+     * `importManifest` re-verifies+stores every blob before committing, so a reaped blob → `read_failed` with NO
+     * dangling-reference manifest, never wrong content.
+     */
     putBlob?(hash: string, bytes: Uint8Array): Promise<FileSnapshotResult>;
 }
+/** Bounds for the reference enumerator — a deliberate, fail-CLOSED cost policy (NOT the grep walk's silent caps). */
 export interface FileSnapshotBounds {
+    /** Hard cap on file count; exceeding it REFUSES the snapshot (`too_large`) rather than silently truncating. */
     maxFiles: number;
+    /** Hard cap on total bytes; exceeding it REFUSES the snapshot. */
     maxBytes: number;
+    /** Directory BASENAMES skipped anywhere in the tree (cost bound). Default `.git` + `node_modules`. */
     ignoreDirs: Set<string>;
 }
 export declare const DEFAULT_SNAPSHOT_BOUNDS: FileSnapshotBounds;
+/**
+ * Capture the working tree under `root` into a manifest `relPath → sha256`, handing each file's bytes to
+ * `putBlob` (the backend stores them content-addressed). **The env-operating + security-critical half a durable
+ * backend MUST reuse** (not re-implement — duplication risks re-introducing the symlink-escape / fail-closed
+ * bugs the dual-review fixed). Fail-CLOSED: an enumerate/read/bound failure returns an error and the caller must
+ * NOT persist a partial manifest. Never throws.
+ *
+ * [789] vanished-file tolerance: a file that DISAPPEARED between enumerate and read (`not_found`) is OMITTED
+ * from the manifest instead of failing the whole capture. This is semantically SAFE — the E19 snapshot runs
+ * concurrently with a live tree (the `done` frame is emitted BEFORE the snapshot, so shell-side per-turn
+ * markers, `.git/index.lock`, editor swap files etc. legitimately vanish mid-walk), and omitting a
+ * just-deleted file yields the CONSISTENT tree state of one instant later — NOT a partial snapshot (which
+ * would mean "captured bytes are missing for a file that exists"). No re-stat second check is needed:
+ * `not_found` is a stable backend-independent FileErrorCode (locally the SOLE mapping of ENOENT,
+ * node-execution-env.ts toFileError) — the read itself IS the authoritative existence probe at capture time,
+ * and a re-stat would only re-open the same race one window later. Every OTHER read error (permission_denied/
+ * EIO/unknown…) and any enumerate failure keeps the fail-closed whole-capture rejection: those mean "the file
+ * is still there but we could not capture it" — omitting it WOULD be a data-lossy partial snapshot.
+ * `skippedVanished` reports the count for observability/tests.
+ */
 export declare function captureManifest(env: ExecutionEnv, root: string, bounds: FileSnapshotBounds, signal: AbortSignal | undefined, putBlob: (hash: string, bytes: Uint8Array) => void | Promise<void>): Promise<{
     ok: true;
     value: Map<string, string>;
@@ -36,7 +126,19 @@ export declare function captureManifest(env: ExecutionEnv, root: string, bounds:
     ok: false;
     error: FileSnapshotError;
 }>;
+/**
+ * CONVERGE the tree under `root` to `manifest`, loading each captured file's bytes via `getBlob`. **The
+ * env-operating + security-critical half a durable backend MUST reuse.** Order is load-bearing (codex BLOCKER +
+ * Opus M1): PHASE 1 removes every current symlink (neutralizes a `dir -> /outside` ancestor that writeFile would
+ * otherwise follow OUT of root) + every file created since; PHASE 2 writes each captured file, clearing a
+ * directory that now occupies a file's path first. Never throws.
+ */
 export declare function applyManifest(env: ExecutionEnv, root: string, bounds: FileSnapshotBounds, signal: AbortSignal | undefined, manifest: Map<string, string>, getBlob: (hash: string) => Uint8Array | undefined | Promise<Uint8Array | undefined>): Promise<FileSnapshotResult>;
+/**
+ * In-memory, content-addressed reference {@link FileSnapshotStore}. Blobs are deduplicated by sha256 ACROSS all
+ * snapshots (a file unchanged between turns is stored once); each snapshot keeps a manifest `relPath → hash`.
+ * Single-process (the default-deps reference; a durable/file-backed impl mirrors `src/stores/file/`).
+ */
 export declare class InMemoryFileSnapshotStore implements FileSnapshotStore {
     private readonly blobs;
     private readonly manifests;
@@ -53,6 +155,8 @@ export declare class InMemoryFileSnapshotStore implements FileSnapshotStore {
     importManifest(scope: string, key: string, manifest: Map<string, string>, srcGetBlob: (hash: string) => Promise<Uint8Array | undefined>): Promise<FileSnapshotResult>;
     reap(scope: string, keepKeys: string[]): Promise<number>;
 }
+/** Test-only window (REF-C2 class pins): pure path helpers whose family-awareness carries a fence/
+ *  restore invariant. Not re-exported from src/index.ts. */
 export declare const __testables: {
     joinUnder: typeof joinUnder;
     relUnder: typeof relUnder;