@sema-agent/core 5.19.0 → 5.21.0

package/dist/core/runner/prepare-task.d.ts

@@ -27,20 +27,107 @@ import { type WiringManifest } from "../wiring-manifest.js";
 import type { ActiveWorktreeSession, AgentMessage, AgentTool, ExecutionEnv } from "../../internal/harness.js";
 import type { NestedUsageAccum, RunnerDeps, TaskEvent, TaskLimits, TaskResult, TaskSpec, ToolActivity, ToolEffect } from "../types.js";
 import type { RepairBundle } from "../../agents/repair-loop.js";
+/**
+ * design/164 — validate `TaskSpec.limits` at the door and return it unchanged.
+ *
+ * Two refusals, both fail-loud (the {@link resolveStallTimeoutMs} posture: a bound nobody can evaluate is
+ * not a bound, and folding it to a default would silently run the task under limits nobody chose):
+ *  - **unknown key** ⇒ `config.limit_unknown_key`. TypeScript already rejects a stale key, but a wire /
+ *    plain-JS caller does not go through TypeScript, and the retired names (`timeoutSec` above all) used
+ *    to be honored — accepting them silently is how a caller keeps believing a limit is armed when the
+ *    engine has stopped reading it.
+ *  - **unevaluable numeric value** (non-number / non-finite / negative) ⇒ `config.limit_invalid`, naming
+ *    the key. `0` is legal on every numeric axis: on `maxTurns` it is the documented "unbounded"
+ *    sentinel, and on the budget axes it is an exhausted window (absurd but honest).
+ */
 export declare function resolveTaskLimits(limits: TaskLimits | undefined): TaskLimits | undefined;
+/**
+ * design/164 件四 — how long before an execution environment's declared `lifetimeMs` expires the engine
+ * stops the run and checkpoints it. The margin has to cover ONE suspend: pausing/snapshotting the
+ * workspace, minting the checkpoint, committing it durably, and letting the loop stop cleanly — with
+ * room for a slow durable store. 60s is generous for that work and small next to any real sandbox
+ * lifetime (the shortest tier observed in the platform survey is minutes), so it neither truncates the
+ * task nor risks losing the race with the platform's reclaim.
+ *
+ * It is an ENGINE constant, not a knob: an adapter that wants a wider safety band declares a shorter
+ * `lifetimeMs` (it owns the platform fact), and one number that every deployment shares keeps the
+ * checkpoint-cost calibration in one place.
+ */
 export declare const ENV_LIFETIME_SUSPEND_MARGIN_MS = 60000;
+/**
+ * design/164 件五 — how long AFTER a governance window frees a `usage_window` checkpoint stays reapable-free.
+ * The retention TTL answers "was this abandoned?"; a usage-window suspend is not abandoned while the window
+ * it waits on is still full, so its deadline is pushed to `retryAfterMs + this`. One hour gives a host's
+ * scheduler a realistic chance to pick the resume up (a cron tick, a queue drain) before the row is
+ * treated as garbage — small next to the 30-day retention it is compared against, and large next to any
+ * polling interval a driver would sanely use.
+ */
 export declare const USAGE_WINDOW_REAP_MARGIN_MS: number;
+/**
+ * design/164 件五 — the run's view of deployment usage governance, built once at prepare when
+ * `RunnerDeps.usageWindows` + `usageWindowStore` are both wired (absent otherwise, so every consumer is
+ * an explicit `!== undefined` test and an ungoverned deployment executes not one extra line).
+ *
+ * Both methods are called SEQUENTIALLY by the run loop (entry check, then one commit per turn boundary,
+ * then one final commit) — the delta bookkeeping in `commit` assumes that and is not a concurrency
+ * primitive.
+ */
 export interface UsageGovernance {
+    /** The ledger key this run is governed under — the principal, or the shared global key. */
     readonly key: string;
+    /** Ms the caller must wait before ANY window would admit work again, or `undefined` when none is
+     *  exhausted as of `now`. Reads the ledger; propagates a store failure (an unreadable ceiling must not
+     *  read as an open one). */
     check(now: number): Promise<number | undefined>;
+    /** Charge whatever of `cumulativeTokens` has not been charged yet. Takes the run's CUMULATIVE total
+     *  rather than a delta so no caller can double-charge by calling twice, and so a caller that skips a
+     *  boundary loses nothing. */
     commit(cumulativeTokens: number, now: number): Promise<void>;
 }
+/**
+ * design/164 件四 — resolve the moment an env's lifetime EXPIRES (epoch ms), or `undefined` when the env
+ * declares none / cannot be aged. Split out as a pure function so the anchor rules are testable and
+ * stated once.
+ *
+ * Honesty of the anchor, in order of preference:
+ *  1. `env.lifetimeStartedAt` — the platform's own answer. The only anchor that survives an env being
+ *     older than this run (a shared static env, or a sandbox restored from a snapshot).
+ *  2. `observedAt` — when this run's `executionEnvFactory` MINTED the env. Exact only for that case,
+ *     which is why the caller passes it only then.
+ *  3. Nothing — an env that declares a lifetime, self-reports no start, and was not minted here. The
+ *     lifetime is NOT enforced and the caller reports it, because the only remaining guess (task start)
+ *     OVERSTATES the remaining lifetime, i.e. errs toward the mid-turn kill this mechanism exists to
+ *     prevent. A silent under-estimate would be the wrong direction to fail in.
+ *
+ * An unevaluable `lifetimeMs` is refused (`config.env_lifetime_invalid`) rather than dropped — the
+ * `resolveTaskLimits` posture: an adapter that fumbled the units must not silently get no protection.
+ */
 export declare function resolveEnvLifetimeExpiry(env: ExecutionEnv, observedAt: number | undefined): {
     expiresAt: number;
 } | {
     unanchored: true;
 } | undefined;
+/** design/77 §4.4: the multi-tenant scope used when a durable suspend fires for an IRREVERSIBLE tool in an
+ *  unattended deployment that did NOT opt into `durableApproval` (so there is no caller-supplied scope). The
+ *  checkpoint carries this scope; resume reads it back from the checkpoint (`cp.scope`), so it is
+ *  self-consistent without needing the original `TaskSpec`. Kept distinct from any tenant key to make an
+ *  unattended irreversible suspend auditable as such. */
 export declare const DEFAULT_IRREVERSIBLE_SCOPE = "irreversible";
+/**
+ * design/153 §7.1 — the SINGLE derivation of a durable-suspend checkpoint's scope (both gate mint
+ * sites + the bg-watcher park lane's expire compensation/arbitration consume THIS; a re-derived copy
+ * that drifted was the exact bug the park tests caught — expire against the wrong scope silently
+ * no-ops). `|| DEFAULT` (not `??`): an EMPTY-string principal must not become a shared scope bucket.
+ *
+ * RB-75 (2026-07-25, red probe): that rule is stated twice in this file and was enforced on ONE of the two
+ * inputs — the principal half used `||`, the `durableApproval.scope` half used `??`, so an empty string
+ * arriving through the scope field (a config-centre / env lookup that came back blank is the realistic
+ * source) sailed through as the literal scope `""`. Two different tenants both landed in that one bucket,
+ * where `listByScope("")` reads BOTH their pending approvals — including each summary's `toolInput`
+ * preview of the raw arguments — and `reap("")` / `resolve(token, "")` act across both. `durableApproval.
+ * scope` is documented as "Multi-tenant isolation key … Required"; a blank string is the absence of an
+ * isolation key wearing its clothes, so both halves now fall through to the default isolation scope.
+ */
 export declare function checkpointScopeOf(spec: {
     durableApproval?: {
         scope?: string;
@@ -48,48 +135,121 @@ export declare function checkpointScopeOf(spec: {
     principal?: string;
 }): string;
 export { resolveCheckpointStore } from "../checkpoint-store.js";
+/** Everything the run loop needs, built once by {@link prepareTask} (task setup, isolated from the loop). */
 export interface Prepared {
     harness: AgentHarness;
+    /** The CONCRETE built-in session (engine-internal: prepare constructs/acquires `StoredSession` itself,
+     *  and the epoch pin path needs its `appendPromptEpoch`/`getPromptEpoch`). Public consumer faces take
+     *  the `Session` contract instead. */
     session: StoredSession;
     sessionId: string;
+    /** The ISOLATION-AWARE working-tree root for this task (a worktree's cwd when `isolation: "worktree"`, else
+     *  `deps.rootPath ?? executionEnv.cwd`) — the same value the hands/LSP/policy/restore use. The Runner's
+     *  rewind/snapshot path MUST key off THIS, not `deps.rootPath`, or a worktree-isolated turn snapshots the base
+     *  repo (CORE-1~9 audit MAJOR). */
     taskRootPath: string;
     model: Model;
+    /** Effective thinking level (explicit `spec.thinking` or the resolved role's default). */
     thinking?: ThinkingLevel;
     compModel?: Model;
     mcp: MaterializedMcp;
+    /** Present only when `spec.a2a` declared peers — the run loop owes it the same end-of-task dispose
+     *  it owes {@link mcp} (no sockets are held, but a disposed mount is what makes a post-task tool
+     *  call refuse loudly instead of dialing a peer on a dead task's behalf). */
     a2a?: MaterializedA2a;
     blockedRef: BlockedRef;
+    /** Holds the structured output once `submit_output` is called (when `spec.outputSchema` is set). */
     outputRef: OutputRef;
+    /** Fires when the task aborts (timeout / max turns / end). Passed to `ToolPolicy.check` so a
+     * pending human-approval gate is released instead of hanging past the deadline (F4). */
     abortController: AbortController;
+    /** Flipped if any session write lost the optimistic lock during the run → `errorCode = "conflict"`. */
     conflictRef: {
         hit: boolean;
     };
+    /** design/134 复审: tool-call ids the gate blocked (policy/hook/plan-mode deny) or suspended —
+     *  populated only while a consumer is wired (per-tool post hooks or postToolBatch). The runner's
+     *  batch collector DELETES on match (its tool_execution_end is the only end-event a blocked call
+     *  emits; the tool_result-side delete in prepare-task never fires for immediate results). */
     blockedToolCalls: Set<string>;
+    /**
+     * What ended the approval a gated call was waiting on, keyed by tool-call id — written ONLY by the
+     * tool gate, at the one exit where an ask resolved, and read once when that call's `tool_end` frame
+     * is minted (the reader deletes on read; a call the gate never settled has no entry).
+     *
+     * It is a sideband and not a field on the tool RESULT because a result is not a trustworthy carrier
+     * for this: `details` is arbitrary tool-authored data that post-tool hooks may also replace, so a
+     * failing tool could stamp `settledBy:"human"` on itself and tell a consumer's audit view that a
+     * person approved something nobody was ever shown. Provenance has to travel on a channel only the
+     * adjudicating layer can write. Same reason the entries are keyed by CALL id: the gate adjudicated
+     * that exact call, and the frame that reads it is that call's own.
+     */
     approvalSettledBy: Map<string, import("../tool-policy.js").ApprovalSettledBy>;
+    /** Summed usage of nested sub-runs (sub-agents) spawned by this task's tools. */
     nestedStats: NestedUsageAccum;
+    /** RB-430-a: prepare-time rewind disclosures (conversation-only branch / no snapshot backend / no file
+     *  env), echoed verbatim onto `TaskResult.rewindNotes`. Present only when there is something to say. */
     rewindNotes?: NonNullable<TaskResult["rewindNotes"]>;
+    /** design/99 §E13 — the per-task logical cwd ref when a real shell is mounted (else undefined). The Runner
+     *  reads `cwdRef.current` after each tool to detect a `cd` move and emit `workspace_changed`. */
     cwdRef?: CwdRef;
+    /** design/155: the ACTIVE EnterWorktree session ref (mounted with the worktree tools; undefined without
+     *  real write hands). runtask's settle write reads `current` for the workspace-state entry. */
     worktreeSessionRef?: {
         current?: ActiveWorktreeSession;
     };
+    /** design/155: the settle-write base — the canonical root + what the cwd/worktree were RESTORED to at
+     *  prepare. runtask diffs the live refs against this at settle and appends a `workspace_state` entry
+     *  when the state changed (skipped on a durable suspend — the checkpoint lane owns that state). */
     workspaceStateSettle?: {
         rootCanonical: string;
         restoredHandsCwd?: string;
         restoredWorktreeDir?: string;
         baselineUnknown?: boolean;
     };
+    /** design/99 §E6 — the DENY-NARROWING layers (session rules + skill scope, deny-only). Re-checked on RESUME
+     *  before an approved pending tool executes, so a rule tightened during the suspend still applies. */
     denyNarrowingPolicy?: ToolPolicy;
+    /** RB-63: the deployment's own caller policy, re-checked on a durable resume ONLY when the approver
+     *  rewrote the pending call's args (see the composition site for why the edit case is special). */
     basePolicyForResumeEdit?: ToolPolicy;
+    /** Removes the `spec.signal` abort listener on task end (else a long-lived signal leaks listeners). */
     releaseSignal: () => void;
+    /**
+     * design/174 — end-of-leg sweep for questions this leg's gate routed to a person. Called once by the
+     * run loop at task end, on every exit path. A binding that is still present means a person ANSWERED and
+     * the call never executed to collect it (aborted, batch torn down, loop threw): that answer is disclosed
+     * through the deployment's error sink rather than dropped, because "a human answered and it vanished" is
+     * precisely the failure this whole path exists to remove — it must not reappear inside the mechanism
+     * that removes it. Idempotent, never throws.
+     */
     settleContentAskBindings: () => ReadonlyArray<{
         deliveryId: string;
         toolCallId: string;
     }>;
+    /** Per-task prefix-cache-break detector (design/31). The fingerprint is mutated when deferred tools
+     *  materialize (design/36) — see `cacheFingerprint`. */
     cacheBreakDetector?: CacheBreakDetector;
+    /** The fingerprinted prefix. `systemPrompt` is stable; `tools` is REFRESHED in place when a deferred
+     *  tool is materialized (placeholder→full schema), so the design/31 detector sees the real tool set. */
     cacheFingerprint?: {
         systemPrompt: string;
         tools: ToolFingerprintInput[];
     };
+    /**
+     * 提示词主权批 — the labelled composition of the assembled system prompt, emitted as the
+     * `prompt.assembled` trace event at task start. `constitution` says who owned the safety layer:
+     * `"core"` (structural, the default), `"replaced"` (provider set `replaceAll` — deliberate opt-out),
+     * `"provider-assembled"` (migration guard: a historic provider returned a full prompt, passed through
+     * un-doubled + onError hint). Deployments/tests assert on this to make "which blocks were in the
+     * prompt" a runtime fact instead of archaeology.
+     */
+    /**
+     * design/173 §8.1 — this leg's EFFECTIVE wiring manifest (built once in prepare from resolved
+     * facts through the same derivation as the static half). runtask emits it as the
+     * `wiring_manifest` TaskEvent after the prepare consume point and before the leg's first
+     * model/tool interaction. Host/operator plane — never enters model context.
+     */
     wiringManifest: WiringManifest;
     promptManifest: {
         constitution: "core" | "replaced" | "provider-assembled";
@@ -98,6 +258,13 @@ export interface Prepared {
             chars: number;
             hash: string;
         }>;
+        /** Manifest v2 (campaign S1, additive): the compiled-IR section view (slot/carrier/cadence/
+         *  cacheClass per section). `contentHash` is the
+         *  digest-tiering face ([1050]②/[1057]): present ONLY on operator-declared sections (the typed
+         *  `stableBlocks` lane, owner "deployment") as an UNSALTED full sha256 of the section text —
+         *  the center-publish ↔ manifest end-to-end reconciliation anchor. Core-native sections (env
+         *  facts, memory tail, user role text) stay salted-only: a plain hash of a short guessable
+         *  block is a dictionary-preimage surface for trace readers (codex [E]). */
         sections?: Array<{
             id: string;
             slot: string;
@@ -108,15 +275,34 @@ export interface Prepared {
             hash: string;
             contentHash?: string;
         }>;
+        /** Campaign S2 (additive): the mounted tools plane — contract identity, durable-replay aliases,
+         *  presentation-invariant shape digest and full wire digest per tool (initial mount face). */
         tools?: ToolManifestRow[];
+        /** design/148 S3 (additive, §10.2): the nine-element cache identity — digests only, no prompt
+         *  text; backfilled once the final wire tool list exists. Live post-refresh truth rides
+         *  `prepared.turnSnapshot`. */
         snapshot?: {
             cacheIdentity: string;
             elements: import("../../prompt-assembly/turn-snapshot.js").CacheIdentityElements;
         };
+        /** design/148 S3 (additive, §10.1): the run's lowering record (version/wire form/known
+         *  intentional divergences — run-static v1, one brain serves every call). */
         lowering?: import("../../prompt-assembly/turn-snapshot.js").LoweringRecord;
+        /** design/168 (additive): the RESOLVED deferred-tool disclosure strategy for this leg and which
+         *  seat chose it. Absent when nothing is deferred (there is no disclosure to describe). */
         toolDisclosure?: ToolDisclosureManifest;
     };
+    /** [1068] ruling a — this run's provider-declared prompt sections (epoch declaration axis),
+     *  threaded to every compaction-boundary epoch selection so boundary re-pins hash the same
+     *  artifact identity as the prepare-time pin. Empty on declaration-free runs. */
     epochDeclaredSections: import("../../prompt-assembly/epoch.js").EpochDeclaredSections;
+    /** RB-31 (design/148 S2) — the compaction-boundary center-adoption seam (undefined = no source
+     *  wired or session not center-pinned). Returns the maybeCompact `centerAdoption` fragment or
+     *  undefined; `apply` runs post-CAS only (auto-compaction owns the ordering). Both
+     *  `epochDeclaredSections` and `promptOverheadTokens` on THIS object are mutated by a successful
+     *  adoption (read them at call time, never capture early). */
+    /** design/148 S3 — the LIVE nine-element identity face (refreshed by deferred materialization and
+     *  the RB-31 adoption swap); the manifest holds the prepare-time initial copy. */
     turnSnapshot?: import("../../prompt-assembly/turn-snapshot.js").TurnPromptSnapshot;
     centerCompactionCandidate?: () => {
         centerArtifactDigest?: string;
@@ -126,16 +312,62 @@ export interface Prepared {
         overheadTokensAfter: number;
         apply: (committedArtifactDigest?: string) => void;
     } | undefined;
+    /** Deferred-tool disclosure (design/36): the monotonic set of activated deferred-tool names. Empty
+     *  (and no `tool_search` injected) when nothing is deferred. Mutated by BOTH disclosure lanes across
+     *  the run — the injected `tool_search` and the RB-403 direct-call placeholder lane (default ON) —
+     *  under ONE shared activation critical section, plus resume seeding at prepare. A leg on which the
+     *  model never calls `tool_search` is therefore NOT quiescent. */
     activeTools: Set<string>;
+    /** RB-313 — the DECLARED deferred set (design/36 `classifyDeferred`, ghost names already pruned).
+     *  Present iff the task has deferred tools at all; `deferredToolNames − activeTools` is the
+     *  "undiscovered" census the tool_search_usage_reminder lane enumerates. Frozen at prepare time: a
+     *  name never leaves the deferred set, it only moves into `activeTools`. */
     deferredToolNames?: ReadonlySet<string>;
+    /** design/168 — the RESOLVED materialization strategy this run runs under (`true` = "static":
+     *  activation never swaps the placeholder; the real schema's only in-context carrier is the
+     *  ToolSearch result text). Consumed by the tools_delta boundary renderer, whose "full schemas are
+     *  loaded" wording is a statement about the tools block and is only true under swap. `false` when
+     *  nothing is deferred (the knob is inert then). */
     toolMaterializeStatic: boolean;
+    /** RB-403 — is the direct-call lane mounted on this run's placeholders (`TaskSpec.deferSelfResolve`
+     *  not disabled; default ON)? The SAME fact `createToolSearchTool` receives as `directCallEnabled`,
+     *  surfaced here so every model-facing face that describes what happens to a call on a
+     *  still-deferred tool reads ONE value — under the direct lane a schema-valid call executes rather
+     *  than failing, so an absolute failure claim is only true for the opt-out posture. `false` when
+     *  nothing is deferred (no placeholders, so the fact is inert). */
     deferDirectCall: boolean;
+    /** design/168 — is THIS deferred name on the static face? False under `"swap"`, and false under
+     *  `"static"` for a tool whose declaration the result-text carrier cannot hold (the per-tool
+     *  exemption: it materializes into the tools block instead). Read at call time — the roster is
+     *  mutated in place by MCP refresh, so renderability is a live fact. Absent when nothing is
+     *  deferred; a caller with no accessor has no deferred family to describe. */
     staticFaceFor?: (name: string) => boolean;
+    /**
+     * design/138 S1 — the MemoryEngine session (present iff `deps.memoryBackend` + `spec.memory.enabled`).
+     * `harvest` is the swallow-guarded boundary hook (task terminal in runtask + the checkpoint mint
+     * point in commitSuspendSaga): it runs the FULL gate set (containment/secret/caps/deletion fuse),
+     * commits entry patches to the backend, self-heals the derived index, and re-baselines (a second
+     * harvest of an unchanged session yields zero patches). It NEVER throws.
+     * S2-B (O-F7/C-F3): the report is NOT discarded — `harvest` hands it to the Runner-owned
+     * `deps.onMemoryHarvestReport` callback (with the boundary phase), and the engine itself enqueues
+     * the announcement-queue entry at its harvest tail (drained into the NEXT session's first inject —
+     * 时机①; the r1 in-run attachments lane was cut, O-F2/C-F4). `phase` defaults to "terminal" (the
+     * runtask call site passes nothing); the checkpoint-mint call site passes "checkpoint".
+     */
     memoryEngineSession?: {
+        /** The WRITE-plane pair (design/142 S2b: dual roots collapse to one session face; these are the
+         *  plane that owns the write gate — the read-only plane is internal to `inject`/`harvest`). */
         engine: MemoryEngine;
         handle: MemorySessionHandle;
+        /** Merged injection across all planes (single-root sessions: identical to engine.inject(handle)). */
         inject: () => import("../memory-engine/engine.js").MemoryInjection;
         harvest: (phase?: "checkpoint" | "terminal") => Promise<HarvestReport | undefined>;
+        /**
+         * design/178 §3 — the session's ONE-WAY pollution face. `markPolluted` fires when an
+         * external-content-class tool is invoked (the prepare-time tool wrap below is the caller);
+         * durable + in-process, no unmark exists at any layer. `polluted` is what the harvest legs read
+         * (they consult it at harvest time themselves — this accessor serves observers/tests).
+         */
         pollution: {
             polluted: () => {
                 at: number;
@@ -143,37 +375,81 @@ export interface Prepared {
             } | undefined;
             markPolluted: (reason: string) => void;
         };
+        /** design/178 §3 — the task's content-safety config (normalized memory spec): the allowlist for
+         *  UNDECLARED tools and the strict execution-class upgrade. Consumed by the tool wrap only. */
         contentSafety: {
             trustedTools: ReadonlySet<string>;
             execIsExternalContent: boolean;
         };
     };
+    /** A per-task env minted by `RunnerDeps.executionEnvFactory` (design/48 remote seam) that THIS task owns
+     *  and the Runner must tear down on task end. Undefined when the env came from a (caller-owned) static
+     *  `deps.executionEnv` or the stub — those outlive the task and must NOT be destroyed here. */
     ownedEnv?: ExecutionEnv;
+    /** design/45: a mutable holder the durable-suspend gate writes when a policy `ask` was checkpointed
+     *  (capture + abort). The run loop reads it to assemble `status:"suspended"`. Empty unless a suspension
+     *  fired this run. */
     suspendRef: {
         token?: CheckpointToken;
         gate?: CheckpointGate;
         scope?: string;
         restoreMode?: "snapshot" | "park_only";
     };
+    /** Ruled 2026-08-05 (matrix ruling arm A): set true by the resume engine when this leg EXECUTES the
+     *  approved pending call — the restart-loop cap then counts from a fresh base (consecutive
+     *  no-progress suspends only). See `suspendChainBase`. */
     suspendProgressRef: {
         executedApproved: boolean;
     };
+    /** design/76 §2.5 (dry-run / shadow) + design/80 D-B (plan-gate): the DUAL of {@link suspendRef} for the
+     *  REVIEW-PAUSE family — a `{kind:"needs_review"}` pause (a profile's dry-run interception committed a
+     *  checkpoint whose predicted state-diff a human/judge must REVIEW) OR a `{kind:"plan_review"}` pause (a
+     *  profile's plan-gate committed a checkpoint whose proposed PLAN a human must approve/edit/reject). The
+     *  commit-side discriminant (`publishCommittedSuspend`) writes HERE for a `needs_review` OR `plan_review`
+     *  gate and into {@link suspendRef} for every other gate kind — **never both** (else assemble-result's slot
+     *  8.6 `needs_review` branch is dead code, v4 MAJOR-A). The run loop reads it to assemble
+     *  `status:"needs_review"`. Empty unless a review pause fired this run. */
     reviewRef: {
         token?: CheckpointToken;
         gate?: CheckpointGate;
         scope?: string;
         restoreMode?: "snapshot" | "park_only";
     };
+    /** RB-439-a: the remote-workspace lifecycle failures this run hit, appended in call order and echoed
+     *  verbatim on `TaskResult.remoteEnvFailures`. A shared array (not a per-call return) because a suspend
+     *  refusal is reported through the deployment's `onError` side channel and the run then continues or
+     *  stops by its own rules — without this collector the caller's result kept no trace that a durable
+     *  suspend was even attempted, let alone which of the eleven codes refused it. Empty unless something
+     *  failed. Resume-leg failures do NOT land here (that leg throws out of prepare before a `Prepared`
+     *  exists) — they ride the thrown error's `remoteEnvFailure` carrier instead. */
     remoteEnvFailures: NonNullable<TaskResult["remoteEnvFailures"]>;
+    /** design/72 §2.2 (B): set when a suspend was REFUSED because the task already suspended `maxSuspends`
+     *  times (a resume/restart loop) — the run is aborted and assembles as `failed`/`suspend.loop` instead
+     *  of minting yet another checkpoint. */
     suspendLoopRef: {
         hit: boolean;
     };
+    /** design/74 Slice 3c: opt-in resource-slice suspend. Present (≠ undefined) ONLY when the task opted in
+     *  (`spec.resourceSuspend`) AND it is eligible to suspend durably (a checkpoint store, durable tool
+     *  results, and a remote — or static caller-owned, never per-task-stub — env). The run loop calls it at a
+     *  CLEAN turn boundary when a resource limit (turns/budget/walltime) was hit: it mints a `resource_limit`
+     *  checkpoint + pauses the workspace + stops the loop cleanly (NOT abort). Returns true iff it committed a
+     *  resumable checkpoint (sets `suspendRef`); false ⇒ caller falls through to normal limit handling.
+     *  `sliceSpend` (Slice 4) is THIS slice's cost/tokens/turns, debited onto the cross-slice ledger. */
     suspendForResource?: (reason: ResourceLimitReason, sliceSpend: {
         costMicroUsd: number;
         tokens: number;
         turns: number;
         walltimeMs: number;
     }) => Promise<boolean>;
+    /** design/164 件四/件五: the PLATFORM-cause suspend — the same commit saga as {@link suspendForResource},
+     *  exposed on the INFRASTRUCTURE alone (checkpoint store + durable tool results + remote/no owned env),
+     *  WITHOUT the `spec.resourceSuspend` opt-in. The run loop calls it at a clean turn boundary when the
+     *  execution environment is about to be reclaimed (`env_lifetime`) or a deployment usage window is
+     *  exhausted (`usage_window`) — causes the task did not choose and cannot ask differently for, so a
+     *  deployment that CAN keep the work has no reason to be asked whether it wants to. `hint.resumeAfterMs`
+     *  (usage windows only) rides the gate and extends the checkpoint deadline. Returns true iff it committed
+     *  a resumable checkpoint; false ⇒ the caller stops the run LOUDLY with the cause's terminal code. */
     suspendForPlatformLimit?: (reason: PlatformLimitReason, sliceSpend: {
         costMicroUsd: number;
         tokens: number;
@@ -182,19 +458,53 @@ export interface Prepared {
     }, hint?: {
         resumeAfterMs: number;
     }) => Promise<boolean>;
+    /** design/164 件四 — epoch ms at which this run must stop and checkpoint because the EXECUTION
+     *  ENVIRONMENT's declared lifetime is about to expire (`ExecutionEnv.lifetimeMs` minus
+     *  {@link ENV_LIFETIME_SUSPEND_MARGIN_MS}). Undefined ⇒ the env declared no lifetime (every local env,
+     *  and any adapter on an unbounded host) or declared one the engine could not anchor — in both cases the
+     *  boundary check is dead code, exactly as it was before design/164. Epoch, not monotonic: the anchor
+     *  comes from the PLATFORM (an env can be older than this process), which is a wall-clock fact and the
+     *  one domain both sides can name. */
     envLifetimeSuspendAt?: number;
+    /** design/164 件五 — deployment usage governance for this run, or undefined when the deployment wired
+     *  none (or wired windows without a ledger, which is reported and not enforced). */
     usageGovernance?: UsageGovernance;
+    /** 1.296 件2b — epoch ms at which the loop ISSUED the current provider call (stamped by the
+     *  per-call stall-watchdog closure, consumed+cleared by runtask's brain.call trace row as
+     *  `callStartedAt`). Always present. */
     callIssuedAtRef: {
         current?: number;
     };
+    /** RB-458 — records the FIRST brain call this run's outer guardrail gave up on (see
+     *  {@link import("../../brain/timeout.js").withBrainCallGuardrail}). Always present; `timedOut`
+     *  stays absent unless the guardrail fired. The run loop reads it AFTER the loop settles and gives
+     *  the task the typed terminal — the harness turns a loop throw into an error assistant message, so
+     *  without this the cause would reach the caller only as the generic `provider.error`. */
     brainCallGuardrailRef: BrainCallGuardrailRef;
+    /** design/80 D-B — set by a tool calling `ctx.requestReview()` (the first-party `present_plan` tool, CC
+     *  ExitPlanMode parity): the run loop honors it at the next CLEAN turn boundary by minting a `plan_review`
+     *  checkpoint. `{ pending }` is set (with an optional reason) the moment a tool requests review; the boundary
+     *  reads + clears it. First request in a batch wins (idempotent). */
     reviewRequestRef: {
         pending?: {
             reason?: string;
         };
     };
+    /** design/80 D-B: present (≠ undefined) ONLY when a `checkpointStore` is wired (the deployment can pause). The
+     *  run loop calls it at a CLEAN turn boundary when `reviewRequestRef.pending` is set: it mints a `plan_review`
+     *  checkpoint (`status:"needs_review"`, routes to `reviewRef`) + pauses the workspace + aborts the loop, reusing
+     *  the SAME commit saga as the human/resource suspends. Returns true iff it committed a resumable checkpoint;
+     *  false ⇒ the request could not be honored (caller drops it and continues). */
     suspendForReview?: (reason?: string) => Promise<boolean>;
+    /** design/74 Slice 4: the prior cross-slice {@link ResourceLedger} (from the resumed checkpoint), so the run
+     *  loop can size this slice's effective budget = `min(maxCostUsd, remaining)`. Undefined on the first slice
+     *  (or a non-resource task). */
     resourceLedger?: ResourceLedger;
+    /** design/80 D-E-core (A3): a mutable holder the run loop populates (right after `stats` exists) so the
+     *  human/irreversible_ask suspend can debit THIS leg's live cumulative spend onto the durable approval
+     *  ledger it attaches (the resource-slice path passes `sliceSpend` explicitly; this event-driven gate has
+     *  no such arg, so it reads the live spend here). Read at suspend time; absent ⇒ this leg's spend is not
+     *  debited (the prior ledger still rides for the cross-leg READ). */
     liveSpendRef: {
         get?: () => {
             costMicroUsd: number;
@@ -203,6 +513,10 @@ export interface Prepared {
             walltimeMs: number;
         };
     };
+    /** design/91: the per-task human-review accumulator (synchronous `resolveAsk` waits this leg + the carried
+     *  prior-leg burden seeded from the resumed checkpoint). The run loop ADDS the durable-resume latency
+     *  (`now() − cp.suspendedAt`) on a resume, then surfaces it as `stats.humanReview` at assembly (omitted when
+     *  empty). **Budget-EXCLUDED** — never folded into cost/the budget gate (design/91 §1). */
     humanReviewRef: {
         count: number;
         totalWaitMs: number;
@@ -214,40 +528,123 @@ export interface Prepared {
             toolArg?: string;
         }>;
     };
+    /** design/91: the injectable wall-clock the run loop uses for the durable-resume human-review latency
+     *  (`humanLatencyMs = now() − cp.suspendedAt`), so it reads the SAME clock as the suspend-side `suspendedAt`. */
     now: () => number;
+    /** design/45 resume: the FULL resolved tool list (real tools, never deferred placeholders) so the
+     *  resume engine can execute a previously-suspended pending tool call directly (it bypasses the gate —
+     *  the human already adjudicated it). Same wrapping (offload + ctx) the harness runs with. */
     tools: AgentTool[];
+    /** Name→effect map for every tool this task can call (design/44 §3). Used by the abort-path orphan
+     *  reconcile (design/64 §9) to make interrupted tool_results effect-aware (read/idempotent = safe to
+     *  repeat; write/unknown = outcome unknown). Unknown names default to `write` (conservative). */
     toolEffects: Map<string, ToolEffect>;
+    /** scan-1/A5 — the orphans the WAKE/CRASH reconcile closed while preparing this run (empty on a fresh or
+     *  clean session). The run loop replays them onto the stream at run open as synthetic `tool_end` +
+     *  `message_committed` frames, the same pair the live-abort leg mints at run close: a previous PROCESS
+     *  died holding those calls, so this run's stream is the only place a consumer can ever learn they ended.
+     *  Not the live-abort set — that one is reconciled inside the run and never passes through here. */
     wakeRecovered: RecoveredOrphan[];
+    /** Fixed per-request prompt overhead (system prompt + tool schemas, ≈chars/4 tokens). Fed to
+     *  `maybeCompact.overheadTokens` so the compaction trigger stays accurate in the anchor-less
+     *  regime (custom Brains that don't report usage — design/64 §26.7). */
     promptOverheadTokens: number;
+    /** design/169-A — accessor for the MAIN lane's latest real brain request (systemPrompt/messages/
+     *  tools snapshot, recorded at the harness's provider seam just before each main-loop call). Fed
+     *  to `maybeCompact.forkContext` on all three compaction lanes so the summary request can FORK the
+     *  already-paid main prefix (CC form). `undefined` until the run's first main-loop call. Summary
+     *  calls themselves never pass through the recorded seam (they ride the separate compaction-brain
+     *  wrapper), so the snapshot is never polluted by a summary request. */
     lastBrainContext: () => CompactionForkContext | undefined;
+    /** Narrow workspace reader for compaction working-file attachments (LONGRUN-2): reads a task file
+     *  via the SAME env the hands ran against (so remote/k8s/E2B tasks read the container's tree, not
+     *  the control plane's). Present only when the hands are enabled — without an env there is no
+     *  workspace to re-read. null = unreadable (deleted/binary/transport error); callers skip it. */
     readTaskFile?: (path: string) => Promise<string | null>;
+    /** CC post-compact restore parity (2026-07-03): the task's READ files, most recent
+     *  first (from the hands' readFileState `lastReadAt` stamps). The compaction working-file
+     *  attachment prefers this over the modified set — CC restores what the model RECENTLY READ,
+     *  including untouched reference files. Present only with hands (same gate as readTaskFile).
+     *  RB-197: seeded entries are excluded — their content lives in the system-prompt lane, which
+     *  compaction never touches, so re-attaching them into the summary would be a duplicate. */
     recentlyReadFiles?: () => string[];
+    /** RB-197②(独立复审 + codex 命中,已修) — canonicalizes a raw (often relative, model-typed) path the
+     *  SAME way the hands toolkit does (`resolveKey` against the same containment root `readTaskFile`
+     *  uses), so `maybeCompact`'s kept-tail/instruction-source exclusions compare paths in the SAME
+     *  coordinate `recentlyReadFiles()` already uses — without this a plain string match silently never
+     *  fires for the common relative-vs-canonical case. Present only with hands (same gate as
+     *  readTaskFile); absent there is no containment root to resolve against, and every path source is
+     *  already in the same raw coordinate anyway. */
     normalizeAttachmentPath?: (raw: string) => Promise<string>;
+    /** RB-197②(codex 交叉复审命中,已修) — recognizes the hands Read tool's own dedup-stub markers
+     *  ({@link isReadDedupStubResult}), so `maybeCompact`'s kept-tail scan can tell a SUBSTANTIVE Read
+     *  result from a stub hit whose original full transmission may already be summarized away. Present
+     *  only with hands (same gate as readTaskFile). */
     isDedupStubResult?: (resultText: string) => boolean;
+    /** RB-197 (form-one; CC 220 clears readFileState at its compaction landing site, @388663): wired to
+     *  `MaybeCompactOptions.onApplied` by every compaction lane. Drops the non-seeded read-state entries
+     *  (the summary just replaced the Read results the dedup stubs point at) and re-registers the files
+     *  that were re-attached WHOLE. Present only with hands (same gate as readTaskFile).
+     *  RB-197②(codex 命中,已修): `preserveReadState` carries the kept-tail-visible files that were
+     *  deliberately skipped for re-attachment — their existing entry must survive the clear too (same
+     *  reasoning as a seeded entry: the model's view of the file did not change). */
     onCompactionApplied?: (attachedComplete: ReadonlyArray<{
         path: string;
         content: string;
     }>, preserveReadState?: ReadonlyArray<string>) => void;
+    /** design/121: the live diagnostics lane (present only when the gate passed — manager w/ registry +
+     *  write hands + not opted out). `registry` is drained by runtask at turn boundaries; `nudge` is
+     *  called (fire-and-forget) after each successful edit/write so the language server re-analyzes. */
     lspDiagnostics?: {
         registry: import("../lsp-diagnostics.js").LspDiagnosticsRegistry;
         nudge: (rawPath: string) => void;
+        /** This run's key into the registry's delivered set (the registry is DEPLOYMENT-scoped — one per
+         *  `NodeLspManager` — so "already delivered" has to be qualified by run). runtask passes it to every
+         *  `drain` and calls `releaseRun` with it at the run's terminal. */
         runIdent: string;
     };
+    /** design/133 件④: the live plan-mode flag (`enter_plan_mode` flips it, run-local one-way). Exposed
+     *  so the run loop's plan-mode attachment producer reads the SAME flag the write-deny enforces —
+     *  never a second source of truth. Always present (`active:false` when plan mode is unused). */
     planModeRef: {
         active: boolean;
     };
+    /** [915] A1 (design/66 anchor revision) — the date-flip detector seam: `legDate` = the date frozen
+     *  into this leg's system prefix; `today()` = the boundary-time LOCAL date (user-zone-bound closure).
+     *  The run loop feeds both to the `date_change` attachment producer; the prefix itself never
+     *  re-renders mid-leg (cache preservation, CC parity). Present only when the prompt carries a date. */
     dateChange?: {
         legDate: string;
         today: () => string;
     };
+    /** [A2] C-4 (design-A §4) — the loadProjectMemory snapshot's declared instruction sources
+     *  (`ProjectMemoryLoad.instructionSources`): the probe input AND the lane's per-path baseline
+     *  hashes for the run loop's `instructions_change` attachment. Present only when the deployment's
+     *  loader declared a non-empty list; the lane additionally requires
+     *  `RunnerDeps.probeInstructionSources` — either absent ⇒ zero probe calls, byte-identical. */
     instructionSources?: ReadonlyArray<{
         path: string;
         contentHash: string | null;
     }>;
+    /** The `workflow_size_guideline_change` lane's seam, the {@link dateChange} shape one lane over:
+     *  `legGuideline` = the RESOLVED guideline this leg's Workflow tool card was built with (the card is
+     *  a per-mount snapshot, so it never re-renders mid-leg — the model learns a retune from the tail
+     *  frame instead); `current()` = the boundary-time resolved guideline, read live off
+     *  `RunnerDeps.workflowLimits` so a deployment retuning it mid-run is observable without a re-prepare.
+     *  Present only when the Workflow tool is actually MOUNTED — a run with no workflow card has no
+     *  guideline to change. The direct-construction face (`RunWorkflowToolDeps.sizeGuideline`) is out of
+     *  scope by construction: this mount never passes it, so the deps channel is the lane's only source. */
     workflowSizeGuideline?: {
         legGuideline: WorkflowSizeGuideline;
         current: () => WorkflowSizeGuideline;
     };
+    /** design/133 F5 (§R3 决议): boundary-time external-change scan over the ≤`maxFiles` most-recently-READ
+     *  files. Stats each via `env.fileInfo` and reports paths whose `mtimeMs` moved past the recorded
+     *  `lastReadAt` + 2s epsilon (CC getChangedFiles shape: readFileState needs NO new field; the agent's
+     *  own write-backs refresh `lastReadAt`, so self-edits are immune). ENOENT evicts the readFileState
+     *  entry (CC evict-only-on-ENOENT — transient stat failures skip, never evict) and is echoed in
+     *  `evicted` so the caller drops its per-path dedup state in lockstep (LOW-9). Present only with
+     *  hands; the run loop calls it ONLY when `spec.attachments.changedFiles` opted in (OFF ⇒ zero stat). */
     detectExternalChanges?: (maxFiles: number) => Promise<{
         changed: Array<{
             path: string;
@@ -255,6 +652,21 @@ export interface Prepared {
         }>;
         evicted: string[];
     }>;
+    /** G1 通告层 — deferred tools MATERIALIZED (design/36 rematerialize) but not yet announced at a
+     *  turn boundary. Appended by the rematerialize diff (newly-activated names only — the announced set
+     *  is seeded with prepare-time actives INCLUDING resume-reseeded ones, so a resume never replays);
+     *  DRAINED by the run loop only when the `tools_delta` attachment actually survived the byte cap.
+     *  Present when the task has deferred tools at all — OR (RB-309) when a declared MCP server failed
+     *  to connect, so the failure is announceable even on a task whose every MCP tool went missing with it.
+     *
+     *  RB-309 — the same frame's MCP arms, filled by the SAME rematerialize seam / materialize-time
+     *  projection and drained by the same intact-survival predicate:
+     *  - `pendingRemoved`: previously-ANNOUNCED tool names that left the live roster (a RefreshMcpTools
+     *    re-splice whose server withdrew them). CC `removedNames`.
+     *  - `pendingReadded`: names in `pendingRemoved`'s history that came back on a later refresh. CC
+     *    `readdedNames`.
+     *  - `pendingFailed`: declared servers whose connect failed at materialize (`statuses`), name/error
+     *    neutralized + bounded at intake. CC `failedMcpServers`. */
     toolsDeltaRef?: {
         pending: string[];
         pendingRemoved: string[];
@@ -264,6 +676,16 @@ export interface Prepared {
             error?: string;
         }>;
     };
+    /** G1 通告层续批 (CC `agent_listing_delta` parity) — the mounted delegation tool's agent-type roster
+     *  (read off `ToolSpec.agentListing`, filled by createSubagentTool), plus the tool's mounted name for
+     *  the CC-verbatim headers. [c209-C]: this seam is now the roster's ONLY model-facing carrier —
+     *  the run loop delivers the initial full frame ON THE FIRST USER TURN (prompt-adjacent) and
+     *  boundary drift deltas after. `models` (Q4, read off `ToolSpec.agentModels`) rides the initial
+     *  frame's tail line. `seedAnnounced` = a durable-resume leg: the run loop seeds the producer's
+     *  announced set from the checkpoint's `announcedListings.agents` name-set when present (drift
+     *  since suspend IS delta-announced), else the MED-3② transcript probe (delivered ⇒ seeded as
+     *  the current entries; unconfirmed ⇒ the resume leg re-announces the initial listing). Present
+     *  only when such a tool is mounted AND its roster is non-empty. */
     agentListing?: {
         entries: ReadonlyArray<{
             name: string;
@@ -273,34 +695,88 @@ export interface Prepared {
         seedAnnounced: boolean;
         models?: readonly string[];
     };
+    /** [c209-C] skills_listing counterpart of {@link agentListing} — the normalized skills METADATA
+     *  projection (names/descriptions/attachment paths, never bodies; the exact list `createSkillTool`
+     *  serves). Initial full `<skills>` frame on the first user turn, drift deltas at boundaries,
+     *  same seeding contract. Present only when `spec.skills` is non-empty (post 1MB-gate). */
     skillsListing?: {
         entries: ReadonlyArray<SkillListingEntry>;
         seedAnnounced: boolean;
     };
+    /** [c209-C] Q5 — the run loop's live mirror of the listing frames' announced NAME-SETS (updated at
+     *  every commit point: first-frame delivery, intact boundary survival, resume seed). Read by the
+     *  suspend-time checkpoint serializer (`CheckpointState.announcedListings`) so a resume leg can
+     *  diff the then-current roster/skills against what the model actually saw. Always present (empty
+     *  object when nothing announced / no listing faces mounted). [c209-C] R2 C7: `models` mirrors the
+     *  ANNOUNCED model catalog the same way (advanced only when a committed frame carried one), so a
+     *  catalog change across a suspend is re-announced as a "Models available…" drift line. */
     announcedListingsRef: {
         agents?: readonly string[];
         skills?: readonly string[];
         models?: readonly string[];
     };
+    /** G1 通告层 — narrow post-compact getter over the process task registry: THIS run's visible
+     *  pending/running background tasks (same owner/scope/session identity the TaskOutput/TaskStop tools
+     *  use), as a bounded display projection (id/description/status — never handles/env/abort). Called by
+     *  the run loop ONLY when `spec.attachments.backgroundTasks` opted in AND a compaction just landed. */
     listBackgroundTasks: () => Array<{
         id: string;
         description?: string;
         status: string;
     }>;
+    /** design/122 D1 — the parent-run subagent-retain ledger (present ONLY when `spec.retainSubagentSessions`
+     *  is enabled). The Runner disposes it (abort in-flight resumes + unpin + release every retained child
+     *  session) in the task's terminal `finally` — same UNCONDITIONAL posture as the background-agent reap:
+     *  retain is NOT durable (a suspend leg's in-memory ledger cannot survive a re-prepare), so releasing on
+     *  every exit path is hygiene, never a loss. */
     subagentRetain?: SubagentRetainLedger;
+    /** design/84 Seam C: run-scoped consecutive-`summaryProvider`-reuse counter, OWNED by the Runner and
+     *  SHARED across both compaction call sites (within-task turn boundary + `finish()`), so the
+     *  `maxConsecutiveProviderReuse` drift guard is enforced over the whole task — incremented when a
+     *  compaction reused the provider's summary, reset to 0 on a real (LLM) summary. */
     compactionReuseRef: {
         consecutive: number;
     };
+    /** design/123 D4 — trim→compaction pressure propagation (16k live sawtooth root cause): set by the
+     *  context hook when `trimToBudget` actually DROPPED messages from a request view (request-only trim
+     *  + usage-anchor mismatch deflates the next boundary's estimate → the trigger and floor are both
+     *  deceived → full-size request spikes alternate with trimmed troughs). The next turn boundary's
+     *  `maybeCompact` consumes it as `force: true` (bypasses the auto threshold AND the §25.2 anti-thrash
+     *  floor — "the request layer was forced to drop history" is direct evidence compaction is overdue).
+     *  One-shot: cleared on consumption; a failed compaction does NOT re-arm it (existing breaker path).
+     *  Content-only clears (`clearStaleToolResults`) never set it — only real message drops do. */
     trimPressureRef: {
         droppedMessages: boolean;
     };
 }
+/**
+ * design/45 resume inputs threaded into {@link prepareTask} to continue a suspended task. The Runner
+ * builds it from the persisted {@link Checkpoint}: rewind the branch to the suspension leaf, skip the
+ * suspended batch during wake-reconcile, and re-seed the §4.bis per-task correctness state so the
+ * resumed run is in the **same state space** it suspended in.
+ */
 export interface PrepareResume {
+    /** The session leaf to rewind to (the suspension point) BEFORE reconcile — discards the abort's
+     *  off-branch "Operation aborted" writes so the resume engine resolves the pending batch cleanly. */
     leafId: string;
+    /** Batch tool-call ids of the suspended turn — wake-reconcile SKIPS these (they are resumed, not
+     *  crash-interrupted; closing them with `[INTERRUPTED]` would DESTROY the suspended batch, §15.2 #7). */
     suspendedBatch: ReadonlySet<string>;
+    /** The §4.bis correctness-state snapshot to re-seed (activeTools / outputRef / nestedStats /
+     *  consolidationNotes / readFileState). */
     seed: CheckpointState;
+    /** design/72 §2.2 (B): how many times this task already suspended (the resumed checkpoint's
+     *  `suspendCount`). The next suspend mints `priorSuspendCount + 1`; past `maxSuspends` it fails
+     *  (`suspend.loop`) instead of re-suspending. Absent/0 ⇒ no prior suspends. */
     priorSuspendCount?: number;
+    /** design/74 Slice 4: the cross-slice {@link ResourceLedger} carried by the resumed `resource_limit`
+     *  checkpoint (cumulative spend + the frozen human totals). The next slice's effective budget is
+     *  `min(maxCostUsd, totalBudget − spent)`, and its own suspend debits onto this. Absent ⇒ the first slice. */
     priorLedger?: ResourceLedger;
+    /** design/91: the accumulated human-review burden carried by the resumed checkpoint
+     *  ({@link import("../checkpoint-store.js").Checkpoint.humanReview}) — the gates resolved up to and including
+     *  the suspend BEFORE this one. Seeds the per-task accumulator so the resumed leg ADDS this suspend's own
+     *  latency (`now() − cp.suspendedAt`) on top, reporting the WHOLE chain's burden. Absent ⇒ no prior human time. */
     priorHumanReview?: {
         count: number;
         totalWaitMs: number;
@@ -312,30 +788,181 @@ export interface PrepareResume {
             toolArg?: string;
         }>;
     };
+    /** design/49 v1.5: when the suspend ran with a remote workspace, the {@link CheckpointState.workspaceHandle}
+     *  to restore — prepare rebuilds the per-task env via `deps.executionEnvFactory` then `resumeVM(snapshotId)`
+     *  + `postResumeInit()` (instead of running on a fresh, empty env). Threaded HERE (not via `ResumeTaskConfig`)
+     *  so the factory stays a deployment-level `RunnerDeps` capability and never pollutes `TaskSpec` — preserving
+     *  the "untrusted caller can't inject an env" red line (remote-env.ts:234, code-ready council round-2). */
     workspaceHandle?: import("../remote-env.js").WorkspaceHandle;
+    /**
+     * design/174 — the call id of the CONTENT ask whose answer an operator's approval was spent on, when
+     * that is what this leg redeems. Scoped as an id, not a leg-wide flag: an `unavailable` outcome on
+     * THAT call must become a coded failure (the approval bought a question nobody answered), while a NEW
+     * question raised later on the same leg had no approval spent on it and keeps the ordinary
+     * continuation. Absent when the resumed pending action is not a question.
+     */
     redeemedContentAskCallId?: string;
+    /** Digest of that question's batch — the id alone can repeat, so the pairing is what keeps a LATER
+     *  question from inheriting the claim that an operator approved it. */
     redeemedContentAskQuestionsHash?: string;
+    /** codex 1360 r6 — true iff this resume will EXECUTE an approved pending tool (`tool_approval`
+     *  checkpoint × an `allow` winner). The divergent-restore fail-closed guard keys on THIS, not on the
+     *  batch being non-empty: a deny winner executes nothing, so a workspace-root divergence must not
+     *  wedge the refusal (it proceeds under the path-state rebase and records the deny). */
     executesApprovedAction?: boolean;
 }
+/**
+ * Parent effective-policy inheritance (tighten-only, {@link RunInternals.inheritedGate}): the spawning
+ * chain's already-evaluated FINAL gate, split into two halves —
+ *
+ * - **Data half** (`ancestorRules`, `shellGate`): serializable snapshots. Each ancestor's per-session
+ *   permission rules ride as (sessionId, principal, rev, rules) so the child's prepare can re-read them
+ *   LIVE (rev-monotonic — a lagging replica never loosens the snapshot) and re-compile them against the
+ *   CHILD's own env/root/effects as extra deny-narrowing layers. `shellGate` folds by max-rank
+ *   (off < classify < always): a child can only tighten the parent's shell doctrine, never relax it.
+ * - **Opaque half** (`parentConstraints`): each ancestor's live caller `ToolPolicy` plus its FROZEN
+ *   `onAsk`, ancestors first — and, for a hook-wired ancestor, a SECOND entry: its PreToolUse screening
+ *   face folded into a `ToolPolicy` (`createPreToolUseConstraintPolicy`), carrying its own frozen
+ *   approver/mandate/env axes (the `preToolUse`/`hookEnv` fields below). Folded AFTER the child's own caller policy and BEFORE the trailing
+ *   deny-narrowing re-check, each wrapper resolving its own `ask` via the ancestor's frozen approver —
+ *   so a parent `ask` never widens into a child auto-allow, and a parent `allow{updatedInput}` rewrite
+ *   is still re-checked by the child's narrowing layers. NOT serializable: a durable resume must
+ *   re-supply it via `resumeStream(..., internals)` (see {@link CheckpointState.inheritedGate}).
+ *
+ * Chain assembly is single-sited in prepareTask's ctx injection (`inheritedGateForChildren`): upstream
+ * chain + THIS task's own contribution (its session-rule snapshot, its RESOLVED caller policy —
+ * `spec.toolPolicy ?? deps.toolPolicy`, the same slot its own gate enforces — + frozen onAsk, its
+ * effective shellGate, and — when this task resolved a PreToolUse hook — a screening entry for that
+ * hook, deduped by full installation so a deps-level hook is consulted once per call at any depth).
+ * Depth-N delegation is therefore a linear chain, each layer evaluated at most once per tool call.
+ */
 export interface InheritedGate {
+    /** Serializable ancestor session-rule snapshots (data half), ancestors first. */
     ancestorRules?: ReadonlyArray<{
         sessionId: string;
         principal?: string;
         rev: number;
         rules: SessionPermissionRules;
     }>;
+    /** The chain's effective shell-gate doctrine — the child folds it by max-rank with its own spec. */
     shellGate?: "off" | "always" | "classify";
+    /**
+     * Org-memory admission freeze (ruled 2026-08-05): the spawning chain's FROZEN admitted org-scope
+     * set — every org memory scope the parent actually mounted (deployment-origin + admitted request).
+     * A delegated child's REQUEST-origin org scopes must be a subset (intersection ≠ request ⇒ the
+     * child's prepare refuses, `memory.admission_denied`); deployment-origin scopes bypass the freeze
+     * (operator authority is deployment-wide). ALWAYS emitted by chain assembly (empty array = parent
+     * mounted no org plane), so an ABSENT field discriminates an older-shape chain — which the child
+     * side reads fail-closed as the empty set. Serializable (plain strings): persists on the
+     * checkpoint's data half and folds seed ∩ live on resume (tighten-only).
+     */
     admittedOrgScopes?: readonly string[];
+    /**
+     * The MONOTONIC org-governance provenance bit (adversarial round 5): `true` when any leg of this
+     * tree ran with an org-admission surface configured (resolver / deployment scope list) or
+     * inherited the bit. It never clears once set (a governed tree stays governed), and it counts as
+     * governance evidence at the admission door EVEN when every admitted set en route is empty — a
+     * governed parent's org-less child, resumed on a surface-less worker, must still refuse
+     * org-shaped non-v2 scopes instead of mounting them as opaque keys. Absent on trees that never
+     * had a governance surface (their opaque posture is untouched). Serializable; persists on checkpoints.
+     */
     orgAdmissionGoverned?: true;
+    /** Live ancestor caller-policy constraints (opaque half), ancestors first. `policy` is the ancestor's
+     *  RESOLVED caller policy (`spec.toolPolicy ?? deps.toolPolicy` — the same slot the ancestor itself
+     *  enforces, so a deps-level baseline is inherited too). `onAsk` is the ancestor's frozen
+     *  `spec.onAsk ?? deps.onAsk` — an ancestor `ask` resolves at that ancestor's own approver
+     *  (headless ⇒ deny), never at the child's. `durableMandate` is frozen at chain-assembly time when the
+     *  ancestor ran under a durable-approval regime that would actually PARK its own plain asks — a
+     *  `forceDurableGate` entitlement, or `durableApproval` with NO live onAsk frozen (with a live approver
+     *  the ancestor's own plain asks resolve synchronously there, so a descendant's ask resolves at that
+     *  same frozen `onAsk` — no mandate). It is a CONSERVATIVE descendant-side mandate: whether or not a given ask would actually
+     *  have parked at the ancestor (the regime may be scoped), the durable-park semantics cannot be
+     *  reconstructed in a delegated child's context — so a wrapper seeing `ask` under this flag denies
+     *  fail-closed (tighten-only holds) instead of resolving synchronously. */
     parentConstraints?: ReadonlyArray<{
         policy: ToolPolicy;
         onAsk?: OnAsk;
         durableMandate?: boolean;
+        /**
+         * Set ONLY on an entry whose `policy` is the folded form of an ancestor's PreToolUse screening face
+         * (issue #33 — the face used to stop at the task that installed it, so a call the ancestor had
+         * refused executed one level down). It carries the raw callback for ONE purpose: identity. A
+         * deployment-level face (`RunnerDeps.hooks`) is resolved by every task in the tree on its own, so
+         * each descendant's gate already runs it in phase 1 — folding it AGAIN as an inherited constraint
+         * would consult the same callback twice per call at depth 1 and once more per level below. Two
+         * identity tests keep that at exactly one consultation per call: chain assembly does not re-append a
+         * face already on the chain, and a descendant substitutes a pass-through for the entry naming the
+         * very callback its own gate will run. A per-task face (`TaskSpec.hooks`) is a different function in
+         * the descendant (or absent), so it folds and travels.
+         *
+         * Identity is the only sound test here, and it is deliberately the CONSERVATIVE one: an assembly that
+         * hands each task a freshly bound wrapper over one underlying callback (the `runSpec` mux does this)
+         * produces two distinct function objects, so the descendant both folds the ancestor's entry and runs
+         * its own — the callback is consulted twice rather than skipped. Erring toward a second screening,
+         * never toward a missed one, is what makes an identity miss a cost rather than a hole.
+         */
         preToolUse?: Hooks["preToolUse"];
+        /**
+         * The environment this screening face was installed against — the source of the `HookEnvCapabilities`
+         * handed to it, compared BY REFERENCE, `undefined` when the installation had no env face. Part of the
+         * installation's identity for the same reason the frozen approver is (codex review, HIGH): a face that
+         * resolves paths through `ctx.env` answers a different question in a different environment, so an
+         * ancestor running against the deployment's tree and a descendant running in an isolated worktree are
+         * two screenings, not one. A deployment with a per-task `executionEnvFactory` therefore has its face
+         * consulted once per environment on the chain rather than once overall — which is the point: the
+         * ancestor's environment is the only place the ancestor's verdict can be reproduced.
+         *
+         * ⚠️ RECORDED BOUNDARY (delegation provenance, codex review): the approver half of the key compares
+         * through {@link askApproverIdentity}, which by its own contract answers "the same decision-maker",
+         * collapsing a `withDelegationProvenance` wrapper onto the approver it forwards to. Two installations
+         * whose approvers differ ONLY in the provenance they attach therefore count as one. Raw reference
+         * equality is not an available alternative: a delegated child's approver is ALWAYS a fresh wrapper
+         * over its parent's, so raw equality would collapse nothing and a deployment-level face would be
+         * consulted once per ancestor level on every leaf call. The exposure is bounded on the side that
+         * matters — the pass-through arm hands the frame to the DESCENDANT's own gate, whose approver carries
+         * the descendant's own provenance (strictly more context, never less). What a chain-assembly collapse
+         * can drop is one intermediate installation's provenance on an ask: an approver that DECIDES on
+         * `req.delegation` would see the surviving installation's rather than both.
+         */
         hookEnv?: unknown;
     }>;
 }
+/**
+ * design/78 Slice-1 (MAJOR-3 wiring): a TRUSTED, run-scoped internal channel into {@link prepareTask}, set
+ * ONLY by a trusted CORE caller (`runRepairLoop` via the Runner's internal `runTaskStream` arg) — NEVER from
+ * a {@link TaskSpec} field (the untrusted-caller surface, design/44 §7 Q4). It is the live-state counterpart
+ * of {@link PrepareResume.seed}: where `resume.seed` re-seeds correctness state RESTORED from a checkpoint,
+ * this carries the LIVE per-task state the Runner cannot otherwise see (it lives in the caller's closure).
+ *
+ * Originally it carried only the repair loop's live {@link RepairBundle}: `runRepairLoop` is a thin composition
+ * OVER `runner.runTask`, so when an orthogonal durable suspend (resource/HITL) interleaves a repair attempt,
+ * the bundle (failureTrace/diagnostics/attemptCount/oracleTier) sits in the loop's closure and was being lost
+ * — the minted checkpoint serialized `repairBundle: undefined`. Threading it here lets
+ * {@link prepareTask}'s `serializeCheckpointState` source the LIVE bundle so a resume re-seeds `attemptCount`
+ * MONOTONICALLY (design/76 §2.2#1 r4 MAJOR-A). Mirrors how `nestedStats`/`resume.seed` thread trusted
+ * run-scoped internals through the Runner without touching `TaskSpec`.
+ */
+/**
+ * R2 双形轴(clay 追加令 2026-07-18): CC 2.1.212's fable-variant prompt gate (b9e —
+ * `fable_5_mitigations` capability / claude-mythos-5), ORTHOGONAL to the simple/classic profile.
+ * sema is BYOM, so the id may carry provider prefixes ("anthropic/claude-fable-5",
+ * "openrouter/anthropic/claude-fable-5"): BOUNDARY-AWARE family match on the last path segment
+ * (codex 统一复审 F3 — raw substring classified "vendor/not-claude-fable-5" and "claude-mythos-50"
+ * as fable), case-normalized. Recognition set = CC's _Nr (startsWith "claude-fable-") + b9e
+ * (mythos-5). R3 system sections fork on the resulting fact.
+ */
 export declare function isFableFamilyModelId(id: string): boolean;
+/**
+ * RB-50 (CC 2.1.220 启示①, clay 2026-07-25): the SINGLE decision point for the two prompt-shape axes.
+ * Both were resolved in separate places with different mechanisms — `promptProfile` off a TaskSpec field,
+ * `fableMitigations` off a raw model-id prefix test — so "which shape does this task speak" had no one
+ * place to read. CC 2.1.220's counterpart is a model-registry `capabilities` array (one table drives
+ * `lean_prompt` + `fable_5_mitigations` alike; anchors/2.1.220/CC-218-220-DIFF.md §2).
+ *
+ * sema stays BYOM: we cannot key off a capability table for arbitrary model ids, so the RESOLUTION RULES
+ * are unchanged — profile: spec > inherited internals > "simple"; mitigations: model family. This is a
+ * consolidation, not a behavior change (the axes stay ORTHOGONAL: neither rewrites the other).
+ */
 export declare function resolveModelPromptTraits(model: {
     id: string;
 }, spec: {
@@ -347,61 +974,443 @@ export declare function resolveModelPromptTraits(model: {
     fableMitigations: boolean;
 };
 export interface RunInternals {
+    /** The live repair bundle from a `runRepairLoop` attempt in flight (attemptCount>0). Serialized onto a
+     *  checkpoint minted MID-attempt so a resume re-seeds it; undefined for any non-repair run. */
     repairBundle?: RepairBundle;
+    /**
+     * design/173 §8.2 — the ENGINE deliberately stripped the spawn turn's per-request `onQuestion`
+     * face from this leg's spec (a long-lived background/retained/revived child must not hold a
+     * callback torn down with the turn that spawned it). Minted ONLY by the subagent lanes'
+     * `stripSpawnTurnQuestionFace` helper, PAIR-PRODUCED with the strip itself — never inferred from
+     * spec shape. Consumed by the wiring manifest (`question.wired: "stripped_bg_lane"`) and by the
+     * interaction-posture door (the strip is core's correct design, not a configuration lie, so an
+     * `"interactive"` tree's engine-stripped legs are exempt). TRUST POSTURE (ruled 2026-08-05):
+     * RunInternals is a public trusted-caller parameter, so this flag is an honesty channel, not a
+     * security gate — a caller forging it is a deployment lying to itself; resource-face safety
+     * stays with its own fail-closed mechanisms.
+     */
     questionFaceStripped?: true;
+    /**
+     * design/173 §8.3 (review fold r2-F1) — the SPAWNING run's resolved interaction posture, carried
+     * into engine-built children over the trusted internals channel (never copied onto the child
+     * SPEC — the §8.3 rule). The child's door resolves `spec ?? THIS ?? deps`, so a root's per-run
+     * posture override governs its whole engine-built tree instead of every child falling back to
+     * the deps-level default. Filled by the delegation lanes' `childInternals` and the workflow
+     * spawn attribution; rides `internalsSnapshot`, so retained/revived legs keep it.
+     */
     parentInteractionPosture?: "interactive" | "headless";
+    /**
+     * design/153 §7.2c (件3c, r6 H-1) — the trusted post-consume hook for the PARKED-RESUME drive:
+     * called by `resumeStream` after its resolve CAS WON (the token is consumed — the master
+     * arbitration is decided) and BEFORE the resumed leg starts. The parked-resume caller uses it to
+     * flip the reserved row `parked→running` (guarded CAS) + adopt the live handle/lane — the ONLY
+     * legal site for that flip (a pre-consume flip would let TaskStop hit the plain running arm and
+     * bypass the checkpoint arbitration entirely). A THROW here aborts the resume (propagates out of
+     * `resumeStream`): the checkpoint is already consumed, so the caller's compensation
+     * (`rollbackParkedClaim`) reads `resolved` and settles the honest failed/outcome-unknown terminal
+     * — never a silent run without an adopted row. Deployment/trusted-caller channel only, mirroring
+     * every other RunInternals field.
+     */
     afterCheckpointResolve?: () => Promise<void>;
+    /**
+     * Parent effective-policy inheritance (tighten-only): the spawning parent's already-evaluated FINAL
+     * gate, threaded into a child task so the child inherits it as ADDITIONAL constraint layers — a child
+     * can only ever be narrowed by this, never widened (its own session rules / skill scope / caller policy
+     * still apply in full). Filled ONLY by core delegation callers (`createSubagentTool`'s execute via
+     * `ToolExecuteContext.inheritedGateForChildren`, the workflow spawn legs) — NEVER a {@link TaskSpec}
+     * field (the untrusted-caller surface), mirroring `inheritedManifestScope`'s ctx-injection posture.
+     * Absent ⇒ no inheritance (a top-level task; fully backward-compatible).
+     */
     inheritedGate?: InheritedGate;
+    /**
+     * #22 (ruled 2026-08-05) — the SESSION-scoped org-admission freeze for a SAME-SESSION continuation
+     * that is NOT a checkpoint resume: a retained background child revived through the in-process resume
+     * leg. The checkpoint plane already freezes the session's own verdict
+     * ({@link InheritedGate.ownAdmittedOrgScopes}); this leg has no checkpoint, so without a carrier it
+     * re-adjudicated from scratch and a resolver whose answer WIDENED between the two legs remounted a
+     * tenant layer the session had already lost.
+     *
+     * A REF, not a value: the revival replays a spread COPY of the spawn-time internals, so a plain field
+     * could only ever carry the value that existed at spawn (always `undefined`). The prepare reads
+     * `current` as its `priorOwnVerdict` — intersected with any checkpoint seed, so the fold can only ever
+     * narrow — and writes this leg's own verdict back, which is ⊆ the prior one by construction.
+     *
+     * TRUSTED internal, filled by `createSubagentTool`'s `childInternals` (one ref per spawned child, never
+     * shared across generations — a child's own children build their own). Absent ⇒ no session freeze from
+     * this channel, byte-identical to a deployment with no governance surface.
+     */
     ownOrgAdmissionRef?: {
         current: import("../memory-admission.js").OwnOrgAdmissionVerdict | undefined;
     };
+    /**
+     * design/176 — this run's LATE-BOUND peer-identity carrier (a REF, same family and reason as
+     * {@link ownOrgAdmissionRef}: revival replays a spread copy of spawn-time internals, and the axes
+     * a run wears are born at different points — a* handle at registration, session/task at prepare's
+     * session acquisition). Created at internals assembly (delegation lanes; runtask normalizes one
+     * in for a top-level run); axes recorded through the single monotonic `addAxis`; the canonical
+     * key freezes at the first recorded axis (h→s→t by call-site ordering). Read by the SendMessage
+     * mount (sender key + hop token) and paired into children as {@link parentPeerRef}.
+     */
     peerSelfRef?: import("../../agents/peer-admission.js").PeerSelfRef;
+    /**
+     * design/176 — this run's INBOUND peer-chain ref: overwritten at the harness consumption boundary
+     * with the chain of the peer message the model just consumed (enqueue-time writes would leak a
+     * not-yet-seen message's chain into outbound sends); seeded by the L3/L4 wake legs; empty
+     * otherwise. Not checkpointed in v1 (recorded honest boundary: a cross-process resume forwards
+     * from an empty chain — fail-open on loop suppression only).
+     */
     peerInboundChainRef?: import("../../agents/peer-admission.js").PeerInboundChainRef;
+    /**
+     * design/176 — the PARENT run's peer-identity ref, PAIR-MINTED with {@link parentNotify} at every
+     * trust point that binds the uplink callback (spawn assembly, the resume face's replacement): the
+     * callback is opaque and the parent AXES deliberately keep the original spawner on the revive arm
+     * while the callback points at the WAKER — so the uplink's admission identity can only travel
+     * with the binding itself. Consumed by the SendMessage mount as `uplinkRecipient`.
+     */
     parentPeerRef?: import("../../agents/peer-admission.js").PeerSelfRef;
+    /**
+     * 🔴 design/97 §H.1 / design/98 §0.1 (BLOCKER3) — the workflow **nesting depth** for this run, a TRUSTED
+     * cross-process channel (worker/script can NEVER set it — it is not a {@link TaskSpec} field nor a
+     * `run_workflow` tool param). When a deployment initiates a workflow on behalf of a parent run that is
+     * itself inside a workflow (e.g. service's `/v1/workflows`), it threads `workflowDepth = parentDepth + 1`
+     * into `startWorkflow`/`runWorkflow` so the one-level nesting guard fires across the process boundary.
+     * In-process nesting needs nothing here — the engine's `AsyncLocalStorage` propagates depth automatically.
+     * Mirrors how `repairBundle`/`inheritedManifestScope` thread trusted run-scoped internals the Runner cannot
+     * see from `spec`. Consumed by the `run_workflow` tool wiring (S8c), not by `prepareTask` itself.
+     */
     workflowDepth?: number;
+    /**
+     * design/110 — set ONLY by the Agent tool's fork route (`Agent(subagent_type:"fork")`, a core caller) on the
+     * child it spawns: this run IS a forked child. `prepareTask` threads it to tool ctx as `insideFork` so the
+     * child's own Agent tool refuses a nested fork (nesting guard — mirrors CC's "fork is not available inside a
+     * forked worker"; a fork can still delegate via `Agent`, just not fork again). TRUSTED internal (NOT a
+     * `TaskSpec` field — the untrusted-caller surface), mirrors `inheritedManifestScope`.
+     */
     insideFork?: boolean;
+    /**
+     * RB-204 P1 (codex review) — set UNCONDITIONALLY by every core spawn path (`createSubagentTool`'s
+     * `childInternals` — shared by all four spawn legs sync/steer/background/fork, its persisted
+     * `internalsSnapshot` for revive, and the workflow orchestrator's `spawnAttribution`), regardless
+     * of whether a NAMEABLE `parentTaskId`/`parentToolCallId` exists. A directly-started workflow (no
+     * launching tool call, e.g. cron-triggered) has neither of those — "no id is ever fabricated" for
+     * attribution — but its spawned agents are still delegated children for consent-notice purposes.
+     * Drives `isSubagent` below: do NOT use `parentTaskId` presence alone as the child-ness signal,
+     * that under-covers exactly this case. TRUSTED run-scoped channel (NOT a {@link TaskSpec} field),
+     * mirroring `insideFork`.
+     */
     isDelegatedChild?: boolean;
+    /**
+     * G1+G2 合车复审修② (1.259.0) — the DEFAULT role-base persona for a DELEGATED child, threaded by
+     * `createSubagentTool`'s execute (a core caller) when neither an agent-definition `systemPrompt` nor the
+     * delegation tool's `opts.systemPrompt` names one. It sits at the BOTTOM of the role-base chain —
+     * `spec.systemPrompt ?? resolvedRole.systemPrompt ?? internals.defaultSystemPrompt` — so a deployment's
+     * `roles.subagent.systemPrompt` / `roles.default.systemPrompt` preset still wins (pre-G1 semantics: an
+     * unset child systemPrompt let the role preset apply; G1's first cut put SUBAGENT_PROMPT at spec level
+     * and silently shadowed the preset). Only when NO preset resolves does the lean SUBAGENT_PROMPT (CC 198
+     * general-purpose persona, pretty.js:419977) replace the full DEFAULT_SYSTEM_PROMPT constitution base.
+     * TRUSTED run-scoped channel (NOT a {@link TaskSpec} field), mirroring `insideFork`.
+     */
     defaultSystemPrompt?: string;
+    /**
+     * design/96 §C (S2) — GOAL MODE flag, a TRUSTED internal channel set ONLY by `runGoal` (a core caller),
+     * NEVER a {@link TaskSpec} field. It drives `featureFlags.goalEnabled` → injects `GOAL_COMPLETION_GUIDANCE`.
+     * Why internal (not a public `TaskSpec.goalMode`): the guidance promises "declaring done STOPS iteration and
+     * surfaces" — a promise only `runGoal`'s loop makes real. A public field would let a caller inject that
+     * prompt with no loop behind it (§6.3 honesty violation). `runGoal` injects the `declare_done` tool itself;
+     * this flag only governs the PROMPT (codex r2 — injection-ownership split).
+     */
     goalMode?: boolean;
+    /**
+     * 🔴 design/77 §3 / §7 (ON-前必关) — skill→subagent manifest-scope PROPAGATION. The parent task's
+     * ACTIVE skill-manifest frames, snapshotted at the moment a subagent was spawned WHILE a manifest scope
+     * was live on the parent. The child's {@link prepareTask} seeds its own {@link ActiveSkillScope} from
+     * these so the child inherits the parent skill's deny-narrowing — fail-closed and MONOTONIC: a child of
+     * a manifested skill is AT MOST as capable as the manifest (its own manifests can only narrow further,
+     * never re-grant a tool/path the parent removed).
+     *
+     * This is a TRUSTED, run-scoped channel filled ONLY by `createSubagentTool`'s `execute` (a core caller),
+     * NEVER a {@link TaskSpec} field (TaskSpec is the untrusted-caller surface — design/44 §7 Q4). It mirrors
+     * how `repairBundle`/`resume.seed` thread live per-task state the Runner cannot see from `spec`.
+     *
+     * Fail-closed: when the parent HAD an active manifest at spawn but the precise frames cannot be
+     * snapshotted, the subagent tool threads a single DENY-ALL `unresolved` frame here rather than letting the
+     * child run unmanifested — the safe path is the default. An empty/absent value = no inheritance (a
+     * subagent spawned with no active parent manifest behaves exactly as before, backward-compatible).
+     */
     inheritedManifestScope?: readonly ActiveSkillFrame[];
+    /**
+     * design/99 §E2 — when this task runs as a SUB-AGENT spawned under a parent task's
+     * tool call, the spawning tool's `ToolExecuteContext.toolCallId`. The Runner stamps it onto this task's
+     * stream content events as {@link TaskEvent.parentToolCallId} so a consumer can attribute the child's live
+     * content to the delegation subtree WITHOUT core merging the child stream into the parent (lightweight
+     * message-identity, not stream-merge). A TRUSTED, run-scoped channel filled by a core caller
+     * (`createSubagentTool`'s `execute`) — NEVER a {@link TaskSpec} field (the untrusted-caller surface),
+     * mirroring `inheritedManifestScope`/`workflowDepth`. Absent for a top-level (non-delegated) task.
+     */
     parentToolCallId?: string;
+    /**
+     * design/99 MF-10 / BC-2 (Service AI [§I 1.5.1]) — a SUBAGENT's human display NAME, threaded at spawn so the
+     * child's `task_progress` ticks carry a readable label (a Fleet child row otherwise shows the raw `taskId`).
+     * Filled by `createSubagentTool`'s `execute` = the explicit `taskName`, else the selected agent-type
+     * (`AgentDefinition.name`). TRUSTED run-scoped channel (NOT a {@link TaskSpec} field), mirroring
+     * `parentToolCallId`. Absent for a top-level run / a bare delegation with neither label — the child's
+     * `task_progress` then carries NO `name` (it keeps its taskId; it deliberately does NOT fall back to the raw
+     * objective, which could leak a delegated secret — dual-review Q2). Untrusted (`taskName` is model-chosen) →
+     * the consumer sanitizes via `inlineUntrusted` at emit.
+     */
     agentName?: string;
+    /**
+     * design/147 S3 (codex R3 label-vs-identity): the EXPLICIT `Agent({name})` spawn identity — set
+     * ONLY when the spawn carried a `name` parameter, unlike {@link agentName} (a DISPLAY label:
+     * description or agent-type, present on nearly every spawn). Teammate semantics (hierarchy clamp,
+     * teammate addendum, uplink attribution) key on THIS field; keying on the display label made
+     * every described child a "teammate" (clamp over-wide, addendum over-composed).
+     */
     explicitAgentName?: string;
+    /**
+     * design/99 (nested-subagent live tree) — the SPAWNING run's taskId, threaded at spawn (from the parent's
+     * `ToolExecuteContext.taskId`) so this child's `task_progress` ticks carry `parentTaskId`. Lets a UI build the
+     * live nested-agent tree directly (child.parentTaskId === parent.taskId) at any depth. TRUSTED run-scoped
+     * channel (NOT a {@link TaskSpec} field), mirroring `parentToolCallId`. Absent for a top-level run.
+     */
     parentTaskId?: string;
+    /** design/147 S2a — the spawning run's sessionId (paired with parentTaskId; see
+     *  ToolExecuteContext.parentSessionId). */
     parentSessionId?: string;
+    /**
+     * The FLEET-task kind of this run, declared by the lane that spawned it and stamped onto every
+     * `task_progress` tick the run mints (`TaskEvent`'s `taskType`). A consumer merging progress ticks
+     * with task notifications into one ledger could otherwise only key on "it showed up on the fleet
+     * stream, so it must be an agent" — an inference that has already produced a row for a task that
+     * was never an agent. Same vocabulary as `TaskNotificationPayload.task_type`, so the merged ledger
+     * has ONE type axis rather than two spellings of one.
+     *
+     * Set by the BACKGROUND delegation lanes (plain + fork), whose runs own a registry `a*` row, and by
+     * both of the workflow orchestrator's spawn legs. A SYNCHRONOUS delegated child declares nothing —
+     * it has no fleet row of any kind, so absence is a fact about the run rather than a gap in the
+     * stamping. TRUSTED run-scoped channel (never a {@link TaskSpec} field).
+     */
     delegationTaskType?: import("../types.js").DelegationTaskType;
+    /** δ 批 [1498]⑦/A-3 — the ROOT host session of the whole delegation tree (fixed point: the
+     *  spawner passes its own `ctx.rootSessionId ?? ctx.sessionId`, so depth 1 gets the host session
+     *  and every deeper level inherits it verbatim). `parentSessionId` is the IMMEDIATE spawner —
+     *  after a restart those intermediate sessions are dead ends, and a recovery face enumerating
+     *  "everything under this host session" needs the root anchor, not an alias walk. */
     rootSessionId?: string;
+    /**
+     * RB-429 — the REGISTRY SCOPE this run's own background row lives in: the domain its registry-facing
+     * tools (TaskOutput / TaskStop / SendMessage / AgentTranscript / Monitor, and the announce listing)
+     * must mount in to see it. Filled by the delegation tool at spawn, which is the party that CHOSE the
+     * domain when it registered the row — `ctx.principal` when the spawning run has one, else the
+     * delegation mount's declared `background.scope`, and on a revival the claimed row's own scope.
+     *
+     * Why this is not just `principal`: a deployment may declare its domain at MOUNT time and run its
+     * tasks without `TaskSpec.principal`. The row then lands in the declared domain while the child runs
+     * with no principal at all, and `principal ?? "default"` sends every one of its registry-facing tools
+     * to a domain the row is not in — scope is fail-closed on both access predicates, so such a child
+     * cannot see its own row, its siblings, or the children it spawns. Carrying the domain as its own
+     * trusted axis keeps `principal` the design/62 IDENTITY it is: the identity also keys the durable
+     * approval / checkpoint namespace (`checkpointScopeOf`), the runtime-capability lookup and the MCP
+     * principal header, and a mount's registry scope has no business moving any of those (an unattended
+     * safety park must not migrate into the caller's opt-in approval bucket — design/153 §7.4).
+     *
+     * TRUSTED channel (never a {@link TaskSpec} field, never a model argument), like the parentage axes
+     * above. When a deployment sets both, they agree by construction: with a principal present the
+     * delegation tool resolves this axis TO that principal.
+     */
     registryScope?: string;
+    /** design/148 S1 (codex F2a) — the spawning run's ADOPTED center artifact, threaded down the
+     *  trusted internals chain so every child in the tree composes the SAME closure (a child must
+     *  never spontaneously adopt the live candidate while its parent runs an older pin — that is the
+     *  exact mixed-version state the epoch exists to prevent). Resolved by-digest through the
+     *  verified store at child prepare; a miss is the same fail-loud `prompt.snapshot_unavailable`. */
     parentCenterArtifactDigest?: string;
+    /** Publish provenance companion of {@link parentCenterArtifactDigest} (audit only). */
     parentCenterSourceRevision?: string;
+    /** R2 双形轴 — parent's resolved prompt profile, inherited unless the child spec overrides. */
     promptProfile?: "simple" | "classic";
+    /**
+     * design/99 (nested-subagent live tree) — an OPT-IN, DISPLAY-ONLY event sink a deployment sets on the TOP run to
+     * receive a subagent's live `task_progress` ticks (which otherwise stay in the child's ISOLATED stream). Threaded
+     * recursively down the delegation tree (via `ctx.forwardEvent`), so every nested subagent's ticks bubble to the
+     * SAME sink. The Runner forwards ONLY `task_progress` through it; the child stream is NEVER merged into the
+     * parent's MODEL context (this is purely a render channel). Absent unless the deployment opted in.
+     */
     onForwardEvent?: (event: TaskEvent) => void;
+    /**
+     * design/115 P2 core slice — trusted run-local system-injection sink. `Runner.runLocked` wires this to the
+     * live TaskStream queue plus the current harness follow-up lane; it is not a public TaskSpec field.
+     */
+    /** design/116 detach: the run-local per-tool-call detach hub. runtask creates it and exposes
+     *  `TaskStream.detach(toolCallId)`; the hands Bash tool threads `signalFor(toolCallId)` into env.exec. */
     detachHub?: import("../tool-detach.js").ToolDetachHub;
-    onTaskNotification?: (notification: TaskNotificationPayload, opts?: {
+    onTaskNotification?: (notification: TaskNotificationPayload, 
+    /** CC injection priority (design/116 §7, re-anchored 2026-08-05): every priority delivers at
+     *  the next turn boundary (arrival order, consecutive frames batch); "later" (default) vs
+     *  "next" now differs only on the park/uplink forwarding path. */
+    opts?: {
         priority?: import("../task-notification.js").SystemInjectionPriority;
     }) => void;
+    /**
+     * design/147 S1a — the PARENT run's notification injector (its runtask-wrapped
+     * `injectTaskNotification`), threaded into a CHILD's internals at spawn time so the child's
+     * SendMessage("main") uplink lands in the parent's queue at a turn boundary (the CC
+     * "delivered automatically" parent half). DELIBERATELY a separate field from
+     * {@link RunInternals.onTaskNotification}: that one is "inject into THIS run" (runtask wraps it
+     * as upstream-observer + own-queue), and reusing it for the child would tee every internal child
+     * notification (grandchild completions, monitor events) into the parent — double delivery.
+     */
     parentNotify?: (notification: TaskNotificationPayload, opts?: {
         priority?: import("../task-notification.js").SystemInjectionPriority;
     }) => void;
+    /**
+     * design/147 S3a (codex F2) — the PARENT run's subagent-retain ledger, threaded to a CHILD so its
+     * SendMessage can continue a RETAINED SIBLING (the sibling's retain entry lives on the parent's
+     * ledger — without this, sibling resolution succeeds but delivery always reads not-retained).
+     * TRUSTED chain; read-only use (the sibling leg resumes through the same fenced resume face).
+     */
     parentRetainLedger?: import("../../agents/retain-ledger.js").SubagentRetainLedger;
+    /**
+     * design/147 S2a — hands THIS run's notification injector back to the SPAWNER once the lane is
+     * live (runtask calls it with its wrapped `injectTaskNotification`). The spawner stores it on the
+     * child's registry handle so a parent/sibling SendMessage can deliver TO the RUNNING child at its
+     * next turn boundary (CC's in-memory `pendingMessages` pedestal, anchors/2.1.212
+     * messaging-runtime.md §2.5). The injector is RUN-SCOPED but fail-safe after the run: the lane's
+     * teardown branch parks late payloads per session (PendingSessionNotifications), which is exactly
+     * CC's durable-mailbox posture for an idle teammate (§2.4) — no separate file mailbox needed.
+     * TRUSTED chain (core spawner only); never reachable from TaskSpec.
+     */
     onNotifyInjectorReady?: (inject: (notification: TaskNotificationPayload, opts?: {
         priority?: import("../task-notification.js").SystemInjectionPriority;
     }) => Promise<"queued" | "parked" | "dropped_duplicate">) => void;
+    /**
+     * design/97 CORE-6 — per-task ISOLATION hint, a TRUSTED run-scoped channel filled ONLY by a core caller
+     * (the workflow's `ctx.agent` when the SCRIPT passed `{ isolation: "worktree" }` as an OPTION) — NEVER a
+     * {@link TaskSpec} field (the untrusted-caller surface, design/44 §7 Q4). Forwarded to
+     * {@link ExecutionEnvFactory} via {@link ExecutionEnvFactoryContext.isolation} so the trusted control-plane
+     * factory mints a git-worktree-rooted env for this agent; and it makes root resolution use the worktree
+     * env's own cwd (the worktree dir), bypassing `deps.rootPath`. Isolate-ONLY: the runtime never merges
+     * — the orchestrator script reads each worktree's result and decides verify/merge in userland.
+     * FAIL-CLOSED: a request the deployment cannot honor (no factory, or an observably non-isolated env)
+     * throws at prepare time — the child never starts; there is no silent fallback to the shared tree.
+     */
     isolation?: "worktree";
+    /**
+     * Sub-agent cwd inheritance (CC parity, 2026-07-03): the PARENT task's effective working root,
+     * filled ONLY by core delegation callers (the workflow's `ctx.agent` / `createSubagentTool`'s execute —
+     * NEVER a {@link TaskSpec} field). Forwarded to {@link ExecutionEnvFactory} via
+     * {@link ExecutionEnvFactoryContext.parentCwd} so a single-user/TOC factory can root the child env at the
+     * parent's cwd instead of an empty per-task sandbox. `isolation: "worktree"` wins over this when both set.
+     */
     parentCwd?: string;
+    /**
+     * [c209-D] codex R3 — the EXPLICIT Agent.cwd request, distinct from the best-effort `parentCwd`
+     * inheritance hint above: inheritance may be silently ignored by a factory (or absent without one),
+     * but an explicit cwd the model asked for MUST either take effect or fail loud. prepareTask enforces
+     * the contract: no `executionEnvFactory` ⇒ throw `config.cwd_unsupported`; after env creation the
+     * env's actual cwd must canonically equal this path or the task fails `config.cwd_not_honored`; the
+     * task root follows the env's cwd (never `deps.rootPath`) when set. Filled ONLY by core delegation
+     * callers (ctx-injection posture, same as `parentCwd`).
+     */
     requestedCwd?: string;
+    /**
+     * Subagent steer verb (dogfood finding 2026-07-03, "中途插话"): the host run's opt-in
+     * SUBAGENT-STEER-HANDLE sink. When set, `createSubagentTool` runs each child via `runTaskStream`
+     * and emits a steer handle here (the model never sees the handle — same host-context-isolation
+     * posture as `onWorkflowAgentSpawn`). A deployment registers it by `taskId` to route a human steer
+     * into the running child (fenced-marker semantics matching the workflow agent handle). Threaded to
+     * the tool ctx as {@link ToolExecuteContext.onSubagentSpawn} and recursively down the delegation
+     * tree. Absent ⇒ children run non-steerable (prior behavior, zero overhead).
+     * SCOPE (fable impl-review F3, recorded): only SYNC delegations emit a handle — a
+     * `run_in_background` child does not (poll/stop it via TaskOutput/TaskStop); wiring the background
+     * lane is a recorded follow-up, not an oversight a deployment should discover at runtime.
+     */
     onSubagentSpawn?: (handle: import("../../agents/subagent.js").SubagentSteerHandle) => void;
+    /**
+     * design/97 CORE-8 (③) — a TRUSTED run-scoped tool-ACTIVITY sink, filled ONLY by a core caller (the workflow's
+     * `ctx.agent`, to render a per-agent "last N tool calls" drill-down). Called synchronously at each tool start +
+     * end with structural data (name/phase/ids) — NEVER args/output (those carry untrusted/host data). NEVER a
+     * {@link TaskSpec} field. Absent ⇒ no activity capture (default).
+     *
+     * **v1 scope (audit MINOR)**: reaches activity on a FRESH run only — the durable-resume entry (`resumeStream`)
+     * does not thread `internals`, so a resumed leg emits no activity. The workflow display is unaffected (its
+     * agents fail-on-suspend rather than durably resume).
+     */
     onActivity?: (activity: ToolActivity) => void;
+    /**
+     * RB-393① (黑板 [2107]②) — a TRUSTED run-scoped WORKSPACE-observation sink, filled ONLY by a core caller
+     * (the workflow's `ctx.agent` / `ctx.agentStream`, to record an isolated agent's worktree directory on the
+     * persisted run record). NEVER a {@link TaskSpec} field — same posture as {@link onActivity}.
+     *
+     * WHY the engine must hand this out: for `isolation: "worktree"` the worktree path is minted INSIDE
+     * {@link RunnerDeps.executionEnvFactory} and lands only on the per-task env's `cwd`; no runner-outward face
+     * (TaskEvent union / TaskStream / TaskResult) carries it back. An orchestrator therefore could not record
+     * WHERE its isolated agent worked — the recovery path after an interrupted run had to enumerate the
+     * worktrees directory and guess, which is exactly the contradiction [2113] recorded against the
+     * "isolate-only, userland decides verify/merge" intent.
+     *
+     * Called at most ONCE per prepared run with the task's FINAL working root (see {@link ResolvedWorkspace}),
+     * after the durable-resume restore may have re-rooted it. Observe-only: a throwing sink is swallowed (an
+     * observation must never fault a prepare that already minted a workspace).
+     *
+     * **v1 scope**: same as {@link onActivity} — a FRESH run only; the durable-resume entry (`resumeStream`)
+     * threads no `internals`, so a resumed leg reports nothing.
+     */
     onWorkspaceResolved?: (workspace: ResolvedWorkspace) => void;
 }
+/**
+ * RB-393① — the payload of {@link RunInternals.onWorkspaceResolved}: the working root this task actually
+ * runs on, plus whether that root is the task's OWN isolated workspace.
+ *
+ * `isolated: true` means "`cwd` is this agent's own git worktree": it is reported only when
+ * {@link RunInternals.isolation} was requested AND the fail-closed worktree enforcement accepted the env, so a
+ * consumer may treat the path as private to this agent (safe to diff / merge / remove in userland). A
+ * non-isolated run reports its plain root with `isolated: false` — the observation face stays complete, while
+ * the honest non-claim keeps a consumer from mistaking a SHARED tree for its own worktree.
+ */
 export interface ResolvedWorkspace {
+    /** The task's effective working root — the same value every fence / LSP / prompt consumer uses. */
     cwd: string;
+    /** True only for an accepted `isolation: "worktree"` request (⇒ `cwd` is this agent's own worktree). */
     isolated: boolean;
 }
+/**
+ * From the resumed/active transcript, the batch position of `currentId` (design/45 §4.ter): the tool-call
+ * ids of the assistant message that issued it (the batch), and the subset already resolved (executed
+ * before the suspend — #1..k-1). ID-based, not positional (council Question #1): immune to reordering.
+ */
 export declare function batchContextAt(messages: AgentMessage[], currentId: string): {
     batchToolCallIds: string[];
     completedCallIds: string[];
 };
+/**
+ * codex 1360 r2-r4 — rebase one checkpointed absolute path from the OLD workspace root onto the RESTORED
+ * one (divergent `resumeVM`). POSIX-ONLY by contract: every remote lane's `mountPath` is a container
+ * path (e2b/k8s/ssh/adb/local-docker are all Linux targets), so a backslash ANYWHERE in the inputs marks
+ * the value outside this function's domain and it returns `p` UNCHANGED — an un-rebased path is honestly
+ * observable (the divergence observation already fired) while a WRONGLY-rebased one silently corrupts
+ * cwd/read-state (r4: drive-root and cross-family recomposition are not implementable without a Windows
+ * path model no lane needs). Trailing slashes are tolerated (from="/app/" must not weld the suffix);
+ * bare "/" keeps filesystem-root semantics; a path outside `from` (incl. the prefix-sibling
+ * "/application" vs "/app") returns unchanged. Exported for direct unit pinning.
+ */
 export declare function rebaseWorkspacePath(p: string, fromRaw: string, toRaw: string): string;
+/**
+ * RB-439-c — {@link rebaseWorkspacePath} over a SET of accepted spellings of the old root: the first
+ * prefix that actually matches wins, and a path under none of them is returned unchanged.
+ *
+ * The set exists because "the old root" has no single spelling. `WorkspaceHandle.mountPath` is whatever the
+ * adapter called the mount, while the persisted paths being migrated were spelled by whoever produced them
+ * (a `cd` the env canonicalized, a Read key resolved through realpath). On a target where the root has an
+ * equivalent alias (`/var` ↔ `/private/var`) those disagree while naming the same directory, and a
+ * single-prefix rebase then matched nothing and silently left the resumed shell in the pre-suspend tree —
+ * under a disclosure that said the task follows the restored root. Order is caller-chosen (the checkpointed
+ * spelling first, its canonical form second) and only matters if one prefix is a prefix of another, in
+ * which case the earlier — more specific — spelling is the intended one. Exported for direct unit pinning.
+ */
 export declare function rebaseWorkspacePathAcross(p: string, froms: readonly string[], to: string): string;
-export declare function prepareTask(spec: TaskSpec, deps: RunnerDeps, sessions: SessionStore, resume?: PrepareResume, internals?: RunInternals, runnerSelf?: Runner): Promise<Prepared>;
+export declare function prepareTask(spec: TaskSpec, deps: RunnerDeps, sessions: SessionStore, resume?: PrepareResume, internals?: RunInternals, 
+/** design/98 §3.1 (S8c): a TRUSTED self-reference to the Runner, passed by the Runner itself (never a
+ *  TaskSpec field) so the `run_workflow` tool can execute child tasks via `runner.runTask`. Undefined when
+ *  prepareTask is exercised standalone (then run_workflow is simply not mounted). */
+runnerSelf?: Runner): Promise<Prepared>;