@sema-agent/core 5.19.0 → 5.21.0

package/dist/core/task-registry-shared.d.ts

@@ -6,24 +6,74 @@ import type { WorkflowHandle, WorkflowRun } from "../orchestration/workflow.js";
 import type { TaskNotificationPayload } from "./task-notification.js";
 import type { ToolResultStore } from "./tool-result-store.js";
 export type SemaTaskType = "background_bash" | "workflow" | "background_agent" | "monitor";
+/** design/134 §3.3 (R3): WHO initiated a kill — recorded at the initiation site (first-marker-wins),
+ *  because the settle-side then/catch context has already lost it. OPEN ENUM on the wire, now in the
+ *  TYPE too (`(string & {})` keeps literal completion while admitting future values like "timeout"
+ *  without a breaking change): consumers must tolerate unknown values and fall back to default copy.
+ *  SINGLE SOURCE of the shape — two wire mirrors are INLINED to avoid import cycles (this module sits
+ *  above both) and must stay in sync: types.ts `BackgroundChildEvent.stoppedBy` and
+ *  task-notification.ts `TaskNotificationPayload.stoppedBy`. */
 export type StopSource = "user" | "parent" | "system" | (string & {});
+/** design/153 §7.1: `"parked"` (background agents only today) = durably suspended on a pending
+ *  approval checkpoint — neither live nor terminal. Every `=== "running"` liveness check treats it
+ *  as not-running (correct: no process exists); it exits poll waits, refuses settles, and is
+ *  reap-exempt. Downstream switches over this union gain an arm (announced, [1556]/L1.5). */
 export type SemaTaskStatus = "pending" | "running" | "parked" | "completed" | "failed" | "killed" | "cancelled";
 export type TaskRetrievalStatus = "success" | "not_ready" | "timeout";
 export interface UnifiedTaskOutput {
     task_id: string;
+    /** RB-92 (2026-07-25, red probe): `"unknown"` is a DECLARED member here, not a stray literal. A
+     *  not-found lookup has no task kind to report, and the TaskStop envelope's `task_type` is required by
+     *  the client schema — so the wrapper was already emitting `"unknown"` while the type said it could
+     *  only be a `SemaTaskType`. Declaring it keeps the two honest with each other, and keeps `SemaTaskType`
+     *  itself clean for every consumer that switches over real task kinds. */
     type?: SemaTaskType | "unknown";
     status?: SemaTaskStatus | string;
     retrieval_status: TaskRetrievalStatus;
     content?: string;
     error?: string;
+    /** RB-386② ([2090]) — machine-readable failure code on a FAILED background_agent row's poll
+     *  details (the child's TaskResult.errorCode taxonomy — brain codes / `limit.*` / `budget.*` …).
+     *  Additive; absent on non-failed rows, on rows whose failure carried no code, and on other lanes. */
     errorCode?: string;
+    /** RB-386② — retryability verdict for a FAILED background_agent row, derived at settle time by the
+     *  same classifier the sync sub-agent report's `error_kind (retryable: …)` line uses. Additive. */
     retryable?: boolean;
+    /** design/134 §3.3: only present when `status === "killed"` (open enum — see {@link StopSource}). */
     stoppedBy?: StopSource;
+    /** server[1526] ask — the durable row's committed stop-cycle number (1.371 settle mint), served on
+     *  durable-fallback polls so a tail consumer can key revive cycles without the notify lane.
+     *  [1532]§三1: ALSO served by the in-process live poll/stop arms (the handle's current cycle
+     *  projection — spawn = 1, each 1.332/tier-3 revival opens the next), same key, same meaning,
+     *  so tail meta is complete whichever arm answers. */
     seq?: number;
+    /** fidelity-sweep A1: the served result is the child's PARTIAL work — it landed after a kill had
+     *  already won the terminal race and was backfilled (produced before/while the task was stopped). */
     partial_result?: boolean;
+    /** P1-3(黑板 [1870] P1-3, cli/server 商定项 — 黑板 [1920]/[1921]/[1924]/[1925]):a cross-channel
+     *  correlation key for ONE completion event. The same task's completion fans out across several
+     *  independent channels today (a live `TaskNotificationPayload` frame, a durable inbox entry, and
+     *  this poll projection) — a consumer today has to reconstruct "are these the same completion?" from
+     *  weaker signals (task_id + status + timing). Minted ONCE per completion, fill-once (first writer
+     *  wins) on the handle/record the completion is settled onto, so every read face — this poll
+     *  projection, the notification payload, and (for background_agent) the cross-restart durable
+     *  fallback row — serves the exact same value. Open-shape `string` (a uuidv7 in this implementation,
+     *  not contractually required to stay one); absent when the underlying task hasn't reached a terminal
+     *  settle yet, or on a pre-P1-3 core build that never minted one. */
     completionId?: string;
     details?: unknown;
 }
+/**
+ * E1 (黑板 [1937]) — the shared internal poll/stop result shape every helper below returns
+ * (`noTask`/`noTaskForStop`/`formatWorkflowRun`/`serveDurableAgentRow`/`pollTask`/`stopTask` and every
+ * per-task-kind poll/stop arm). `UnifiedTaskOutput` (the `details` face) has no isError channel of its
+ * own — it is a REQUIRED-field wire shape consumed by callers beyond these two tools too, so isError is
+ * carried as a sibling on the WRAPPER instead (trap avoidance per the E1 sweep: never smuggle isError
+ * through a narrower helper contract). Optional, absent/false = success — `createTaskOutputTool`/
+ * `createTaskStopTool` forward it onto the real `ToolReturn` at the tool boundary. Every internal helper
+ * keeps constructing `content`/`details` exactly as before; this only adds a place to say "and this one
+ * is a genuine failure" where the failure is actually detected.
+ */
 export type UnifiedTaskResult = {
     content: string;
     details: UnifiedTaskOutput;
@@ -40,22 +90,59 @@ export interface SemaTaskHandle {
     createdAt: number;
     updatedAt: number;
     outputFile?: string;
+    /** P1-3 — see {@link UnifiedTaskOutput.completionId}. Minted fill-once at this task's own settle
+     *  point ({@link mintCompletionId}); absent until the task reaches a terminal status. */
     completionId?: string;
 }
+/** P1-3(黑板 [1920]/[1921]/[1924]/[1925]) — mint a cross-channel completion correlation id ONCE per
+ *  handle/record, fill-once (first writer wins): every settle/direct-terminal-flip site calls this
+ *  instead of writing `completionId` directly, so no matter how many terminal-transition sites a lane
+ *  has (settle / TaskStop bypass / backfill), the value is minted exactly once and every later caller
+ *  (including an idempotent re-call from a bypass path that already ran) gets back the SAME id. `string`
+ *  is intentionally loose (any object with an optional `completionId` field) so the same helper serves
+ *  both a `RegisteredTaskHandle` and a `WorkflowRun` (orchestration/workflow.ts — a different module,
+ *  no shared base type, same fill-once shape). */
 export declare function mintCompletionId(target: {
     completionId?: string;
 }): string;
 export interface TaskAccess {
     owner?: string;
     scope?: string;
+    /** design/129: the caller's SESSION id — matches session-scoped handles across turns (a fresh per-turn
+     *  spec.taskId changes `owner`, but the session is the stable key a background child outlives turns under). */
     sessionId?: string;
 }
 export interface BackgroundBashTaskHandle extends SemaTaskHandle {
     type: "background_bash";
     env: ExecutionEnv & BackgroundShellCapability;
     shellId: BackgroundShellId;
+    /** (design/129 lifetime discipline, CC parity): a background bash spawned inside a SESSION
+     *  outlives the run — CC's bg shells survive the agent turn (TB live evidence in settleKilledForOwner's
+     *  T1-1 note) and die at the SESSION terminal. When set, owner MUST be the sessionId: skipped by the
+     *  run-teardown settle/evict, kept alive through the dispose except-list, reaped by
+     *  {@link TaskRegistry.reapSessionBackground}. Explicit flag only — never inferred from owner shape. */
     sessionScoped?: true;
+    /** Deliver-a-living-service ledger mark: the run-teardown settle sweep skipped this row under the
+     *  retain gate (spec-level `TaskSpec.retainBackgroundProcesses` OR the env-declared capability). The
+     *  row is the delivered daemon's ONLY management surface — while the process runs it survives the
+     *  per-run evict (TaskOutput/TaskStop resolve through this map; the watcher must stay live to mint
+     *  the natural-exit receipt) and rides every later run's dispose except-list on the same env
+     *  ({@link TaskRegistry.retainedShellIds}). A terminal row evicts normally. Terminals: explicit
+     *  TaskStop, the process's own exit (watcher settle), or env destruction (watcher env-death settle)
+     *  — deliberately NO timed reaper (the deliverable is the living process). A retained SESSION-resident
+     *  row is likewise exempt from the session-release reap ({@link TaskRegistry.reapSessionBackground}):
+     *  the delivered daemon outlives its session, with the same three terminals. */
     retained?: true;
+    /** design/116 §7 G2b: when a watcher is attached, the registry accumulates the FULL output here (rolling
+     *  bound) — TaskOutput then serves a RE-READABLE snapshot (CC semantics) instead of a consume-once cursor.
+     *  `timedOut`/`timeoutSec` record a SELF-INFLICTED background-timeout kill (the env's per-shell budget
+     *  fired), so later re-readable polls keep rendering it distinguishably from an external stop.
+     *  `mirrorFailed` records that at least one append to the advertised output FILE failed — the terminal
+     *  frame then discloses the file as incomplete instead of letting the launch receipt's "full output is
+     *  appended there" promise stand over a silently partial file. */
+    /** RB-238 ([1937] M1): `droppedBytes`/`dropUnknown` account ENV-SIDE tail-buffer eviction disclosed by
+     *  the poll (`bytesDroppedBeforeCursor`/`truncated`) — a loss upstream of (and distinct from) the
+     *  registry's own `rolledChars` memory bound. Bytes counted here never reached the spool at all. */
     spool?: {
         stdout: string;
         stderr: string;
@@ -68,9 +155,18 @@ export interface BackgroundBashTaskHandle extends SemaTaskHandle {
         dropUnknown?: true;
     };
     watcher?: ReturnType<typeof setInterval>;
+    /** design/134 §3.3 (R3 MED, 修类不修点): same attribution pair as the agent handle — see there. */
     stopSource?: StopSource;
     stoppedBy?: StopSource;
+    /** The terminal-notification sink, HELD ON THE HANDLE (not only inside the watcher closure)
+     *  so the run-teardown killed settle ({@link TaskRegistry.settleKilledForOwner}) can mint the receipt the
+     *  watcher never will — a disposed shell polls as vanished ("nothing to notify about") and an evicted
+     *  handle stops the watcher outright. */
     onTerminal?: (notification: TaskNotificationPayload) => void;
+    /** Terminal-notification once-latch (fidelity R1-3): set atomically right before the FIRST terminal
+     *  notice is sent. A teardown settle and an in-flight watcher tick can both reach their emit point
+     *  (the kill/poll awaits are suspension windows between the status gate and the send) — whichever
+     *  fires first wins; every later producer stays silent. */
     terminalNotified?: true;
 }
 export interface WorkflowTaskHandle extends SemaTaskHandle {
@@ -78,37 +174,104 @@ export interface WorkflowTaskHandle extends SemaTaskHandle {
     runId: string;
     handle: WorkflowHandle<unknown>;
     store?: WorkflowRunStore;
+    /** γ 批 B-1 (live leg) — see {@link RegisterWorkflowInput.originatingSessionId}. */
     originatingSessionId?: string;
+    /** RB-215(黑板 [1870] C6,已修): design/129 session-lifetime discipline, extended to workflow — the
+     *  ONE background kind that never had it (`background_bash`/`monitor`/`background_agent` all do).
+     *  Unlike those three (task-scoped BY DEFAULT, `sessionScoped` an explicit opt-in via
+     *  `TaskSpec.backgroundScope`), a workflow is unconditionally session-anchored — `originatingSessionId`
+     *  is set at every standard mount (`prepare-task.ts`, never gated), and Workflow's whole raison d'être
+     *  (its own guidance text) is "runs asynchronously, notifies you or is polled LATER" — there is no
+     *  sensible "dies with this turn" mode for it to opt out into, unlike a background_agent which
+     *  genuinely has both use cases. Set `true` whenever `originatingSessionId` is present (`registerWorkflow`).
+     *  Read only by {@link TaskRegistry.reapSessionBackground} — the explicit, deployment-invoked session
+     *  terminal anchor (core has no session TTL reaper of its own); NEVER by `Runner.runTask()`'s own
+     *  per-leg teardown, whose finally block runs on every NORMAL leg completion, not just a genuine
+     *  session end — a would-be regression caught by cross-review before this shipped (see docs/
+     *  REVIEW-BACKLOG.md's "RB-215 复核" entry for the full incident). */
     sessionScoped?: true;
+    /** See {@link RegisterWorkflowInput.onServedTerminal}. Cleared after the single fire. */
     onServedTerminal?: () => void;
+    /** 复审 r2 MAJOR: the bounded return value, captured on the done-hook so the STORE-LESS in-memory lane's
+     *  terminal poll can hand it over too (the launch note promises it; without a store there was no result). */
     result?: string;
+    /** T2A-8: the failure reason (bounded + redacted), captured on the done-hook's rejection so a store-less
+     *  terminal poll can say WHY it failed (the store lane's formatWorkflowRun already carries run.error). */
     error?: string;
 }
+/** design/151 S1a — the per-row durable write lane. The registry is the row's SINGLE writer; writes
+ *  are serialized on a promise chain (put → bind → settle order preserved), CAS'd with the locally
+ *  held `record.rev`, and BEST-EFFORT (a store outage degrades durability with a visible warning,
+ *  never execution). A lost CAS or a put `already_exists` means a FOREIGN row lives under this
+ *  handle (leftover from a dead process / another writer) — the lane poisons itself loudly instead
+ *  of clobbering (design/151 MED-8: the writer's own rev is the anti-clobber line). */
 export interface DurableAgentLane {
     store: BackgroundAgentStore;
+    /** The writer's authoritative local copy (rev included — bumped only on a confirmed CAS win). */
     record: BackgroundAgentRecord;
     chain: Promise<void>;
+    /** True once the initial `put` landed (an outage before that retries put on the next write). */
     written: boolean;
     poisoned: boolean;
+    /** codex r3 F2 — true while the LATEST flush exhausted its retries (cleared by the next success).
+     *  The lifecycle-flip probe requires it false: a row whose bind/settle never persisted must not
+     *  have its transcript preserved-but-unreachable (the local record accumulates patches, so the
+     *  next successful write self-heals the missing fields). */
     flushFailed: boolean;
+    /** codex 增量 R-4 — consecutive heartbeat re-drives of a settled flush-failed lane (reset on any
+     *  flush success); past the ceiling the lane is abandoned loudly instead of retrying forever. */
     redrives?: number;
 }
 export interface BackgroundAgentTaskHandle extends SemaTaskHandle {
     type: "background_agent";
+    /** design/115 P3: aborting this cancels the child run (TaskStop / parent teardown). */
     abort: AbortController;
+    /** RB-236 — lineage axes, declared (registration always spread them into the handle; readers used
+     *  to cast). `rootSessionId` feeds {@link canAccess}'s root-session arm; the other two stay
+     *  read-only lineage metadata on the live face (no parentSessionId access arm — see the arm's
+     *  comment for why). [1344]② clamps `parentTaskId` register-side. */
     parentTaskId?: string;
     parentSessionId?: string;
     rootSessionId?: string;
+    /** design/151 S1a — the child's store session id (transcript/resume anchor), bound once the child
+     *  session is minted ({@link TaskRegistry.bindBackgroundAgentSession}). */
     sessionId?: string;
+    /** design/151 S1a — the durable write lane (present iff the registration wired a store). */
     durable?: DurableAgentLane;
+    /** design/147 S2a — the RUNNING child run's notification injector (attached once its lane is
+     *  live, dropped at terminal settle). A parent/sibling SendMessage delivers through this at the
+     *  child's next turn boundary (CC in-memory pendingMessages pedestal); late calls after the run
+     *  ends park per session inside the injector itself (the lane-teardown branch). */
     notify?: (notification: import("./task-notification.js").TaskNotificationPayload, opts?: {
         priority?: import("./task-notification.js").SystemInjectionPriority;
     }) => "queued" | "parked" | "dropped_duplicate" | Promise<"queued" | "parked" | "dropped_duplicate">;
+    /** design/147 S2a (codex R3 F5) — messages that arrived in the STARTUP window (row already
+     *  running, lane not yet bound). Bounded; flushed in order by attachAgentNotify. Discarded at
+     *  terminal settle: a run that failed during prepare never had a lane to park through, and the
+     *  sender's completion notification (failed) prompts the resend. */
+    /** S2b codex F1 — park redeemability (see RegisterBackgroundAgentInput.retainedContinuation). */
     retainedContinuation?: boolean;
+    /** S2b RB-27② — revive-cycle stamp (see reviveBackgroundAgent): attach/settle from a resume leg
+     *  carry it so a stale cycle's late calls no-op instead of clobbering the newer cycle. */
     reviveCycle?: number;
+    /** [1532]§三1 — the CURRENT stop-cycle number in settle-generation terms (spawn run = 1; each
+     *  revival — 1.332 retained or tier-3 seeded — opens the next). Served by the LIVE poll/stop
+     *  projection under the SAME `seq` key as the durable-fallback arm, so a tail consumer keys
+     *  revive cycles identically whichever arm answered. Re-aligned to the settle's authoritative
+     *  `outcome.seq` at settle time (the ledger's cycleSeq is the mint; this is its projection). */
     cycleSeq?: number;
+    /** design/153 §7.1 — the approval checkpoint this handle is parked on (`status:"parked"` only). */
     parkedCheckpointToken?: string;
+    /** design/153 §7.1 — in-process TaskStop arbitration closure, minted by the parking watcher
+     *  (captures the checkpoint store + token; the registry itself holds no durable stores — r4 F-06).
+     *  Resolves `true` iff the STOP won the checkpoint CAS (expire landed; resume can no longer
+     *  consume it) — only then may the row flip killed. `false` = a resume consumed the token first.
+     *  Absent (cross-process row, no live park context) ⇒ TaskStop refuses honestly: the durable
+     *  approval inbox (server /decide) owns that arbitration. */
     resolveParkedStop?: () => Promise<boolean>;
+    /** S2b codex R5-F2 — resolvers of DIRECT (post-attach) deliveries currently awaiting the
+     *  injector; terminal settle/stop sweep these as not_running so a never-settling adapter can
+     *  never pin the sender's tool call. */
     inFlightDirect?: Set<(r: {
         ok: true;
         disposition: "queued" | "parked";
@@ -116,6 +279,8 @@ export interface BackgroundAgentTaskHandle extends SemaTaskHandle {
         ok: false;
         reason: "not_found" | "not_running" | "no_channel";
     }) => void>;
+    /** S2a F7 — channel lifecycle: undefined = unsupported (spawner never declared), "attaching" =
+     *  declared, lane not yet bound (buffer window), "attached" = live injector present. */
     channelState?: "attaching" | "attached";
     preAttachQueue?: Array<[
         import("./task-notification.js").TaskNotificationPayload,
@@ -130,32 +295,101 @@ export interface BackgroundAgentTaskHandle extends SemaTaskHandle {
             reason: "not_found" | "not_running" | "no_channel";
         }) => void) | undefined)?
     ]>;
+    /** [c209-D] the EXPLICIT addressing name (CC Agent.name parity, validated at spawn: charset regex +
+     *  "main" reserved). Distinct from `description` (the display/legacy-matching label): the name layer
+     *  resolves latest-wins ("a newer agent took the name"), the description layers keep their
+     *  running-preferred + ambiguous posture. Absent on pre-[c209] rows and unnamed spawns. */
     name?: string;
+    /** design/129: this child OUTLIVES its parent turn — owner is the SESSION id; the parent-teardown reap
+     *  skips it; `reapSessionBackground` is its terminal anchor. Explicit flag, never inferred from key values
+     *  (hostTaskId===sessionId deployments would otherwise be ambiguous). */
     sessionScoped?: true;
+    /** Terminal snapshot (bounded, {@link BG_AGENT_RESULT_MAX} in subagent.ts) — served by TaskOutput
+     *  once the child finishes. */
     result?: string;
+    /** RB-205-B: the FULL result (bounded only by the defensive {@link BG_AGENT_RESULT_FULL_MAX} ceiling
+     *  in subagent.ts), set ONLY when it differs from `result` — same shape as {@link WorkflowRun.resultFull}
+     *  (workflow.ts NH-1). Before this field existed, the settle call sites pre-sliced `child.result` to
+     *  ~2-4K chars with no disclosure — clipTaskOutput's own file-pointer/offload-friendly design at the
+     *  poll layer was structurally unreachable because `result` itself could never be long enough to need it. */
     resultFull?: string;
+    /** design/158 S1 (RB-205-B 半) — the tool-result-store ref `resultFull`'s full text was spilled to,
+     *  the FIRST time a poll's `clipTaskOutput` actually cut it (lazy write, not at settle time). Cached
+     *  here so every LATER poll within the SAME cycle reuses the same ref instead of re-writing (the
+     *  store's own `put` is write-once too, but re-deriving/re-calling it every poll would still cost a
+     *  redundant round-trip on a durable backend, and a changing ref across polls would be a needless
+     *  disclosure churn). {@link reviveBackgroundAgentLane} clears this on revive — the cycle's full text
+     *  is gone, so a stale ref must not be reused across cycles. Ref format ties in `reviveCycle` (see
+     *  {@link import("./task-registry-agent.js").spillClippedAgentResult}) precisely so a revived cycle's
+     *  eventual spill lands under a DIFFERENT ref rather than colliding with (and being silently refused
+     *  by the write-once store under) cycle 1's. */
     spillRef?: string;
     error?: string;
+    /** RB-386② ([2090]) — the machine-readable failure code beside `error`, threaded from the settle
+     *  mint point (subagent.ts computes it ONCE from the child's TaskResult.errorCode taxonomy /
+     *  extractErrorCode — single source with the sync report's classification). Served on the failed
+     *  row's poll `details` and the failed terminal notification. Absent when no code was known. */
     errorCode?: string;
+    /** RB-386② — retryability verdict for a FAILED row, computed at the settle mint point by the SAME
+     *  classifier the sync report face uses (`classifySubagentError` — error_kind ∈ rate_limit/
+     *  overloaded/timeout/network ⇒ true, logic ⇒ false). Stored rather than re-derived so the core
+     *  poll lane never has to import the agents-domain classifier (no new domain cycle). */
     errorRetryable?: boolean;
+    /** RB-405 G3 ([2135]/[2136]) — the coarse classification KIND beside `errorRetryable`
+     *  (classifySubagentError's error_kind ∈ rate_limit/overloaded/timeout/network/logic), threaded
+     *  from the same settle mint point and stored for the same no-domain-cycle reason as its sibling.
+     *  Rendered on the FAILED row's poll TEXT face as the `(error_kind: …, retryable: …)` clause —
+     *  the same field names the sync report's error_kind line already speaks. */
     errorKind?: string;
+    /** Ruled 2026-08-05 (governance kind follow-up): the wait hint paired with a deferred-retryable
+     *  failure (`usage.*` codes — errorKind `"governance"`), threaded from the same settle mint point
+     *  as its three siblings. Without it the background faces exposed `retryable:false` with no way to
+     *  know WHEN the refusal lifts — the sync report card carried `retryAfterMs` while the bg poll/
+     *  notification faces structurally lost it. */
     errorRetryAfterMs?: number;
+    /** fidelity-sweep A1: `result` arrived AFTER a kill won the status race — it is the child's partial
+     *  work (produced before/while being stopped), backfilled by the refused settle. Poll frames label it. */
     resultIsPartial?: boolean;
+    /** design/134 §3.3 (R3): the PENDING attribution marker, written by {@link TaskRegistry.markStopSource}
+     *  at the kill INITIATION site, strictly BEFORE the abort/status flip (once the handle leaves "running"
+     *  the marker is refused and attribution falls back to "system"). First-marker-wins. */
     stopSource?: StopSource;
+    /** The LANDED attribution — set exactly when the handle goes `killed`, never rewritten afterwards
+     *  (first-writer-wins, same discipline as the terminal status itself). Absent on natural completion/failure. */
     stoppedBy?: StopSource;
+    /** RB-375 A1 — the reap-time terminal notifier, hung by the spawn lanes (subagent.ts) right after
+     *  registration: composes and sends the SAME terminal faces (observer sink + parent notification)
+     *  the child's own unwind would, so {@link import("./task-registry.js").TaskRegistry.reapSessionBackground}
+     *  can emit the terminal news AT REAP TIME instead of waiting on the child's unwind (which blocks on
+     *  the in-flight tool actually honoring the abort — unbounded). The bash handle's `onTerminal` twin.
+     *  Cleared at the accepted settle (with `notify`); invoked at most once via {@link terminalNotified}. */
     onReapTerminal?: () => void;
+    /** RB-375 A1 — terminal-notification once-latch (the bash/monitor `terminalNotified` twin): claimed
+     *  by whichever side reaches its emit point first — the session-release reap sweep (synchronous send)
+     *  or the child's own unwind (`TaskRegistry.claimAgentTerminalNotify`). The loser stays silent, so a
+     *  reaped child never double-announces. Cleared on revive (a new stop cycle owns its own terminal). */
     terminalNotified?: true;
 }
+/** design/135 G2 (Monitor): injectable timer/clock seam for the monitor watcher — the 200ms batch window
+ *  and the timeout/storm checks must be drivable by a test without real sleeps (design/87 discipline).
+ *  `setInterval` receives an ASYNC tick (the default adapter fires it void; a fake can await it). */
 export interface MonitorTimers {
     setInterval: (fn: () => unknown, ms: number) => unknown;
     clearInterval: (handle: unknown) => void;
     now: () => number;
 }
 export declare const defaultMonitorTimers: MonitorTimers;
+/** design/135 G2: Monitor watch — background_bash's near kin, but the watcher streams stdout LINES as
+ *  batched event notifications instead of firing one terminal notify. Spool stays re-readable (TaskOutput). */
 export interface MonitorTaskHandle extends SemaTaskHandle {
     type: "monitor";
     env: ExecutionEnv & BackgroundShellCapability;
     shellId: BackgroundShellId;
+    /** RB-238/RB-239/RB-240 ([1937] M1-M3) spool honesty fields: `droppedBytes`/`dropUnknown` = env-side
+     *  tail-buffer eviction (see the bash handle's twin); `dropNotified` = the once-latch for the event-stream
+     *  disclosure (terminal frames disclose unconditionally); `drainFailed` = the stop-time final drain poll
+     *  failed, so the spool may be missing the last window; `timedOut`/`timeoutSec` = the env's own
+     *  background time budget killed the process (bash-lane parity — renders distinguishably from a stop). */
     spool: {
         stdout: string;
         stderr: string;
@@ -168,8 +402,18 @@ export interface MonitorTaskHandle extends SemaTaskHandle {
         timedOut?: boolean;
         timeoutSec?: number;
     };
+    /** Partial (newline-less) stdout tail awaiting completion — a line becomes an event only once terminated. */
     lineBuf: string;
+    /** Per-batch monotonic counter → unique notification dedup keys (see task-notification.ts). */
     seq: number;
+    /** RB-334 (CC `PCo`/`TIs` 220:403278-403321): the TWO-LEVEL event-storm control's state.
+     *  Level 1 = a token bucket (`stormTokens` out of `stormBurst`, refilled one per
+     *  `stormRefillIntervalMs`): a batch that cannot consume a token is SUPPRESSED (its lines stay in the
+     *  re-readable spool) and counted in `suppressedBatches`; the next batch that DOES consume one first
+     *  emits the disclosure frame naming that count. Level 2 = kill, and only for a monitor that stayed
+     *  continuously over budget since `overloadSince` for MONITOR_STORM_KILL_AFTER_MS.
+     *  `lastSuppressedAt` clears `overloadSince` once the pressure is old enough (CC's `OCo * 3` rule) —
+     *  a short burst every few minutes must never accumulate into a kill. */
     stormTokens: number;
     stormBurst: number;
     stormRefillIntervalMs: number;
@@ -179,24 +423,65 @@ export interface MonitorTaskHandle extends SemaTaskHandle {
     lastSuppressedAt?: number;
     batchWindowMs: number;
     maxBatchesPerMinute: number;
+    /** Session-level residency (design/129 sessionScoped semantics): reaped by `reapSessionBackground`,
+     *  skipped by the per-run `clearBackgroundForOwner`, and NEVER timeout-killed by the watcher. */
     persistent?: true;
     sessionScoped?: true;
+    /** Deliver-a-living-service ledger mark — same semantics as the bash handle's `retained` (see there). */
     retained?: true;
+    /** Non-persistent only: watcher-enforced hard deadline (epoch ms on the injected clock).
+     *  (CC parity): this deadline — not the parent run — is the watch's lifetime anchor.
+     *  A monitor's life = min(timeout, process exit, TaskStop); a persistent one is SESSION-anchored.
+     *  NEITHER is run-anchored: the run teardown leaves an in-window watch alive (settle/evict/dispose
+     *  all skip it) so between-turns events keep flowing through the pending lane. */
     deadlineAt?: number;
     timeoutMs?: number;
     watcher?: unknown;
+    /** RB-239 ([1937] M2): a watcher tick is suspended on its pollBackground await RIGHT NOW. The stop-time
+     *  final drain must skip its own poll then (that in-flight tick already consumed the env cursor — and a
+     *  never-resolving adapter must not pin TaskStop). Set/cleared in lockstep with the tick's re-entrancy
+     *  guard. */
     tickInFlight?: true;
     timers: MonitorTimers;
     onEvent?: (n: TaskNotificationPayload) => void;
     stopSource?: StopSource;
     stoppedBy?: StopSource;
+    /** Terminal-notification once-latch — same discipline as the bash handle (fidelity R1-3). Only the
+     *  TERMINAL frame is latched; "event" frames are unaffected. */
     terminalNotified?: true;
+    /** design/158 S2 (RB-364 半) — the offload store a ROLLED-OFF spool middle spills to, captured at
+     *  REGISTRATION time (RegisterMonitorInput's additive field), not per-poll like the background_agent
+     *  lane's `TaskPollOptions.toolResultStore` (S1): the roll happens inside the watcher tick — an async
+     *  timer callback with no per-call "access" to thread a store through — so registration is the only
+     *  point that has one to hang on the handle. Absent ⇒ legal degrade: `rollSpoolText`'s `onDrop` hook
+     *  is simply never wired, byte-identical to pre-S2 rolling (design/158 §2.2). */
     toolResultStore?: ToolResultStore;
+    /** design/158 S2 — the session id spilled refs are scoped under (same `TaskAccess.sessionId` role as
+     *  every other `buildToolResultRef` call site); captured at registration for the same reason as
+     *  `toolResultStore` above. */
     spillSessionId?: string;
+    /** design/158 S2 — next segment index to mint for the STDOUT dropped-middle ref chain (0-based;
+     *  design/158 §3 "方案 a": a ref PER dropped segment, chained by index, rather than one ref with an
+     *  append primitive — ToolResultStore's contract is write-once with no append). stdout and stderr get
+     *  INDEPENDENT counters (this field vs `spillErrSegCount`) so each stream's own segments concatenate
+     *  back in original byte order without interleaving the other stream's drops between them. */
     spillSegCount?: number;
+    /** design/158 S2 — the STDERR twin of {@link spillSegCount}. */
     spillErrSegCount?: number;
+    /** design/158 S2 — cumulative chars (UTF-16 code units, `string.length`) handed to `store.put`
+     *  across every segment this handle has spilled so far (both streams combined) — the per-handle
+     *  disk-cap accounting ({@link import("./task-registry-monitor.js")} reads `MONITOR_SPILL_CAP_CHARS`
+     *  against this). RB-396-b: the field used to be named `spillBytesUsed` while the ledger counted
+     *  chars — renamed to the axis it really measures (see the constant's own doc for why chars). */
     spillCharsUsed?: number;
+    /** design/158 S2 — the per-handle spill cap (`MONITOR_SPILL_CAP_CHARS`) was reached; further
+     *  rolled-off middles are no longer spilled (already-written segments stay readable — "earlier
+     *  segments retained"). One-time latch; the poll disclosure reads it to stop claiming full ref
+     *  coverage. */
     spillCapped?: true;
+    /** design/158 S2 — at least one `store.put` for this handle rejected or threw. One-time latch; the
+     *  poll disclosure downgrades its wording once this is set (never claims the ref chain is complete —
+     *  the fire-and-forget write may have silently failed; see task-registry-monitor.ts's spill helper). */
     spillFailed?: true;
 }
 export type RegisteredTaskHandle = BackgroundBashTaskHandle | WorkflowTaskHandle | BackgroundAgentTaskHandle | MonitorTaskHandle;
@@ -205,15 +490,27 @@ export interface RegisterMonitorInput extends TaskAccess {
     env: ExecutionEnv & BackgroundShellCapability;
     description?: string;
     toolUseId?: string;
+    /** Session-level residency: no watcher timeout; reaped by session release (design/129 semantics —
+     *  when set, `owner` MUST be the session id and `sessionScoped` should be set too). */
     persistent?: boolean;
+    /** design/129 explicit-flag discipline: session-scoped access matching + session-terminal reap. */
     sessionScoped?: true;
+    /** Non-persistent watch deadline (ms). The tool clamps to [1, 3_600_000], default 300_000. */
     timeoutMs?: number;
+    /** The event sink — each stdout-line batch AND the single terminal state fires exactly one payload. */
     onEvent?: (n: TaskNotificationPayload) => void;
+    /** design/87: injectable timers/clock (tests drive ticks + time manually; default = real timers). */
     timers?: MonitorTimers;
+    /** Batch window (ms, default 200): lines arriving within one tick coalesce into one notification. */
     batchWindowMs?: number;
+    /** RB-334: the SUSTAINED batch rate the storm bucket refills at (default 50/min). Exceeding it is
+     *  suppression, not death — see `stormBurst` and MONITOR_STORM_KILL_AFTER_MS. */
     maxBatchesPerMinute?: number;
+    /** RB-334: burst capacity of the storm bucket (default MONITOR_STORM_BURST = CC's 10). */
     stormBurst?: number;
     now?: number;
+    /** design/158 S2 (RB-364 半) — the offload store a rolled-off spool middle spills to (see
+     *  {@link MonitorTaskHandle.toolResultStore}). Absent ⇒ legal degrade, byte-identical rolling. */
     toolResultStore?: ToolResultStore;
 }
 export interface RegisterWorkflowInput extends TaskAccess {
@@ -223,28 +520,109 @@ export interface RegisterWorkflowInput extends TaskAccess {
     description?: string;
     toolUseId?: string;
     now?: number;
+    /** γ 批 B-1 (live leg): the ORIGINATING session id — anchors the in-process handle to its session
+     *  so a later turn of the SAME session (fresh per-turn owner) reaches it through `canAccess`'s
+     *  workflow session arm, mirroring the durable predicate. A workflow is a SESSION-level asset
+     *  (its completion notification routes to the session) — deliberately unlike a background agent's
+     *  live handle, whose sibling-turn invisibility is a channel-discipline ruling (§3.1c). */
     originatingSessionId?: string;
+    /**
+     * Fired AT MOST ONCE when a `pollTask` through THIS registry entry (= the originating
+     * session's own lane; cross-session store-fallback polls don't fire it) serves a TERMINAL snapshot.
+     * The RunWorkflow tool wires it to {@link import("../orchestration/run-workflow-tool.js").WorkflowCompletionNotifier.ackServed}
+     * so the deployment can drop the now-redundant completion-inbox entry. Errors are swallowed.
+     */
     onServedTerminal?: () => void;
 }
+/** T2A-7 (2026-07-05 soak): one blocked-poll step, CLAMPED to the caller's deadline — a small timeoutMs
+ *  (e.g. 10ms) must not sleep the full 400ms step (~40× overshoot, and the overshoot window even served a
+ *  late terminal as success). `undefined` deadline keeps the plain step (callers without a deadline). */
 export declare const sleepPollStep: (deadline: number | undefined, signal?: AbortSignal) => Promise<void>;
 export declare const sleepMs: (ms: number, signal?: AbortSignal) => Promise<void>;
+/** design/135 G2 Monitor defaults (CC schema: 200ms batch window; timeout default 5min / max 60min).
+ *  `MONITOR_MAX_BATCHES_PER_MINUTE` = the SUSTAINED batch rate the storm bucket refills at
+ *  (RB-334: CC `TIs(bIs=10, OCo=2000)` 220:403284/403421-403423 refills 1 token per 2000ms = 30/min;
+ *  sema keeps its own 50/min figure — the sema batch window is the same 200ms, so the two are the same
+ *  order of magnitude — and derives the refill interval from it, see `stormRefillIntervalMs`). */
 export declare const MONITOR_BATCH_WINDOW_MS = 200;
 export declare const MONITOR_DEFAULT_TIMEOUT_MS = 300000;
 export declare const MONITOR_MAX_TIMEOUT_MS = 3600000;
 export declare const MONITOR_MAX_BATCHES_PER_MINUTE = 50;
+/** RB-334 (CC `bIs` 220:403421): burst capacity of the storm token bucket — how many batches may fire
+ *  back-to-back before the SUPPRESSION level engages. CC value, adopted verbatim. */
 export declare const MONITOR_STORM_BURST = 10;
+/** RB-334 (CC `FN_` 220:403423): how long a monitor must stay CONTINUOUSLY over budget before the
+ *  second level (kill) fires. CC value, adopted verbatim. */
 export declare const MONITOR_STORM_KILL_AFTER_MS = 30000;
+/** RB-334 (CC `bdd` 220:403427): the partial-line accumulator bound. sema's `lineBuf` had NO bound —
+ *  a monitored process emitting megabytes without a single newline grew it without limit (the spool's
+ *  own roll never covered it). Keep the TAIL (the newest bytes are the ones a watch is about). */
 export declare const MONITOR_LINE_BUF_CAP = 1048576;
+/** RB-239 ([1937] M2): the monitor event-result clip, shared by the watcher's batch/terminal emits and
+ *  the stop-time drain emit (one clip, one truncation wording). */
 export declare function clipMonitorEvent(s: string): string;
+/** RB-334 (CC `DCo` leg): per-line clip applied to the `lines[]` a batch carries. Spool untouched. */
 export declare function clipMonitorLine(s: string): string;
+/**
+ * RB-335 (CC `rFs` 220:507725-507743, all six branches verbatim): the ONE terminal-notification summary
+ * HEAD for a background command / monitor watch. Every terminal frame in the bash and monitor lanes
+ * composes its summary as `terminalTaskSummary(...)` plus this lane's own honest detail clause — the
+ * pre-RB-335 code had six hand-written phrasings whose comment claimed "no CC sample for those faces"
+ * while 220 carries a verbatim sample for every one of them (the `failed` branch was the concrete
+ * mismatch: sema said `failed (exit code N)`, CC says `failed with exit code N`).
+ */
 export declare function terminalTaskSummary(kind: "bash" | "monitor", label: string, status: "completed" | "failed" | "killed", exitCode?: number): string;
 export declare const TASK_OUTPUT_MAX_CHARS = 160000;
+/**
+ * CC `FHl` shape (pretty.js:458012-458016) when the task has an on-disk output file: TAIL-keep (a
+ * background command's latest output is the valuable end) behind a `[Truncated. Full output: <path>]`
+ * pointer so the model can Read the full spool. Without a file (workflow/agent results), keep the
+ * legacy head+tail middle-omission — there is no path to point at, and the head often carries status.
+ * RB-198 F4: the clip arithmetic itself moved to the shared {@link clipWithFilePointer} (a second caller,
+ * the foreground Bash tool, needed the SAME already-hardened RB-85/RB-112/RB-122 logic) — this wrapper
+ * only supplies the task-output budget.
+ */
 export declare function clipTaskOutput(s: string, fullOutputPath?: string): string;
 export declare function statusFromBackground(status: string, exitCode?: number): SemaTaskStatus;
+/** Rolling middle-drop bound for the bash spool, shared by the watcher's per-tick accumulate and the
+ *  teardown settle's terminal flush: keep head+tail halves within `cap`, account the dropped middle in
+ *  `rolledChars` (the honesty counter the poll face reports as permanently-dropped bytes).
+ *
+ *  design/158 S2 (RB-364 半): `onDrop`, when given, is called SYNCHRONOUSLY (before this function
+ *  returns) with exactly the middle substring being dropped — the ONE place that substring is ever
+ *  materialized, so a caller wanting to preserve it (the monitor lane's spill-to-offload-store) does not
+ *  need to re-derive the same slice arithmetic a second time. Every EXISTING caller (the background_bash
+ *  lane, task-registry.ts) omits the 4th argument, so their behavior — return value AND `rolledChars`
+ *  accounting — is untouched byte-for-byte; the callback is a pure side-channel hook. */
 export declare function rollSpoolText(spool: {
     rolledChars: number;
 }, s: string, cap: number, onDrop?: (dropped: string) => void): string;
+/** design/158 S2 (RB-364 半) — per-monitor-handle hard cap on cumulative CHARS (UTF-16 code units)
+ *  spilled to the offload store (design/158 §3's S3 half, pulled forward alongside S2). Once a
+ *  handle's running total reaches this, further rolled-off middles are simply not spilled —
+ *  already-written segments stay readable (the poll disclosure says "earlier segments retained"),
+ *  matching the pre-S2 loss shape for whatever is dropped PAST the cap. Exported so the boundary is a
+ *  testable contract, not a buried literal.
+ *
+ *  RB-396-b (回溯复查批, [c209-C] R2 C4① char/byte 同名异轴族): the constant used to be named
+ *  `..._BYTES` while the ledger added `dropped.length` — chars, up to ~3× fewer than UTF-8 bytes on
+ *  multibyte content. CHARS is the axis kept (name changed, arithmetic untouched) because it is the
+ *  offload store family's own coordinate (`InMemoryToolResultStore.maxTotalChars` evicts by
+ *  `content.length`; `ToolResultSlice.totalChars`) and the spool's `rolledChars` axis — one unit
+ *  end-to-end; a `Buffer.byteLength` ledger here would sit crosswise to the store's own cap. */
 export declare const MONITOR_SPILL_CAP_CHARS: number;
+/** RB-238 ([1937] M1): fold one poll's env-side-loss disclosure into the spool's account. The env's
+ *  tail buffer evicts its HEAD under pressure (node-execution-env 8MB bound) — those bytes are gone
+ *  before any watcher ever saw them, which is a different loss than the registry-side `rolledChars`
+ *  middle-drop. `bytesDroppedBeforeCursor` only counts bytes dropped before an unconsumed cursor, so
+ *  summing successive polls never double-counts; an env that says only `truncated` (no byte figure)
+ *  degrades to the unquantified flag. Shared by ALL THREE consumers of a background poll — the monitor
+ *  watcher, the bash watcher, and the blocking pollBackgroundBash leg (one class, one arithmetic).
+ *  The blocked-wait leg used to keep its own hand-rolled `dropped += bytesDroppedBeforeCursor ?? 0`
+ *  accumulator, which ignored `truncated` outright: an env that discloses the loss WITHOUT a byte
+ *  figure produced ZERO disclosure on that leg. It routes through here now — the header's former
+ *  "already accounted this on its own" claim was describing exactly the half-accounting that made the
+ *  degraded shape invisible. */
 export declare function accountDroppedBytes(spool: {
     droppedBytes?: number;
     dropUnknown?: true;
@@ -252,10 +630,19 @@ export declare function accountDroppedBytes(spool: {
     truncated?: boolean;
     bytesDroppedBeforeCursor?: number;
 }): void;
+/** RB-238 ([1937] M1) — the POLL-FACE wording for env-side loss (the terminal/event-frame wording is
+ *  {@link droppedGapNote}'s; the two faces differ by design and always have). One function so the two
+ *  quantified/unquantified branches cannot drift between the three legs that render it: the monitor
+ *  re-readable spool, the bash re-readable spool, and the bash blocked wait. Trailing newline included
+ *  (it is a banner LINE above the stdout heading); "" when nothing was dropped. */
 export declare function spoolDropNote(acct: {
     droppedBytes?: number;
     dropUnknown?: true;
 }): string;
+/** The re-readable spool fields {@link renderSpoolBody} reads — the intersection of the bash handle's
+ *  optional `spool` and the monitor handle's mandatory one (both carry supersets: `mirrorFailed` is
+ *  bash-only, `drainFailed`/`dropNotified` monitor-only). Declared as a named shape, not inlined, so
+ *  the renderer's contract is one thing both lanes are checked against. */
 export interface RenderableSpool {
     stdout: string;
     stderr: string;
@@ -266,27 +653,82 @@ export interface RenderableSpool {
     droppedBytes?: number;
     dropUnknown?: true;
 }
+/** The per-lane inputs {@link renderSpoolBody} cannot derive from the spool itself.
+ *  `rolledExtraClause` / `drainNote` are PRE-RENDERED STRINGS, deliberately not booleans or a lane
+ *  discriminator: the renderer must stay ignorant of which lane called it, otherwise the two monitor-only
+ *  disclosures (design/158 S2 spill refs; RB-239 stop-time drain failure) come back as in-renderer
+ *  branches on a kind switch — the exact shape that let the two hand-copied renderers drift in the first
+ *  place. Both are "" on a lane that has no such disclosure. */
 export interface SpoolBodyOptions {
+    /** The handle is still running (drives the "running" display status). */
     running: boolean;
+    /** Fallback display status for a non-running handle with no recorded exit code. */
     handleStatus: SemaTaskStatus;
+    /** The lane's filter+clip projection, applied to stdout and stderr alike. */
     shape: (text: string) => string;
+    /** Appended INSIDE the roll note, before its newline ("" when the lane has no extra clause). */
     rolledExtraClause: string;
+    /** A full banner line (own trailing newline) rendered after the drop note, or "". */
     drainNote: string;
 }
+/** RB-238/RB-239/RB-240 ([1937] M1-M3) — the ONE renderer for a re-readable spool's TaskOutput body,
+ *  shared by the monitor lane (pollMonitorLane) and the bash spool lane (pollBackgroundBash).
+ *
+ *  Both faces were hand-copied twins carrying three real disclosure bugs' worth of wording (env-side
+ *  eviction vs registry roll are SEPARATE notes, never merged; a self-inflicted background-timeout kill
+ *  renders distinguishably from an external stop; a spool with a disclosed gap must stop advertising
+ *  itself as "full") — kept in sync by a comment on each side telling the reader to make the same edit
+ *  twice. The heading rule is the load-bearing one: any disclosed gap (env-side drop OR a failed
+ *  stop-time drain) downgrades the heading, so a caller cannot add a gap note and forget the heading.
+ *
+ *  NOT used by the blocked-wait leg: that face is a consume-once "new stdout" increment with its own
+ *  wording ("accumulated char(s) dropped from the middle during the blocked wait"), an intentional
+ *  divergence — it shares {@link accountDroppedBytes} + {@link spoolDropNote}, not this. */
 export declare function renderSpoolBody(spool: RenderableSpool, opts: SpoolBodyOptions): string;
+/** RB-238: the honesty suffix for frames over a spool with env-side loss. Empty when nothing dropped. */
 export declare function droppedGapNote(spool: {
     droppedBytes?: number;
     dropUnknown?: true;
 }): string;
+/** RB-238: the event-stream disclosure rides the FIRST batch after a loss is observed (once-latch —
+ *  a chatty watch must not repeat the note on every batch; terminal frames disclose unconditionally). */
 export declare function firstDropNote(spool: {
     droppedBytes?: number;
     dropUnknown?: true;
     dropNotified?: true;
 }): string;
+/** RB-244 ([1937] T1): ONE wording for "you stopped nothing" across every already-terminal stop face —
+ *  the in-process bash/monitor/agent arms and the durable-row fallback previously split: the durable
+ *  arm answered honestly while the in-process arms claimed `Terminated <id>.` over work that finished
+ *  (or was killed) on its own. CC 220 refuses the call outright (`Task X is not running (status: …)`,
+ *  220:468231-468236); sema keeps the idempotent no-op posture (stopWorkflow / durable-arm precedent,
+ *  no isError) but the receipt must tell the truth. */
 export declare function alreadyTerminalStopNote(id: string, status: string): string;
+/** design/115 review B1 → β 批 A-2: register-side fail-fast, now on BOTH axes — `canAccess` is
+ *  default-deny, so a handle missing either axis would be unreachable by every caller (a dead row
+ *  is worse than a loud registration error). The production chain always sets both (hostTaskId +
+ *  principal-or-"default"); a direct registry caller declares its access domain explicitly
+ *  (`scope: "default"` is the single-tenant spelling — explicit, never implied). */
 export declare function assertOwnership(input: TaskAccess, site: string): void;
+/** γ 批 B-1 (2026-07-22, [1510] 同窗) — POSITIVE-MATCH form, one polarity with `canAccess`/
+ *  `canAccessAgentRecord` (β 批 A-2): scope must match, then the caller must HIT an arm — owner
+ *  (the spawning task) or SESSION (the run's `originatingSessionId`). The session arm is the B-1
+ *  HIGH fix: the completion notification routes back to the originating SESSION, but per-turn
+ *  taskIds die with their turn — before this arm, a later turn of the same session could not poll
+ *  or stop its own workflow (default-deny functional breakage, [1502] R4 sibling). The old form's
+ *  `access.owner === undefined ⇒ pass` scope-only residue is gone with the same β polarity ruling
+ *  (design/136 §2.3 S-1 定谳 posture, now positive-match on every arm). Exported: the run-workflow
+ *  tool's resume-ownership recheck and a deployment's serving layer apply the SAME predicate. */
 export declare function canAccessWorkflowRun(run: Pick<WorkflowRun, "scope" | "sourceTaskId" | "originatingSessionId">, access: TaskAccess): boolean;
 export declare function formatWorkflowRun(run: WorkflowRun): UnifiedTaskResult;
+/** design/157 B13 一期定稿(二期细察补充 §「私有成员解法」)——the kernel-面 seam the MON/WF lane free
+ *  functions call through instead of `this`: exactly the 5 members `startMonitorWatcher`/`stopMonitor`/
+ *  `registerMonitor`/`registerWorkflow` actually reach into (`this.*` 耦合 grep 逐方法统计,见 B13 档).
+ *  Does NOT include `fireServedTerminal` (WF-private helper, only called from within `pollWorkflow`
+ *  itself — travels with the lane, never crosses the core seam) nor any AGENT-domain member (二期 extends
+ *  this as `DurableAgentCore` per B13 §「私有成员解法」). The TaskRegistry class satisfies this via a
+ *  `#coreView`-style cached object (`private readonly core: RegistryCore`), declared AFTER `handles` so
+ *  the eager `handles` field reference below sees an already-initialized Map. */
 export interface RegistryCore {
     handles: Map<string, RegisteredTaskHandle>;
     mintTaskId(type: SemaTaskType): string;
@@ -294,20 +736,62 @@ export interface RegistryCore {
     notifyTerminalOnce(handle: BackgroundBashTaskHandle | MonitorTaskHandle, send: () => void): void;
     pokeBgQuiescence(owner: string | undefined): void;
 }
+/** codex S1a F2 — writer-lease renewal period for armed durable rows (see ensureDurableHeartbeat).
+ *  Exported so deployments size `staleRunningMaxAgeMs` against it (recommend ≥10× this). */
 export declare const DURABLE_AGENT_HEARTBEAT_MS = 60000;
+/** design/151 S1a (codex F3): the durable fallback consults the store ONLY for handle-shaped ids —
+ *  a NAME (the fuzzy stop leg) or a foreign-domain id must not take a store round-trip, and a store
+ *  outage must never block the local name-resolution ladder. Mint form: `a` + 16 hex; the revive
+ *  leg re-registers the same form.
+ *  EXPORTED ([1518] server ask): a serving layer's fallback needs the SAME shape gate before its
+ *  durable arm (a bare exact-key miss lets padded/legacy/name-shaped ids leak into live branches —
+ *  the server 1.250 HIGH) — one shared regex kills the drift, roster-normalize precedent. */
 export declare const DURABLE_AGENT_HANDLE_RE: RegExp;
+/** Synthetic settle error the subagent reap path passes after a stop/parent teardown. It is NOT a
+ *  real child error — settleBackgroundAgent never stores it (status "killed" + stoppedBy already say
+ *  it); exported so the subagent call sites and the registry agree on the exact sentinel. */
 export declare const BG_AGENT_REAP_STOP_ERROR = "stopped (parent task ended or TaskStop)";
+/** CC206-B 欠账 — TaskStop name addressing, CC `XN` verbatim (206:574955-574962): NFKC-normalize, strip
+ *  control/format chars (whitespace-class ones survive), trim, lowercase, whitespace runs → hyphens. Both
+ *  the query and the candidate label go through this, so "Fix Tests" addresses "fix tests".
+ *  [c209-D] codex R4: EXPORTED — SendMessage's "main" reserved lane must use the SAME canonicalization
+ *  as this resolver, or an NFKC-equivalent spelling (fullwidth "ｍａｉｎ") skips the reserved lane and
+ *  reaches the description layers. One normalizer, every name face. */
 export declare function normalizeAgentName(s: string): string;
+/** CC `gtr` (fable 复审 F1 — 亲核 @16169850: NOT plain Levenshtein but OSA / restricted
+ *  Damerau-Levenshtein, WITH the adjacent-transposition term `o[i][s]=min(o[i][s], o[i-2][s-2]+1)`
+ *  when `e[i-1]===t[s-2] && e[i-2]===t[s-1]`). The transposition matters: a typo like "tset"→"test"
+ *  is distance 1 (CC has a Did-you-mean), plain Levenshtein would call it 2. */
 export declare function editDistance(a: string, b: string): number;
+/** CC `htr` shape (206:519814-519827): candidates within Levenshtein ≤2 (length-diff ≤2 pre-filter),
+ *  best-first; the single best is the "Did you mean" suggestion (`htr(e, keys, 1)[0]`, 206:575196). */
 export declare function closestName(query: string, candidates: Iterable<string>): string | undefined;
+/** β 批 A-2 (clay 裁定 2026-07-22, 一步到位): DEFAULT-DENY on BOTH axes — the old predicate skipped
+ *  a missing axis (owner-less handle = readable by everyone in scope; scope-less handle = readable
+ *  across scopes), splitting polarity with `canAccessAgentRecord` and re-opening the session-axis
+ *  class cli/server just swept. Registration now REQUIRES both axes ({@link assertOwnership}), so a
+ *  missing axis here is a broken invariant, answered with denial, never a pass. */
 export declare function canAccess(handle: SemaTaskHandle, access: TaskAccess): boolean;
+/** design/157 B13 二期(B13 档预调研 §4.2/§4.3 定稿)— the durable-agent lane's widened core seam.
+ *  Extends {@link RegistryCore} with EXACTLY the 5 extra members the AGENT lane's `this.*` census
+ *  reached (73 处/9 成员,扣车道内互调后落在这 5 个上,见 B13 档「二期细察补充」)。
+ *  `durableAgentWrite`/`ensureDurableHeartbeat`/`settleBackgroundAgent` are NOT here — they are lane
+ *  members themselves (车道内直接函数调用;类上只留转发或不留)。The class satisfies this via the
+ *  same cached-view field, upgraded with lazy getter/setter proxies (an IIFE capturing `this`) so
+ *  field declaration ORDER no longer constrains it — `writerId`/`reapingHandles` 등 are read at
+ *  call time, after construction completes. */
 export interface DurableAgentCore extends RegistryCore {
     readonly writerId: string;
     readonly reapingHandles: Set<string>;
     readonly claimingHandles: Set<string>;
+    /** get/set proxy — `ensureDurableHeartbeatLane` both reads AND writes the timer slot. */
     durableHeartbeatTimer: ReturnType<typeof setInterval> | undefined;
     readonly deliverConfirmTimeoutMs: number;
 }
+/** design/153 §7.2c (件3b) — the compensable reservation ticket {@link TaskRegistry.claimParkedAgent}
+ *  returns: everything {@link TaskRegistry.rollbackParkedClaim} and the 件3c consume flip need to
+ *  proceed or compensate. `row` is the PRE-RESERVATION snapshot (restored verbatim on rollback);
+ *  `reservedRev` is the row's rev AFTER the reservation CAS (the next guarded write binds to it). */
 export interface ParkedClaimTicket {
     handle: string;
     scope: string;
@@ -316,29 +800,85 @@ export interface ParkedClaimTicket {
     reservedRev: number;
     row: import("./background-agent-store.js").BackgroundAgentRecord;
 }
+/** P1-3 独立复审第三轮(已修) — sibling of {@link mintCompletionId} for a caller that must compute the
+ *  value BEFORE it is safe to commit (a CAS not yet known to win): fill-once with an EXTERNALLY-chosen
+ *  value instead of generating a fresh one. Exists because `rollbackParkedClaim`'s original fix minted
+ *  directly onto the live handle before its durable CAS was confirmed — a losing CAS then left a
+ *  non-terminal ("parked") handle carrying a completionId nothing ever cleared, which a later legitimate
+ *  parked→running flip (`consumeParkedFlip`) silently carried into an unrelated real completion via
+ *  `mintCompletionId`'s own fill-once guard (independently reproduced end-to-end). The fix: compute the
+ *  candidate once, use it in the durable payload immediately (that write is fine — it only takes effect
+ *  if its own CAS wins), and commit it to the live handle ONLY from the call that already knows the CAS
+ *  won. */
 export declare function commitCompletionIdIfEmpty(target: {
     completionId?: string;
 }, value: string): string;
 export interface RegisterBackgroundAgentInput extends TaskAccess {
+    /** design/153 §7.2d (件3c) — parked-resume registration shape: the handle is born PARKED (the
+     *  pre-consume window keeps the live face's checkpoint arbitration; the consume flip
+     *  {@link TaskRegistry.adoptParkedResume} is the only path to running). Pass the ticket's token
+     *  and a stop-arbitration closure alongside. Also licenses replacing an in-process PARKED prior
+     *  handle of the same id (the planned park→resume handoff; lane poisoned like the terminal replace). */
     initialStatus?: "parked";
+    /** design/153 §7.2d — the parked checkpoint token this parked-born handle waits on. */
     parkedCheckpointToken?: string;
+    /** design/153 §7.2d — the TaskStop arbitration closure for the parked-born handle (expire CAS). */
     resolveParkedStop?: () => Promise<boolean>;
+    /** design/147 S2a (codex R5 F7) — declare that the spawner WILL attach a mid-run delivery
+     *  channel (attachAgentNotify) once the child's lane binds. Only declared-"attaching" rows buffer
+     *  startup-window messages; an undeclared row refuses `no_channel` IMMEDIATELY — a spawner that
+     *  never attaches must not collect acknowledged-then-discarded messages (silent loss). */
     deliveryChannel?: "attaching";
+    /** S2b RB-27① codex F1 — the spawner DECLARES whether a parked message is redeemable: true when
+     *  the child's session outlives the run (retain ledger or session-scoped registration), so a
+     *  continuation can drain the park. A non-retained row must NOT hand out parked acknowledgements
+     *  (the session is released right after settle — the park would be irrecoverable): its
+     *  lane-dead race window reads as `not_running` instead, steering the sender to the settled path. */
     retainedContinuation?: boolean;
     description?: string;
+    /** [c209-D] explicit addressing name (CC Agent.name parity) — the CALLER validates it (charset +
+     *  reserved "main") before registration; the registry stores it verbatim. Duplicate names are legal
+     *  (latest-wins at resolution; older rows stay task_id-addressable). */
     name?: string;
+    /** [1358]/[1336]A — the RESOLVED subagent type ("general-purpose"/"fork"/a roster name), persisted
+     *  so a REVIVE cycle's observer frames can reproduce the row's TYPE column (never the description). */
     agentType?: string;
+    /** [1371]② — the spawn frame's parent linkage, persisted so a REVIVE cycle's spawn frame nests the
+     *  revived row exactly like the first spawn did. The caller passes the SAME values it emitted on the
+     *  original frame (parentTaskId already [1344]②-clamped there; parentSessionId always-on). */
     parentTaskId?: string;
     parentSessionId?: string;
+    /** δ 批 [1498]⑦ — the ROOT host session of the delegation tree (fixed point down the trusted
+     *  internals chain; equals parentSessionId at depth 1). Persisted on the handle, the durable row
+     *  and the roster so recovery faces enumerate the whole tree under the root without alias walks. */
     rootSessionId?: string;
+    /** design/151 S3b — revival lookup keys (CC meta-sidecar shape): the RESOLVED model id and the
+     *  team name, persisted on the durable row so a tier-3 revival rebuilds the spec the way a fresh
+     *  named-teammate spawn would. Lookup keys only, never a serialized spec. */
     model?: string;
     teamName?: string;
     toolUseId?: string;
     abort: AbortController;
     now?: number;
+    /** design/129: register as session-scoped (owner MUST be the sessionId; see the handle flag). */
     sessionScoped?: true;
+    /** design/151 S1a (LOW-12): caller-supplied handle — the tier-3 revival leg (S3) re-registers the
+     *  SAME durable handle so the row stays continuous across restarts. Collision with a live in-memory
+     *  row throws (registerBackgroundBash parity). Absent ⇒ mint. */
     id?: string;
+    /** design/151 S1a: the durable execution-row ledger. Present (with BOTH owner and scope — the
+     *  durable predicate is fail-closed on both axes) ⇒ this registration writes a durable row
+     *  (put → bind → settle, a serialized best-effort single-writer lane); absent ⇒ the pre-151
+     *  in-memory-only lifecycle, byte for byte. */
     store?: BackgroundAgentStore;
+    /** design/151 §7.2 (X-2/F-7) — tier-3 revival lane seeding: the CLAIMED durable row (identity
+     *  inherited verbatim, status running, writerId = this instance) and its post-claim rev. Present
+     *  ⇒ the durable lane starts from this snapshot with `written: true` and SKIPS the initial put
+     *  (the claim-CAS already committed the row); every later write CASes against `rev`, so the first
+     *  settle moves the claim forward instead of losing to it. Also authorizes REPLACING a leftover
+     *  TERMINAL in-memory handle of the same id (the pre-revival cycle's row survives ~1h of terminal
+     *  GC): its stale lane is silenced first — a queued/re-driven write from it carries the pre-claim
+     *  rev under this process's own writerId, and the adopt path would clobber the claim. */
     durableSeed?: {
         record: BackgroundAgentRecord;
         rev: number;