@sema-agent/core 5.20.0 → 5.21.0

package/dist/core/untrusted-egress.d.ts

@@ -3,7 +3,15 @@ export type { RedactionFinding, RedactionReport, RedactionConfidence, RedactionS
 export { summarizeRedactions } from "./arg-summary.js";
 export declare function redactSecrets(s: string, report?: RedactionReport): string;
 export declare function redactHostLeaks(s: string, report?: RedactionReport): string;
+/** Secret-redact + size-bound (NO injection fence) — the SAME-PRINCIPAL tier: workflow outputs/results/errors
+ *  riding back to the launching model/script, run rows behind scope-gated observe. Paths/URLs survive
+ *  ([1295]② — the assertion pattern depends on them); secrets never do. */
 export declare function boundedRedactedSummary(value: unknown, max: number): string;
+/**
+ * The FULL untrusted-egress transform (design/97 CORE-2): full host-leak redaction + size-bound + FENCE. Use
+ * for any worker prompt/output (#5 transcript) or steer content (#6) shown to a HUMAN or exported beyond the
+ * launching principal, so untrusted text can neither leak host internals nor pose as instructions.
+ */
 export declare function untrustedEgressForHuman(value: unknown, opts: {
     label: string;
     max: number;

package/dist/core/untrusted-text.d.ts

@@ -1,12 +1,72 @@
+/**
+ * Untrusted-text containment (design/53 §2.A — "untrusted-data-everywhere").
+ *
+ * A multi-agent code-orchestration system treats **every worker's output** (report / diff / code / module)
+ * as untrusted data: an LLM worker can be prompt-injected or adversarial, and its output flows into other
+ * models' prompts (the L3 judge, the leader, the next worker) where it could pose as instructions —
+ * e.g. emitting `</system-reminder>` to escape its framing and forge a verdict (threat BUG1, verify.ts).
+ *
+ * The trusted side of the codebase REJECTS such sequences (runtask.ts: trusted steering / deny reasons must
+ * not contain `</system-reminder>`). Worker text can't be rejected — it must be **contained**: this module
+ * NEUTRALIZES break-out sequences and wraps the text in a clearly-labeled opaque fence the consuming prompt
+ * tells the model to treat as data, not instructions. Structural and reusable across the chain, not a
+ * per-call point-fix.
+ *
+ * This is defense-in-depth, NOT a guarantee: an LLM cannot reliably honor a "this is data" boundary on its
+ * own (instructions and data share one channel). The real boundary is decorrelation + reading the objective
+ * artifact (the diff / working tree) rather than the worker's self-report (design/53 §3, design/54 §3).
+ */
+/**
+ * Neutralize structural break-out sequences in UNTRUSTED text so it can't escape its framing into
+ * model-facing instructions. Always neutralizes `<system-reminder>` / `</system-reminder>` (the codebase's
+ * elevated-authority wrapper) by inserting a zero-width space after the leading `<`. Pass `extraTags` to also
+ * neutralize a CALLER's own data-framing tags — e.g. `team.ts` embeds member output inside `<statement>` /
+ * `<team-discussion>`, so an untrusted member could emit `</statement>` to break out (search [46] BUG2);
+ * the caller passes those tag names. Tag names must be literal (alphanumeric/hyphen) — they are code-supplied
+ * wrapper names, never untrusted input. Idempotent for prompt assembly (a defused tag no longer matches).
+ */
 export declare function sanitizeUntrustedText(text: string, extraTags?: string[]): string;
+/**
+ * [c209-C] codex 收口 C1/C2 (metadata-driven, replaces the shape-anchored
+ * `stripLeadingSystemReminders`) — cut the engine-prepended prefix off a user-lane message using the
+ * EXACT length recorded on the message at mint time (`UserMessage.enginePrefixChars`, stamped where
+ * the engine concatenated first-frame listing reminders / a UserPromptSubmit additionalContext
+ * reminder / a resume continuation's trusted head AHEAD of the real user text). The first user turn
+ * carries those bytes as engine guidance, not user speech — a consumer that re-presents user
+ * messages under a `[user]`/`[User]:` label (the auto-mode classifier window, the compaction
+ * summarizer input) must not let them (a) impersonate user authority or (b) evict the real
+ * objective from a head-truncated excerpt.
+ *
+ * The old helper GUESSED by reminder shape, which mis-fired in both directions (codex 收口轮): a
+ * same-line engine mint (`<system-reminder>[deadline] …</system-reminder>`) was NOT recognized and
+ * entered the window under `[user]` authority, while a user who legitimately opened their own
+ * prompt with a byte-exact reminder block WAS stripped. Metadata removes the guess entirely:
+ * - a message WITH `enginePrefixChars` is cut at exactly that offset (no regex, no shape matching);
+ * - a message WITHOUT metadata is rendered VERBATIM — user-authored `<system-reminder>` prefixes
+ *   are never stripped, and OLD sessions (persisted before the field existed) render unchanged.
+ *   Conservative direction, deliberate: a classifier/summarizer seeing engine listings as user text
+ *   is acceptable; silently losing real user text is not.
+ * An out-of-range length (≤0 / > text length — corrupt or foreign data) is ignored the same way.
+ * [c209-C] R5: the parameter is `unknown` — the field can arrive as shape-poison from old/foreign
+ * imported sessions (a string "9", null) and the typeof/integer checks below are the total guard.
+ */
 export declare function cutEnginePrefix(text: string, enginePrefixChars: unknown): {
     text: string;
     cut: boolean;
 };
+/** An engine-trusted segment of a user-lane message: a half-open `[start, end)` UTF-16 code-unit
+ *  range — see `UserMessage.engineSegments` (engine/llm/types.ts) for the full field contract. */
 export interface EngineSegment {
     start: number;
     end: number;
 }
+/**
+ * [c209-C] R5 codex R4 复核 — the three-state result of {@link normalizeEngineSegments}. `absent`
+ * and `malformed` are DIFFERENT states on purpose (R4 #1): a message whose `engineSegments` field
+ * is present-but-malformed must render WHOLLY verbatim — the metadata family is suspect, so a
+ * co-present `enginePrefixChars` must NOT get a second chance to cut (absent metadata is the only
+ * state where the prefix sugar applies).
+ */
 export type NormalizedEngineSegments = {
     readonly state: "absent";
 } | {
@@ -15,14 +75,110 @@ export type NormalizedEngineSegments = {
     readonly state: "valid";
     readonly segments: ReadonlyArray<EngineSegment>;
 };
+/**
+ * [c209-C] R4 codex 终判 (R5: three-state + exception-safe over `unknown`) — validate
+ * `UserMessage.engineSegments` against the text it indexes into.
+ * - `absent`: the field is `undefined` (or an empty array — it claims no engine bytes), so the
+ *   `enginePrefixChars` sugar MAY still apply.
+ * - `valid`: EVERY range is well-formed (elements are objects whose `start`/`end` are integers,
+ *   `0 ≤ start < end ≤ text.length`, ascending and non-overlapping — `prev.end ≤ next.start`).
+ *   Returns FRESH `{start, end}` copies (canonical plain data, e.g. for the import gate).
+ * - `malformed`: anything else — including non-array values (`null`, `{}`), non-object elements
+ *   (`[null]`), and shape-poison (`[{}]`, string offsets) from old/foreign session data. ONE bad
+ *   range invalidates the WHOLE field and consumers render the entire message verbatim, prefix
+ *   suppressed (losing real user text is worse than showing engine bytes). NEVER throws: the input
+ *   is `unknown` by contract and any exotic shape (throwing getters included) collapses to
+ *   `malformed`.
+ * Shared single source for the mint clamp (agent-harness `createUserMessage`), the session import
+ * gate, and every projection side (auto-mode window / compaction serializer / prompt suggestions).
+ */
 export declare function normalizeEngineSegments(text: string, segments: unknown): NormalizedEngineSegments;
+/**
+ * [c209-C] R4 codex 终判 — the SEGMENT sibling of {@link cutEnginePrefix}: remove every
+ * engine-trusted `[start, end)` segment from a user-lane message, keeping the bytes OUTSIDE the
+ * segments verbatim (the caller/operator-authored content that derived views may present under
+ * `[user]`/`[User]:` authority). Unlike the prefix cut, segments can sit mid-message: the resume
+ * continuation preserves issue order (parked steer first, wake second — the public
+ * ResumeOutcome/ResumeRun contract), so a trusted engine frame may legally follow an untrusted
+ * fenced one.
+ *
+ * [c209-C] R5 (codex R4 #1) — the result distinguishes WHY nothing was cut: `malformed:true`
+ * means the field was PRESENT but bad (per {@link normalizeEngineSegments}) — the caller must
+ * render the whole message verbatim and MUST NOT fall through to `enginePrefixChars` (segments
+ * exist ⇒ they own the message; malformed ⇒ the metadata family is suspect wholesale). Only
+ * `cut:false, malformed:false` (absent metadata) allows the prefix-sugar fallback. Never throws.
+ */
 export declare function cutEngineSegments(text: string, segments: unknown): {
     text: string;
     cut: boolean;
     malformed: boolean;
 };
+/**
+ * [c209-C] R5 (codex R4 #3) — the ONE flatten under which `engineSegments`/`enginePrefixChars`
+ * offsets are DEFINED: a user-lane message qualifies only when its content is a plain string or a
+ * SINGLE text block (whose text is that same string). Multi-block / image-bearing content returns
+ * `undefined` and consumers render the message VERBATIM with their own local flatten — the two
+ * projection sides flatten blocks DIFFERENTLY (the auto-mode window joins with `\n` + `[image]`
+ * placeholders; the compaction serializer drops non-text blocks and joins with no separator), so a
+ * single `[start, end)` range would point at different characters on each side. The restriction
+ * costs nothing real: every engine-assembled prefixed/segmented message (first-frame objective
+ * concatenation, resume continuation) is minted from ONE plain string — the sole exception is a
+ * first-frame objective that ALSO carries user images, which now falls back to verbatim (the
+ * accepted conservative direction: engine listing bytes visible under user authority, never lost
+ * user text). Single-source helper shared by both projections, the suggestions transcript, and
+ * the session import gate. Accepts `unknown` (import-side data) and never throws.
+ */
 export declare function flattenableUserText(content: unknown): string | undefined;
+/**
+ * Defuse this module's triple-angle fence sentinels (`<<<` / `>>>`) inside an untrusted body so the body
+ * cannot forge {@link delimitUntrusted}'s own OPEN/CLOSE markers and break out of the fence. A worker (or
+ * an external page via `web_fetch`, an MCP resource — the label format is open-source, so the close marker
+ * `<<<END UNTRUSTED <label>>>>` is guessable) could otherwise emit the literal close marker followed by
+ * top-level injection. Caps any run of 3+ identical brackets at 2 consecutive by inserting a zero-width
+ * space — the reader still sees the text, but no `<<<`/`>>>` triple survives. Idempotent: a capped run
+ * (≤2) never re-matches `{3,}`. Defusing EITHER bracket breaks the marker; we defuse both for symmetry.
+ *
+ * Residual (council QUESTION, accepted): only ASCII `<`/`>` (U+003C/003E) are defused. A Unicode lookalike
+ * (fullwidth `＜`/`＞`, U+FF1C/FF1E) is NOT — but a fullwidth marker is a DIFFERENT string from the real
+ * ASCII close sentinel, so it cannot break out at the string level; at worst it visually resembles the
+ * fence to the model. Consistent with this module's "defense-in-depth, NOT a guarantee" posture.
+ *
+ * Exported (design/138 S2-C, O-F11/C-F10): the memory write-time scan detects a forged fence by diffing
+ * `defuseFenceMarkers(text) !== text` — the ONE sentinel definition serves both the defusing and the
+ * detection, so the two can never drift apart. Do not hand-copy the `<<<`/`>>>` pattern anywhere else.
+ */
 export declare function defuseFenceMarkers(body: string): string;
+/**
+ * design/177 — control-character hygiene for an untrusted BLOCK that is rendered as-is under a framing
+ * line (shared-store document content). Two steps, in order:
+ *  ① fold `\r\n` and a lone `\r` to `\n`, so a carriage return cannot repaint a rendered line;
+ *  ② scan by code POINT and replace every C0 control except tab and newline, plus the C1 range
+ *    (U+007F–U+009F), with U+FFFD.
+ *
+ * REPLACE, never delete — deliberately, and this is the half a naive strip gets wrong: deletion makes a
+ * document with an embedded escape sequence read as clean text, while a replacement character is a scar
+ * both the model and a human reviewer can see. Surrogate pairs survive intact (the scan is by code
+ * point, not by UTF-16 unit).
+ *
+ * This is the CHARACTER layer only. Structural containment (elevated-authority tags, fence sentinels)
+ * is {@link sanitizeUntrustedText} + {@link defuseFenceMarkers}, which the same pipeline applies after
+ * this one — a framing line is a discipline statement, tag neutralization is the structural defense,
+ * and an untrusted block needs both.
+ */
 export declare function defuseControlChars(text: string): string;
+/**
+ * Make untrusted text safe to interpolate INLINE on a trusted prompt line (not inside a {@link delimitUntrusted}
+ * fence) — e.g. design/80 D-F echoes a chosen option label into the "The user answered:" block. Folds EVERY
+ * line/space separator to a single space so the text cannot forge a new line — `\s` (covers CR/LF/TAB/VT/FF and
+ * U+2028/U+2029 + the Unicode spaces) PLUS U+0085 NEL, which `\s` does NOT match — caps the length, then applies
+ * the same tag-neutralization (`</system-reminder>`) + fence-sentinel (`<<<`/`>>>`) defusing the fenced body gets.
+ * Defense-in-depth, NOT a guarantee (same posture as the rest of this module).
+ */
 export declare function inlineUntrusted(text: string, maxLen?: number): string;
+/**
+ * Wrap untrusted text in a clearly labeled opaque fence. The consuming prompt should instruct the model to
+ * treat everything inside as untrusted data — never as instructions. Sanitizes internally (system-reminder
+ * neutralization + fence-sentinel defusing, on the body AND the label), so callers may pass raw
+ * worker/external text — and labels derived from external identifiers (hostnames, resource URIs).
+ */
 export declare function delimitUntrusted(label: string, text: string, maxBody?: number): string;

package/dist/core/usage-window-store.d.ts

@@ -1,37 +1,132 @@
+/**
+ * design/164 件五 — DEPLOYMENT-level usage governance (the seam, its arithmetic, and the in-memory
+ * reference implementation).
+ *
+ * This is a different axis from `TaskSpec.limits`: a task limit is the allowance ONE task asked for,
+ * while a usage window is the allowance an OPERATOR grants a principal (or a whole deployment) ACROSS
+ * tasks — the shape the industry converged on for account-level governance (a first-use window plus a
+ * long rolling one). Core never invents a window: with `RunnerDeps.usageWindows` unset, nothing here
+ * runs and no ledger is written.
+ *
+ * The arithmetic lives HERE, as pure functions over a per-key {@link UsageWindowRecord}, and every
+ * store implementation is a persistence shell around them — that is what makes the in-memory and file
+ * backends equivalent by construction rather than by two hand-written copies that drift.
+ */
+/**
+ * One governed window. Both fields are allowances, not hints: `windowMs` is the window's WIDTH and
+ * `maxTokens` the tokens it admits. `anchor` picks between the two window shapes that actually exist in
+ * the wild:
+ *  - `"first-use"` — the window OPENS at the key's first charge and lasts `windowMs`; when it lapses with
+ *    no further use, the next charge opens a fresh one. This is the "5 hours from when you started"
+ *    shape: bursty use is admitted at full width, and an idle key is never penalized for old traffic.
+ *  - `"rolling"` — a continuously sliding window: the charge from `now − windowMs` to `now`. This is the
+ *    "7 days" shape: it never resets, so sustained use is bounded no matter how it is spread.
+ */
 export interface UsageWindow {
+    /** Window width in ms. Must be finite and > 0 (a zero-width window admits nothing and expires
+     *  instantly — refused at the door rather than silently governing every task to death). */
     windowMs: number;
+    /** Tokens the window admits before it is exhausted. Must be finite and >= 0; `0` is a real, always-full
+     *  window (an operator lock-out), not "unset". */
     maxTokens: number;
+    /** Which of the two window shapes above this is. */
     anchor: "first-use" | "rolling";
 }
+/** One charge against a key: `tokens` charged at epoch ms `at`. The unit of the rolling lane's ledger. */
 export interface UsageSlot {
     at: number;
     tokens: number;
 }
+/** The OPEN first-use window for one `windowMs` on one key. Rows for other widths coexist, so a
+ *  deployment governing 5h and 7d windows keeps one row per width rather than one blended counter. */
 export interface UsageBucketRow {
+    /** The width this row belongs to — the row's identity, matched against {@link UsageWindow.windowMs}. */
     windowMs: number;
+    /** Epoch ms the window opened (its first charge). */
     openedAt: number;
+    /** Tokens charged into it since it opened. */
     tokens: number;
 }
+/** Everything one key's governance state consists of: the rolling lane's slots and the first-use lane's
+ *  open buckets. Persisted verbatim by every backend (plain JSON, no methods). */
 export interface UsageWindowRecord {
     slots: readonly UsageSlot[];
     buckets: readonly UsageBucketRow[];
 }
+/** The state of one window for one key, as of a given instant. */
 export interface UsageWindowReading {
+    /** The window this reading answers for (verbatim, so a caller can name the offending allowance). */
     window: UsageWindow;
+    /** Tokens the window currently holds. */
     tokens: number;
+    /** `tokens >= window.maxTokens` — the window admits no further work. */
     exhausted: boolean;
+    /** Ms until this window next frees capacity: for `first-use`, when the open window lapses; for
+     *  `rolling`, when its OLDEST in-window slot ages out (which frees that slot's tokens, not
+     *  necessarily enough for a whole task — a driver that resumes then and re-suspends is behaving
+     *  correctly, and each attempt gets a fresh, later hint). `0` when the window is not exhausted. */
     retryAfterMs: number;
 }
+/**
+ * The cross-task token ledger the governance windows are evaluated against. Deliberately two methods and
+ * no query language: core charges what a task spent and asks what the key's windows hold — everything
+ * else (retention, sharding, multi-writer safety) belongs to the backend.
+ *
+ * **Keying**: the caller passes a key that is the PRINCIPAL when the task declares one, and a single
+ * shared global key otherwise (see `GLOBAL_USAGE_KEY`) — so a multi-tenant deployment governs per tenant
+ * and a single-tenant one governs the deployment, with no branch in either.
+ */
 export interface UsageWindowStore {
+    /**
+     * Charge `tokens` to `key` at epoch ms `at`. `windows` is the deployment's live window set: the store
+     * needs it to know which first-use buckets to keep open and how far back the rolling lane must
+     * remember, so the ledger stays bounded instead of growing for the life of the deployment.
+     * Called once per accounting point; never with a negative or non-finite `tokens`.
+     */
     charge(key: string, tokens: number, at: number, windows: readonly UsageWindow[]): Promise<void>;
+    /** Read `key`'s state for each window as of `now`, in the order the windows were given. */
     read(key: string, windows: readonly UsageWindow[], now: number): Promise<readonly UsageWindowReading[]>;
 }
+/** The ledger key for a task that declares NO principal: one shared bucket that governs the whole
+ *  deployment. Distinctive on purpose — it must never collide with a real principal id. */
 export declare const GLOBAL_USAGE_KEY = "__usage_global__";
+/** A key with no history yet. Frozen: it is handed to callers as a starting value and must not be
+ *  mutated into a shared-state bug. */
 export declare const EMPTY_USAGE_WINDOW_RECORD: UsageWindowRecord;
+/**
+ * Validate `RunnerDeps.usageWindows` at the door and return it unchanged — the `resolveTaskLimits`
+ * posture: an unevaluable governance window is not a governance window, and folding it to a default
+ * would govern a deployment by a number nobody chose. Refuses with `config.usage_window_invalid`.
+ */
 export declare function resolveUsageWindows(windows: readonly UsageWindow[] | undefined): readonly UsageWindow[] | undefined;
+/**
+ * Fold one charge into a key's record and return the NEW record (pure — the input is never mutated, so a
+ * store that keeps records in a Map cannot be corrupted by a half-applied charge).
+ *
+ * Retention is part of the fold rather than a separate sweep: slots older than the widest ROLLING window
+ * can never be read again, and a first-use bucket for a width the deployment no longer governs can never
+ * be read again either, so both are dropped here. A record therefore stays bounded by (charges within the
+ * widest rolling window) + (one row per governed first-use width).
+ */
 export declare function chargeUsageRecord(record: UsageWindowRecord, tokens: number, at: number, windows: readonly UsageWindow[]): UsageWindowRecord;
+/**
+ * Read a key's record against the governed windows as of `now` (pure). The `first-use` lane reads the open
+ * bucket; the `rolling` lane sums the slots inside `(now − windowMs, now]`.
+ */
 export declare function readUsageRecord(record: UsageWindowRecord, windows: readonly UsageWindow[], now: number): UsageWindowReading[];
+/**
+ * The TIGHTEST binding constraint across a set of readings: how long the caller must wait before ANY
+ * window would admit work again. `undefined` when nothing is exhausted. The MAXIMUM (not the minimum) of
+ * the exhausted windows' hints — resuming when the shortest one clears would immediately re-suspend on
+ * the longer one.
+ */
 export declare function usageRetryAfterMs(readings: readonly UsageWindowReading[]): number | undefined;
+/**
+ * Process-local {@link UsageWindowStore} reference implementation. Governs correctly within ONE Runner
+ * process and loses its ledger on restart — the right choice for tests and single-process deployments,
+ * and explicitly NOT the right choice for a fleet (use the file backend, or a real database, when the
+ * governance must survive a restart or span replicas).
+ */
 export declare class InMemoryUsageWindowStore implements UsageWindowStore {
     private readonly records;
     charge(key: string, tokens: number, at: number, windows: readonly UsageWindow[]): Promise<void>;

package/dist/core/version.d.ts

@@ -1 +1,2 @@
+/** The running engine's package version ("unknown" when unresolvable). */
 export declare function engineVersion(): string;

package/dist/core/warm-resume.d.ts

@@ -1,5 +1,22 @@
 import type { Runner } from "./runner/runtask.js";
 import type { TaskResult, TaskSpec } from "./types.js";
+/**
+ * design/114 P0 — a convenience for the RECOMMENDED safe warm-resume of a (failed / timed-out) run: FORK the
+ * session, then run a continuation on the fork. Fork-first is the safe path (design/114 §3.2):
+ *  - **idempotent** — each call branches a FRESH session, so resuming twice can't corrupt the source's linear
+ *    history (vs `runTask({sessionId})` reuse, which appends two divergent continuations onto one history);
+ *  - **orphan-safe** — the fork drops an in-flight tool call (`settledForkOptions`), so a continuation of an agent
+ *    that died mid-tool-call gets a clean point rather than inheriting an `[INTERRUPTED]` orphan;
+ *  - **fail-loud** — a missing source returns `null`; it NEVER silently starts a fresh EMPTY run the way
+ *    `runTask({sessionId})` would via create-on-miss (the "looks warm, actually fresh" trap). Cross-restart /
+ *    cross-replica warm-resume therefore requires a DURABLE `SessionRepo` — an in-memory fork is lost on restart.
+ *
+ * Returns `null` when the store can't fork OR the source session is gone — the caller decides what to do (surface
+ * an error, fall back, etc.), never a silent fresh run. `sessionId` typically comes from a failed
+ * `WorkflowAgentRun.sessionId` (design/114) or a prior `TaskResult.sessionId`. The continuation's `objective` is
+ * the directive for picking up the work; pass the model (and any other spec fields) via `opts` — a continuation
+ * still needs a model like any task.
+ */
 export declare function warmResume(runner: Runner, sessionId: string, objective: string, opts?: Omit<Partial<TaskSpec>, "objective" | "sessionId"> & {
     owner?: string | null;
 }): Promise<TaskResult | null>;

package/dist/core/wiring-manifest.d.ts

@@ -1,41 +1,128 @@
+/**
+ * design/173 — the wiring manifest: a machine-readable disclosure of HOW this deployment/run is
+ * assembled around the optional human-interaction seams (ask / question / elicit / park lane /
+ * durability / fleet observability / governance surfaces).
+ *
+ * GUARANTEE BOUNDARY (design/173 §0): this is STATIC ASSEMBLY SELF-DISCLOSURE — seam presence and
+ * shape, as facts. It does NOT prove liveness (a callback bound to the wrong run, a dead queue, an
+ * adapter's internal failure, an answer routed to the wrong instance). Liveness belongs to
+ * round-trip probes, which are a separate obligation. Nothing here may claim "the wiring was
+ * verified" — only "the wiring was disclosed". This module provides no liveness API, deliberately;
+ * consumers (e.g. a park-wiring startup self-check) must quote this boundary rather than promise
+ * more than the manifest can know.
+ *
+ * TWO HALVES, ONE SCHEMA (design/173 §2.1): the STATIC half ({@link describeStaticWiring}) is a pure
+ * synchronous function over `(deps, spec)` — a server startup self-check. Facts it cannot compute
+ * (per-principal runtime caps, the prepare-time safety-tool vocabulary) are reported `"unresolved"`,
+ * never guessed, and `ask.effective` is OMITTED entirely (reporting "would park" as "auto-deny"
+ * would be a false fact, worse than silence). The EFFECTIVE half is built once per prepared leg by
+ * `prepareTask` from RESOLVED facts, through the SAME {@link deriveWiringManifest} derivation — two
+ * copies of the derivation would drift, so there is exactly one. A startup snapshot and a leg's
+ * effective snapshot are two DIFFERENT facts; neither may impersonate the other.
+ */
 import type { RunnerDeps, TaskSpec } from "./types.js";
 import { type StoreDurability } from "./checkpoint-store.js";
 export type { StoreDurability };
+/** The manifest-face projection of {@link StoreDurability}: `"declared_durable"` (the name says it —
+ *  a DECLARATION relayed, not a verification) vs `"process_local"` (declared so, or fail-closed
+ *  absent). */
 export type ManifestDurability = "declared_durable" | "process_local";
+/** Which prepare leg an EFFECTIVE manifest describes (`leg` is absent on the static half — a
+ *  startup self-check has no leg). taskId/parentTaskId ride the event's `TaskEventIdentity`, not
+ *  this object (design/173 §8.4). "Every leg self-evidences" means ON ITS OWN STREAM: a delegated
+ *  child's manifest rides the CHILD's event stream and is deliberately not in the parent-forwarding
+ *  whitelist — a host that wants a child's assembly evidence subscribes to the child. */
 export type WiringLegKind = "root" | "child" | "resume";
+/** The shape of the resolved permission-ask seat (`spec.onAsk ?? deps.onAsk`): a live approver
+ *  callback, a blanket `"allow"`/`"deny"` policy setting, or nothing at all. `"deny"` (a deliberate
+ *  policy) and `"absent"` (a degrade to the headless auto-deny default) are DISTINCT on purpose —
+ *  design/173 codex 5. */
 export type AskSeamForm = "callback" | "allow" | "deny" | "absent";
+/** What a policy `ask` actually reaches under this assembly. `"unresolved"` = not computable from
+ *  the facts at hand (the static half's park-dependent arm). */
 export type AskEffective = "human_reachable" | "auto_allow" | "auto_deny" | "park_only" | "unresolved";
+/**
+ * The content-question channel, three-valued (design/173 §8.2 — a derived enum, not a bare
+ * boolean): `"wired"` (a resolved `onQuestion` face exists), `"absent"` (none), or
+ * `"stripped_bg_lane"` — the ENGINE deliberately stripped the spawn turn's per-request face from a
+ * long-lived background/retained leg (correct design, not a configuration lie; the flag is minted
+ * ONLY by the engine's strip sites, pair-produced with the strip itself — never inferred from spec
+ * shape).
+ */
 export type QuestionChannelState = "wired" | "absent" | "stripped_bg_lane";
+/** Which seat supplied a resolved seam value (`spec` wins over `deps` everywhere). Tree-internal
+ *  child legs read `"spec"` for inherited faces by construction — the delegation lane copies the
+ *  parent's effective face onto the child SPEC seat (design/173 opus F7). */
 export type SeamProvenance = "spec" | "deps";
+/** Machine-readable reason codes for a park lane that is not (or not provably) effective. */
 export type ParkLaneReason = "no_checkpoint_store" | "no_durable_approval_opt_in" | "no_force_durable_gate" | "no_armed_safety_vocabulary" | "await_runtime_caps" | "await_tool_vocabulary";
+/**
+ * design/173 §2.2/§8.4 — the wiring manifest. Consumers MUST ignore unknown fields
+ * (`schemaVersion` bumps only on a semantic break of an EXISTING field). The TaskEvent face is the
+ * host/operator plane — the manifest never enters model context.
+ */
 export interface WiringManifest {
     schemaVersion: 1;
+    /** Present on EFFECTIVE (per-leg) manifests only; the static half has no leg. */
     leg?: {
         kind: WiringLegKind;
     };
     ask: {
         form: AskSeamForm;
+        /** Absent iff `form === "absent"` (no seat supplied a value — a fabricated provenance would be
+         *  a false fact). */
         provenance?: SeamProvenance;
+        /** OMITTED on the static half (design/173 §8.4): the absent-form arm depends on the park lane,
+         *  which the static half cannot always resolve. Always present on the effective half. */
         effective?: AskEffective;
     };
     question: {
+        /** Three-valued channel state — see {@link QuestionChannelState}. The field keeps the frozen
+         *  design name `wired`. */
         wired: QuestionChannelState;
+        /** Present iff `wired === "wired"`. */
         provenance?: SeamProvenance;
+        /**
+         * design/173 §3 (F13, effective half only) — the composition-lie detector:
+         * `interactiveTools === true` mounted the question tool while NO delivery face exists (no live
+         * `onQuestion`, no durable park consumer, not an engine-stripped lane). The model will be
+         * offered a question tool whose answers can reach nobody. Always disclosed here; under
+         * posture `"interactive"` the prepare door additionally refuses the leg.
+         */
         interactiveToolsWithoutDeliveryFace?: true;
     };
+    /** The interaction-posture declaration (the prepare door's input): `"interactive"` promises a
+     *  reachable human and the door refuses a leg that cannot deliver one, `"headless"` documents the
+     *  opposite, `"absent"` = no declaration (no check). Until this field existed, posture was the one
+     *  interactive-face declaration the manifest did not report. */
     interaction: {
         posture: "interactive" | "headless" | "absent";
     };
+    /** `seamWired` = a deployment `onElicit` seam exists. Seam presence ≠ the elicitation family is
+     *  usable: the other half is per-server opt-in (`spec.mcp[].elicitation === true`), counted in
+     *  `serversOptedIn` (statically readable from the spec). */
     elicit: {
         seamWired: boolean;
         serversOptedIn: number;
     };
     parkLane: {
+        /** A checkpoint store is wired (capability — design/173 codex 13: capability and current policy
+         *  are reported separately). */
         capable: boolean;
+        /** capable ∧ (durableApproval opt-in ∨ forceDurableGate entitlement ∨ armed safety-tool
+         *  vocabulary). `"unresolved"` on a static half that cannot decide (runtime caps / tool
+         *  vocabulary are prepare-time facts). */
         effective: boolean | "unresolved";
+        /** Why `effective` is `false`/`"unresolved"` — empty when `true`. The derivation chain an
+         *  operator follows from `static unresolved` to `effective park unavailable` (codex 7). */
         reasons: readonly ParkLaneReason[];
+        /** design/173 §8.4 (opus R7): the DECLARED durability of the resolved checkpoint store — an
+         *  armed park lane over a process-local store is the "armed but memory-backed" degrade shape
+         *  §1 names, and it must be reportable. Present iff `capable`. */
         checkpointDurability?: ManifestDurability;
     };
+    /** The session store's DECLARED durability (declaration relayed verbatim — never class-name
+     *  sniffing; absent declaration reads fail-closed as `process_local`). */
     session: {
         store: ManifestDurability;
     };
@@ -43,9 +130,19 @@ export interface WiringManifest {
         backgroundAgentStore: boolean;
         hostChildEventSink: boolean;
     };
+    /** design/179 — the persisted allow-rule seam. The ONE loosening seam in the assembly, so its presence
+     *  is a fact an operator has to be able to read off the manifest rather than infer. `false` on a
+     *  deployment that wired no store, which is the shape the field has to have: an absent field would say
+     *  "this build has no such feature", and a present-and-false one says "it exists and is off here". */
     permissionRules: {
         storeWired: boolean;
     };
+    /**
+     * Governance surfaces (presence facts only). `audience: "operator"` is the MACHINE-READABLE
+     * projection classification (design/173 codex 9): a serving layer forwarding this event to a
+     * multi-tenant/shared stream MUST project this section for operators only — and when it does no
+     * projection, the default is to NOT disclose the section, never to leak it.
+     */
     governance: {
         audience: "operator";
         lockedConfig: boolean;
@@ -53,27 +150,47 @@ export interface WiringManifest {
         memoryAdmission: boolean;
         retention: boolean;
     };
+    /** EFFECTIVE half only — a short, non-sensitive fingerprint (sha256 prefix over the canonical
+     *  JSON of this manifest's own resolved facts; every field here is an enum/boolean/count, no
+     *  secrets) so an operator can correlate legs that ran under the same resolved assembly. */
     configFingerprint?: string;
 }
+/**
+ * The FULL fact set both halves derive from — one input shape, one derivation
+ * ({@link deriveWiringManifest}), so the halves cannot drift. `undefined` on the optional park
+ * atoms means "not knowable at this half" and derives `"unresolved"`, never a guess.
+ */
 export interface WiringFacts {
     half: "static" | "effective";
+    /** Required on the effective half; must be absent on the static half. */
     leg?: WiringLegKind;
     askForm: AskSeamForm;
     askProvenance?: SeamProvenance;
     questionWired: boolean;
     questionProvenance?: SeamProvenance;
+    /** The engine-minted strip flag (trusted RunInternals channel) — effective half only; the static
+     *  half has no run internals and never reports `stripped_bg_lane`. */
     questionStrippedByEngine?: boolean;
+    /** F13 composition-lie fact (effective half only). */
     interactiveToolsWithoutDeliveryFace?: boolean;
+    /** The interaction-posture declaration this half can see: the static half reads `spec ?? deps`,
+     *  the effective half reports the RESOLVED posture (spec > spawning parent > deps). Absent = no
+     *  declaration anywhere — reported as `"absent"`, never guessed. */
     interactionPosture?: "interactive" | "headless";
     elicitSeamWired: boolean;
     elicitServersOptedIn: number;
     parkCapable: boolean;
     parkDurableApprovalOptIn: boolean;
+    /** `undefined` = unresolved at this half (per-principal runtime caps are a prepare-time fact). */
     parkForceDurableGate?: boolean;
+    /** `undefined` = unresolved at this half (the irreversible/egress tool vocabulary is assembled in
+     *  prepare). */
     parkSafetyVocabularyArmed?: boolean;
+    /** Present iff `parkCapable` (the resolved checkpoint store's declaration). */
     checkpointDurability?: StoreDurability;
     sessionDurability: StoreDurability;
     backgroundAgentStoreWired: boolean;
+    /** design/179 — a persisted allow-rule store provider is wired. */
     permissionRuleStoreWired: boolean;
     hostChildEventSinkWired: boolean;
     lockedConfigWired: boolean;
@@ -81,21 +198,73 @@ export interface WiringFacts {
     memoryAdmissionWired: boolean;
     retentionPolicyWired: boolean;
 }
+/** Named view of the deps seats the static half reads (a `Pick` of the real {@link RunnerDeps} —
+ *  single-source shapes, no parallel hand-copied interface). */
 export type StaticWiringDeps = Pick<RunnerDeps, "onAsk" | "onQuestion" | "interactionPosture" | "onElicit" | "checkpointStore" | "sessionStore" | "backgroundAgentStore" | "onBackgroundChildEvent" | "lockedConfig" | "compliancePostureResolver" | "memoryScopeAdmission" | "retentionPolicy" | "permissionRuleStore">;
+/** Named view of the spec seats the static half reads (a `Pick` of the real {@link TaskSpec}). */
 export type StaticWiringSpec = Pick<TaskSpec, "onAsk" | "onQuestion" | "checkpointStore" | "durableApproval" | "mcp" | "interactiveTools" | "interactionPosture">;
+/**
+ * Read a store's {@link StoreDurability} declaration: absent ⇒ `"process-local"` (fail-closed —
+ * under-promise, never over-promise), a declared value passes through, and an UNPARSEABLE value is
+ * refused loudly (`config.store_durability_invalid`) — a junk declaration silently folded to either
+ * arm would be a manifest that lies in whichever direction the fold picked.
+ */
 export declare function resolveDeclaredDurability(store: {
     readonly durability?: StoreDurability;
 } | undefined, storeName: string): StoreDurability;
+/**
+ * The ONE `ask.effective` derivation (design/173 codex 5) — shared by the effective manifest AND
+ * the posture door (`config.interaction_posture`), so "what does the door require" and "what does
+ * the manifest report" can never disagree:
+ *  - a live approver callback ⇒ `human_reachable` (regardless of the park lane);
+ *  - blanket `"allow"`/`"deny"` ⇒ the park lane decides first: a string seat is NOT a live approver,
+ *    so on an armed park lane the ask parks and the honest report is `park_only` — reporting the
+ *    blanket as what the ask "reaches" would be a false fact of exactly the kind this module refuses.
+ *    Off the park lane the blanket is what happens: the deliberate auto policies;
+ *  - no seat at all ⇒ the park lane decides: armed ⇒ `park_only`, unresolved ⇒ `unresolved`,
+ *    else the headless degrade `auto_deny`.
+ */
 export declare function deriveAskEffective(form: AskSeamForm, parkEffective: boolean | "unresolved"): AskEffective;
+/**
+ * design/173 §2.1 — the SINGLE derivation from facts to manifest, shared by both halves. The static
+ * half omits `ask.effective`, `leg` and the fingerprint; the effective half carries all three. Any
+ * second construction point for {@link WiringManifest} is a defect (single-mint rule).
+ */
 export declare function deriveWiringManifest(facts: WiringFacts): WiringManifest;
+/** The one ask-seat resolution (`spec` wins over `deps`), shared with the effective half so the
+ *  form/provenance read cannot fork. Junk values (a JS caller passing something outside the OnAsk
+ *  union) are refused loudly — a manifest must not classify what it cannot name. */
 export declare function resolveAskSeamForm(spec: Pick<TaskSpec, "onAsk">, deps: Pick<RunnerDeps, "onAsk">): {
     form: AskSeamForm;
     provenance?: SeamProvenance;
 };
+/** The one question-seat resolution (`spec` wins over `deps`), shared by both halves. Review fold
+ *  r2-F2: a NON-FUNCTION present value (a JS caller passing `onQuestion: null`/junk) is refused
+ *  loudly — the engine's `??` resolution would keep it, the mount's presence check would count it,
+ *  and the manifest would report `wired` for a callback nothing can ever call.
+ *
+ *  design/174: "a value is present" is NOT the criterion — `wired` is derived through THE shared
+ *  {@link isLiveQuestionFace} predicate, the same one the gate routes on. The reserved
+ *  `QUESTION_AWAITS_RESUME` placeholder is a function and is the documented standard assembly of the
+ *  durable topology, but its whole contract is that it never runs; reporting it as a wired channel
+ *  told an operator a question could reach a person in-stream when the only real delivery face on
+ *  that assembly is the park lane (which this manifest reports separately, and honestly). */
 export declare function resolveQuestionSeam(spec: Pick<TaskSpec, "onQuestion">, deps: Pick<RunnerDeps, "onQuestion">): {
     wired: boolean;
     provenance?: SeamProvenance;
 };
+/** Count of MCP servers that opted into elicitation on this spec (the per-server half of the
+ *  elicit capability — statically readable). */
 export declare function countElicitOptIns(spec: Pick<TaskSpec, "mcp">): number;
+/** The one elicit-seat resolution, shared by both halves (review fold r3-F3 — the onQuestion rule
+ *  applies here too): absent ⇒ not wired; a function ⇒ wired; a present NON-function (a JS caller
+ *  passing null/junk) is refused loudly rather than reported as a live seam nothing can call. */
 export declare function resolveElicitSeam(deps: Pick<RunnerDeps, "onElicit">): boolean;
+/**
+ * design/173 §2.1 — the STATIC half: a pure synchronous description of what `(deps, spec)` can
+ * prove about the wiring, for a server's startup self-check. Facts that only prepare can resolve
+ * (per-principal runtime caps, the safety-tool vocabulary) derive `"unresolved"`; `ask.effective`
+ * is omitted entirely (see the module doc). This is DISCLOSURE, not verification — see the §0
+ * guarantee boundary above. `spec` may be omitted for a spec-less deployment self-check.
+ */
 export declare function describeStaticWiring(deps: StaticWiringDeps, spec?: StaticWiringSpec): WiringManifest;