@sema-agent/core 5.20.0 → 5.21.0

package/dist/core/checkpoint-store.d.ts

@@ -7,48 +7,225 @@ import type { ConsolidationNote } from "./runner/memory-consolidation.js";
 import type { SessionPermissionRules } from "./session-policy-store.js";
 import type { NestedUsageAccum, TaskResult } from "./types.js";
 import type { ActiveWorktreeSession } from "../internal/harness-types.js";
+/**
+ * design/45 — the **durable-checkpoint** primitive: cross-process / resumable `suspend`/`resume`.
+ *
+ * A {@link CheckpointStore} is the third pluggable durable seam (alongside `ToolResultStore` and
+ * `MemoryStore`): a token-addressable store of "enough state to resume a suspended task", with an
+ * **atomic CAS `resolve`** so a token is acted on **exactly once** even across replicas / double
+ * approvals. Two profiles share this one seam (design/43 原语 4, proven by two service instances):
+ *
+ *  - **F4** (`gate.kind === "human"`) — a running task hit a tool-policy `ask` that no in-process
+ *    approver can answer (headless / long / cross-replica), so it persists a checkpoint and returns
+ *    `status:"suspended"`. Later `runner.resume(token, {gate:"policy_ask", decision})` continues it.
+ *    This is the cross-process version of the synchronous `onAsk` gate (design/37).
+ *  - **1C** (`gate.kind === "task_done"`) — design/38 Path A persists a background sub-task handle here
+ *    so a caller can `get` its outcome across replicas. v1 stores the handle only; the parent does NOT
+ *    mid-task suspend (Path A unchanged) — `runner.resume()` does NOT serve this gate in v1.
+ *
+ * **opt-in, default-off**: with no `CheckpointStore` wired (and no durable approval mode requested), a
+ * policy `ask` still resolves the 1.63 way (synchronous `onAsk` / headless auto-deny) — behavior
+ * unchanged. Default {@link InMemoryCheckpointStore} is process-only (single instance / tests); a
+ * durable backend (service's `tidb-approval-store` / `tidb-run-store`) makes it cross-replica.
+ *
+ * See `design/45-durable-checkpoint原语-suspend-resume.md`.
+ */
+/**
+ * A high-entropy, single-use checkpoint token. Branded so it can't be confused with a `sessionId` /
+ * `taskId` (council Question #2): the token doubles as the resume capability (token-as-auth, §6), so a
+ * mix-up would be a security bug, not just a type slip. Mint with {@link mintCheckpointToken}.
+ */
 export type CheckpointToken = string & {
     readonly __brand: "CheckpointToken";
 };
+/** Mint a CSPRNG 128-bit checkpoint token (token-as-auth, §6/Q5): unguessable, never logged/in-URL. */
 export declare function mintCheckpointToken(): CheckpointToken;
+/**
+ * Who resumes a checkpoint, and how the resume `outcome` is interpreted. The `kind` is the discriminant
+ * that {@link ResumeOutcome} must match at the resume entry (council #3: prevents a `task_done` gate
+ * being resumed with a `policy_ask` outcome → type confusion / corruption).
+ */
+/** design/74: why a resource-slice suspend fired. `"budget"` covers cost OR tokens (both are checked by
+ *  `overBudget`); `"walltime"` is the soft slice deadline; `"turns"` the slice turn cap.
+ *  design/80 Seam #2: `"preempt"` is NOT a resource limit — it is an EXTERNAL scheduler yield (the scheduler
+ *  raised `spec.preemptSignal` to free resources for a higher-priority task). It rides the SAME durable-suspend
+ *  mechanism: the gate.kind stays `resource_limit` (the mechanism), so the resume path is byte-identical to a
+ *  budget/turns/walltime resume (continue the work, no decision); `"preempt"` is only the CAUSE. */
+/**
+ * Why a `resource_limit` suspend was minted. design/164 split the single `budget` member: a token
+ * window and a $ window are different allowances with different owners, and a scheduler reading a
+ * checkpoint inbox to decide "grant more of what?" could not tell them apart. The reasons match the
+ * terminal codes the non-suspending tier reports (`limits.max_*_exceeded`), so one vocabulary covers
+ * both tiers.
+ *
+ * **Consumers pinning the old closed set**: `"budget"` is gone — a switch on it now falls through.
+ *
+ * design/164 件四/件五 added two more members, and they are a DIFFERENT CLASS from the task axes above:
+ * `"env_lifetime"` (the execution environment's platform lifetime is about to expire) and
+ * `"usage_window"` (a deployment-level usage-governance window is exhausted) are EXTERNAL causes — the
+ * task did not choose them and cannot avoid them by asking for less. They therefore suspend on the
+ * INFRASTRUCTURE eligibility alone (checkpoint store + non-volatile offload + remote/no owned env),
+ * without the `TaskSpec.resourceSuspend` opt-in the task axes require. When several causes land on one
+ * turn boundary the attribution order is
+ * `preempt > env_lifetime > usage_window > budget_tokens > budget_cost > turns > walltime`
+ * (external causes above self-chosen allowances; preempt keeps the top seat it always had).
+ *
+ * **Consumers pinning the closed set again**: a `switch` that was exhaustive over the five 5.x members
+ * now falls through on these two.
+ */
 export type ResourceLimitReason = "budget_tokens" | "budget_cost" | "walltime" | "turns" | "preempt" | "env_lifetime" | "usage_window";
+/**
+ * design/164 件四/件五 — the EXTERNAL subset of {@link ResourceLimitReason}: causes that come from the
+ * platform or the operator rather than from the task's own declared allowances. Written as an `Extract`
+ * of the parent union so the two can never drift into disagreeing about what "external" means, and so a
+ * seam that may only be reached by an external cause (the infrastructure-only suspend lane) cannot be
+ * handed a task-axis reason by mistake.
+ */
 export type PlatformLimitReason = Extract<ResourceLimitReason, "env_lifetime" | "usage_window">;
+/**
+ * design/80 D-2: which SAFETY MARK(s) on the tool caused an `ask` to mint an {@link CheckpointGate}
+ * `irreversible_ask`. Derived from the tool's STATIC spec marks (`ToolSpec.egress` / `ToolSpec.irreversibility`,
+ * round-1 council fix — NOT the per-call `decisionReason`, which missed a policy/hook pre-ask and was
+ * forgeable). Persisted on the gate so a network budget/escalation resolver reads WHY this is a safety ask FROM
+ * THE DURABLE RECORD (never re-derives risk from a model-controlled value — the model self-reports nothing
+ * here). Both can be true (a tool marked BOTH egress AND irreversible).
+ */
 export interface SafetyAxis {
+    /** design/70: the tool is egress-marked (`ToolSpec.egress` — an external write: push, open PR, send). */
     egress?: boolean;
+    /** design/77 §4: the tool's irreversibility tier is `always` or `maybe` (`ToolSpec.irreversibility`). */
     irreversible?: boolean;
 }
+/**
+ * design/80 §D-E: a DETERMINISTIC, REDACTED risk summary attached AT MINT to an escalation
+ * {@link CheckpointGate} (`human` / `irreversible_ask` — the tool-call approval escalations) so a supervisor
+ * INBOX can sort/triage by TRUE severity without re-deriving risk. **Display/triage metadata ONLY** — core
+ * NEVER reads it to gate / budget / suppress anything (structural ask strictly wins via `combinePolicies`;
+ * no mint suppression reads it). The profile/inbox READS it; core only ATTACHES it. Pure function of the
+ * call (no clock/random) — same call ⇒ identical descriptor.
+ */
 export interface RiskDescriptor {
+    /** ToolEmu-style severity tier 1..5 (5 = most severe). The inbox sorts DESC by this. Deterministic — the
+     *  pure {@link riskSeverity} of {@link axes}. The ORDERING is what matters (the inbox's triage key). */
     severity: 1 | 2 | 3 | 4 | 5;
+    /** Which safety axes tripped — for `irreversible_ask`, derived from the D-2 {@link SafetyAxis} (+ the
+     *  shell-gate). `shell` marks a coarse shellGate tighten (a bash command gated only because the deployment
+     *  set `shellGate`, with NO explicit per-tool egress/irreversible mark). Empty `{}` for a plain budgetable
+     *  `human` ask. Self-contained so the inbox needn't cross-ref `safetyAxis`. */
     axes: {
         egress?: boolean;
         irreversible?: boolean;
         shell?: boolean;
     };
+    /** The tool whose call is gated (mirrors the gate's `toolName`). */
     toolName: string;
+    /** Ruled 2026-08-05 (forensics): the run's resolved shellGate doctrine, present ONLY when this ask
+     *  was minted through the shell gate (coarse `always`, or a `classify` probe that declined to
+     *  auto-allow). Absent for per-tool safety-axis / plain policy asks. Answers "which doctrine was
+     *  live when this gate fired" from the persisted row alone — three artifact layers could not
+     *  answer that in the field. */
     shellGateDoctrine?: "classify" | "always";
+    /** A REDACTED, length-capped ONE-LINE summary of the call (the command for a shell gate; a brief key-arg
+     *  digest otherwise) for the inbox preview. NEUTRALIZED via {@link import("./untrusted-text.js").inlineUntrusted}
+     *  + length-capped (it is persisted + shown to a human inbox, so a crafted tool arg carrying a
+     *  `</system-reminder>` variant / newline / huge string must NOT inject into the render or bloat storage).
+     *  NEVER raw secrets / full args / env. Deterministic. Optional (omitted when nothing safe to summarize). */
     summary?: string;
+    /** Best-effort file paths the action touches (fs-tool `path` args; shell parsing is deliberately NOT
+     *  attempted — over-reaching a shell parse risks a wrong/forgeable path). Each path `inlineUntrusted`-capped.
+     *  Omitted when none derivable. */
     touchedPaths?: string[];
 }
+/**
+ * design/80 §D-E: the DETERMINISTIC severity tier (1..5) for an escalation checkpoint, a PURE function of the
+ * tripped {@link RiskDescriptor.axes} (NO LLM, NO clock/random) so the inbox's sort order is stable and
+ * unit-testable in isolation. The ORDERING is the contract; the absolute numbers map to ToolEmu's 5 tiers:
+ *  - irreversible AND egress → **5** (the most severe — an external, irreversible write)
+ *  - irreversible only       → **4**
+ *  - egress only             → **3**
+ *  - shell-gated tighten     → **3** (a coarse shellGate ask with no explicit egress/irreversible mark — the
+ *                                     command MAY be benign, so it is not auto-graded as high as a marked tool)
+ *  - plain `human` ask       → **2** (no safety axis tripped — a budgetable approval)
+ *  - (1 reserved — least-severe / informational; not expected from these gates.)
+ * `egress` dominates the shell coarse-grade (an explicitly egress-marked shell tighten is still ≥3). A future
+ * arm may refine this — but only with a stated reason, and the ORDERING must stay monotone in risk.
+ */
 export declare function riskSeverity(axes: {
     egress?: boolean;
     irreversible?: boolean;
     shell?: boolean;
 }): 1 | 2 | 3 | 4 | 5;
+/** design S1e (service [204]): the char cap for the {@link CheckpointSummary.toolInput} BOUNDED raw preview of a
+ *  `tool_approval` pendingAction's `args` (`JSON.stringify`-ed). Caps the `listByScope` payload size; over-cap
+ *  is truncated with a trailing `…`. Bounded raw (NOT neutralized) — redaction is the consumer's job (echo-only). */
 export declare const MAX_TOOL_INPUT_PREVIEW_CHARS = 512;
+/**
+ * HRD-APV-4: the char cap {@link validatePendingSteer} enforces on a parked operator steer — the last
+ * persisted, model-facing string on a checkpoint row that had none.
+ *
+ * Sized as an INSTRUCTION budget, not a preview budget: the siblings above cap echo-only projections at
+ * 200/512 chars, while a steer is prose a human wrote for the model to act on and is re-delivered on
+ * every resume of the checkpoint. 16k chars (~4k tokens) holds any realistic operator instruction and
+ * still bounds the durable row and the per-resume context cost. Exported so a BFF can validate before it
+ * calls {@link CheckpointStore.setPendingSteer} rather than discovering the reject at persist time.
+ */
 export declare const MAX_PENDING_STEER_CHARS = 16000;
+/**
+ * design/171 §6.3 — the BYTE budget the whole parked-steer queue must fit inside, measured on its JSON
+ * serialization (the form every backend actually persists).
+ *
+ * 48,000 bytes sits under a MySQL `TEXT` column's 65,535-BYTE ceiling with room for UTF-8 expansion: the
+ * per-entry cap above counts CHARACTERS, and 16,000 CJK characters serialize to ~48,000 bytes, so a
+ * char-only cap does not bound the column at all. Both limits are enforced and either one can bind.
+ */
 export declare const PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES = 48000;
+/**
+ * design/171 §6.3 — the queue's entry-count cap, DERIVED from the byte budget and the per-entry char cap
+ * (how many maximum-size entries the budget can hold). It bounds the count independently of the byte
+ * measure so a flood of tiny steers cannot grow the row unboundedly through per-entry overhead alone.
+ * Exceeding either limit is a fail-loud `steering.queue_full` — never a silent drop of the oldest entry
+ * (a dropped operator instruction is exactly the failure this queue exists to remove).
+ */
 export declare const MAX_PENDING_STEER_ENTRIES: number;
+/**
+ * design/171 §6.3 — the FROZEN field set of a persisted {@link PendingSteerEntry}. `validatePendingSteer`
+ * copies by this set and REFUSES an unknown key, so a producer one release ahead of this worker gets a
+ * loud rejection instead of having its new field silently dropped on the parked leg. Consumers (other
+ * repos' backends) read it to assert they round-trip every field rather than hand-listing their own copy.
+ */
 export declare const PENDING_STEER_FROZEN_FIELDS: readonly ["text", "trusted", "actor", "seq", "inputId", "priority"];
+/**
+ * design/171 §6.1 — WHO a piece of human input came from, as an attribution label. ONE definition:
+ * the shape lives at its layering-legal home (`engine/llm/types.ts`, where `UserMessage.actor`
+ * carries it and the engine cannot import core) and this module re-exports it — the live message
+ * seat and the parked entry can never drift apart. Normative clauses (never authority; ingress-only
+ * `hostAsserted`) are on the definition.
+ */
 import type { ActorAssertion } from "../internal/llm.js";
 export type { ActorAssertion } from "../internal/llm.js";
+/**
+ * design/171 §5.3/§6.3 — one entry of the parked-steer QUEUE. Replaces the former single seat, whose
+ * last-writer-wins overwrite silently destroyed an undelivered operator instruction whenever two people
+ * steered the same suspended run.
+ */
 export interface PendingSteerEntry {
+    /** The operator's instruction text (validated exactly like the pre-queue single seat). */
     text: string;
+    /** Frozen at append time from the SERVICE's verified-principal check; never recomputed on resume. */
     trusted: boolean;
+    /** Attribution only (see {@link ActorAssertion}) — absent = the caller supplied none (anonymous). */
     actor?: ActorAssertion;
+    /** Queue-monotonic ordering key, minted by the store on append (first entry = 1). Drain order. */
     seq: number;
+    /** Caller-supplied correlation/idempotency id (a service passes the message id it already minted);
+     *  a uuidv7 is minted when absent. Re-appending the SAME `inputId` is a no-op, which is what keeps
+     *  `setPendingSteer` retry-safe now that it appends instead of overwriting. */
     inputId: string;
+    /** Carried VERBATIM for the serving layer; it does NOT reorder the drain (drain is `seq` order). */
     priority?: SystemInjectionPriority;
 }
+/** design/171 §6.3 — the caller-supplied half of a {@link PendingSteerEntry}: everything except `seq`,
+ *  which only the store may mint. `inputId` is optional on the way in (minted when absent). */
 export interface PendingSteerInput {
     text: string;
     trusted: boolean;
@@ -56,59 +233,281 @@ export interface PendingSteerInput {
     inputId?: string;
     priority?: SystemInjectionPriority;
 }
+/**
+ * design/80 §D-E: build the DETERMINISTIC, REDACTED {@link RiskDescriptor} for an escalation checkpoint at
+ * MINT. Pure — a function ONLY of (`toolName`, `args`, the D-2 `safety` axis, the `shellGated` flag); it reads
+ * NO clock/random, so the SAME call ⇒ an IDENTICAL descriptor (pinned by a test).
+ *
+ * **Determinism contract = plain-DATA args** (the real flow: model-JSON / hook-rewritten plain objects). A
+ * Proxy whose `ownKeys` trap returns a DIFFERENT key set per call is OUT OF CONTRACT — JS cannot detect a Proxy
+ * (codex review Item 2), so its (display-only) digest may vary. This NEVER affects a security/budget/mint
+ * decision: `riskDescriptor` is INERT (no core path reads it to gate), so an out-of-contract input can at worst
+ * degrade an inbox preview, never a permission outcome.
+ *
+ * **Redaction is load-bearing** (the `summary`/`touchedPaths` are PERSISTED + surfaced to a human inbox):
+ * every model-controlled value goes through {@link inlineUntrusted} (folds CR/LF/Unicode separators to one
+ * space, defuses `</system-reminder>` variants + `<<<`/`>>>` fence sentinels) AND a length cap, so a
+ * crafted arg carrying a break-out tag / newline / huge string can neither inject into the inbox render nor
+ * bloat the durable row. NEVER dumps full args / env / secrets — only a bash command string or a short
+ * `name=value` digest of the SHOWN args.
+ *
+ * `summary` for a shell gate = the `command` string (capped 200 cp); otherwise a `name=value` digest of the
+ * call's top-level string/number/boolean args (each value capped), omitted when nothing safe to summarize.
+ * `touchedPaths` reads ONLY the obvious fs `path` arg (read_file/edit_file/write_file) — shell parsing is
+ * deliberately NOT attempted (over-reaching a shell parse risks a wrong/forgeable path, so OMIT for bash).
+ */
 export declare function buildRiskDescriptor(input: {
     toolName: string;
     args: unknown;
+    /** The D-2 {@link SafetyAxis} threaded to the mint (egress/irreversible), or `undefined` for a plain ask. */
     safety?: SafetyAxis;
+    /** True ONLY when this is a `bash` call gated coarsely by `shellGate` (no explicit per-tool egress/irreversible
+     *  mark) — drives the `shell` axis + severity-3 coarse grade. */
     shellGated?: boolean;
+    /** The resolved doctrine to persist when `shellGated` (see {@link RiskDescriptor.shellGateDoctrine}). */
     shellGateDoctrine?: "classify" | "always";
 }): RiskDescriptor;
-export type CheckpointGate = {
+export type CheckpointGate = 
+/** F4: a human (or any external authority) must allow/deny a pending tool call. design/80 §D-E:
+ *  carries an OPTIONAL display-only {@link RiskDescriptor} (severity/axes/summary) for the supervisor
+ *  inbox to triage by — INERT (core never reads it to gate/budget). */
+{
     kind: "human";
     reason: string;
     toolName: string;
     riskDescriptor?: RiskDescriptor;
-} | {
+}
+/** design/77 §4 (Gate 4) + design/80 D-2: a PRE-ACTION human approval before a SAFETY-tightened tool runs —
+ *  an IRREVERSIBLE tool (send money/email, file a return) OR an EGRESS tool (push, open PR, send). Same
+ *  approval family as `human` (a pending tool call to allow/deny → suspendRef → `status:"suspended"`, resumed
+ *  with a `policy_ask` outcome). **design/80 D-2 (load-bearing):** minted whenever an `ask` is for a tool
+ *  carrying the egress / irreversibility (`always`/`maybe`) SAFETY MARKS — regardless of how the ask arose
+ *  (a gate tighten OR a policy/hook that already asked; round-1 council fix: keying on the per-call
+ *  `decisionReason` missed the policy-ask case AND was forgeable) — **EVEN WHEN `durableApproval` is wired**
+ *  (`durableApproval` supplies scope/ttl, NOT the kind). The DISJOINT-from-`human` kind is what a
+ *  network budget resolver keys on to NEVER auto-approve a safety ask (a budget may only down-budget a plain
+ *  `human` ask). {@link SafetyAxis} records which axis(es) tightened. NOT a dry-run review. */
+ | {
     kind: "irreversible_ask";
     reason: string;
     toolName: string;
     safetyAxis?: SafetyAxis;
     riskDescriptor?: RiskDescriptor;
-} | {
+}
+/** design/74: a resource slice limit (budget/walltime/turns) was reached — suspend (resumable) instead of
+ *  fail. There is NO pending tool to adjudicate; resume just continues the run with the next slice's
+ *  allowance (sized from {@link Checkpoint.resourceLedger}). The matching {@link ResumeOutcome} arm is
+ *  `{ gate: "resource_limit"; decision: "continue" }`.
+ *
+ *  design/164 件五: `resumeAfterMs` is the RESUME-TIMING hint that pairs with {@link Checkpoint.deadline}
+ *  — how long the driver should wait before resuming, because resuming sooner would only re-suspend.
+ *  **In-scope condition**: present ONLY for `reason: "usage_window"` (the one cause that knows when it
+ *  clears); every other reason omits it, so a consumer must not read its presence as "this is
+ *  resumable". Additive on the existing checkpoint version — a reader that ignores it is unchanged. */
+ | {
     kind: "resource_limit";
     reason: ResourceLimitReason;
     resumeAfterMs?: number;
-} | {
+}
+/** design/76 §2.5 (dry-run / shadow): a POST-PREDICTION REVIEW pause. A profile's dry-run interception ran a
+ *  predicted action and produced a buffered state-diff a human (or judge) must REVIEW before it is applied —
+ *  so the task suspends to the durable `needs_review` TERMINAL (`TaskStatus:"needs_review"`) instead of
+ *  finishing. **DISJOINT from the approval family** (`human`/`irreversible_ask`): those are PRE-ACTION
+ *  *approvals* (suspendRef → `status:"suspended"`, resumed with a `policy_ask` outcome); this is a
+ *  POST-prediction *review* (reviewRef → `status:"needs_review"`, resumed with a `dry_run_review` outcome).
+ *  The split is load-bearing — reusing the approval family would make assemble-result report `"suspended"`
+ *  and the `needs_review`/`review.pending` branch dead code (v4 MAJOR-A). It is ALSO disjoint from the
+ *  `RepairTerminal.needs_human_oracle` (design/78) — a different type space; never cross-use the two.
+ *  The state-diff itself is a PROFILE concern (a REF, not stored here — design/76 §9 / §2.5); core only
+ *  owns the gate/status/discriminant plumbing. NOT a pre-action approval. */
+ | {
     kind: "needs_review";
     reason: string;
-} | {
+}
+/** design/80 D-B (plan-gate): a PRE-ACTION human PLAN REVIEW. Before an agent acts on a high-blast-radius
+ *  plan (a profile's plan-gate fires on shell⇒gate + an irreversible/egress/finance mark present + a
+ *  blast-radius trigger — NOT every task), the run pauses so a human can **approve / edit / reject the
+ *  proposed PLAN** before any step runs. It is its OWN gate kind (r2 ruling — do NOT reuse `needs_review`,
+ *  whose gateMatch arm forces a `dry_run_review` outcome; reusing it would make a plan resume a
+ *  type-confusion mismatch), but it shares the **review-pause** machinery: it routes to `reviewRef` +
+ *  `status:"needs_review"` (a human-review pause), resumed with a `plan_review` outcome.
+ *
+ *  **THREE-WAY SPLIT (load-bearing):**
+ *   - the APPROVAL family (`human`/`irreversible_ask`) → PRE-ACTION *approvals* of a pending TOOL CALL
+ *     (suspendRef → `status:"suspended"`, resumed with a `policy_ask` outcome bound to a tool call);
+ *   - `needs_review` → a POST-prediction *review* of a buffered state-diff (reviewRef →
+ *     `status:"needs_review"`, resumed with a `dry_run_review` outcome);
+ *   - `plan_review` (this) → a PRE-ACTION *review* of a PLAN (reviewRef → `status:"needs_review"`, resumed
+ *     with a `plan_review` outcome). It binds NO tool call — the human reviews the PLAN, not a pending arg —
+ *     so it carries no `tool_approval` pendingAction (its pendingAction is `{kind:"plan_review"}`, with no
+ *     tool fields) and the `policy_ask` decision-action binding machinery never touches it. The plan/diff
+ *     artifact is a PROFILE concern (a REF, not stored here — design/76 §9); core owns the
+ *     gate/status/discriminant plumbing only. NOT a pre-action approval, NOT a dry-run review. */
+ | {
     kind: "plan_review";
     reason: string;
-} | {
+}
+/** 1C: the checkpoint tracks a background sub-task's completion (design/38 Path A). v1 = handle only. */
+ | {
     kind: "task_done";
 };
+/**
+ * The outcome a caller supplies to `runner.resume(token, outcome)` — a **discriminated union** keyed by
+ * `gate`, validated against `checkpoint.gate.kind` at the entry (council #3). **v1 implements only the
+ * `policy_ask` arm**: `task_done` is a dead branch under 1C Path A (the caller orchestrates, never
+ * mid-task `resume()`), typed here for completeness and the v2 join-suspend option.
+ */
 export type ResumeOutcome = {
     gate: "policy_ask";
+    /**
+     * design/80 D-1 (decision-action binding): the `toolCallId` the human actually saw/approved. The
+     * resume is REJECTED (`checkpoint.invalid_outcome`, fail-closed, pre-CAS) unless it matches the
+     * checkpoint's pending tool call (`pendingAction.toolCallId`) — this closes the TOCTOU re-suspend
+     * wrong-apply: a stale `yes` minted against pending call X must not resolve a DIFFERENT pending call
+     * Y (approve vendor-A $5k applied to vendor-B). The decision must name the action it bound to; the
+     * runner never trusts that the caller matched the correct pending call (design/77 doctrine —
+     * deterministic structural backstop, not a model self-report).
+     *
+     * The correct value is the resumed checkpoint's `pendingAction.toolCallId`; the caller has it via the
+     * `suspendRef` / pending record it is answering.
+     */
     boundCallId: string;
+    /**
+     * design/80 D-1 §2 (slice 1a.2): the **server-minted opaque** hash of the pending tool call's input
+     * that the human actually saw/approved (`PendingAction.tool_approval.boundInputHash`, computed by the
+     * engine at suspend-mint via {@link import("./canonical-json.js").boundInputHashOf} over the post-hook
+     * `args`). The caller echoes it VERBATIM — it is opaque; the SDK/service NEVER re-canonicalize args
+     * (review r3: a second runtime's serialization could diverge → false mismatch → fail-closed a
+     * legitimate approval). The resume verifies it by **string equality** against the checkpoint's
+     * persisted value (`checkpoint.invalid_outcome`, fail-closed, pre-CAS) — closing the TOCTOU "same call
+     * id, different input" variant that `boundCallId` alone misses (a re-mint that swapped the input under
+     * the same tool-call id). It binds the SHOWN input, NOT `updatedInput`: an `allow` edit is the same
+     * operator's authorized rewrite, applied AFTER this binding check (design/37,末位应用), so the echoed
+     * hash is always the pending record's value regardless of any edit. (Legacy pre-1a.2 checkpoints have
+     * no persisted hash → the resume skips this check, binding on `boundCallId` alone; new mints enforce.)
+     */
     boundInputHash: string;
+    /** `allow` → execute the pending tool call; `deny` → inject a denial result and continue. */
     decision: "allow" | "deny";
+    /** A re-written arg payload (design/37 policy `allow` rewrite); re-validated on execute. */
     updatedInput?: unknown;
+    /** Model-readable reason attached to a `deny` (else a default is used). */
     reason?: string;
+    /**
+     * The ANSWER to a CONTENT-ASK (the reserved AskUserQuestion tool), carried by the decide itself
+     * (ruled 2026-08-04). A content-ask is a question TO the user: `allow` alone says "let the tool
+     * run" but supplies nothing to run it AGAINST, and the only pre-existing answer seat was the
+     * resumed leg's `onQuestion` config closure — a seat an OFFLINE background child has no operator
+     * on, because its resume config is rebuilt from the parked row rather than handed in. With the
+     * answer on the decision payload, the same `/decide`-shaped call serves both arms: the resume
+     * binds it as the resumed leg's answering face, so the pending call executes against the SAME
+     * tool, the SAME `selected ⊆ options` fence and the SAME untrusted free-text framing (design/80
+     * D-F) as a live answer — one support surface, not two.
+     *
+     * TRUST: untrusted wire data. It is NEVER read as instructions — the tool splits it into the
+     * trusted selections (which must be the model's own option labels) and a fenced free-text
+     * remainder. Off-list `selected` values and `note` are exactly the "Other" free-text path.
+     *
+     * ARM-SCOPED, like `updatedInput`/`reason` on this same arm: only a `policy_ask` `allow` whose
+     * pending call IS the reserved tool may carry one. Supplying it anywhere else is rejected
+     * pre-CAS (`checkpoint.invalid_outcome`, `detail.field: "answer"`) rather than silently dropped,
+     * and OMITTING it on a content-ask allow with no live answering face is rejected the same way —
+     * consuming the approval to hand the model a fabricated "no human available" default is the
+     * silent-continue this seat exists to end.
+     */
     answer?: QuestionAnswer;
+    /**
+     * WHAT ENDED THIS APPROVAL — `"human"` (a person gave the final verdict), `"timeout"` (the
+     * configured window elapsed with no answer), or `"aborted"` (every other non-human end: the run
+     * was cancelled, the connection dropped, the store gave way, retries ran out). See
+     * {@link import("./tool-policy.js").ApprovalSettledBy} for the vocabulary itself.
+     *
+     * Attribution travels WITH the decision because it is a property OF the decision, not something
+     * a later reader can reconstruct: by the time an approval reaches a consumer, "denied" and "the
+     * window closed" have already collapsed into the same `decision:"deny"`, and only the caller that
+     * settled it still knows which happened. Core does not derive it, does not default it, and never
+     * infers it from some other outcome — it carries what the settling caller wrote onto the
+     * `tool_end` frame of the call this resume resolves.
+     *
+     * **Fill it at every settlement site.** A deployment resolving an approval from several places
+     * (an operator decide, an SLA sweep at the deadline, a cancel path) names the cause at each of
+     * them. Deriving it once, centrally, from the last outcome at hand is precisely how a window that
+     * elapsed gets reported to a person as another person's refusal.
+     *
+     * OPTIONAL and additive: absent means the caller named no source (a caller written before this
+     * field existed), and a consumer must NOT read a semantic out of the absence — core neither
+     * substitutes a default nor guesses. A value outside the three words is refused pre-CAS
+     * (`checkpoint.invalid_outcome`), like every other out-of-domain field on this arm: a settlement
+     * source nobody can read is worse than none at all. So is one that contradicts its own decision:
+     * `decision:"allow"` accepts only `"human"` or omission, because "nobody answered, therefore it
+     * ran" is not a record of anything that happened (a deployment whose CONFIGURATION auto-allows an
+     * elapsed window omits the field — no one ended that wait).
+     *
+     * SCOPE — this rides the settlement, NOT the persisted winner: `winnerFromOutcome` records the
+     * decision (and its rewrite/answer/reason), which is what an `env_failed` replay must reproduce
+     * exactly, and the source is not part of that authorization. A replay therefore states its own
+     * source and is not held to the first one. Binding it into the persisted winner would also make a
+     * re-supply that merely OMITS the field fail closed on the recovery path, which is the wrong place
+     * to add a new refusal; carrying it into the durable row is a store-shape change owned jointly
+     * with the backends and belongs to its own change, not to this one.
+     */
     settledBy?: import("./tool-policy.js").ApprovalSettledBy;
-} | {
+}
+/** design/74: continue a resource-suspended run with the next slice's allowance. NO decision payload and
+ *  NO budget figure — the allowance is computed from {@link Checkpoint.resourceLedger}, so money never
+ *  reaches the caller or the model. Matches `CheckpointGate.kind === "resource_limit"`. */
+ | {
     gate: "resource_limit";
     decision: "continue";
-} | {
+}
+/** design/76 §2.5 (dry-run / shadow): resolve a `needs_review` suspend after a human/judge reviewed the
+ *  buffered predicted state-diff. `decision:"approve"` → the profile applies the buffered diff (atomically,
+ *  invalidating `readFileState` on touched paths — design/76 §2.5; the apply itself is PROFILE, not core)
+ *  then continues; `decision:"reject"` → the prediction is discarded and the run continues without it. Kept
+ *  DISJOINT from `policy_ask` (the approval family) so the resume-side discriminant never confuses a
+ *  post-prediction review with a pre-action approval (the third `needs_review`/`dry_run_review` gateMatch arm).
+ *  No money/diff payload reaches the caller here — the diff lives in the profile's REF store (design/76 §9). */
+ | {
     gate: "dry_run_review";
     decision: "approve" | "reject";
     reason?: string;
-} | {
+}
+/** design/80 D-B (plan-gate): resolve a `plan_review` PRE-ACTION plan pause after a human reviewed the
+ *  proposed PLAN. `decision:"approve"` → proceed with the plan as-is; `decision:"edit"` → proceed with the
+ *  human's `editedPlan` (a TYPED sibling of the plan — NEVER a raw tool `updatedInput`; a plan is not a tool
+ *  arg, so this binds NO action and never enters the `policy_ask` boundCallId/boundInputHash machinery);
+ *  `decision:"reject"` → the model RE-PLANS (the rejected plan is discarded; a `reason` may steer the
+ *  re-plan). Kept DISJOINT from `policy_ask` (approval) AND `dry_run_review` (post-prediction review) so the
+ *  resume-side discriminant never confuses the three (the `plan_review`/`plan_review` gateMatch arm). It
+ *  binds no TOOL CALL, but since RB-64 it does record a winner: `winnerFromOutcome` returns the decision
+ *  (plus `editedPlan` as `updatedInput` and the reviewer `reason`) under the synthetic `gate:plan_review`
+ *  marker, so an `env_failed` reopen can replay it. The `boundCallId`/`boundInputHash` TOOL-CALL binding
+ *  is what stays `policy_ask`-only. No plan/diff payload (beyond the human's
+ *  `editedPlan` text) reaches core — the plan artifact lives in the PROFILE's REF store (design/76 §9). */
+ | {
     gate: "plan_review";
     decision: "approve" | "edit" | "reject";
     editedPlan?: string;
     reason?: string;
-} | {
+}
+/** design/144 §3 (message-wake): wake a PARKED (non-gate) checkpoint and drive it to continue — a pure
+ *  un-park verb, **NOT a gate decision**: it never allows/denies/approves anything. Governance-gate
+ *  purity is enforced at the resume entry (fail-closed, pre-CAS): a checkpoint awaiting ANY pending
+ *  gate decision (`gate.kind` ∈ {human, irreversible_ask, needs_review, plan_review, resource_limit} —
+ *  i.e. the tool_approval / dry_run_review / plan_review / resource_limit decision families) REJECTS a
+ *  wake with `wake.gate_pending`, so wake can never become a side door around an approval. Only a
+ *  non-gate park (e.g. a deployment-minted approval-timeout park / pure suspend) is wakeable.
+ *
+ *  `message` (optional): operator content delivered to the resumed run — the ATOMIC equivalent of
+ *  `setPendingSteer` + resume in one verb (same `validatePendingSteer` persist-time guards, same
+ *  trusted/untrusted delivery framing as {@link CheckpointState.pendingSteer}). It rides the resume
+ *  continuation's steer tail as its OWN segment, appended AFTER any already-parked `pendingSteer`
+ *  (X5: both are delivered — the wake message never displaces a parked, undelivered supervisor steer;
+ *  each segment is framed under its own `trusted` semantics, never one merged trust domain). WITHOUT a
+ *  `message`, the checkpoint must already carry a parked `pendingSteer` — a wake with nothing to
+ *  deliver is rejected (`wake.nothing_to_deliver`, anti spin-wake). Idempotency rides the existing
+ *  resolve CAS: a second wake of the same token loses the CAS (`checkpoint.already_resolved`). */
+ | {
     gate: "wake";
     message?: {
         text: string;
@@ -118,46 +517,220 @@ export type ResumeOutcome = {
     gate: "task_done";
     result: TaskResult;
 };
+/**
+ * The pending action a checkpoint suspends *before* — a **discriminated union** keyed by `kind`. Every
+ * consumer that reads the tool fields MUST branch on `kind` first: the `resource_limit` arm (design/74)
+ * has none (a resource slice suspend has no pending tool to resolve).
+ *
+ * `tool_approval` (§4): a tool call adjudicated `ask` in durable mode, captured with its **post-hook args**
+ * (the design/37 rewrite already applied) so resume executes the exact same call without re-running
+ * PreToolUse hooks (§11 M2). `batchToolCallIds` / `completedCallIds` capture the **mid-batch** position
+ * (§4.ter): one assistant turn can emit a batch of tool calls; if call #k hits `ask`, calls #1..k-1 already
+ * executed (in `completedCallIds`) and #k+1..N are still pending. ID-based (a `Set<toolCallId>`), not
+ * positional — immune to reordering / off-by-one (council Question #1), and it doubles as the reconcile
+ * suspended-batch discriminant (§15.2 net-add #7) so wake-reconcile never closes a suspended call.
+ */
 export type PendingAction = {
     kind: "tool_approval";
     toolCallId: string;
     toolName: string;
+    /** Post-hook (design/37-rewritten) args to execute on `allow`. */
     args: unknown;
+    /** [1245] (additive) — the tool's approval display projection of `args`, minted alongside the
+     *  row (see AgentTool.approvalPreview; control-char-sanitized + 16KiB-clamped at mint).
+     *  **UNTRUSTED, ADVISORY**: inboxes must escape contextually and surface `args` alongside.
+     *  NEVER read by the resume path (args + boundInputHash stay the sole execution contract). */
     preview?: unknown;
+    /** design/179 §4 (additive) — the persistable allow-rule forms this parked call could be covered by,
+     *  minted from the SAME post-hook args the row executes. Advisory display metadata for the approval
+     *  inbox's "stop asking me this" option; never read by the resume path, and never a rule by itself
+     *  (minting one goes through the approval-record protocol). Absent when no rule lane is armed or the
+     *  command is one the lane cannot speak for. */
     ruleSuggestions?: readonly import("./permission-rule-model.js").RuleSuggestion[];
+    /**
+     * design/80 D-1 §2 (slice 1a.2): the server-minted **opaque** boundInputHash of {@link args} — a
+     * SHA-256 (hex) via {@link import("./canonical-json.js").boundInputHashOf}, computed ONCE here at
+     * suspend-mint and persisted on the row. The operator sees it (surfaced on the pending record) and
+     * echoes it back as {@link ResumeOutcome} `boundInputHash`; the resume verifies opaque string equality
+     * against THIS value (never re-serializing the args — see the field's doc). Absent only on a legacy
+     * pre-1a.2 checkpoint (deserialized without it), in which case the resume skips the hash check.
+     */
     boundInputHash: string;
+    /** All tool-call ids in the suspending assistant message, in emission order. */
     batchToolCallIds: string[];
+    /** Ids of calls already executed (results in the session) when the suspend fired — #1..k-1. */
     completedCallIds: string[];
-} | {
+}
+/** design/74: suspended at a resource slice boundary — there is NO pending tool to resolve. Consumers
+ *  that read the tool-approval fields above MUST branch on `kind` first (this arm has none). */
+ | {
     kind: "resource_limit";
     reason: ResourceLimitReason;
-} | {
+}
+/** design/80 D-B (r3 — an EXPLICIT arm, NOT a reused `resource_limit` placeholder): paused at a PRE-ACTION
+ *  PLAN REVIEW (`CheckpointGate.kind === "plan_review"`). There is NO pending tool to resolve — the human
+ *  reviews the PLAN, not a tool call — so this arm has no tool fields. Every consumer that reads the
+ *  `tool_approval` fields above MUST branch on `kind` FIRST: a `plan_review` checkpoint must never flow into
+ *  a `resource_limit`- or `tool_approval`-shaped continuation (a contract test pins this). The plan artifact
+ *  is a PROFILE concern (a REF — design/76 §9); core stores no plan here. */
+ | {
     kind: "plan_review";
-} | {
+}
+/** design/144 §3 (X2) — the NON-GATE arm: nothing pends a decision. The shape of a deployment-minted
+ *  PARK checkpoint (approval-timeout park / pure suspend; paired with `gate.kind === "task_done"`, the
+ *  non-gate gate arm) and of a 1C `task_done` handle row. It is the ONLY pendingAction kind the `wake`
+ *  resume entry accepts — every other kind above is a pending GATE decision, and the wake gate rejects
+ *  it (`wake.gate_pending`) via an EXHAUSTIVE switch (a future kind added here without classifying it
+ *  there is a compile error, and an unknown kind on a deserialized row fails closed at runtime). Core
+ *  never mints this arm itself (the park convention is the deployment half); the pre-existing doc
+ *  references to "a task_done pendingAction" (`getCheckpointSummary` et al.) name exactly this shape. */
+ | {
     kind: "task_done";
 };
+/**
+ * The per-task correctness state a checkpoint must carry so a resumed task runs in the **same state
+ * space** it suspended in (§4.bis, the jury head must-fix). An **explicit whitelist** of serializable
+ * correctness fields — never a blind `JSON.stringify(Prepared)`, which would silently corrupt the 9+
+ * non-serializable runtime objects (`harness`/`session`/`abortController`…) it holds (round-2 BUG#1).
+ *
+ * Round-trip fidelity of every field is covered by tests; runtime objects are **forbidden** here.
+ * `cacheFingerprint` (design/31) is deliberately **excluded** — it is observation-only, so resume just
+ * suppresses cache-break detection on the first turn rather than persisting it as correctness state.
+ */
 export interface CheckpointState {
+    /** design/36: deferred-tool activation set — else resume re-discloses / diverges from history. */
     activeTools: string[];
+    /** 1.41 submit_output: the validated structured output set pre-suspend, else it's lost on resume. */
     outputRef?: {
         value?: unknown;
         set?: boolean;
     };
+    /** design/38: nested sub-agent cumulative cost — else pre-suspend child cost evaporates (§4.bis/Q7). */
     nestedStats: NestedUsageAccum;
+    /** design/41: consolidation notes collected pre-suspend — else the task-end pass loses them. */
     consolidationNotes?: ConsolidationNote[];
+    /** design/44: the hand's read-file state (content hashes), serialized from the hands-toolkit closure
+     *  (NOT part of Prepared — §15.2 net-add #8). Without it a resumed `edit_file` is rejected "not read". */
     readFileState?: Array<[string, ReadEntry]>;
+    /**
+     * design/78 Slice-1: the SAFE-tier self-repair loop's durable state (`failureTrace`/`diagnostics`/
+     * `rejectedHypotheses`/`attemptCount`/`oracleTier` — all JSON/`structuredClone`-safe, no fn/Date). Set ONLY
+     * when an orthogonal durable suspend (resource/HITL) interleaves a `runRepairLoop` run — the happy path is
+     * in-memory only. On resume it re-seeds `RepairLoopConfig.resumeBundle` so `attemptCount` advances
+     * MONOTONICALLY (never reset). `baselinePassTests` is deliberately NOT carried here (grader-computed
+     * out-of-process — a worker must not be able to shrink the ratchet). Absent for a run with no repair loop.
+     */
     repairBundle?: RepairBundle;
+    /**
+     * design/49 v1.5: the remote workspace's serializable identity (E2B sandbox id / provider / mount path /
+     * snapshot id). Set ONLY when the suspended task ran with a remote, suspendable {@link WorkspaceHandle}
+     * (a per-task `executionEnvFactory` env that was `suspendVM()`-paused rather than destroyed). Resume
+     * rebuilds the env via the factory and `resumeVM(snapshotId)` so the restored workspace matches the
+     * `readFileState` above. All-string fields → JSON/`structuredClone` round-trips safely (consistent with
+     * this whitelist's "no runtime objects" rule). Absent for a process-local (non-remote) suspend.
+     */
     workspaceHandle?: WorkspaceHandle;
+    /**
+     * design/80 D-A: a durable mid-task STEER for a DURABLY-SUSPENDED task. Live `TaskStream.steer`
+     * (runtask.ts) is unreachable while the harness is idle (durably suspended), so a human supervisor's
+     * guidance is parked HERE via {@link CheckpointStore.setPendingSteer} and injected on resume (runtask.ts,
+     * after the resume-continuation prompt). It is GUIDANCE ONLY — never an approval channel (§3 inv #4) and
+     * never parsed into control state (§3 inv #5); a budget/autonomy/gate-threshold is CONFIG, not steer text.
+     *
+     * `trusted` is FROZEN at `setPendingSteer` from the SERVICE's verified-principal check (an operator-role
+     * check, NOT a client header — the service's job, out of scope here) and NEVER recomputed on resume
+     * (§3 inv #1). On resume a `trusted:false` steer reaches the model as a PLAIN user message with NO
+     * `<system-reminder>` wrapper (no authority laundering, §3 inv #3); a `trusted:true` steer MAY ride the
+     * reminder (`formatHookFeedback`, mirroring the live trusted branch). `text` containing `</system-reminder>`
+     * is REJECTED at `setPendingSteer` (typed `steering.invalid_content`) so a dirty steer never enters this
+     * state (§3 inv #2); the untrusted-injection path ALSO sanitizes the text as untrusted data, belt-and-braces.
+     * Absent when no steer is pending. All-string fields → JSON/`structuredClone` round-trips safely.
+     *
+     * **Delivery is BEST-EFFORT, at-most-meaningfully-once (review-council, by design):** a steer is GUIDANCE,
+     * not a correctness-critical message, so the delivery guarantee is intentionally loose:
+     *  - It rides EVERY resume of THIS checkpoint that runs a turn — including a faithful `env_failed`/
+     *    `tool_unavailable` reopen→re-resume, which re-shows the guidance (coherent with the reopen REPLAYING the
+     *    leg; the model re-does the work, re-seeing the steer). It is NOT carried onto a NEW re-suspend checkpoint
+     *    (serializeCheckpointState stamps `undefined`) — a supervisor steers the new checkpoint afresh.
+     *  - It is DROPPED (never delivered) on a resume that runs no turn (an exhausted-budget resume) or that is
+     *    set in the get→resolve race window of an in-flight resume — both rare; the run is ending or the steer
+     *    just missed its train. A supervisor re-issues `setPendingSteer` if a steer didn't land.
+     *  A precise exactly-once delivery would need clearing the steer from the persisted row on consume (a reopen
+     *  clear + a get→resolve interlock); deferred as not worth the cross-backend complexity for guidance text.
+     *
+     * **Superseded by {@link CheckpointState.pendingSteerQueue} (design/171 §5.3).** New writes go to the
+     * queue; this seat remains ONLY so rows written before the queue existed keep delivering their parked
+     * steer. Never read it directly — {@link readPendingSteerQueue} is the single read point that folds
+     * this legacy seat in as queue member 0.
+     */
     pendingSteer?: {
         text: string;
         trusted: boolean;
     };
+    /**
+     * design/171 §5.3 — the BOUNDED, ORDERED queue of parked operator steers, drained in `seq` order on
+     * resume with every entry framed under its own trust semantics.
+     *
+     * It replaces the single {@link CheckpointState.pendingSteer} seat, whose last-writer-wins overwrite
+     * meant two people steering one suspended run silently destroyed the first instruction — and destroyed
+     * it with no attribution, so nobody could tell afterwards that anything was lost.
+     *
+     * Bounds are fail-loud, never lossy: {@link MAX_PENDING_STEER_ENTRIES} entries and
+     * {@link PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES} serialized bytes, whichever binds first, reject the
+     * APPEND with `steering.queue_full` rather than evicting an already-accepted instruction.
+     *
+     * Absent when nothing is parked. A row may legally carry BOTH this and the legacy seat (a pre-queue
+     * suspend that was steered again after the upgrade); the read helper orders the legacy seat first.
+     */
     pendingSteerQueue?: PendingSteerEntry[];
+    /**
+     * SR-7 (CC 2.1.198 orphaned-background-task notice: F6c pretty.js:698391-698398, resume leg
+     * :707384-707399 under the `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` gate — the cloud-worker restart
+     * leg, exactly sema's durable-resume shape): the background tasks (pending/running, this run's
+     * owner triple) still ALIVE at suspend. Background processes never survive a suspend (design/103
+     * §3.7 unconditional dispose + 飞轮 [506]③ killed receipts), so on resume any snapshot entry NOT
+     * alive in the resume leg's registry is an ORPHAN — aggregated into ONE CC-verbatim "The container
+     * was restarted…" reminder appended to the resume continuation (single message: header +
+     * `- description (task id)` list + re-create instruction; never a per-task barrage). A survivor
+     * (session-resident shell / in-window monitor) is excluded — still reachable via TaskOutput/
+     * TaskStop, it needs no obituary. CC's per-orphan `Ku(task_id,"stopped")` status write (:707399)
+     * is N/A here: the suspend teardown already settled them killed with receipts. Absent for a run
+     * with no live background tasks at suspend, and for pre-1.262 checkpoints (deserialized without
+     * the field) — both resume silently, exactly like CC with an empty list.
+     */
     runningBackgroundTasks?: Array<{
         id: string;
         description?: string;
     }>;
+    /**
+     * codex 终审 1.255 F2: the hands band's LOGICAL working directory at suspend (`handsCwdRef.current` —
+     * moved by `cd` and by EnterWorktree). Without it a resume silently reset the task cwd to the task root:
+     * relative Read/Edit/Write paths and Bash commands then operated somewhere else than the model believes.
+     * Absent when the task has no tracked cwd (no real shell / read-only hands). The directory itself is
+     * plain on-disk state that survives a process-local suspend (worktrees included — the tree stays on disk).
+     */
     handsCwd?: string;
+    /**
+     * codex 终审 1.255 F2: the ACTIVE EnterWorktree session at suspend (worktree.ts keeps it in a shared
+     * serializable ref, not a closure-only var, precisely so it lands here). Without it a resume LOST the
+     * session: ExitWorktree became a no-op (the unchanged worktree could never be removed), a second
+     * EnterWorktree was wrongly accepted, and `handsCwd` pointed into a worktree the tooling no longer
+     * owned. All-string fields; the worktree directory survives the suspend on disk (managed under the
+     * task root, `git worktree` metadata intact).
+     */
     activeWorktree?: ActiveWorktreeSession;
+    /**
+     * Parent effective-policy inheritance (tighten-only): the durable projection of the run's
+     * {@link import("./runner/prepare-task.js").InheritedGate}. Only the serializable DATA half persists —
+     * `ancestorRules` (each ancestor's session-rule snapshot: sessionId/principal/rev/rules, re-compiled on
+     * resume against the resumed leg's env) and `shellGate` (the chain's max-rank shell doctrine). The OPAQUE
+     * half (`parentConstraints` — live ToolPolicy/onAsk closures) CANNOT persist; `requiresParentConstraint`
+     * records only its PRESENCE, so the resume pre-CAS ladder can fail-loud (`resume.parent_constraint_missing`,
+     * checkpoint stays `pending`) when the resuming caller did not re-supply the closures via
+     * `resumeStream(..., internals)`. Absent for a task that inherited nothing (pre-1.294 checkpoints included)
+     * — distinguishable from `requiresParentConstraint: false` with data-only inheritance, which resumes
+     * without any re-supplied internals. All-data fields → JSON/`structuredClone` round-trips safely.
+     */
     inheritedGate?: {
         ancestorRules?: ReadonlyArray<{
             sessionId: string;
@@ -166,36 +739,174 @@ export interface CheckpointState {
             rules: SessionPermissionRules;
         }>;
         shellGate?: "off" | "always" | "classify";
+        /** Org-memory admission freeze (ruled 2026-08-05): the chain's admitted org-scope set at
+         *  suspend (data half, plain strings). The resume leg folds it seed ∩ live (tighten-only) and
+         *  re-runs admission under it — a resume must never widen the delegation freeze. Absent on
+         *  older checkpoints ⇒ the live channel (or, for a delegated child, the fail-closed ∅) stands.
+         *  Cross-VERSION enforcement (an older worker resuming a newer checkpoint ignores fields it
+         *  does not know) is the deployment's server/core version-gate concern, not a per-field fence. */
         admittedOrgScopes?: readonly string[];
+        /** THIS task's OWN admitted org verdict at suspend (adversarial-review adoption, 2026-08-05):
+         *  distinct from {@link admittedOrgScopes} (the incoming PARENT constraint). The resume leg
+         *  applies it as the SESSION freeze on the final admitted projection — regardless of origin
+         *  (deployment-origin scopes bypass the chain freeze, never the session freeze) — so a session's
+         *  verdict can only NARROW across suspend/resume: re-adjudication still runs every leg (a
+         *  revoked grant refuses the resume), but a policy widened mid-session cannot widen THIS
+         *  session's mount or the chain its children inherit. Present (possibly EMPTY — an adjudicated
+         *  empty verdict is not "org-less") iff the suspend leg adjudicated an org plane; absent on
+         *  older checkpoints / org-less tasks. Checkpoints carrying this state are stamped
+         *  {@link ORG_ADMISSION_CHECKPOINT_VERSION} so a pre-admission worker rejects them pre-CAS. */
         ownAdmittedOrgScopes?: readonly string[];
+        /** The WRITE half of the session freeze: the org write grant this session held at suspend —
+         *  `null` = the org write face was read-only (a resume must not gain write authority the
+         *  suspend leg did not hold); a scope string = the explicit grant. Present iff
+         *  {@link ownAdmittedOrgScopes} is (same adjudication record). */
         ownAdmittedOrgWriteScope?: string | null;
+        /** The MONOTONIC org-governance provenance bit (adversarial round 5): `true` when any leg of
+         *  the suspended tree ran with an org-admission surface (or inherited the bit). A resume worker
+         *  missing the surface still treats the leg as governed — org-shaped scopes respelled outside
+         *  the v2 contract are refused, even when every admitted set en route was EMPTY. Absent on
+         *  trees that never had a governance surface. */
         orgAdmissionGoverned?: true;
         requiresParentConstraint: boolean;
+        /** How many opaque parent constraints the suspended leg ran under (present iff `requiresParentConstraint`).
+         *  The resume pre-CAS ladder rejects a re-supply whose `parentConstraints.length` differs
+         *  (`resume.parent_constraint_mismatch`) — a partial re-supply is a typed error, never a silently
+         *  thinner chain. Absent on older checkpoints ⇒ only the non-empty check applies. */
         parentConstraintCount?: number;
     };
+    /**
+     * [c209-C] Q5 — the listing frames' announced NAME-SETS at suspend (agent types / skills the model
+     * has actually been shown this run, committed on first-frame delivery or intact boundary survival).
+     * A resume leg seeds its producers from these names and DIFFS the current roster/skill set against
+     * them, so cross-leg drift (config-center roster change between suspend and resume) is announced as
+     * a delta frame at the first boundary instead of silently swallowed — the exact event the listing
+     * eviction from the cached prefix exists to serve. Names only, never contents (a description change
+     * on a surviving name is deliberately not re-announced — name-keyed diff, agent_listing parity).
+     * Schema ADDITION (backward-compatible, B-5): an older checkpoint without the field resumes via the
+     * MED-3② transcript probe (delivered ⇒ seeded as the CURRENT entries, drift undetectable there;
+     * not found ⇒ full re-announce at the first boundary — conservative direction preserved).
+     *
+     * [c209-C] R2 C7 — `models`: the model CATALOG names announced (the agent_listing initial frame's
+     * "Models available for the 'model' parameter:" tail, Q4). The resume seed feeds it to the
+     * producer; a differing current catalog ⇒ the first boundary's agent_listing frame re-carries the
+     * full line — without this a catalog swap between legs was never re-disclosed anywhere (the
+     * catalog left the tool description with Q4). Absent (older checkpoint / never announced) ⇒ drift
+     * undetectable, silent (conservative, same B-5 direction).
+     */
     announcedListings?: {
         agents?: string[];
         skills?: string[];
         models?: string[];
     };
 }
+/**
+ * {@link CheckpointState} with **every** field made required-PRESENT, while each value keeps its original
+ * type (so an absent optional field is still passed explicitly as `undefined`). The suspend-side
+ * serialization builds `state` as this type (design/45 P3 / design/51 §P3): adding a new per-task
+ * correctness field to {@link CheckpointState} is then a **compile error** at the serialization site until
+ * it is explicitly handled — it can never be silently omitted and lost on resume. (Keying off
+ * `keyof Required<…>` makes the mapped type non-homomorphic, so it forces presence of every key yet leaves
+ * each value's `| undefined` intact — `workspaceHandle: undefined` for a process-local suspend still
+ * type-checks.)
+ */
 export type SerializedCheckpointState = {
     [K in keyof Required<CheckpointState>]: CheckpointState[K];
 };
+/**
+ * The BASELINE {@link Checkpoint} schema version (design/49 §3, code-ready council round-2): the
+ * shape a plain human-approval suspend carried before any feature raised the format. It is NOT the highest
+ * a resume accepts — that is {@link MAX_SUPPORTED_CHECKPOINT_VERSION}, which the per-feature stamps
+ * (RESOURCE / BINDING / TOKEN / ORG_ADMISSION) have each raised on their own, deliberately without moving
+ * this constant. Resume stays forward-compatible by `<=` against MAX, never `===`. Every live mint site
+ * stamps one of the feature versions, so nothing in-tree produces this value today; it is kept as the
+ * floor of the version ladder and as the reading for a row written before any feature raised the format.
+ */
 export declare const CURRENT_CHECKPOINT_VERSION = 1;
+/** design/74 R3-B: the schema version a `resource_limit` suspend stamps (v2 — it adds `resourceLedger` and a
+ *  `resource_limit` `pendingAction`/`gate` an old worker can't handle). An old worker (`MAX_SUPPORTED`=1)
+ *  rejects it pre-CAS (stays `pending`, retryable on a new worker). */
 export declare const RESOURCE_CHECKPOINT_VERSION = 2;
+/**
+ * design/80 D-1 (version-skew downgrade fix): the schema version a **binding-bearing** human/irreversible_ask
+ * `tool_approval` suspend stamps. These checkpoints carry the decision-action binding (`boundCallId` +
+ * `boundInputHash`) whose enforcement lives ENTIRELY in the resuming worker's resume path. A pre-D-1 worker
+ * (released 1.100.0: `MAX_SUPPORTED`=2, and its resume code has ZERO binding logic) would otherwise resume a
+ * D-1-minted v1 checkpoint and execute the pending tool with NO decision-action verification — the exact
+ * "approve vendor-A $5 → execute vendor-B $5000" bypass the binding exists to prevent (council BLOCKER #1).
+ * Stamping these at **v3 (> the old worker's MAX of 2)** forces a pre-D-1 worker to reject them PRE-CAS
+ * (`unsupported_version`, stays `pending`, retried on a binding-enforcing worker) instead of silently voiding
+ * the binding. A resource_limit suspend keeps stamping v2; a pre-binding (legacy 1.100.0) checkpoint is v1.
+ */
 export declare const BINDING_CHECKPOINT_VERSION = 3;
+/**
+ * design/164 (the BINDING_CHECKPOINT_VERSION precedent replayed a third time): the schema version a suspend
+ * stamps when its ledger CARRIES a cross-slice TOKEN allocation (`resourceLedger.totalTokens` set). The
+ * enforcement — window clamp against the remaining allocation, exhausted-resume fail-fast — lives ENTIRELY
+ * in the resuming worker, so a pre-164 worker (MAX_SUPPORTED=4) would accept the row, ignore
+ * `spentTokens` as a bound, and grant a fresh full window. Stamping v5 forces it to reject PRE-CAS
+ * (`unsupported_version`, stays `pending`, retried on an enforcing worker). A ledger with NO token total
+ * keeps the historic stamps (v2 resource / v3 binding) — deployments not using it see zero version movement.
+ *
+ * v4 (the retired wall-clock total) is deliberately NOT reused: this worker still READS v4 rows, and one
+ * whose ledger carries the retired axis is refused with its own typed code (see
+ * {@link CheckpointError} `checkpoint.walltime_axis_retired`) instead of silently resuming under a bound
+ * nobody enforces any more.
+ */
 export declare const TOKEN_CHECKPOINT_VERSION = 5;
+/**
+ * Org-memory admission state (adversarial round 2, 2026-08-05 — the BINDING_CHECKPOINT_VERSION
+ * precedent replayed a fourth time): the schema version a suspend stamps when its state carries
+ * org-admission freeze fields (`inheritedGate.admittedOrgScopes` / `ownAdmittedOrgScopes` /
+ * `ownAdmittedOrgWriteScope` — the adjudicated-empty record included). The enforcement — the
+ * session/delegation freeze on resume, the tenant-admission door itself — lives ENTIRELY in the
+ * resuming worker, so a pre-admission worker (MAX_SUPPORTED=5) would accept the row, ignore the
+ * freeze fields, and remount the raw org scopes with no admission at all. Stamping v6 forces it to
+ * reject PRE-CAS (`unsupported_version`, stays `pending`, retried on an enforcing worker). A
+ * checkpoint with NO org-admission state keeps the historic stamps — deployments not using org
+ * memory see zero version movement.
+ */
 export declare const ORG_ADMISSION_CHECKPOINT_VERSION = 6;
+/** The highest {@link Checkpoint.version} `runner.resume` will act on; a higher one is rejected pre-CAS with
+ *  {@link CheckpointError} `unsupported_version` (the checkpoint stays `pending`, retryable on a newer worker).
+ *  Raised to 6 for org-admission-bearing checkpoints — this worker reads v1 (legacy human), v2
+ *  (resource), v3 (binding human/irreversible_ask), v4 (a pre-164 row, refused only when it carries the
+ *  retired wall-clock allocation), v5 (token-allocation-bearing resource/approval) and v6
+ *  (org-admission freeze state). */
 export declare const MAX_SUPPORTED_CHECKPOINT_VERSION = 6;
+/**
+ * Read a checkpoint's schema version, defaulting an absent field to **legacy `0`** (a 1.67-era checkpoint
+ * written before the field existed — it carries no `workspaceHandle`, so resuming it the v1 way is safe).
+ * Compare with `<= MAX_SUPPORTED_CHECKPOINT_VERSION`, never `=== CURRENT_CHECKPOINT_VERSION` (design/49 §3).
+ */
 export declare function checkpointVersionOf(cp: Pick<Checkpoint, "version">): number;
+/**
+ * design/74 R3-B: cross-slice resource accounting carried by a `resource_limit` {@link Checkpoint}. The
+ * total budget is the human's allocation; `spent*` accumulate across the resume→re-suspend chain (debited
+ * at each suspend's `put`). A resumed slice's effective `maxCostUsd` = `min(window, totalBudgetMicroUsd -
+ * spentMicroUsd)`; the final {@link TaskResult} stats aggregate `spent* + this slice's stats` so a
+ * multi-slice run reports the whole, not just the last segment. Lives ON the checkpoint row so one
+ * `resolve`/`put` CAS covers status + ledger atomically (no cross-store split).
+ */
 export interface ResourceLedger {
+    /** The human's total $ allocation in micro-USD; `undefined` = no $ ceiling (only window/walltime bound). */
     totalBudgetMicroUsd?: number;
+    /** design/164 — the human's total TOKEN allocation across the whole resume→re-suspend chain;
+     *  `undefined` = no token ceiling (only the per-slice window binds). Replaces the retired wall-clock
+     *  total: tokens are additive across processes, wall-clock across a suspend chain is not. */
     totalTokens?: number;
+    /** Cumulative cost across all slices so far (micro-USD), debited at each suspend's `put`. */
     spentMicroUsd: number;
+    /** Cumulative tokens across all slices so far. */
     spentTokens: number;
+    /** Cumulative turns across all slices so far. */
     spentTurns: number;
+    /** Cumulative wall-clock across all slices so far (ms; each slice measured on the monotonic clock).
+     *  design/164: PURE ACCOUNTING — it is no longer a gate on anything (the wall-clock resource axis
+     *  retired). Kept because "how long did this chain actually run" is a real observability question.
+     *  Absent on checkpoints written before it existed; readers treat missing as 0. */
     spentWalltimeMs?: number;
+    /** How many slices have run so far (the resource chain's suspend count). */
     sliceCount: number;
 }
 export declare function debitLedger(prior: ResourceLedger | undefined, slice: {
@@ -209,34 +920,180 @@ export declare function debitLedger(prior: ResourceLedger | undefined, slice: {
 }, opts?: {
     countSlice?: boolean;
 }): ResourceLedger;
+/** design/74 Slice 4: the $ budget (micro-USD) the NEXT slice may still spend = `totalBudgetMicroUsd -
+ *  spentMicroUsd`, never negative. `undefined` when no total $ ceiling is set (the run is bounded only by the
+ *  per-slice window / walltime). A resumed slice's effective `maxCostUsd` is `min(window, this)`. NB: `0` is a
+ *  VALID, exhausted ceiling — NOT "unlimited" (only `undefined` is unlimited). Any spend then immediately trips
+ *  `overBudget`, and the run loop fails an exhausted resume fast (runtask). Never falsy-test this value (a
+ *  `if (remaining)` would skip a legitimate 0 ceiling and silently bypass the budget). */
 export declare function remainingBudgetMicroUsd(ledger: ResourceLedger | undefined): number | undefined;
+/** design/164 (the TOKEN sibling of {@link remainingBudgetMicroUsd}): tokens the NEXT slice may still
+ *  spend = `totalTokens − spentTokens`, never negative. `undefined` when no token total is set (the run is
+ *  bounded only by the per-slice window / the $ axis). A resumed slice's effective `limits.maxTokens` is
+ *  `min(window, this)` — a resume can't refresh the allocation. NB: `0` is a VALID, exhausted ceiling
+ *  (only `undefined` is unlimited); the run loop fails an exhausted resume fast — never falsy-test it. */
 export declare function remainingTokens(ledger: ResourceLedger | undefined): number | undefined;
+/**
+ * design/80 D-1 (reopen-by-reason + persist-winner): the WINNING resume binding, recorded ON the
+ * checkpoint row the moment a {@link CheckpointStore.resolve} CAS wins (pending → resolved). It is the
+ * durable record of "which decision was approved against which pending action" so a later reopen→re-resume
+ * can be validated against it. A `policy_ask` resolve and BOTH review-gate resolves record a winner: only
+ * `policy_ask` is bound to a specific pending tool call, while `plan_review` / `dry_run_review` record
+ * their decision under the synthetic `gate:<kind>` marker instead (RB-64). A `resource_limit` / `wake` /
+ * `task_done` resolve records none (there is no decision to bind). `boundInputHash` (binding the exact executed bytes) is a SEPARATE
+ * later D-1 slice (1a.2) and is deliberately NOT part of this winner.
+ */
 export interface ResolvedOutcome {
+    /** The pending tool call this decision was bound to (design/80 D-1 slice 1a). RB-64: a REVIEW gate binds
+     *  no tool call, so it records the synthetic `gate:<kind>` marker instead — the replay guard compares the
+     *  DECISION for those, never a call id. */
     boundCallId: string;
+    /** The adjudication the operator made. RB-64 widens this to the review verdicts (`approve`/`reject`/
+     *  `edit`) so a `plan_review`/`dry_run_review` winner can be persisted and replayed by the same
+     *  env_failed reopen guard the approval gate has — previously review gates recorded NO winner, which is
+     *  what left their reopen path with nothing to check a re-vote against. */
     decision: "allow" | "deny" | "approve" | "reject" | "edit";
+    /** A re-written arg payload, if the `allow` rewrote the call (design/37). Carried so an `env_failed`
+     *  re-resume (a system retry of the SAME approved action) must replay the identical `updatedInput`. */
     updatedInput?: unknown;
+    /** The content-ask ANSWER the `allow` carried, if any (ruled 2026-08-04). Recorded for the same reason
+     *  `updatedInput` is: the answer is the SUBSTANCE of a content-ask decision, not a decoration on it, so
+     *  an `env_failed` re-resume — a system retry of the already-approved action — must replay the identical
+     *  answer. Without it the replay could keep the verdict and swap the answer text going into the model's
+     *  context (the shape the plan-edit replay guard closed for `editedPlan`). Omitted when absent so the
+     *  replay equality check does not falsely diverge on `undefined`. */
     answer?: QuestionAnswer;
+    /** The operator's NOTE, if the decision carried one — the approval lane's deny `reason` and the review
+     *  lanes' reject `reason` alike. Recorded for the same reason `updatedInput` and `answer` are: the note
+     *  is the substance of the decision, not a decoration on it. It is the text the resume continuation
+     *  fences into the model-facing reminder that steers the re-plan, so a replay keeping the verdict and
+     *  swapping the note delivers a different instruction under the same word. Omitted when absent.
+     *
+     *  ADDITIVE and OPTIONAL by contract: rows persisted before this field existed carry no `reason` key,
+     *  and the key's absence is read as "this dimension was never recorded" — the replay guard skips it —
+     *  NEVER as "recorded as empty", which would refuse every legitimate retry of an existing row. Absence
+     *  is therefore indistinguishable from a genuinely note-less decision, which is the accepted price of
+     *  the additive shape: the binding starts with the rows that record it.
+     *
+     *  RECORDED VERBATIM, and independently of the verdict: any supplied note is kept exactly as given —
+     *  including `""`, and including a note on a verdict that never relays one (an `allow`, an `approve`, an
+     *  `edit`). The winner is a record of the decision that was made, not of the subset of it the
+     *  continuation happens to render, and `updatedInput` has carried the same property since D-1 (a rewrite
+     *  on a `deny` is recorded and replay-compared although nothing executes it). Normalizing here would
+     *  mean an empty note collapsed into the "never recorded" hole above and a note on a non-relaying
+     *  verdict became free to change between the resolve and its replay — both weaken "the retry presents
+     *  the same decision" for no delivery benefit, since a replay is produced by re-presenting the same
+     *  outcome, not by reconstructing an equivalent one. */
     reason?: string;
 }
+/**
+ * design/80 D-1: why a consumed checkpoint was {@link CheckpointStore.reopen | reopened} (resolved →
+ * pending). The reason drives re-resume validation (§3 invariant #1): an `env_failed` reopen is a SYSTEM
+ * RETRY of the ALREADY-APPROVED action — the re-resume MUST replay the persisted {@link ResolvedOutcome}
+ * winner, never a new vote — while a `tool_unavailable` reopen (the action could not run, may now be
+ * invalid — P-7) lets a human RE-DECIDE with the tool present, so a fresh operator decision IS allowed.
+ */
 export type ReopenReason = "env_failed" | "tool_unavailable";
+/**
+ * design/80 D-1 (atomicity fix): the optimistic-concurrency precondition a {@link CheckpointStore.resolve}
+ * caller passes so its CAS is atomic with the validation it did against an earlier `get()` snapshot. The
+ * resume-side decision-action guards (boundCallId/boundInputHash) bind to per-token-IMMUTABLE fields, but the
+ * **reopen-by-reason** guard reads `reopenReason` + `resolvedOutcome` — which a concurrent
+ * {@link CheckpointStore.reopen}/{@link CheckpointStore.resolve} cycle mutates. Passing the monotonic
+ * {@link Checkpoint.rev} the caller observed makes `resolve` additionally require the LIVE row's `rev` to still
+ * equal it; ANY intervening resolve/reopen bumps `rev`, so a cycle in the get→resolve window loses the CAS
+ * (fail-closed), forcing a re-`get` + re-validate.
+ *
+ * **Why a counter, not the reopenReason value (round-2 BLOCKER fix):** `reopenReason` is a 2-valued enum, so a
+ * full `env_failed`→`tool_unavailable`→`env_failed` cycle (the `tool_unavailable` arm permits a fresh P-7
+ * re-decision) returns `reopenReason` to the SAME value while `resolvedOutcome` silently changed to a different
+ * (e.g. RETRACTED) winner — a classic ABA on the OCC key. A monotonic `rev` bumped on every resolve/reopen is
+ * ABA-proof: a returned-to-the-same-value `reopenReason` still has a strictly higher `rev`. Omit `expect`
+ * (legacy callers / direct store tests) → no OCC.
+ */
 export interface ResolveExpectation {
+    /** The monotonic {@link Checkpoint.rev} the caller observed at `get()` (absent rev ⇒ legacy `0`). */
     rev: number;
 }
+/** A persisted suspension point: enough to resume a task on any replica. `status` drives the 3-state
+ *  machine (pending → resolved | expired) that makes resume idempotent (§5). */
 export interface Checkpoint {
     token: CheckpointToken;
+    /**
+     * Schema version of this checkpoint (design/49 v1.5). Every live suspend stamps the version of the
+     * FEATURE it carries (RESOURCE / BINDING / TOKEN / ORG_ADMISSION); {@link CURRENT_CHECKPOINT_VERSION}
+     * is the baseline at the bottom of that ladder, not the stamp of any current mint site.
+     * absent ⇒ legacy `0` (1.67-era, no `state.workspaceHandle`). Resume rejects `> MAX_SUPPORTED_CHECKPOINT_VERSION`
+     * pre-CAS so an old worker can't silently ignore fields a newer format relies on (forward-compatible by `<=`).
+     * Read via {@link checkpointVersionOf}.
+     */
     version?: number;
+    /** Multi-tenant isolation key (forced through `resolve`/`reap` WHERE, §2.1 service [4]). */
     scope: string;
+    /** The session to resume (via the SessionStore). */
     sessionId: string;
+    /** The session leaf the suspend happened at — the resume point (CAS write base, §5). */
     leafId: string;
     gate: CheckpointGate;
     pendingAction: PendingAction;
     state: CheckpointState;
+    /** design/74 R3-B: cross-slice resource accounting. Present for a `resource_limit` gate (debited at the
+     *  suspend's `put`; read on resume to size the next slice + aggregate the final stats). **design/80 D-E-core
+     *  (A3):** ALSO attached to a human/irreversible_ask APPROVAL suspend — debited with that leg's spend — so a
+     *  STATELESS policy can read durable cumulative spend across the resume chain via {@link ToolCallRequest.budget}
+     *  (a fresh in-memory counter would reset every leg). On the approval path it is READ-CONTEXT ONLY: the final
+     *  -stats aggregate fold (runtask) is gated to the `resource_limit` gate kind, so an approval resume is never
+     *  double-counted. Absent for `task_done`. See {@link ResourceLedger}. */
     resourceLedger?: ResourceLedger;
+    /**
+     * Absolute epoch-ms deadline for an awaiting-human checkpoint; past it, `reap` expires it (§6).
+     *
+     * **design/80 §D-D semantic contract (the DURABLE FIELD a reaper-loop consumes — read it on
+     * {@link CheckpointStore} too):** for an APPROVAL gate (`gate.kind` ∈ {`human`, `irreversible_ask`}) the
+     * deployment's reaper-loop treats this as an **SLA resolve-deny** time (FACET A — its fast path: at deadline
+     * it `resolve`s the checkpoint as a `deny` so the run ends cleanly), with a LATER `terminalAt` abandonment
+     * backstop the loop ALSO honors (crash-safe if the SLA timer never fired). For an UNATTENDED-TTL gate
+     * (`gate.kind` ∈ {`resource_limit`, `needs_review`, `plan_review`} — the resource + review-pause family) this
+     * is an **abandonment-TTL** → `expire`/{@link reap} ONLY, NEVER a resolve-deny (FACET B — those kinds resume
+     * only with their OWN outcome, so a `policy_ask` resolve-deny hits no `gateMatch` arm → `gate_mismatch`). The
+     * reaper-loop + the gate.kind policy + minting `terminalAt` are the DEPLOYMENT's job
+     * (its store impl + loop — owned service-side); CORE only guarantees this `deadline`
+     * field (for `human`/`irreversible_ask`) + the persisted {@link gate}.kind survive the round-trip so any
+     * reaper consumer (the service's TiDB loop OR a non-service Pg deployment) implements the SAME contract.
+     */
     deadline?: number;
     status: "pending" | "resolved" | "expired";
     createdAt: number;
+    /**
+     * How many times THIS task has suspended, counting this checkpoint (1 = first suspend; design/72
+     * §2.2 (B)). Carried forward across resume→re-suspend (each new checkpoint = the prior count + 1), so
+     * a restart-prone model that keeps re-issuing the gated/egress call — re-suspending every resume —
+     * is capped: past `maxSuspends` the run fails (`suspend.loop`) instead of minting another checkpoint
+     * and looping forever. Absent ⇒ legacy `0` (pre-§2.2 checkpoints; treated as "no prior suspends").
+     */
     suspendCount?: number;
+    /**
+     * design/91 — the wall-clock instant (epoch ms, from {@link import("./types.js").RunnerDeps.now}) this task
+     * suspended at a HUMAN-REVIEW gate. Resume derives the human-review latency for this leg as
+     * `now() − suspendedAt` and folds it into `TaskResult.stats.humanReview` (the design/89 §2.4 C2 burden axis).
+     * The human-review family is the APPROVAL gates (`gate.kind` ∈ {`human`, `irreversible_ask`}) — core stamps
+     * this automatically on the approval-suspend mint — AND the REVIEW-PAUSE gates (`needs_review` = a dry-run
+     * diff review, `plan_review` = a pre-action PLAN review). Review-pause checkpoints are minted by a PROFILE
+     * (core owns only the routing/resume discriminants), so a profile that wants the C2 wait counted MUST stamp
+     * `suspendedAt = deps.now()` at mint — the same injectable clock the resume reads, so a test pins the latency.
+     * Absent on a `resource_limit` suspend (a machine backstop, not a human wait), on a review-pause checkpoint
+     * whose profile did not opt in, and on a legacy pre-design/91 checkpoint (⇒ resume skips the durable latency
+     * for that leg — no undercount surprise, just no entry).
+     */
     suspendedAt?: number;
+    /**
+     * design/91 — the accumulated {@link import("./types.js").TaskResult.stats}`.humanReview` from all PRIOR legs,
+     * carried forward across resume→re-suspend (like {@link suspendCount} / {@link resourceLedger}) so a
+     * multi-leg suspend/resume chain reports the WHOLE human-review burden, not just the last leg's. It holds
+     * the gates resolved up to and including the suspend BEFORE this one — the latency for THIS suspend is added
+     * by the resume that wakes it (`now() − suspendedAt`). Absent ⇒ no prior human-review time (a first suspend
+     * with no earlier synchronous asks). Budget-EXCLUDED side observable — never a cost/gate input.
+     */
     humanReview?: {
         count: number;
         totalWaitMs: number;
@@ -246,49 +1103,469 @@ export interface Checkpoint {
             decision?: string;
         }>;
     };
+    /**
+     * design/80 D-1 (persist-winner): the winning resume binding, recorded by {@link CheckpointStore.resolve}
+     * when its CAS wins (pending → resolved) — present after a `policy_ask` resolve and after either REVIEW-gate
+     * resolve (`plan_review` / `dry_run_review`, RB-64); absent on a freshly minted pending checkpoint and on
+     * `resource_limit` / `wake` / `task_done` resolves. PRESERVED (never cleared) across a
+     * {@link CheckpointStore.reopen} so an `env_failed` re-resume can be validated against it. See
+     * {@link ResolvedOutcome}.
+     */
     resolvedOutcome?: ResolvedOutcome;
+    /**
+     * design/80 D-1 (reopen-by-reason): why this checkpoint was last reopened (resolved → pending), recorded
+     * by {@link CheckpointStore.reopen}. Drives re-resume validation (§3 invariant #1): `env_failed` ⇒ the
+     * re-resume must replay the persisted {@link resolvedOutcome} winner (a system retry of the approved
+     * action); `tool_unavailable` ⇒ a fresh operator decision is allowed (P-7 re-decide with the tool
+     * present). Absent on a never-reopened checkpoint (a first resume is unconstrained by reason).
+     */
     reopenReason?: ReopenReason;
+    /**
+     * design/80 D-1 (atomicity fix, round-2 BLOCKER): a **monotonic revision counter** bumped by EVERY
+     * {@link CheckpointStore.resolve} (won) and {@link CheckpointStore.reopen}. It is the optimistic-concurrency
+     * key ({@link ResolveExpectation}): a resume reads it at `get()` and `resolve` requires the live `rev` to
+     * still equal it, so any resolve/reopen cycle landing in the get→resolve window loses the CAS (fail-closed).
+     * Unlike the 2-valued `reopenReason`, it cannot ABA back to a prior value. Absent ⇒ legacy `0` (a checkpoint
+     * minted before this field; treated as never mutated).
+     */
     rev?: number;
+    /**
+     * design S1d (source-tag persistence, service [198]/[199]): the issuing task's session id, stamped at the
+     * APPROVAL suspend mint so a supervisor inbox can attribute a paused/awaiting checkpoint to the worker that
+     * raised it (the durable analog of {@link import("./tool-policy.js").AskRequest}.sourceTaskId — the durable
+     * suspend path does NOT invoke `onAsk`, so the synchronous source identity is captured here instead). It is
+     * the SAME value the synchronous ask carries: `= sessionId` at the mint.
+     *
+     * **Security invariant (carried verbatim from the 1.113.0 ask-bubbling contract):** for a Runner-created
+     * DELEGATED subagent this is **worker-unforgeable** (a child never sets its own sessionId — the Runner mints
+     * it); a top-level caller MAY continue its own session id via {@link import("./types.js").TaskSpec.sessionId},
+     * so this is NOT a global "never forgeable" run id — aggregation only aggregates delegated workers, where it
+     * holds. **ECHO-ONLY triage metadata, NEVER a gate input:** no gate / CAS / winner / resume-validation path
+     * reads it (a contract-test pins this). Absent ⇒ no source task id (a non-ask gate, or a legacy checkpoint).
+     */
     sourceTaskId?: string;
+    /**
+     * design S1d (source-tag persistence): the issuing task's authenticated end-user {@link
+     * import("./types.js").TaskSpec.principal} (design/62), stamped at the APPROVAL suspend mint so an aggregating
+     * inbox can attribute a paused checkpoint per-user — the durable analog of {@link
+     * import("./tool-policy.js").AskRequest}.principal. Caller-set (never a tool/worker arg), and like
+     * {@link sourceTaskId} it is **ECHO-ONLY triage metadata, NEVER a gate input** (no gate/CAS/winner/resume path
+     * reads it). Absent ⇒ no principal (a non-ask gate, an unauthenticated task, or a legacy checkpoint).
+     */
     principal?: string;
+    /**
+     * design/153 §7.4 (1.389.0, RB-42②③): the VERBATIM `TaskSpec.durableApproval` opt-in in force at this
+     * APPROVAL suspend's mint — the engine-recorded provenance of "this task was durable-approval armed, with
+     * this scope and this reaper TTL". Consumed by the parked-resume drive's REVIVE-CONTINUITY re-derivation
+     * (subagent settle path): the drive spec carries no forwarding seat, so without this record a resumed leg's
+     * SECOND plain ask would headless-deny instead of re-parking. Reading it explicitly (instead of inferring
+     * the opt-in from `gate.kind === "human"`) covers a SAFETY-TIER first park (irreversible_ask — the kind
+     * alone never proved the spawn opted in) and carries `ttlMs` across the re-park so the re-minted
+     * checkpoint re-arms its reaper `deadline` (previously unbounded). Absent ⇒ the mint ran with NO
+     * `durableApproval` (an unattended safety suspend, a non-ask gate, or a legacy pre-1.389 checkpoint — the
+     * consumer then falls back to the human-kind scope-only inference for legacy rows and injects NOTHING for
+     * unattended parks, so a spawn that never opted in can never gain the opt-in through a resume). Engine-
+     * minted from the task's own spec — a worker/tool cannot forge it (`durableApproval` never rides tool args).
+     */
     durableApproval?: {
         scope: string;
         ttlMs?: number;
     };
 }
+/**
+ * design/80 assistant-scheduler seam #1: a LIGHTWEIGHT projection of one PENDING
+ * checkpoint, returned in bulk by {@link CheckpointStore.listByScope} so a supervisor scheduler can list a
+ * scope's suspended/awaiting tasks in ONE call (no N+1 `get`s, no full-{@link Checkpoint} payloads). It is a
+ * read-only DISPLAY/triage summary — every field is DERIVED from the persisted {@link Checkpoint}; nothing
+ * here is a new source of truth or a gate input.
+ */
 export interface CheckpointSummary {
+    /** The resume capability token ({@link Checkpoint.token}). */
     token: CheckpointToken;
+    /** The suspended task / session id ({@link Checkpoint.sessionId}). */
     sessionId: string;
+    /** The multi-tenant scope this checkpoint lives in ({@link Checkpoint.scope}) — always equal to the query's. */
     scope: string;
+    /** The gate's discriminant ({@link CheckpointGate}.kind): which kind of pause this is. */
     gateKind: CheckpointGate["kind"];
+    /** The deterministic risk tier (1..5) when the gate carries a {@link RiskDescriptor} (the `human` /
+     *  `irreversible_ask` approval escalations), derived via {@link riskSeverity} from the descriptor's axes —
+     *  the SAME value as `gate.riskDescriptor.severity`, recomputed from the single source helper rather than
+     *  re-stored. `undefined` for a gate with no descriptor (resource_limit / needs_review / plan_review / a
+     *  legacy human ask minted before D-E). The inbox sorts DESC by this. */
     severity?: 1 | 2 | 3 | 4 | 5;
+    /** Cumulative spend debited to this suspend chain ({@link ResourceLedger.spentMicroUsd}) in micro-USD —
+     *  present whenever the checkpoint carries a {@link Checkpoint.resourceLedger} (every resource_limit suspend,
+     *  and every approval suspend on the D-E-core budget-read path); `undefined` when no ledger is attached. */
     spentMicroUsd?: number;
+    /** The awaiting-human SLA / abandonment deadline ({@link Checkpoint.deadline}, epoch ms) when present. */
     deadline?: number;
+    /** design S1d (source-tag): the issuing worker's session id ({@link Checkpoint.sourceTaskId}) — projected so
+     *  a supervisor inbox attributes each pending checkpoint to its worker in ONE `listByScope` call (no N+1
+     *  `getCheckpoint`). ECHO-ONLY display/triage; absent on a non-ask gate / legacy checkpoint. */
     sourceTaskId?: string;
+    /** design S1d (source-tag): the issuing task's end-user principal ({@link Checkpoint.principal}) for per-user
+     *  inbox attribution. ECHO-ONLY display/triage; absent when the checkpoint carries no principal. */
     principal?: string;
+    /** The pending tool call's id ({@link PendingAction} `tool_approval.toolCallId`) when this is an approval
+     *  suspend — projected so the inbox shows WHICH call awaits a decision without an N+1 `getCheckpoint`.
+     *  `undefined` for a non-`tool_approval` pendingAction (resource_limit / plan_review / task_done).
+     *
+     *  **ABSENCE SHAPE (contract, [1995]②)** — shared by every optional field on this projection: a
+     *  tool-less park (`resource_limit` / `plan_review` / `task_done` — none of which binds a tool call)
+     *  gets the key **OMITTED**, never `null` and never a present-but-`undefined` property. The
+     *  `PendingAction` arms for those kinds declare no tool/binding fields at all, so there is nothing to
+     *  project; `summarizeCheckpoint` spreads them conditionally for exactly this reason. A consumer
+     *  therefore tests presence (`"toolCallId" in summary`), and a re-projecting service (BFF / SDK wire
+     *  face) must not materialize the keys as `null` on the way out. Pinned in
+     *  `test/checkpoint-store.test.ts` ("[1995]②③ tool-less park …"). */
     toolCallId?: string;
+    /** The pending tool's name ({@link PendingAction} `tool_approval.toolName`) when this is an approval suspend.
+     *  OMITTED (not `null`) for a non-`tool_approval` pendingAction — see {@link toolCallId}'s absence-shape note. */
     toolName?: string;
+    /** design/99 MF-14 (design-review DoR): the DERIVED content-gate classification — `"content_ask"` when this
+     *  `tool_approval` gates the reserved AskUserQuestion tool (a question TO the user, not a side-effecting tool).
+     *  A TYPED discriminant so a shell renders the question UI without sniffing `toolName` or parsing the bounded
+     *  `toolInput` preview. The full typed questions ride the drilled-in Checkpoint's `pendingAction.args` (kept off
+     *  this lightweight `listByScope` projection). Deliberately NOT a new `content_ask` checkpoint gate kind (that
+     *  would cross the durable-checkpoint once-only-winner / reaper-deadline / batch invariants — the DoR). */
     contentKind?: "content_ask";
+    /** design S1e (service [204]): when the checkpoint was created ({@link Checkpoint.createdAt}, epoch ms) —
+     *  projected so a supervisor inbox can sort/age pending entries (oldest-first triage) in ONE `listByScope`
+     *  call, no N+1 `getCheckpoint`. ECHO-ONLY display/triage; always present (a Checkpoint always has a
+     *  `createdAt`). */
     createdAt?: number;
+    /**
+     * design S1e (service [204]): a **BOUNDED, UNREDACTED** raw preview of the pending tool call's input
+     * ({@link PendingAction} `tool_approval.args` `JSON.stringify`-ed, truncated to {@link
+     * MAX_TOOL_INPUT_PREVIEW_CHARS} chars with a `…` marker when over) — projected so a supervisor inbox shows
+     * WHAT a paused tool call will do without an N+1 `getCheckpoint`. `undefined` for a non-`tool_approval`
+     * pendingAction (resource_limit / plan_review / task_done — no args to preview).
+     *
+     * **Contract (load-bearing):**
+     *  - **bounded raw preview** — length-capped to {@link MAX_TOOL_INPUT_PREVIEW_CHARS} so it cannot bloat the
+     *    `listByScope` payload, but the chars within the cap are the RAW serialized args (no folding/escaping).
+     *  - **redaction is the CONSUMER's responsibility** — core gives the inbox the unredacted bounded raw; the
+     *    service/inbox decides what (if anything) to mask before showing a human. (Contrast {@link
+     *    RiskDescriptor.summary}, which is the NEUTRALIZED+capped descriptor that DOES ride into a render —
+     *    `toolInput` is the raw-data sibling for a consumer that wants the actual args.)
+     *  - **same data as the full {@link Checkpoint}** — it is a projection of `pendingAction.args`, which the
+     *    caller could already read via `get`; this adds NO new exposure, it only saves the round-trip.
+     *  - **ECHO-ONLY, like {@link sourceTaskId}** — NO gate / CAS / resume / {@link winnerFromOutcome} path reads
+     *    it (a contract test pins this); it is pure display/triage metadata, never a control input.
+     */
     toolInput?: string;
+    /**
+     * RB-439-b — HOW this pause's remote workspace comes back, projected from
+     * `state.workspaceHandle.restoreMode` so a supervisor inbox can tell the two apart in ONE `listByScope`
+     * call. `"snapshot"` = the VM was paused into a snapshot (billing typically stops, memory state
+     * captured); `"park_only"` = a non-suspendable target (SSH host / ADB device) was never paused — the
+     * machine is still running and still costing, and resume just reconnects. OMITTED (see the
+     * {@link toolCallId} absence-shape note) for a process-local suspend, which captured no remote
+     * workspace at all. ECHO-ONLY display/triage — nothing gates on it. Mirrors `TaskResult.workspaceRestoreMode`.
+     */
     restoreMode?: "snapshot" | "park_only";
+    /** [1245] codex F2 — the tool's approval display projection ({@link PendingAction} `preview`),
+     *  projected so the ONE-CALL inbox (`listByScope`) can render a rich confirmation without an N+1
+     *  `get`. Same trust posture as `toolInput`: **UNTRUSTED, advisory display metadata** (strings are
+     *  sanitized of control chars at mint but may still carry model-authored markdown — renderers must
+     *  contextually escape), ECHO-ONLY (no gate/CAS/resume reads it), and surfaces SHOULD show the
+     *  bound raw args (`toolInput`/`pendingAction.args`) alongside — the preview never replaces them. */
     preview?: unknown;
 }
+/**
+ * design/80 assistant-scheduler seam #1: project a single PENDING {@link Checkpoint} to its lightweight
+ * {@link CheckpointSummary}. Shared by every {@link CheckpointStore} impl so the projection is IDENTICAL
+ * across the in-memory, file, and durable backends (the anti-drift guard) — `severity` always derives from the
+ * gate's {@link RiskDescriptor} via the single {@link riskSeverity} helper, `spentMicroUsd` always reads
+ * {@link ResourceLedger.spentMicroUsd}. Pure; reads no clock/random.
+ */
 export declare function summarizeCheckpoint(cp: Checkpoint): CheckpointSummary;
+/** A typed checkpoint-store error so callers branch on `code` (mirrors `SessionError`). */
 export declare class CheckpointError extends Error {
-    readonly code: "checkpoint.already_exists" | "checkpoint.already_resolved" | "checkpoint.not_found" | "checkpoint.gate_mismatch" | "checkpoint.resume_aborted" | "checkpoint.invalid_outcome" | "checkpoint.unsupported_version" | "checkpoint.walltime_axis_retired" | "checkpoint.reopen_revote" | "checkpoint.reopened_concurrently" | "checkpoint.reopen_failed" | "steering.invalid_content" | "steering.queue_full" | "steering.duplicate_input_id" | "wake.gate_pending" | "wake.nothing_to_deliver" | "resume.parent_constraint_missing" | "resume.parent_constraint_mismatch";
+    readonly code: "checkpoint.already_exists" | "checkpoint.already_resolved" | "checkpoint.not_found"
+    /** `runner.resume` was handed an {@link ResumeOutcome} whose `gate` arm does not match the
+     *  persisted {@link CheckpointGate} `kind` (council #3 — type confusion guard), or a gate v1
+     *  resume does not serve (`task_done`). */
+     | "checkpoint.gate_mismatch"
+    /** RB-77: `runner.resume` was handed an ALREADY-ABORTED `TaskSpec.signal`. Refused BEFORE the CAS, so
+     *  the checkpoint stays `pending` — this worker demonstrably cannot execute the approved action, and
+     *  consuming the human's decision on a leg that will abort immediately loses BOTH the decision and the
+     *  suspended work with nothing to reopen. Re-resume with a live signal. */
+     | "checkpoint.resume_aborted"
+    /** `runner.resume` was handed an outcome whose payload is unsafe to apply — e.g. a deny `reason`
+     *  carrying a `</system-reminder>` tag that would escape the model-facing wrapper (round-2 #1). */
+     | "checkpoint.invalid_outcome"
+    /** The checkpoint's {@link Checkpoint.version} is newer than this worker supports
+     *  (`> MAX_SUPPORTED_CHECKPOINT_VERSION`), or it carries a remote `workspaceHandle` but no
+     *  `executionEnvFactory` is wired to rebuild the env — either way this worker cannot safely resume it.
+     *  Rejected pre-CAS so the checkpoint stays `pending` and a capable worker can still resume it
+     *  (design/49 §2/§3, code-ready council round-2). */
+     | "checkpoint.unsupported_version"
+    /** design/164: the checkpoint was written by a pre-164 worker AND its ledger carries the RETIRED
+     *  cross-slice wall-clock allocation (`resourceLedger.totalWalltimeSec`). The axis no longer exists,
+     *  so resuming would run the leg with the operator's time ceiling silently unenforced. Refused
+     *  PRE-CAS (the row stays `pending`, so a worker of the previous release can still finish it) rather
+     *  than migrated: there is no honest conversion from a wall-clock allocation to a token one. */
+     | "checkpoint.walltime_axis_retired"
+    /** design/80 D-1 (reopen-by-reason): a re-resume of an `env_failed`-reopened checkpoint supplied an
+     *  outcome that does NOT equal the persisted {@link ResolvedOutcome} winner. An `env_failed` reopen is
+     *  a SYSTEM RETRY of the already-approved action (the infra failed, not the decision) — it must replay
+     *  the exact winning binding, never a new vote. Rejected pre-CAS, fail-closed, so the checkpoint stays
+     *  `pending` for the correctly-replayed retry. (A `tool_unavailable` reopen — P-7 — is exempt: it lets
+     *  a human re-decide with the tool present, so a fresh decision is permitted there.) */
+     | "checkpoint.reopen_revote"
+    /** design/80 D-1 (atomicity fix): the resume validated its decision-action / reopen-by-reason guards
+     *  against a `get()` snapshot, but a concurrent {@link CheckpointStore.resolve}/{@link CheckpointStore.reopen}
+     *  cycle advanced the monotonic {@link Checkpoint.rev} in the get→resolve window, so the
+     *  {@link CheckpointStore.resolve} CAS's optimistic-concurrency check lost (the validation is stale). The
+     *  row is still `pending` — fail-closed; the caller must re-`get` and re-validate against the CURRENT state
+     *  (a fresh resume), never blindly retry. */
+     | "checkpoint.reopened_concurrently"
+    /** A post-CAS compensation {@link CheckpointStore.reopen} returned `false` — the consumed row could not
+     *  be flipped back to `pending` (missing, expired, or changed under a concurrent cycle), so no retryable
+     *  checkpoint exists. Surfaced instead of silently treating the failed reopen as committed, so the
+     *  caller's compensation path settles the token as terminally consumed. */
+     | "checkpoint.reopen_failed"
+    /** design/80 D-A: {@link CheckpointStore.setPendingSteer} was handed `text` containing a
+     *  `</system-reminder>` close tag — it would escape the model-facing `<system-reminder>` wrapper a
+     *  trusted steer rides on resume. Rejected fail-closed so a dirty steer NEVER enters {@link CheckpointState}
+     *  (§3 inv #2). Mirrors the trusted-steer reject at runtask.ts (`steering.invalid_content`). */
+     | "steering.invalid_content"
+    /** design/171 §6.3: the append would cross the parked-steer queue's entry-count or byte bound
+     *  ({@link MAX_PENDING_STEER_ENTRIES} / {@link PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES}). Fail-loud
+     *  rather than evicting: an already-accepted operator instruction is never dropped to make room —
+     *  the caller delivers or removes a parked steer first. Nothing is written on this path. */
+     | "steering.queue_full"
+    /** design/171 §6.3 (adversarial review adoption): the append reused an `inputId` already parked on
+     *  this checkpoint, but with DIFFERENT content. Re-appending an IDENTICAL payload stays the
+     *  idempotent no-op a retry needs; a differing one is refused, because swallowing it would lose the
+     *  second operator's instruction — the exact silent loss the queue replaced. Retry with a fresh id.
+     *  Nothing is written on this path. */
+     | "steering.duplicate_input_id"
+    /** design/144 §3 (governance-gate purity, fail-closed pre-CAS): a `wake` outcome was supplied for a
+     *  checkpoint that awaits a PENDING GATE DECISION (tool approval / dry-run review / plan review /
+     *  resource-limit continue). Wake is a pure un-park verb and must never bypass an approval — resume
+     *  the checkpoint through its own decide entry instead (the error message names it). */
+     | "wake.gate_pending"
+    /** design/144 §3 (anti spin-wake): a `wake` outcome carried no `message` and the checkpoint has no
+     *  parked `pendingSteer` either — there is nothing to deliver, so the wake is rejected pre-CAS
+     *  (the checkpoint stays pending) instead of burning the token on an empty continuation. */
+     | "wake.nothing_to_deliver"
+    /** Parent effective-policy inheritance: the checkpoint records `state.inheritedGate.requiresParentConstraint`
+     *  (the suspended task ran under inherited OPAQUE parent-policy constraints — live closures that cannot
+     *  persist), but the resume supplied no `RunInternals.inheritedGate.parentConstraints` to re-instate them.
+     *  Resuming anyway would silently DROP the ancestors' gate (a widening), so this rejects pre-CAS — the
+     *  checkpoint stays `pending`; re-resume via `resumeStream(token, outcome, config, internals)` with the
+     *  parent chain re-supplied. */
+     | "resume.parent_constraint_missing"
+    /** Parent effective-policy inheritance (shape check): the resume DID re-supply
+     *  `internals.inheritedGate.parentConstraints`, but its length differs from the checkpoint's recorded
+     *  `parentConstraintCount` — a partial/mismatched re-supply would silently run the child under a
+     *  thinner (or different) ancestor chain than it suspended with. Rejected pre-CAS (the checkpoint
+     *  stays `pending`); re-resume with the full original chain. */
+     | "resume.parent_constraint_mismatch";
+    /** Structured discrimination a caller can branch on where the code alone is ambiguous. Today one
+     *  member: `field` names WHICH part of the decision payload was rejected on a
+     *  `checkpoint.invalid_outcome` — `"boundCallId"` (the action you decided on has been replaced:
+     *  re-fetch the pending list), `"boundInputHash"` (the input you reviewed has changed under the same
+     *  action: re-review), or `"answer"` (the content-ask answer is missing, or was attached to a
+     *  decision that cannot carry one: re-decide with a well-formed answer — ruled 2026-08-04), or
+     *  `"settledBy"` (the settlement source is outside the three-word vocabulary: re-decide naming one
+     *  of them, or omit the field). The throw
+     *  sites always knew which arm fired; this carries that fact instead of dropping it (ruled
+     *  2026-08-03, cross-repo HITL discussion). Additive and optional — `code` remains the only REQUIRED
+     *  discriminant. */
     readonly detail?: {
         field?: "boundCallId" | "boundInputHash" | "answer" | "settledBy";
     } | undefined;
-    constructor(code: "checkpoint.already_exists" | "checkpoint.already_resolved" | "checkpoint.not_found" | "checkpoint.gate_mismatch" | "checkpoint.resume_aborted" | "checkpoint.invalid_outcome" | "checkpoint.unsupported_version" | "checkpoint.walltime_axis_retired" | "checkpoint.reopen_revote" | "checkpoint.reopened_concurrently" | "checkpoint.reopen_failed" | "steering.invalid_content" | "steering.queue_full" | "steering.duplicate_input_id" | "wake.gate_pending" | "wake.nothing_to_deliver" | "resume.parent_constraint_missing" | "resume.parent_constraint_mismatch", message: string, detail?: {
+    constructor(code: "checkpoint.already_exists" | "checkpoint.already_resolved" | "checkpoint.not_found"
+    /** `runner.resume` was handed an {@link ResumeOutcome} whose `gate` arm does not match the
+     *  persisted {@link CheckpointGate} `kind` (council #3 — type confusion guard), or a gate v1
+     *  resume does not serve (`task_done`). */
+     | "checkpoint.gate_mismatch"
+    /** RB-77: `runner.resume` was handed an ALREADY-ABORTED `TaskSpec.signal`. Refused BEFORE the CAS, so
+     *  the checkpoint stays `pending` — this worker demonstrably cannot execute the approved action, and
+     *  consuming the human's decision on a leg that will abort immediately loses BOTH the decision and the
+     *  suspended work with nothing to reopen. Re-resume with a live signal. */
+     | "checkpoint.resume_aborted"
+    /** `runner.resume` was handed an outcome whose payload is unsafe to apply — e.g. a deny `reason`
+     *  carrying a `</system-reminder>` tag that would escape the model-facing wrapper (round-2 #1). */
+     | "checkpoint.invalid_outcome"
+    /** The checkpoint's {@link Checkpoint.version} is newer than this worker supports
+     *  (`> MAX_SUPPORTED_CHECKPOINT_VERSION`), or it carries a remote `workspaceHandle` but no
+     *  `executionEnvFactory` is wired to rebuild the env — either way this worker cannot safely resume it.
+     *  Rejected pre-CAS so the checkpoint stays `pending` and a capable worker can still resume it
+     *  (design/49 §2/§3, code-ready council round-2). */
+     | "checkpoint.unsupported_version"
+    /** design/164: the checkpoint was written by a pre-164 worker AND its ledger carries the RETIRED
+     *  cross-slice wall-clock allocation (`resourceLedger.totalWalltimeSec`). The axis no longer exists,
+     *  so resuming would run the leg with the operator's time ceiling silently unenforced. Refused
+     *  PRE-CAS (the row stays `pending`, so a worker of the previous release can still finish it) rather
+     *  than migrated: there is no honest conversion from a wall-clock allocation to a token one. */
+     | "checkpoint.walltime_axis_retired"
+    /** design/80 D-1 (reopen-by-reason): a re-resume of an `env_failed`-reopened checkpoint supplied an
+     *  outcome that does NOT equal the persisted {@link ResolvedOutcome} winner. An `env_failed` reopen is
+     *  a SYSTEM RETRY of the already-approved action (the infra failed, not the decision) — it must replay
+     *  the exact winning binding, never a new vote. Rejected pre-CAS, fail-closed, so the checkpoint stays
+     *  `pending` for the correctly-replayed retry. (A `tool_unavailable` reopen — P-7 — is exempt: it lets
+     *  a human re-decide with the tool present, so a fresh decision is permitted there.) */
+     | "checkpoint.reopen_revote"
+    /** design/80 D-1 (atomicity fix): the resume validated its decision-action / reopen-by-reason guards
+     *  against a `get()` snapshot, but a concurrent {@link CheckpointStore.resolve}/{@link CheckpointStore.reopen}
+     *  cycle advanced the monotonic {@link Checkpoint.rev} in the get→resolve window, so the
+     *  {@link CheckpointStore.resolve} CAS's optimistic-concurrency check lost (the validation is stale). The
+     *  row is still `pending` — fail-closed; the caller must re-`get` and re-validate against the CURRENT state
+     *  (a fresh resume), never blindly retry. */
+     | "checkpoint.reopened_concurrently"
+    /** A post-CAS compensation {@link CheckpointStore.reopen} returned `false` — the consumed row could not
+     *  be flipped back to `pending` (missing, expired, or changed under a concurrent cycle), so no retryable
+     *  checkpoint exists. Surfaced instead of silently treating the failed reopen as committed, so the
+     *  caller's compensation path settles the token as terminally consumed. */
+     | "checkpoint.reopen_failed"
+    /** design/80 D-A: {@link CheckpointStore.setPendingSteer} was handed `text` containing a
+     *  `</system-reminder>` close tag — it would escape the model-facing `<system-reminder>` wrapper a
+     *  trusted steer rides on resume. Rejected fail-closed so a dirty steer NEVER enters {@link CheckpointState}
+     *  (§3 inv #2). Mirrors the trusted-steer reject at runtask.ts (`steering.invalid_content`). */
+     | "steering.invalid_content"
+    /** design/171 §6.3: the append would cross the parked-steer queue's entry-count or byte bound
+     *  ({@link MAX_PENDING_STEER_ENTRIES} / {@link PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES}). Fail-loud
+     *  rather than evicting: an already-accepted operator instruction is never dropped to make room —
+     *  the caller delivers or removes a parked steer first. Nothing is written on this path. */
+     | "steering.queue_full"
+    /** design/171 §6.3 (adversarial review adoption): the append reused an `inputId` already parked on
+     *  this checkpoint, but with DIFFERENT content. Re-appending an IDENTICAL payload stays the
+     *  idempotent no-op a retry needs; a differing one is refused, because swallowing it would lose the
+     *  second operator's instruction — the exact silent loss the queue replaced. Retry with a fresh id.
+     *  Nothing is written on this path. */
+     | "steering.duplicate_input_id"
+    /** design/144 §3 (governance-gate purity, fail-closed pre-CAS): a `wake` outcome was supplied for a
+     *  checkpoint that awaits a PENDING GATE DECISION (tool approval / dry-run review / plan review /
+     *  resource-limit continue). Wake is a pure un-park verb and must never bypass an approval — resume
+     *  the checkpoint through its own decide entry instead (the error message names it). */
+     | "wake.gate_pending"
+    /** design/144 §3 (anti spin-wake): a `wake` outcome carried no `message` and the checkpoint has no
+     *  parked `pendingSteer` either — there is nothing to deliver, so the wake is rejected pre-CAS
+     *  (the checkpoint stays pending) instead of burning the token on an empty continuation. */
+     | "wake.nothing_to_deliver"
+    /** Parent effective-policy inheritance: the checkpoint records `state.inheritedGate.requiresParentConstraint`
+     *  (the suspended task ran under inherited OPAQUE parent-policy constraints — live closures that cannot
+     *  persist), but the resume supplied no `RunInternals.inheritedGate.parentConstraints` to re-instate them.
+     *  Resuming anyway would silently DROP the ancestors' gate (a widening), so this rejects pre-CAS — the
+     *  checkpoint stays `pending`; re-resume via `resumeStream(token, outcome, config, internals)` with the
+     *  parent chain re-supplied. */
+     | "resume.parent_constraint_missing"
+    /** Parent effective-policy inheritance (shape check): the resume DID re-supply
+     *  `internals.inheritedGate.parentConstraints`, but its length differs from the checkpoint's recorded
+     *  `parentConstraintCount` — a partial/mismatched re-supply would silently run the child under a
+     *  thinner (or different) ancestor chain than it suspended with. Rejected pre-CAS (the checkpoint
+     *  stays `pending`); re-resume with the full original chain. */
+     | "resume.parent_constraint_mismatch", message: string, 
+    /** Structured discrimination a caller can branch on where the code alone is ambiguous. Today one
+     *  member: `field` names WHICH part of the decision payload was rejected on a
+     *  `checkpoint.invalid_outcome` — `"boundCallId"` (the action you decided on has been replaced:
+     *  re-fetch the pending list), `"boundInputHash"` (the input you reviewed has changed under the same
+     *  action: re-review), or `"answer"` (the content-ask answer is missing, or was attached to a
+     *  decision that cannot carry one: re-decide with a well-formed answer — ruled 2026-08-04), or
+     *  `"settledBy"` (the settlement source is outside the three-word vocabulary: re-decide naming one
+     *  of them, or omit the field). The throw
+     *  sites always knew which arm fired; this carries that fact instead of dropping it (ruled
+     *  2026-08-03, cross-repo HITL discussion). Additive and optional — `code` remains the only REQUIRED
+     *  discriminant. */
+    detail?: {
         field?: "boundCallId" | "boundInputHash" | "answer" | "settledBy";
     } | undefined);
 }
+/**
+ * The pluggable durable seam (design/45 §2.1). Symmetric with `ToolResultStore`/`MemoryStore`:
+ * create-once `put`, `get`, an **atomic CAS `resolve`** (the once-only foundation), and a `reap` for TTL
+ * expiry. A durable backend (TiDB) makes resume cross-replica; the default in-memory impl is single
+ * instance / tests only.
+ *
+ * **Load-bearing contract (§2.1, service-side report):** `resolve` is the once-only gate. The store guarantees
+ * *exactly one* `resolve(token, ...)` wins the CAS (pending → resolved); the **runner** must treat
+ * "won the CAS" as the *sole* trigger to execute the pending action — that is what makes a pending tool
+ * call run exactly once across retries / double approvals / multiple replicas.
+ *
+ * **design/80 §D-D expiry semantic contract (gate.kind-aware reap + `terminalAt` backstop):** the
+ * reaper-LOOP that calls {@link reap}/{@link expire} is the DEPLOYMENT's (its store impl + loop — OWNED
+ * service-side); core's D-D job is ONLY to keep writing the durable FIELDS the loop
+ * reads ({@link Checkpoint.deadline} for an approval gate + the persisted {@link Checkpoint.gate}.kind) and
+ * to DOCUMENT the contract here so ANY reaper consumer (the service's TiDB loop, or a non-service Pg
+ * deployment) implements it IDENTICALLY:
+ *  - **FACET A — APPROVAL gates** (`gate.kind` ∈ {`human`, `irreversible_ask`}): the loop's FAST PATH at
+ *    `deadline` is an SLA **resolve-deny** (`resolve(token, {gate:"policy_ask", decision:"deny"}, …)` so the
+ *    suspended run ends cleanly), with a LATER `terminalAt` **abandonment backstop** the loop ALSO honors
+ *    (crash-safe if the SLA timer never fired — then {@link reap}/{@link expire} flips it `expired`).
+ *  - **FACET B — UNATTENDED-TTL gates** (`gate.kind` ∈ {`resource_limit`, `needs_review`, `plan_review`} — the
+ *    resource slice + the review-pause family): `deadline` is an abandonment-TTL → {@link expire}/{@link reap}
+ *    ONLY, **NEVER** a resolve-deny (a resolve-deny on these kinds hits NO `gateMatch` arm → `gate_mismatch`;
+ *    their resume outcome is `resource_limit`/`dry_run_review`/`plan_review` respectively, not `policy_ask`).
+ *  NO core-minted `terminalAt`, NO core reaper, NO change to {@link reap} logic — minting `terminalAt` and
+ *  running the gate.kind-aware loop are the deployment's, by design.
+ */
+/**
+ * design/173 §2.3 — the store DURABILITY declaration vocabulary (declaration, never duck-typing —
+ * the exact posture of {@link CheckpointStore.retention}): `"durable"` promises the rows SURVIVE A
+ * PROCESS RESTART of the deployment that owns the store's data domain (a durable park can be
+ * resumed by a later process); `"process-local"` states they die with the process. **This axis
+ * claims restart survival ONLY — it does NOT claim multi-replica coordination** (whether a SECOND
+ * concurrent replica can serve the same rows is a separate property of the backend: the file
+ * backend is single-instance-per-data-dir by design, Pg/TiDB backends coordinate — both honestly
+ * declare `"durable"` on THIS axis; review fold round 1, finding 2). ABSENT is read FAIL-CLOSED as
+ * `"process-local"` (the wiring manifest may under-promise durability, never over-promise it); an
+ * unparseable value is refused loudly (`config.store_durability_invalid`) rather than folded to
+ * either arm. Adapter contract with a conformance obligation: a backend that persists outside the
+ * process (file/Pg/TiDB) SHOULD declare `"durable"` — until it does, restart-surviving resume
+ * capability is reported as absent.
+ */
 export type StoreDurability = "durable" | "process-local";
+/**
+ * The store ENCODING-FIDELITY declaration vocabulary — the third honest-declaration axis, alongside
+ * {@link StoreDurability} and {@link CheckpointStore.retention}, and the one that says WHICH VALUES a
+ * row can hold unchanged.
+ *
+ * `"structured-clone"` promises the structured-clone value domain survives a round trip through the
+ * backend (a `Date` comes back a `Date`, a `Map` a `Map`, `NaN` stays `NaN`); `"json"` states the
+ * backend serialises through JSON, so the row that comes back after a restart carries the JSON
+ * PROJECTION of what was filed (`Date` → string, `Map`/`Set` → `{}`, `NaN`/`Infinity` → `null`, `-0`
+ * → `0`, an `undefined`-valued key gone).
+ *
+ * Why this has to be declared rather than inferred: the mint decides what a durable approval row may
+ * carry, and it decides it with `structuredClone` — which is WIDER than a JSON codec. A value can pass
+ * that check, be filed, degrade on disk, and come back a different value, while the binding hash minted
+ * over the pre-serialisation value still matches the one the operator echoes (the resume compares the
+ * persisted string opaquely and never re-hashes). The approval is then accepted for arguments that are
+ * not the arguments it bound. Only the backend knows its own codec, so only the backend can say.
+ *
+ * ABSENT is read FAIL-CLOSED as `"json"` — the narrower domain, the same "may under-promise, never
+ * over-promise" posture {@link StoreDurability} takes with `"process-local"`: an undeclared backend gets
+ * a row it can certainly hold, and a backend that can hold more earns the wider domain by saying so. An
+ * unparseable value is refused loudly (`config.store_fidelity_invalid`) rather than folded to either arm.
+ */
 export type StoreFidelity = "structured-clone" | "json";
+/**
+ * Resolve a store's declared {@link StoreFidelity} (the read half of the declaration — the exact shape
+ * `resolveDeclaredFidelity`'s durability twin has): ABSENT → the fail-closed `"json"`, a recognized
+ * value verbatim, anything else refused loudly. Never duck-types the backend.
+ */
 export declare function resolveDeclaredFidelity(store: {
     readonly fidelity?: StoreFidelity;
 } | undefined, storeName: string): StoreFidelity;
+/**
+ * Project an already-captured value onto what a backend of the given {@link StoreFidelity} can hold, so
+ * everything minted from it — the row's args, the approval preview, the binding hash, the risk
+ * descriptor — describes the value that comes BACK, not the one that went in.
+ *
+ * `"structured-clone"` is the identity: the caller's snapshot already is what such a backend stores.
+ * `"json"` runs the backend's own codec (`JSON.stringify` → `JSON.parse`, `toJSON` hooks included, since
+ * that is exactly what the backend will do to it). The input is expected to be an accessor-free snapshot
+ * already, so no property is read a second time here.
+ *
+ * A value JSON cannot ENCODE AT ALL (a `BigInt`, a cycle) fails instead of degrading — those would throw
+ * inside the backend's own write anyway, and failing here means the caller can say why while nothing has
+ * been committed. The thrown value rides out on `cause` so the caller decides how to word the refusal.
+ */
 export declare function encodeAtFidelity(fidelity: StoreFidelity, value: unknown): {
     ok: true;
     value: unknown;
@@ -296,40 +1573,319 @@ export declare function encodeAtFidelity(fidelity: StoreFidelity, value: unknown
     ok: false;
     cause: unknown;
 };
+/**
+ * CONSERVATIVE "these two are provably the same value" for deciding whether a {@link encodeAtFidelity}
+ * projection moved anything, and whether a policy's rewrite names the very value about to be filed.
+ *
+ * Deliberately NOT the binding hash, which is the wrong instrument for this question in two directions:
+ * it folds `-0` onto `0` (a real projection change the policy may care about, invisible to the hash), and
+ * it is a digest, so a collision would read as sameness. `Object.is` at the leaves keeps the `-0`
+ * distinction; comparing own-key SETS keeps the dropped `undefined`-valued key visible.
+ *
+ * Conservative on purpose — the answer it must never give wrongly is TRUE, because both callers read
+ * TRUE as "nothing moved / the policy named this very value" and act by filing. So sameness has to be
+ * PROVED, not merely un-disproved:
+ *  - the PROTOTYPES must match and be the plain-object or array one. `[object Object]` is not proof of
+ *    a plain object — a class instance and a null-prototype object both report it, and a tool executing
+ *    the arguments can observe inherited behaviour. (Neither input to the projection comparison can be
+ *    such a value: `structuredClone` and `JSON.parse` both produce plain data. A policy's rewrite can.)
+ *  - own keys are compared with `Reflect.ownKeys` and POSITIONALLY, so a SYMBOL key or a non-enumerable
+ *    property on one side is a difference rather than an invisible extra, and so is a different order
+ *    (which `Object.keys`, `JSON.stringify` and any tool iterating its arguments can see).
+ *  - properties are compared through their DESCRIPTORS — every flag, so a frozen object is not the
+ *    mutable value a JSON decode produces — and an accessor on either side answers FALSE without being
+ *    read: an approval decision must not be made by running deployment code, and what a getter returns
+ *    need not be the same twice.
+ *  - reference TOPOLOGY counts: two properties that share one object are not two properties holding
+ *    equal objects, and a JSON round trip is precisely what turns the first into the second.
+ *  - what it CANNOT prove on its own is that the value it inspected answers ordinary reads the way its
+ *    descriptors did — a Proxy reports the target's descriptors and can return anything from a `get`.
+ *    A caller comparing a value it did not construct must first establish that it is an inert data
+ *    graph (the capture clone does exactly that, and refuses a Proxy outright).
+ *  - any brand outside plain object/array that is not already reference-identical answers FALSE (a Date
+ *    is never the string a JSON codec leaves behind, a Map is never the `{}`), and so does any
+ *    inspection that throws.
+ * An uncertain answer therefore costs a policy consultation or a park, never a silently filed value.
+ */
 export declare function samePlainValue(a: unknown, b: unknown): boolean;
 export interface CheckpointStore {
+    /**
+     * Managed-retention declaration (ruled 2026-08-05, retention.ts): `"managed"` promises the
+     * `ManagedRetentionCapability` contract — including the reap/unpin gap this interface documents on
+     * {@link reap} (a managed store's scheduled expiry DOES release the session pins). `"none"` (or
+     * ABSENT — read fail-closed as `"none"`) states the store cannot delete on schedule; a deployment
+     * with a LOCKED retention policy refuses to start over it. Declaration, never duck-typing.
+     */
     readonly retention?: import("./retention.js").RetentionDeclaration;
+    /**
+     * design/173 §2.3 — durability declaration (see {@link StoreDurability}): whether checkpoints
+     * this store accepts survive a process restart. Same "declaration, never duck-typing" posture as
+     * {@link retention}; the wiring manifest relays it verbatim and reads ABSENT fail-closed as
+     * `"process-local"`.
+     */
     readonly durability?: StoreDurability;
+    /**
+     * Encoding-fidelity declaration (see {@link StoreFidelity}): which value domain a row keeps INTACT
+     * through this backend. Same "declaration, never duck-typing" posture as {@link durability}; the park
+     * mint reads it to decide the width of the snapshot it files, and reads ABSENT fail-closed as
+     * `"json"`. A backend that serialises through JSON MUST say so (or leave it absent, which says the
+     * same) — a `"structured-clone"` claim it cannot keep is what lets a row degrade under a binding hash
+     * that still matches.
+     */
     readonly fidelity?: StoreFidelity;
+    /** Create-once. Throws {@link CheckpointError} `already_exists` on a token collision (never a silent
+     *  overwrite — a reused token would clobber a live suspension). */
     put(token: CheckpointToken, cp: Checkpoint): Promise<void>;
     get(token: CheckpointToken): Promise<Checkpoint | null>;
+    /**
+     * Atomic CAS: `UPDATE … SET status='resolved' WHERE token=? AND scope=? AND status='pending'`.
+     * Returns `true` for the single winner (was pending → now resolved), `false` if already resolved/
+     * expired (`AlreadyResolved` — the caller treats it as a no-op, never re-executes). `scope` is in the
+     * WHERE for multi-tenant isolation (a wrong-scope resolve must not win).
+     *
+     * `outcome` is supplied so a **durable** backend persists it atomically with the status flip (design/45
+     * v2 resumable-resume hook). **design/80 D-1 (persist-winner):** when the CAS wins, the store ALSO records
+     * the winning binding as {@link Checkpoint.resolvedOutcome} on the row — so a later {@link reopen} →
+     * re-resume can be validated against the approved decision (an `env_failed` reopen must replay the same
+     * winner; design/80 §3 inv #1). A `policy_ask` outcome records the decision bound to its pending tool
+     * call; the two REVIEW outcomes (`plan_review` / `dry_run_review`) record theirs under a synthetic
+     * `gate:` marker; `resource_limit` / `wake` / `task_done` bind nothing and record no winner.
+     *
+     * **Implementers: derive the winner with {@link winnerFromOutcome} and persist the object WHOLE.** Its
+     * field set GROWS (`updatedInput`, then `answer`, then `reason` — each additive and optional), and the
+     * replay guard reads an absent optional field as "this backend never recorded it" so that rows written
+     * before the field existed still replay. A backend that projects a hand-listed subset of columns is
+     * therefore indistinguishable from an old row and silently leaves that dimension UNBOUND for every
+     * decision it ever writes — the replay guard cannot tell the two apart, and there is no capability
+     * negotiation on this interface to tell it. Round-trip the whole record (opaque JSON is what every
+     * in-tree backend does) rather than enumerating its keys.
+     *
+     * (The crash-recovery semantics of *acting* on a won CAS are runner contract — see
+     * {@link Runner.resume}; the store only owns the atomic once-only flip + the durable winner.)
+     */
     resolve(token: CheckpointToken, scope: string, outcome: ResumeOutcome, expect?: ResolveExpectation): Promise<boolean>;
+    /**
+     * Inverse of {@link resolve}: CAS `resolved → pending` (`UPDATE … SET status='pending' WHERE token=?
+     * AND scope=? AND status='resolved'`). Returns the CAS winner (`true` = was resolved → now pending again).
+     *
+     * **Compensation for a post-CAS env-restore failure (design/45/49).** `Runner.resumeStream` wins the
+     * `resolve` CAS *before* the workspace `resumeVM` runs; if that restore then fails (`resume.env_failed`)
+     * the pending action never executed yet the checkpoint is consumed — without this the suspended work is
+     * lost to a forced "re-initiate" (fine for a short approval, ruinous for a long unattended task).
+     * Reopening lets a retry re-resume the SAME work. Optional: a store that omits it keeps the prior (lossy)
+     * behavior, and the runner degrades gracefully. Safe by the `status='resolved'` guard — only the run that
+     * consumed the checkpoint (and then failed to restore) can reopen it, and only while it is still `resolved`.
+     *
+     * **design/80 D-1 (reopen-by-reason):** the `reason` distinguishes the two reopen triggers (both shipped at
+     * runtask.ts) so re-resume can validate per reason (§3 inv #1): `env_failed` (the action is still valid,
+     * only infra failed → re-resume MUST replay the persisted {@link Checkpoint.resolvedOutcome} winner) vs
+     * `tool_unavailable` (P-7: the approved tool vanished, the action may now be invalid → a human re-decides,
+     * so a FRESH decision is allowed). The store RECORDS the reason on the row as {@link Checkpoint.reopenReason}
+     * and PRESERVES the persisted winner across the reopen (never clears it).
+     */
     reopen?(token: CheckpointToken, scope: string, reason: ReopenReason): Promise<boolean>;
+    /**
+     * design/80 D-A: park a durable mid-task STEER on a DURABLY-SUSPENDED task's checkpoint. CAS-style update
+     * `SET state.pendingSteerQueue=? WHERE token=? AND scope=? AND status='pending'`: returns `true` iff the
+     * checkpoint is still `pending` (a resolved/expired checkpoint can't be steered → `false`, a no-op). Scope
+     * is in the WHERE for multi-tenant isolation, exactly like {@link resolve}/{@link expire}.
+     *
+     * **design/171 §5.3 — this APPENDS to {@link CheckpointState.pendingSteerQueue}; it no longer overwrites a
+     * single seat.** Two people steering one suspended run used to silently destroy the first instruction,
+     * with no record that anything was lost. Idempotency moved from last-writer-wins to the `inputId` key:
+     * re-appending an `inputId` already queued (a service retrying with the message id it already minted)
+     * is a no-op that still returns `true`. Crossing {@link MAX_PENDING_STEER_ENTRIES} or
+     * {@link PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES} throws `steering.queue_full` — bounded fail-loud, never
+     * by evicting an accepted instruction.
+     *
+     * **Migration (additive read):** a row written before the queue existed keeps its legacy
+     * {@link CheckpointState.pendingSteer} seat and is read back as queue member 0 by
+     * {@link readPendingSteerQueue}; new writes only ever touch the queue. A backend must round-trip BOTH
+     * fields, and must build its new queue with {@link appendPendingSteer} so the bounds and the `seq` mint
+     * are one implementation rather than one per store.
+     *
+     * **Trust is FROZEN here** — `steer.trusted` is whatever the SERVICE computed from the verified principal
+     * at this call (an operator-role check, NOT a client header — the service's job); the core stores it
+     * VERBATIM and NEVER recomputes it on resume (§3 inv #1).
+     *
+     * **Validation (load-bearing, §3 inv #2):** `steer.text` containing a `</system-reminder>` close tag is
+     * REJECTED with a typed {@link CheckpointError} `steering.invalid_content` (mirroring runtask.ts's trusted-
+     * steer reject) — a dirty steer NEVER enters {@link CheckpointState}, so the persisted state stays clean
+     * regardless of `trusted`. (The untrusted RESUME-injection path ALSO sanitizes the text as untrusted data;
+     * this persist-time reject is the belt that keeps a forged close tag out of the durable record on BOTH
+     * paths.) Text over {@link MAX_PENDING_STEER_CHARS} is rejected with the same code (HRD-APV-4 — the
+     * steer is re-delivered into the model context on every resume, so it is capped like every other
+     * persisted model-facing field on this row; rejected rather than truncated because cutting an
+     * instruction can invert it). NOT an approval channel: this only writes the parked queue, never
+     * touches status / the resolve path / any decision (§3 inv #4).
+     */
     setPendingSteer(token: CheckpointToken, scope: string, steer: PendingSteerInput): Promise<boolean>;
+    /**
+     * CAS-expire a **single** `pending` checkpoint by token: `UPDATE … SET status='expired' WHERE token=?
+     * AND scope=? AND status='pending'`. Returns the CAS winner (`true` = was pending → now expired; `false`
+     * = already resolved/expired). The same UPDATE as {@link reap} but keyed by **token**, not by deadline.
+     *
+     * **Load-bearing contract (design/51 §2/§4):** `expire` and {@link resolve} race the **same `pending`
+     * row**, so the store serializes them — exactly one wins. This is what makes {@link TaskStream.destroy}
+     * a correct *fence-then-reap*: `destroy` calls `expire` FIRST to fence any concurrent `resume` (which
+     * goes through `resolve`); only the `expire` winner then destroys the paused env, so the same checkpoint
+     * is **never both reaped and resumed**. `scope` is in the WHERE for multi-tenant isolation, like
+     * `resolve`/`reap`.
+     */
     expire(token: CheckpointToken, scope: string): Promise<boolean>;
+    /**
+     * CAS-expire `pending` checkpoints in `scope` whose `deadline` has passed (`deadline <= cutoff`):
+     * `pending → expired`. Returns the count expired (for metrics). Idempotent across replicas (DB
+     * serializes; only the first wins each row) — no leader election needed (§6).
+     *
+     * **Does NOT unpin the sessions of the checkpoints it expires (council finding #2).** A suspend pinned
+     * its session against idle eviction; reaping the checkpoint here leaves that pin in place. The reaper
+     * that calls `reap` owns releasing the pin. For a **durable** session store this is a no-op anyway
+     * (`pin`/`unpin` are no-ops; it never idle-GCs), so reap-without-unpin is harmless — the only store with
+     * a real pin is the in-memory `TtlSessionStore` (single-instance / tests), where an un-released pin
+     * keeps an abandoned suspended session in the cache until process exit. v1 leaves the runner without an
+     * auto-reaper (the service owns the TTL worker); a reaper over the in-memory store should track and
+     * `unpin` the expired sessions itself if that leak matters for its deployment.
+     */
     reap(scope: string, cutoff: number): Promise<number>;
+    /**
+     * design/80 assistant-scheduler seam #1: list a lightweight {@link CheckpointSummary}
+     * for EVERY **pending** checkpoint in `scope` (the suspended / awaiting-human tasks — NOT resolved/expired) in
+     * ONE call, so a supervisor scheduler can enumerate a scope's open suspensions without N+1 `get`s or hauling
+     * full {@link Checkpoint} payloads. Read-only — it never mutates a row, takes no CAS, and has ZERO effect on
+     * the once-only resolve. The PENDING predicate is byte-for-byte the {@link resolve} CAS's (`scope === scope &&
+     * status === 'pending'`), so the list reflects exactly the rows that are still resumable. Order is unspecified
+     * (the inbox sorts by `severity`/`deadline` itself). An empty scope returns `[]`.
+     *
+     * **OPTIONAL** for backward-compat with external {@link CheckpointStore} impls (a caller probes
+     * `store.listByScope?.(scope) ?? []`); ALL THREE first-party impls (in-memory, file, Pg) provide it.
+     */
     listByScope?(scope: string): Promise<CheckpointSummary[]>;
+    /**
+     * server [1800] seam: the DISTINCT scopes that currently have at least one PENDING checkpoint — the
+     * enumeration face `listByScope` lacks. A host keeping its own scope registry (e.g. a sidecar file for a
+     * cross-scope inbox) can rebuild it from the data itself when the registry is lost/corrupt, instead of the
+     * enumeration silently going empty and pending approvals turning invisible. Scoped to PENDING deliberately:
+     * it matches `listByScope`'s visible surface, so `listScopes() × listByScope()` is exactly the full inbox.
+     * **OPTIONAL** like {@link listByScope}; the in-memory and file first-party impls provide it.
+     */
     listScopes?(): Promise<string[]>;
 }
+/**
+ * The SINGLE resolution of "which CheckpointStore does this run use" (ruled 2026-08-04; re-homed
+ * from prepare-task with the design/173 wiring manifest so the static self-check half shares it
+ * without a runtime cycle). The spec seat is three-valued — a store wins, `undefined` falls through
+ * to the deployment's `RunnerDeps.checkpointStore`, and an explicit `null` means this run has NO
+ * store at all (see `TaskSpec.checkpointStore`: the per-run off switch for the durable machine, so
+ * a machine-started run cannot mint a checkpoint nobody will ever resolve).
+ *
+ * Written as an explicit `=== null` test rather than the obvious `spec.checkpointStore ??
+ * deps.checkpointStore` BECAUSE `??` treats `null` exactly like `undefined`: under a bare nullish
+ * coalesce the null falls through and the run is handed the very deployment store the caller asked
+ * it not to have, re-arming every suspend leg — silently, since the resulting run looks perfectly
+ * normal right up until it parks forever. Every read of the pair goes through here so that trap has
+ * ONE place to be wrong instead of nine.
+ */
 export declare function resolveCheckpointStore(spec: {
     checkpointStore?: CheckpointStore | null;
 }, deps: {
     checkpointStore?: CheckpointStore;
 }): CheckpointStore | undefined;
+/**
+ * design/80 D-1 (persist-winner): derive the durable {@link ResolvedOutcome} winner from a resume
+ * `outcome`, or `undefined` when the outcome binds to no pending action. A `policy_ask` resume names a
+ * specific tool call (`boundCallId`) + decision; since RB-64 the REVIEW gates (`plan_review` /
+ * `dry_run_review`) record their decision under a `gate:` sentinel too — the env_failed replay guard can
+ * only compare what is recorded here. Only `resource_limit` / `task_done` bind nothing and record no
+ * winner. Shared by every {@link CheckpointStore} impl so the persisted winner is identical across the
+ * in-memory and durable backends.
+ */
 export declare function winnerFromOutcome(outcome: ResumeOutcome): ResolvedOutcome | undefined;
+/**
+ * design/80 D-A: the persist-time validation every {@link CheckpointStore.setPendingSteer} impl runs so the
+ * reject is IDENTICAL across the in-memory and durable backends. A `steer.text` carrying a `</system-reminder>`
+ * close tag would escape the model-facing `<system-reminder>` wrapper a trusted steer rides on resume — reject
+ * fail-closed (`steering.invalid_content`) so a dirty steer NEVER enters {@link CheckpointState} (§3 inv #2).
+ * Applied for BOTH `trusted` values: the durable record must be clean on either path (the untrusted resume
+ * path ALSO sanitizes as untrusted data, but the close tag must never reach the persisted state at all).
+ * Returns a copy built from the FROZEN field set ({@link PENDING_STEER_FROZEN_FIELDS} minus the
+ * store-minted `seq`), so no extra caller field leaks into the row — and, since design/171 §6.3, an
+ * unknown key is a loud rejection rather than a silent drop: a producer one release ahead of this worker
+ * must learn that its new field would not survive the parked leg.
+ */
 export declare function validatePendingSteer(steer: PendingSteerInput): Omit<PendingSteerEntry, "seq">;
+/** design/171 §6.1 — the `actor` id/issuer bound. Attribution labels ride the durable row and the model
+ *  context, so they are capped like every other persisted model-facing string on this row. */
 export declare const MAX_ACTOR_FIELD_CHARS = 256;
+/** design/171 §6.3 — bound on the caller-supplied correlation id (a service's own message id). */
 export declare const MAX_STEER_INPUT_ID_CHARS = 128;
+/** design/171 §6.1 — the frozen field set of an {@link ActorAssertion} (same fail-loud posture as the
+ *  entry's own set: an unknown key means a producer's provenance field would vanish silently). */
 export declare const ACTOR_ASSERTION_FROZEN_FIELDS: readonly ["id", "hostAsserted", "issuer"];
+/**
+ * design/171 §5.3 — THE single read point for a checkpoint's parked steers, in delivery (`seq`) order.
+ *
+ * Additive read: a row written before the queue existed carries its steer in the legacy
+ * {@link CheckpointState.pendingSteer} seat, and it is folded in as the FIRST member (it was parked
+ * before anything in the queue could have been). Every consumer — the resume drain, the wake's
+ * nothing-to-deliver guard, a serving layer — goes through here, so no site can grow its own idea of
+ * what "the parked steer" is.
+ */
 export declare function readPendingSteerQueue(state: Pick<CheckpointState, "pendingSteer" | "pendingSteerQueue">): PendingSteerEntry[];
+/** design/171 §5.3 — the synthetic `inputId` a pre-queue single-seat steer reads back as. Stable (never
+ *  minted per read) so dedupe and re-reads behave, and reserved so a caller cannot collide with it. */
 export declare const LEGACY_PENDING_STEER_INPUT_ID = "legacy-single-seat";
+/**
+ * design/171 §5.3/§6.3 — THE append, shared by every backend so the bounds and the ordering are one
+ * implementation rather than one per store.
+ *
+ * Returns the NEW queue (the caller persists it); throws `steering.queue_full` when either bound would
+ * be crossed. Re-appending an entry whose `inputId` is already queued is a NO-OP returning the queue
+ * unchanged — that is what keeps `setPendingSteer` retry-safe now that it appends instead of overwriting.
+ */
 export declare function appendPendingSteer(state: Pick<CheckpointState, "pendingSteer" | "pendingSteerQueue">, entry: Omit<PendingSteerEntry, "seq">): PendingSteerEntry[];
+/**
+ * REF-A4 — THE row half of every guarded checkpoint transition's CAS predicate, shared by every backend:
+ * the row must EXIST, its `scope` must match (multi-tenant isolation, §2.1 — a wrong-scope caller never
+ * wins), and it must currently be in `status`. `resolve` requires `"pending"`, `reopen` requires
+ * `"resolved"` (the inverse gate), `setPendingSteer`/`expire` require `"pending"`.
+ *
+ * PURE: it decides nothing about persistence. Each backend keeps its own commit half — the in-memory one
+ * flips fields in place, the file one appends+fsyncs the event BEFORE the flip (RB-150: commit ordering is
+ * that backend's own correctness core and must never be absorbed into a shared abstraction).
+ */
 export declare function checkpointRowMatches(cp: Checkpoint | undefined, scope: string, status: Checkpoint["status"]): cp is Checkpoint;
+/**
+ * REF-A4 — THE optimistic-concurrency half of `resolve`'s CAS predicate (design/80 D-1), shared by every
+ * backend. The caller validated its reopen-by-reason guard against a `get()` snapshot; if a concurrent
+ * resolve/reopen cycle moved the monotonic `rev` in the get→resolve window, that validation is stale ⇒
+ * lose the CAS (fail-closed), forcing a re-get + re-validate. Keyed on `rev`, NOT on `reopenReason` — a
+ * 2-valued enum can ABA back to a prior value while the winner changed (round-2 BLOCKER fix). An absent
+ * expectation opts out of the guard entirely.
+ */
 export declare function checkpointOccMatches(cp: Checkpoint, expect?: ResolveExpectation): boolean;
-export type CheckpointFaultMode = "resolve-after-commit" | "resolve-before-commit";
+/** Fault-injection mode for {@link InMemoryCheckpointStore.testInjectFault} (council #5). One-shot. */
+export type CheckpointFaultMode = 
+/** `resolve` commits the CAS (status → resolved) then throws — simulates a crash *after* the commit
+ *  but before the caller is acked, so a retry must see `resolved` and NOT re-execute (idempotency). */
+"resolve-after-commit"
+/** `resolve` throws *before* the CAS — simulates a crash before the commit; the row stays `pending`
+ *  so a retry can still win it. */
+ | "resolve-before-commit";
+/**
+ * Default in-process {@link CheckpointStore}. Single-instance / tests only — it does NOT survive a
+ * restart or span replicas, so it cannot deliver the cross-process guarantee a durable backend does.
+ * Single-threaded JS already serializes `resolve`, so the CAS is trivially atomic here;
+ * {@link testInjectFault} simulates the crash-recovery races a real backend must survive.
+ */
 export declare class InMemoryCheckpointStore implements CheckpointStore {
+    /** In-memory rows die with the process, but there is no scheduled tenant-scoped deletion contract
+     *  here — honestly `"none"` (a locked retention policy must refuse this store). */
     readonly retention: "none";
+    /** design/173 §2.3 — honest declaration: in-memory rows die with the process. */
     readonly durability: "process-local";
+    /** Honest declaration on the fidelity axis: `put`/`get` are `structuredClone`, so a row keeps the
+     *  whole structured-clone domain — a `Date` filed here is a `Date` when it comes back. */
     readonly fidelity: "structured-clone";
     private cps;
     private fault;
@@ -342,6 +1898,8 @@ export declare class InMemoryCheckpointStore implements CheckpointStore {
     reap(scope: string, cutoff: number): Promise<number>;
     listByScope(scope: string): Promise<CheckpointSummary[]>;
     listScopes(): Promise<string[]>;
+    /** Arm a one-shot fault on the next `resolve` (council #5: makes crash-recovery unit-testable). */
     testInjectFault(mode: CheckpointFaultMode | null): void;
+    /** Test/inspection helper: number of stored checkpoints. */
     get size(): number;
 }