@sema-agent/core 5.20.0 → 5.21.0

package/dist/core/runner/prepare-task.js

@@ -88,17 +88,18 @@ import { countElicitOptIns, deriveAskEffective, deriveWiringManifest, resolveAsk
 import { GLOBAL_USAGE_KEY, resolveUsageWindows, usageRetryAfterMs } from "../usage-window-store.js";
 const RECONCILE_MAX_RETRIES = 3;
 const DEFAULT_MAX_SUSPENDS = 5;
-const TASK_LIMIT_KEYS = [
-    "maxTokens",
-    "maxCostUsd",
-    "maxTurns",
-    "maxWalltimeMs",
-    "maxOutputTokens",
-    "approachNotice",
-    "budgetStreamCancel",
-    "degrade",
-    "brainCallGuardrailMs",
-];
+const TASK_LIMIT_KEY_DICT = {
+    maxTokens: true,
+    maxCostUsd: true,
+    maxTurns: true,
+    maxWalltimeMs: true,
+    maxOutputTokens: true,
+    approachNotice: true,
+    budgetStreamCancel: true,
+    degrade: true,
+    brainCallGuardrailMs: true,
+};
+const TASK_LIMIT_KEYS = Object.keys(TASK_LIMIT_KEY_DICT);
 const NUMERIC_TASK_LIMIT_KEYS = ["maxTokens", "maxCostUsd", "maxTurns", "maxWalltimeMs", "maxOutputTokens"];
 const RETIRED_TASK_LIMIT_KEYS = {
     timeoutSec: "maxWalltimeMs (milliseconds, not seconds)",

package/dist/core/runner/prompt-suggestions.d.ts

@@ -2,6 +2,7 @@ import type { Model } from "../../internal/llm.js";
 import type { AgentMessage, ThinkingLevel } from "../../internal/harness-types.js";
 import type { Brain } from "../types.js";
 import type { ModelPricing } from "../pricing.js";
+/** The LLM handle for the suggestion pass (mirrors `ConsolidationLLM`). */
 export interface SuggestionLLM {
     brain: Brain;
     model: Model;
@@ -21,5 +22,11 @@ export interface SuggestionResult {
     tokens: number;
     costMicroUsd: number;
 }
+/** Parse the model's reply into ≤count clean suggestion strings. Returns [] on anything non-conforming. */
 export declare function parseSuggestions(text: string, count: number): string[];
+/**
+ * Run ONE suggestion inference pass. May throw on a hard LLM/transport error — the caller
+ * (`Runner.suggestNextPrompts`) is fire-and-forget and swallows, so a failure just yields no suggestions.
+ * Returns `{ suggestions: [], tokens: 0, costMicroUsd: 0 }` when the transcript is empty.
+ */
 export declare function generatePromptSuggestions(llm: SuggestionLLM, transcript: AgentMessage[], count: number): Promise<SuggestionResult>;

package/dist/core/runner/runtask.d.ts

@@ -7,18 +7,80 @@ import type { SessionStore } from "../session.js";
 import { type RecoveredOrphan } from "../session-reconcile.js";
 import { type ApprovalSettledBy } from "../tool-policy.js";
 import type { AgentDefinition, RunnerDeps, TaskEvent, TaskResult, TaskSpec, TaskStream } from "../types.js";
+/**
+ * Config re-supplied to {@link Runner.resume} (design/45). A suspended task's tools / model / policy /
+ * hooks cannot be reconstructed from a checkpoint token (the session stores neither tool implementations
+ * nor the hand band), so the caller's trusted control plane re-supplies the same {@link TaskSpec} it ran
+ * with — minus the conversation bits: `sessionId` comes from the checkpoint and `objective` is replaced by
+ * an internally-generated continuation, so both are omitted.
+ */
 export type ResumeTaskConfig = Omit<TaskSpec, "objective" | "sessionId">;
+/** design/45 resume plan threaded from {@link Runner.resume} into the shared run loop. */
 interface ResumeRun {
     cp: Checkpoint;
+    /**
+     * RB-152 (2026-07-25, 按面收口): did the APPROVED ACTION actually begin executing?
+     *
+     * The reopen compensation used to key on an error-code whitelist (`resume.env_failed` /
+     * `resume.session_not_found` / `resume.tool_unavailable`). That is a proxy for the thing that actually
+     * matters, and every time a NEW way to exit without running the action appeared, the whitelist did not
+     * know about it: a caller's abort landing anywhere between the CAS and `tool.execute` — across
+     * `SessionStore.acquire` (pluggable, cross-network on a durable backend), the MCP reconnect, the env
+     * rebuild, `resumeVM`, tool materialization — produced a `failed` result with NO errorCode, no reopen,
+     * and a human approval consumed for work that never happened. Two rounds of fixes (RB-77, RB-109) each
+     * moved that window rather than closing it, because both extended the whitelist.
+     *
+     * This binds the compensation to the FACT instead: set the instant before `tool.execute` for the gated
+     * call (the same `onExecuteStart` signal the orphan-reconcile split already trusts). Every terminal —
+     * throw OR returned result — asks one question: was the checkpoint consumed while this stayed false?
+     */
     pendingActionStarted?: boolean;
+    /** Validated against `cp.gate.kind` at the resume entry: human/irreversible_ask→`policy_ask`,
+     *  resource_limit→`resource_limit` (design/74), needs_review→`dry_run_review` (design/76 §2.5),
+     *  plan_review→`plan_review` (design/80 D-B). The gate-match guard in `resumeStream` enforces the
+     *  correlation. design/144 §3: `wake` is the NON-GATE arm — only a checkpoint awaiting NO gate
+     *  decision passes the resume entry with it (gate purity, `wake.gate_pending`); the run loop skips
+     *  `applyResumeDecision` for it (no pending action to resolve) and re-enters via the continuation +
+     *  pendingSteer tail alone. */
     outcome: Extract<ResumeOutcome, {
         gate: "policy_ask" | "resource_limit" | "dry_run_review" | "plan_review" | "wake";
     }>;
+    /** design/144 §3 (X5) — the wake's own operator message, validated (`validatePendingSteer`) at the
+     *  resume entry and carried SEPARATELY from the checkpoint's parked `pendingSteer`: a message-bearing
+     *  wake of a checkpoint that ALSO holds a parked steer must deliver BOTH (park order: parked first,
+     *  wake message second), each under its own trusted framing — the old merge-into-the-slot shape
+     *  silently DISPLACED the parked (undelivered) supervisor steer. Wake outcomes only. */
     wakeMessage?: Omit<PendingSteerEntry, "seq">;
+    /** Compensation hook (design/45/49): called iff the resumed run fails with `resume.env_failed` (post-CAS
+     *  workspace `resumeVM` failed) OR `resume.tool_unavailable` (P-7: the approved tool vanished) — in both
+     *  the CAS already consumed the checkpoint but the pending action never ran. `resumeStream` supplies a
+     *  closure that reopens the checkpoint (`resolved → pending`) so a retry re-resumes the SAME suspended work
+     *  instead of losing it to a forced "re-initiate". design/80 D-1 (reopen-by-reason): the `reason` is
+     *  recorded on the reopened row so the next re-resume validates per reason — an `env_failed` reopen must
+     *  replay the persisted winner (a system retry of the approved action), while a `tool_unavailable` reopen
+     *  lets a human re-decide with the tool present (a fresh decision is allowed — preserves P-7). */
     onEnvRestoreFailed?: (reason: ReopenReason) => Promise<void>;
+    /** RB-471/FR-C1 — set in the run body right after `applyResumeDecision` completes: the negative-
+     *  decision twin of `pendingActionStarted`. A reject/deny consumes its gate BY BEING DELIVERED, and
+     *  this bit is the delivery fact — every throw-arm cause (prepare failure, `session_not_found`, a
+     *  pre-delivery abort) and the walltime-exhausted settle fire BEFORE it is set, so an undelivered
+     *  negative decision still reopens as `env_failed` (the retry replays the persisted decision; it
+     *  never re-asks — design/80 D-1), closing the RB-152/RB-70 loss class the first RB-471 cut reopened. */
     decisionDelivered?: boolean;
 }
-declare function toolEndBodyFrom(result: unknown, isError: boolean, settledBy?: ApprovalSettledBy): {
+/** The `tool_end` body fields projected from a harness tool result — output/truncated/totalChars via
+ *  {@link toolOutputFrom} and the CC card via {@link structuredFrom}. Single construction point for BOTH
+ *  the live loop's frames and the resumed batch's frames (`resolvePendingCall` + the deferred-sibling
+ *  close): the resumed frames used to carry only `isError`, so a client rendering tool output from frames
+ *  showed an empty body for every durable-approved call. Same projection = same source as the transcript.
+ *  Also the one place `settledBy` reaches a frame — see the parameter. */
+declare function toolEndBodyFrom(result: unknown, isError: boolean, 
+/** What ended the approval this call was waiting on, supplied by the CALLER of this projection — the
+ *  live loop reads it off the gate's per-call sideband, the resumed leg off the decide. Deliberately
+ *  a parameter and never derived from `result`: a tool's own `details` (which post-tool hooks may
+ *  also replace) is writable by layers that adjudicate nothing, so reading provenance out of it would
+ *  let a failing tool claim a person approved it. Omitted ⇒ this call settled no approval. */
+settledBy?: ApprovalSettledBy): {
     output?: unknown;
     truncated?: boolean;
     totalChars?: number;
@@ -26,45 +88,284 @@ declare function toolEndBodyFrom(result: unknown, isError: boolean, settledBy?:
     errorCode?: string;
     settledBy?: ApprovalSettledBy;
 };
+/**
+ * scan-1/A1 — the BODY of the synthetic `tool_end` that closes a reconcile-recovered orphan. ONE
+ * construction point for BOTH minting legs (the live-abort loop at the end of a run, and the wake/crash
+ * leg's replay at run open), so the two can never disagree about the shape of the same event.
+ *
+ * Both frames used to carry `isError:true` and NOTHING else: a consumer rendering tool output from the
+ * event stream showed an EMPTY body for every interrupted call, even though the persisted transcript
+ * (which the model reads) carried the full `[INTERRUPTED]` explanation — the two faces of one call
+ * disagreed. The projection goes through the same {@link toolEndBodyFrom} every live tool result uses, so
+ * `output` = the persisted model-facing text and `errorCode` = the persisted `details.errorKind`
+ * (`interrupted_never_started` / `interrupted_outcome_unknown`) — a consumer discriminates on the code
+ * instead of prose-matching. No `structured`: the reconcile mints no CC card (no `details.type`), which
+ * `structuredFrom`'s allowlist already enforces.
+ */
 export declare function reconciledToolEndBody(orphan: Pick<RecoveredOrphan, "text" | "errorKind">): ReturnType<typeof toolEndBodyFrom>;
 export declare const GOVERNANCE_READ_STALLED: unique symbol;
+/** Await a ledger charge, firing `onSlow` ONCE if it has not settled after
+ *  {@link CHARGE_SETTLE_DISCLOSE_MS}. The charge itself is always awaited to completion. */
 export declare function awaitChargeWithSlowDisclosure<T>(charge: Promise<T>, onSlow: () => void, discloseAfterMs?: number): Promise<T>;
+/**
+ * Await `p` until the absolute epoch `deadline`, then give up with {@link GOVERNANCE_READ_STALLED}.
+ *
+ * Chunked, and deliberately so: the deadline is derived from a caller-declared environment lifetime, so
+ * the distance to it can exceed {@link MAX_TIMER_DELAY_MS} — a single timer armed for that distance
+ * would fire at once and abandon a perfectly healthy read. Each chunk re-reads the wall clock, so the
+ * decision is always made against the deadline itself rather than against an allowance computed once.
+ *
+ * Exported for its own unit pin (the same posture as the brain-call guardrail primitive): the
+ * behaviors below are clock behaviors, and only a virtual clock can assert them without spending the
+ * wall-clock time they describe. Not re-exported from the package index.
+ *
+ * An already-overdue deadline still gets ONE zero-delay pass: a promise that is settled (or settles in a
+ * microtask, which is every in-process store) must be allowed to win, because giving up on an answer we
+ * already hold would be a fabricated stall. The second pass is what makes the loop terminate.
+ */
 export declare function raceUntilDeadline<T>(p: Promise<T>, deadline: number): Promise<T | typeof GOVERNANCE_READ_STALLED>;
 export declare class Runner {
     private deps;
     readonly sessions: SessionStore;
+    /** Per-sessionId serialization so two tasks never mutate one session concurrently. */
     private sessionLocks;
+    /** service [403](a) — roots whose rewind-files snapshot hit `too_large`, with the refusal time.
+     *  A 20G workspace otherwise pays a full bounded tree-walk (stat tens of thousands of files) EVERY
+     *  task just to re-discover the same refusal; once too_large, skip further snapshots for that root
+     *  (announced once via onError). E19 semantics unchanged — rewind for that root was already
+     *  impossible. codex 131 审 C: TTL'd (30min), not permanent — a long-lived Runner over a tree the
+     *  user later SHRINKS re-probes instead of being locked out until restart.
+     *  RB-430-b: `skipAnnounced` makes the SKIP itself observable — one announcement per cooldown window,
+     *  so an operator can tell "this turn produced no snapshot" from "snapshots are working", without the
+     *  per-turn log spam the latch exists to prevent. Cleared with the entry when the window elapses. */
     private snapshotTooLargeRoots;
+    /** 飞轮 [492]② — task notifications born BETWEEN turns (run torn down / harness already idle), parked
+     *  per session and drained into the session's next run at its first boundary. Runner-lived (outlives any
+     *  single run, like the registry handles that produce into it); bounded + drop-disclosing, see
+     *  {@link PendingSessionNotifications}. Not checkpointed — the producing handles are process-local. */
     private readonly pendingSessionNotifications;
+    /** Parent effective-policy inheritance (same-process resume convenience): checkpoint token → the OPAQUE
+     *  `parentConstraints` the suspended leg ran under. Registered by `runTaskStream`'s result hook whenever a
+     *  run spawned WITH `internals.inheritedGate.parentConstraints` ends `suspended` (process-local closures
+     *  parked while the park is live — the same lifecycle posture as the subagent retain ledger's
+     *  `internalsSnapshot`). `resumeStream` consults it when the caller supplied no constraints, so a
+     *  same-process `runner.resume()` on a delegated child's checkpoint auto re-supplies the chain; a
+     *  CROSS-process resume (registry miss — a different Runner/process) still requires an explicit
+     *  `resumeStream(..., internals)` and fail-louds otherwise (`resume.parent_constraint_missing`).
+     *  Retention: entries are kept across an `env_failed` reopen (the same token is retried), evicted on an
+     *  observed `already_resolved` and by the FIFO cap — an evicted entry only ever degrades to the explicit
+     *  re-supply requirement (fail-loud), never fail-open. */
     private readonly parentConstraintRegistry;
     private static readonly PARENT_CONSTRAINT_REGISTRY_CAP;
     constructor(deps: RunnerDeps);
+    /** design/73 §1 v1 — fire `RunnerDeps.onTaskOutcome` through the single swallow-guarded chokepoint
+     *  ({@link emitTaskOutcome}: mechanical-tier only, throwing sink never breaks the caller). Public so
+     *  thin compositions OVER the Runner (`runGoal`) can emit at their terminal state without reaching
+     *  into private deps. */
     emitTaskOutcome(outcome: TaskOutcome): void;
+    /** design/141 件A — the deployment agent catalog (RunnerDeps.agents/builtinAgents), exposed READ-ONLY
+     *  so the Agent-tool lane (`createSubagentTool`) defaults to the SAME registry the workflow lane
+     *  consumes (single source; the types.ts "pass the same array" follow-on made structural). The array
+     *  is a fresh copy — a caller mutating it never rewrites this Runner's own deps; the definitions
+     *  themselves are the shared objects (frozen by convention, same as gateBaseline's posture). */
     get agentCatalog(): {
         agents?: AgentDefinition[];
         builtinAgents?: boolean;
         models?: Record<string, Model>;
     };
+    /** design/125 (codex 实现审 B1) — the deployment-level gating baseline, exposed READ-ONLY so thin
+     *  assemblers over the Runner (`runSpec`) can COMPOSE with it. The task-level engine semantic is a
+     *  WHOLE-SLOT override (`spec.toolPolicy ?? deps.toolPolicy`, same for hooks — prepare-task), so any
+     *  assembler that sets `spec.toolPolicy`/`spec.hooks` without folding these in silently shadows the
+     *  deployment baseline. Getter only — nothing here is writable from outside. */
     get gateBaseline(): {
         toolPolicy?: RunnerDeps["toolPolicy"];
         hooks?: RunnerDeps["hooks"];
     };
+    /** Acquire the lock for a sessionId; returns a release fn. New (undefined) sessions need no lock. */
     private acquireSessionLock;
+    /** [1463]① — one-shot brain-routed utility query (see {@link runSideQuery} for the full contract):
+     *  preserves system/multi-turn messages/tool DEFINITIONS, routes through the deployment's brain with
+     *  the same model resolution as tasks, returns real usage/model. No session, no tool execution, no
+     *  policy gate, no accounting — caller-trusted. */
     sideQuery(spec: SideQuerySpec): Promise<SideQueryResult>;
+    /** Run a task and stream live events; await `.result()` for the final TaskResult. `resume` (internal)
+     *  drives a design/45 durable resume through the same loop instead of a fresh objective prompt.
+     *  `internals` (internal, design/78 Slice-1) is a TRUSTED run-scoped channel for live per-task state the
+     *  Runner cannot see from `spec` (today: a `runRepairLoop` attempt's live `repairBundle`) — NOT a
+     *  `TaskSpec` field; undefined on the public path.
+     *  **Eager:** the task starts executing the moment this stream is constructed (fire-and-forget), NOT lazily
+     *  on first iteration — you do NOT need to pull events for the run (and its `finish()`/env teardown) to
+     *  happen. Iterating just observes events (the buffer is backpressure-free); `.result()` awaits completion. */
     runTaskStream(spec: TaskSpec, resume?: ResumeRun, internals?: RunInternals): TaskStream;
     private runLocked;
+    /**
+     * design/100 §E12 — the post-completion prompt-suggestion pass. Never throws (failures route to
+     * `onError(phase:"suggestions")` and resolve to `[]`), so it is fire-and-forget safe and `suggestions()`
+     * never rejects. Also fills the budget-excluded `stats.suggestions` line.
+     */
     private suggestNextPrompts;
+    /**
+     * design/101 §E19 — capture a working-tree snapshot of the just-finished turn, keyed by the leaf
+     * `SessionTreeEntry.id`. Best-effort + never throws (errors route to `onError(phase:"rewind")`). Runs against
+     * ANY ExecutionEnv (local or remote) when a `fileSnapshotStore` is wired (GATE-SPLIT, service [263]) — the
+     * snapshot is portable (env FileSystem ops). A deployment wanting VM-snapshot instead wires a VM-backed store.
+     */
     private snapshotTurn;
+    /** Run a task to completion and return a machine-readable result. */
     runTask(spec: TaskSpec, internals?: RunInternals): Promise<TaskResult>;
-    resume(token: CheckpointToken, outcome: ResumeOutcome, taskConfig: ResumeTaskConfig, internals?: RunInternals): Promise<TaskResult>;
-    resumeStream(token: CheckpointToken, outcome: ResumeOutcome, taskConfig: ResumeTaskConfig, internals?: RunInternals): Promise<TaskStream>;
+    /**
+     * Resume a task suspended at a durable approval gate (design/45 F4). The token came back as
+     * `TaskResult.checkpointToken` from a `status:"suspended"` run; `outcome` carries the human/external
+     * decision (`allow`/`deny`, with an optional `updatedInput` arg rewrite or `reason`); `taskConfig`
+     * **re-supplies** the same tools / model / policy the task ran with (a token cannot reconstruct tool
+     * implementations or the hand band — the session stores neither).
+     *
+     * Flow (§2.1): `get` the checkpoint → validate the outcome arm matches the gate (council #3) → **atomic
+     * CAS `resolve`**. *Winning the CAS is the sole trigger to execute the pending action* — so a double /
+     * concurrent resume of the same token loses the CAS and is rejected (`checkpoint.already_resolved`),
+     * never re-running the side-effecting tool. The winner rewinds the session to the suspension point,
+     * resolves the gated call (execute on `allow`, inject a denial on `deny`), closes the rest of the
+     * suspended batch as deferred, and re-enters the run loop with a continuation — returning a normal
+     * {@link TaskResult} (which may itself be `suspended` again with a fresh token).
+     *
+     * v1 serves only the `human`/`policy_ask` gate (F4). A `task_done` checkpoint (1C Path A) is not
+     * resumable here — the caller orchestrates that one and reads its handle directly.
+     *
+     * **🔒 Authorization boundary (design/80 D-2 / [122] invariant #1) — token-as-auth, scope is store-level
+     * isolation, NOT caller authorization.** `resume` is TOKEN-AS-AUTH: whoever presents a valid, still-`pending`
+     * checkpoint token resolves it. The scope passed to the store CAS is the checkpoint's OWN `cp.scope` (read
+     * off the row), so the store's scope-WHERE is store-level multi-tenant DATA isolation (one tenant's reaper /
+     * mis-scoped resolve can't touch another's row) — it does **not** verify that THIS CALLER is authorized for
+     * that scope. Authorizing the operator's principal against the checkpoint (the "tenant-B holding tenant-A's
+     * token must not resolve it" property) is the **caller's** responsibility: the BFF / supervisor service mints
+     * the principal, scopes the approval inbox to it, and only calls `resume` for a checkpoint that principal
+     * owns. The token's secrecy + single-use HMAC binding (D-G) is what keeps it from reaching the wrong tenant.
+     * A direct (non-BFF) client is BLOCKED until D-G's cryptographic principal binding — never trust a
+     * client-supplied principal/scope here.
+     *
+     * @throws {@link CheckpointError} `not_found` (no store / unknown token), `gate_mismatch` (outcome arm
+     *   ≠ gate, or an unsupported gate), `invalid_outcome` (decision-action binding failed — boundCallId/
+     *   boundInputHash mismatch, or a deny reason with a `</system-reminder>` tag), `reopen_revote` (an
+     *   env_failed re-resume supplied a decision ≠ the persisted winner), `reopened_concurrently` (the
+     *   optimistic-concurrency `rev` changed under a concurrent resolve/reopen — re-resume against current
+     *   state), `unsupported_version` (checkpoint newer than this worker / remote handle with no factory),
+     *   `already_resolved` (lost the CAS — idempotent no-op).
+     */
+    resume(token: CheckpointToken, outcome: ResumeOutcome, taskConfig: ResumeTaskConfig, 
+    /** RB-48② (1.404): same TRUSTED run-internals seam as {@link resumeStream} — the convenience wrapper
+     *  FORWARDS it (it used to silently drop a 4th arg, so a cross-process re-supply through resume()
+     *  looked wired but always failed `resume.parent_constraint_missing`). */
+    internals?: RunInternals): Promise<TaskResult>;
+    /**
+     * Streaming form of {@link resume}: runs the identical pre-CAS guards + atomic CAS, then returns the live
+     * {@link TaskStream} of the resumed run (its events + `result()`) instead of draining it to a final
+     * {@link TaskResult}. Use this when the resumed segment's tool/turn events must reach an event sink for
+     * observability parity with the original `runInBackground` stream (service [15]); `resume()` is the
+     * convenience wrapper that drains it. The guards + CAS run FIRST, so this rejects with the same
+     * {@link CheckpointError}s as `resume` *before* any stream is returned (winning the CAS is still the sole
+     * trigger to execute the pending action — a lost CAS rejects, never returns a re-running stream).
+     *
+     * **Eager (like {@link runTaskStream}):** once this resolves, the resumed run is already executing — the
+     * pending action runs exactly once and the run-loop tail's `teardownOwnedEnv` (service [325]) tears down the
+     * rebuilt remote env even if you never iterate the stream. So abandoning the returned stream is safe (no leak,
+     * no hang); it only means you
+     * don't observe the resumed segment's events.
+     */
+    resumeStream(token: CheckpointToken, outcome: ResumeOutcome, taskConfig: ResumeTaskConfig, 
+    /** service [371]①: the TRUSTED run-internals seam, symmetric with {@link runTaskStream} — a resume leg
+     *  otherwise has no `onForwardEvent`席位, so a subagent's task_progress ticks (child-isolated stream,
+     *  only exit = the forward sink) were unreachable on resume. Deployment-owned, never a TaskSpec field.
+     *  Parent effective-policy inheritance CONTRACT: a checkpoint whose `state.inheritedGate.
+     *  requiresParentConstraint` is true was suspended under inherited OPAQUE parent-policy constraints
+     *  (live ToolPolicy/onAsk closures — non-serializable); this is the ONLY seam that re-supplies them
+     *  (`internals.inheritedGate.parentConstraints`). Omitting them for such a checkpoint rejects pre-CAS
+     *  with `resume.parent_constraint_missing` (fail-loud; the checkpoint stays pending) — never a silent
+     *  resume with the ancestors' gate dropped — unless this SAME Runner spawned the leg (the spawn-time
+     *  registry auto re-supplies them; see `parentConstraintRegistry`). The re-supplied chain's LENGTH must
+     *  match the checkpoint's recorded `parentConstraintCount` (`resume.parent_constraint_mismatch`
+     *  otherwise). Most entries are policies the deployment authored and can hand straight back; a
+     *  hook-wired ancestor also contributes a PreToolUse SCREENING entry (issue #33) whose policy the
+     *  engine mints — rebuild that one with the exported `createPreToolUseConstraintPolicy(hook, env)`. The DATA half (ancestorRules/shellGate) rides the checkpoint itself and needs no
+     *  re-supply; on the resumed leg the CHECKPOINT snapshot is the trust floor — live internals may only
+     *  TIGHTEN it (per-entry rev-monotonic ancestorRules replacement, max-rank shellGate fold), never
+     *  displace it wholesale. TRUST BOUNDARY: `internals` is the DEPLOYMENT trust channel (the same tier as
+     *  `inheritedManifestScope` and every other RunInternals field) — the library caller is trusted to
+     *  re-supply the genuine chain; a caller able to invoke resumeStream already holds full Runner
+     *  authority, so constraint substitution here is outside the enforced threat model (the count check
+     *  catches shape MISTAKES, not a malicious trusted caller). */
+    internals?: RunInternals): Promise<TaskStream>;
+    /**
+     * design/45 resume step: with the harness idle and the branch rewound to the suspension leaf, resolve
+     * the gated tool call and close the rest of the suspended batch, all by appending `toolResult`s to the
+     * session (the next `harness.prompt(continuation)` replays them as context).
+     *  - `allow` → execute the pending tool ONCE (re-validating `updatedInput`/captured post-hook args),
+     *    append its real result. This deliberately bypasses the tool gate (the human already adjudicated)
+     *    and the PostToolUse hook (documented v1 gap — rare, acceptable).
+     *  - `deny` → append a model-readable denial result instead.
+     *  - the remaining batch siblings (#k+1..N) → deferred-reissue results (v1 doesn't blind-run them).
+     */
     private applyResumeDecision;
+    /** Resolve the single gated call of a resumed batch (design/45): execute it once on `allow`, or inject
+     *  a model-readable denial on `deny`. Appends exactly one `toolResult` for `pendingAction.toolCallId`.
+     *  `emit` streams `tool_start`/`tool_end` for the resolved call so a `resumeStream` observer sees the
+     *  approved tool actually execute (API#2 observability parity — service [15]/[37]; the gated call never
+     *  emitted execution events in the original run, it suspended at the gate before running).
+     *
+     *  RB-22 RULING (2026-07-18, deliberate — the $ counterpart of RB-21's walltime question): a HUMAN-
+     *  APPROVED call executes even when the $ budget is already exhausted (`maxCostMicroUsd` ≤ spent).
+     *  The tool execution itself consumes no model spend — the budget's coordinate is LLM cost, and the
+     *  very next turn boundary's budget gate stops the run — so the overrun is ≈0 while refusing would
+     *  WASTE the human approval (the review effort is already sunk). This deliberately differs from the
+     *  walltime ruling (RB-21: NOT exempt) on principle: wall-clock exhaustion endangers the write-out
+     *  window (time cannot be clawed back), $ exhaustion after an approved no-spend action endangers
+     *  nothing. Pinned in resume tests; do not "fix" this into a pre-execution budget check. */
     private resolvePendingCall;
+    /**
+     * design/84 Seam C — the cost-optimization compaction options threaded into BOTH `maybeCompact` call
+     * sites (within-task turn boundary + `finish()`). All three fields come from `RunnerDeps` (a trusted
+     * FUNCTION seam — never `TaskSpec`, which is serializable/durable-resumable/untrusted-caller). The
+     * Runner OWNS the consecutive-reuse counter (`prepared.compactionReuseRef`) so the
+     * `maxConsecutiveProviderReuse` drift guard spans the whole task across both sites: it FEEDS the current
+     * count in as `consecutiveProviderReuse`, and {@link recordCompactionReuse} updates it from the result.
+     * Returns `undefined` when no provider is wired (so the call site spreads nothing → byte-identical to
+     * the pre-design/84 behavior).
+     */
     private seamCCompactionOptions;
+    /** design/134 §3.2 — resolve the pre/postCompact lifecycle callbacks (whole-slot `spec.hooks ??
+     *  deps.hooks`, same resolution as the stop hook) and wrap each in a SWALLOW+TRACE shell before
+     *  threading them into maybeCompact. The wrapper owns the observability half of the R3 MED contract
+     *  (maybeCompact swallows defensively too, but has no sink): a throwing callback is reported via
+     *  `onError(phase:"hook")` and treated as absent; a `block` returned under a "forced" trigger is
+     *  reported as ignored (maybeCompact enforces the ignore — blocking a compaction the provider/trim
+     *  layer already demanded would kill the run). */
     private compactionHookOptions;
+    /** design/84 Seam C — fold a finished compaction's `reused` flag into the run-scoped consecutive-reuse
+     *  counter: a reused (provider) summary increments it, a real (LLM) summary resets it to 0. A no-op
+     *  compaction (`compacted:false`) leaves the counter untouched. No-op when no provider is wired. */
     private recordCompactionReuse;
     private finish;
+    /**
+     * design/48 remote seam + service [325]: tear down a per-task env minted by `executionEnvFactory` (e.g. a
+     * remote container, or a `withWorktreeIsolation` worktree) — this task owned its lifetime. Best-effort, like
+     * `mcp.dispose`: a `destroy()` failure must not break the run. Only `ownedEnv` (factory-produced) is destroyed;
+     * a caller-owned static `deps.executionEnv` outlives the task and is left untouched. The service control plane's
+     * reaper is the backstop for an env orphaned by a rare pre-teardown throw (same posture as `mcp`).
+     *
+     * Runs from the run-loop tail AFTER every env-reader (finish()'s compaction `attachWorkingFiles` +
+     * `snapshotTurn`'s rewind-files capture), so the working tree is still readable when they run. This ORDER is the
+     * fix for service [325]: the old in-`finish()` destroy ran BEFORE `snapshotTurn`, so a factory-minted
+     * remote/worktree lane snapshotted an already-destroyed env (plain host/static lanes were false-green).
+     *
+     * design/49 v1.5 / design/76 §2.5: a SUSPENDED (`suspendRef.token`) or `needs_review` (`reviewRef.token`) pause
+     * `suspendVM`-paused the env and persisted its `workspaceHandle` into the checkpoint — destroying it would
+     * discard the paused VM and make resume fail to restore. Skip teardown; `resume()` rebuilds + `resumeVM`s it. A
+     * cancelled pause is reaped via `TaskStream.destroy()` (design/51); an abandoned one is the service container
+     * reaper's backstop. The gate here MIRRORS the tail's reap-stash (same durable fact
+     * `suspendRef.token===undefined && reviewRef.token===undefined`), so exactly one path owns the env's fate.
+     */
     private teardownOwnedEnv;
 }
+/** Convenience: one-shot run with explicit deps (creates a throwaway Runner). */
 export declare function runTask(spec: TaskSpec, deps: RunnerDeps): Promise<TaskResult>;
 export type { TaskEvent, TaskStream };

package/dist/core/runner/session-file-state-replay.d.ts

@@ -1,7 +1,56 @@
+/**
+ * Rebuild the hands' read-before-write state from a session's own transcript (ruled 2026-08-05).
+ *
+ * `readFileState` is minted per TASK and, until this module existed, was only ever re-seeded from a
+ * durable-resume checkpoint. An ordinary session CONTINUATION — a new `runTask` carrying the previous
+ * `sessionId` — therefore started blind: turn 1 Read the file, turn 2 was told "File has not been
+ * read yet", and every file cost a re-read round-trip on every turn of a long conversation.
+ *
+ * The transcript already records what is needed, so no new persisted surface is minted here: the
+ * tool results carry the file's whole text in their `details` card. This module walks those records
+ * and reports, per file, the LAST content the transcript can prove — the caller turns each into a
+ * read-state entry whose staleness hash is computed from THAT text.
+ *
+ * Two rules make the reconstruction safe rather than merely convenient:
+ *
+ *  1. **The content never comes from disk.** Every hash the caller derives from these records is a
+ *     hash of what the transcript recorded. A file changed between the turns (by the user, a linter,
+ *     a `git checkout`, a bash command — anything this transcript does not record) therefore fails
+ *     the staleness comparison and the edit is refused, exactly as it is inside a single task. A
+ *     reconstruction that re-read the file to build its hash would instead wave the dirty edit
+ *     through; that is the one thing this module must never do.
+ *  2. **Only WHOLE-file records qualify.** A partial read, a notebook projection or an `Edit` result
+ *     does not carry the file's full post-condition text, so there is nothing to hash honestly.
+ *     Those files are simply not reported: the gate then behaves exactly as it does today (the model
+ *     re-reads), which is the pre-existing cost, not a new failure.
+ */
 import type { AgentMessage } from "../../internal/harness.js";
+/** The whole text of one file at the moment the transcript recorded it. */
 export interface TranscriptFileRecord {
+    /** The path as the tool recorded it — absolute (see {@link wholeFileRecordsFromTranscript}). */
     path: string;
+    /** The file's ENTIRE text at that moment, in the decoded coordinate the fs tools hash. */
     content: string;
+    /** The recording tool result's own timestamp — the most honest "last read at" available. */
     at: number;
 }
+/**
+ * Per-file, the last whole-file content the transcript proves — in transcript order, last record wins.
+ *
+ * Records are read only from SUCCESSFUL results (an `isError` result changed nothing and proves
+ * nothing). A `Write` proves the post-condition it just persisted; a whole-file `Read` proves what it
+ * just served. An `Edit` result proves that the file CHANGED without recording its new text, so it
+ * retracts whatever an earlier record said — leaving a stale entry behind would blame the user for
+ * the agent's own edit ("modified since read") the next turn. Anything else (partial reads, dedup
+ * stubs, notebook projections, image/document reads, foreign tools) is inert: it neither proves nor
+ * retracts, because reading a file does not change it.
+ *
+ * The parameter is the session's own message lane (`AgentMessage`, custom lanes included) rather than
+ * the narrowed model-facing union: this reads the branch as the session stores it, and every lane that
+ * is not a tool result falls out on the first line of the loop.
+ *
+ * Paths are reported only when the tool recorded an ABSOLUTE one. A relative spelling was resolved
+ * against the tracked working directory of that moment, which this task cannot reconstruct; re-
+ * resolving it here could key the entry to a different file.
+ */
 export declare function wholeFileRecordsFromTranscript(messages: readonly AgentMessage[]): TranscriptFileRecord[];

package/dist/core/runner/session-rule-policy.d.ts

@@ -2,9 +2,67 @@ import type { ExecutionEnv } from "../../internal/harness-types.js";
 import type { ToolEffect } from "../types.js";
 import { type NamedToolPolicy } from "../tool-policy.js";
 import type { SessionPermissionRules } from "../session-policy-store.js";
+/** Tool names whose write target is the `file_path`/`path` arg ({@link fileArgPath}).
+ *
+ *  REF-B3 — the ONE definition of that narrower set. Production consumer today:
+ *  `createActiveSkillScopePolicy` (runner/active-skill-scope.ts, manifest `allowPaths`). The
+ *  `allowDirs`/fs-write faces consume the superset {@link PATH_CONFINABLE_WRITE_TOOLS} instead.
+ *
+ *  BOUNDARY: this set stays `file_path`-keyed — its members' write target is read by {@link fileArgPath}.
+ *  `NotebookEdit` (whose target is `notebook_path`) lives in the superset
+ *  {@link PATH_CONFINABLE_WRITE_TOOLS} below, NOT here: `createActiveSkillScopePolicy` reads THIS set and
+ *  deliberately keeps fail-closed-denying notebooks under a manifest `allowPaths` fence (widening the
+ *  skill face is a separate capability decision with its own review). */
 export declare const PATH_WRITE_TOOLS: ReadonlySet<string>;
+/** The FULL path-confinable write-tool set: {@link PATH_WRITE_TOOLS} plus `NotebookEdit`, whose write
+ *  target is `notebook_path` and is extracted by the shared tool-aware {@link writeTargetPath} ([886]①b —
+ *  notebook_path outranks a decoy `file_path` for that tool).
+ *
+ *  REF-B3 — the ONE spelling of "tools this codebase can confine by path". Consumers:
+ *  {@link createSessionRulePolicy} (below, `allowDirs`) and `createFsWriteGatePolicy`
+ *  (core/fs-write-gate-policy.ts), which used to rebuild `[...PATH_WRITE_TOOLS, "NotebookEdit"]` inline.
+ *  A fourth spelling survives as a LITERAL in core/tool-policy.ts (the transcript-dir gate) because THIS
+ *  module imports tool-policy.ts — that one is a documented coordinate held in sync by a source-scan pin
+ *  (SW-10), not a silent copy.
+ *
+ *  SW-10 relax (ruled 2026-08-04): `NotebookEdit` was previously absent from the session-rule face's
+ *  covered set, so an `allowDirs` confinement denied it OUTRIGHT via the "mutating but not path-confinable"
+ *  arm — a capability GAP relative to the fs-write gate, which has always proven the tool confinable.
+ *  Both faces now share this set and the same target extractor, so the session face confines notebooks by
+ *  path instead of refusing them. The fail-closed deny for every OTHER non-confinable mutating tool
+ *  (bash, deployment-authored write tools, unknown effects) is unchanged. */
 export declare const PATH_CONFINABLE_WRITE_TOOLS: ReadonlySet<string>;
+/** Path-segment-aware containment, FAMILY-AWARE ([K-PLATFORM-SWEEP] MAJOR#2: canonical keys are
+ *  backslash-form on a win32 env — the "/"-hardcoded suffix rejected every legitimate write there).
+ *  Compare in "/" form with drive-letter case folded; never keyed on process.platform (the env may be
+ *  remote and of the OTHER family than the host).
+ *
+ *  REF-B3 — exported as the single source for the policy modules that fence WRITES by an allowlist of
+ *  directories: active-skill-scope.ts (manifest `allowPaths`) and fs-write-gate-policy.ts (`acceptDirs`
+ *  /`exemptDirs`), plus the K-PLATFORM sweep tests. The line here used to read "exported ONLY for the
+ *  K-PLATFORM sweep tests", which was already false when written (fs-write-gate-policy.ts imports it in
+ *  production), and active-skill-scope.ts carried a byte-identical private twin — comment included — so
+ *  a platform-family fix had to be remembered at two coordinates.
+ *
+ *  The sibling implementation is `within()` in tools/fs/safety.ts (the fs-tool root fence). Those stay
+ *  separate functions on purpose — that one is private to the fence and keyed on canonical roots — but
+ *  they must never disagree on a verdict; the empty-root arm below is that alignment. */
 export declare function isWithin(root: string, p: string): boolean;
+/**
+ * Build the per-session deny-narrowing policy. For each tool call:
+ *  - `toolDeny` → deny the listed tools.
+ *  - `toolAllow` (if set) → deny any tool NOT listed (a narrowing allowlist).
+ *  - `commandAllow`/`commandDeny` → delegate to {@link createCoarseCommandNamePolicy} (argv[0] names; only
+ *    speaks about shell tools). allowlist mode denies the un-listed/un-parseable; blocklist mode asks on the
+ *    un-parseable bypass surface (the gate decides).
+ *  - `allowDirs` (if set) → a WRITE tool must land inside one of the dirs (resolved via `canonicalizeTarget`,
+ *    so a symlink can't smuggle a write out); a write-capable tool that cannot be path-confined (e.g. `bash`)
+ *    is DENIED while `allowDirs` is set (fail-closed, mirrors active-skill-scope MAJOR-2).
+ * Returns `allow` when nothing constrains the call. `env`/`rootPath` are the task's real exec env + root, so
+ * matching sees the actual filesystem (a remote/E2B task resolves in its container). RB-108: a relative
+ * TARGET prefers the call's live tracked cwd ({@link ToolCallRequest.cwd}) when the engine stamps one;
+ * `allowDirs` entries always resolve against `rootPath`.
+ */
 export declare function createSessionRulePolicy(rules: SessionPermissionRules, opts: {
     env: ExecutionEnv;
     rootPath?: string;

package/dist/core/runner/strict-output-schema.d.ts

@@ -1,4 +1,5 @@
 import type { TSchema } from "typebox";
+/** Port of 204 `Lqn` — derive the strict form of a whole schema (root must be `type:"object"`). */
 export declare function deriveStrictSchema(schema: unknown): {
     ok: true;
     schema: Record<string, unknown>;
@@ -6,15 +7,29 @@ export declare function deriveStrictSchema(schema: unknown): {
     ok: false;
     reason: string;
 };
+/** Exposed for callers that only need validity (no derivation). Runs the size guard first. */
 export declare function validateJsonSchemaShape(schema: unknown): string | null;
-export type CompiledOutputSchema = {
+export type CompiledOutputSchema = 
+/** The schema is not a valid JSON Schema (or too large) — callers must FAIL FAST, never run silently. */
+{
     error: string;
-} | {
+}
+/** Strict derivation succeeded: `modelSchema` is the tightened form to hand the model. */
+ | {
     modelSchema: TSchema;
     strict: true;
-} | {
+}
+/** Valid but outside the strict subset: serve the schema as-is; `fallbackReason` is the observable why. */
+ | {
     modelSchema: TSchema;
     strict: false;
     fallbackReason: string;
 };
+/**
+ * Validate + strict-derive a structured-output schema (CC 2.1.205 semantics):
+ *   invalid / oversized schema → `{error}` (the caller throws — no silent acceptance);
+ *   in-subset schema → `{modelSchema: strictForm, strict:true}` (`additionalProperties:false` stamped);
+ *   valid-but-unsupported schema → `{modelSchema: original, strict:false, fallbackReason}` (observable).
+ * A derivation CRASH also falls back non-strict (CC's inner try/catch), never fails the task.
+ */
 export declare function compileOutputSchema(schema: TSchema): CompiledOutputSchema;