@sema-agent/core 5.64.0 → 6.0.0

package/dist/core/types.d.ts

@@ -119,11 +119,11 @@ export type ToolContentOrigin = "external" | "execution" | "local";
  * design/77 §4 — what a {@link ToolSpec.reversibilityProbe} returns for ONE call.
  *
  * `reversible` alone decides: the gate tightens a surviving `allow` to `ask` unless it is exactly `true`,
- * and neither optional member can widen that. They exist so the resulting approval card can say WHY, a
+ * and no optional member can widen that. They exist so the resulting approval card can say WHY, a
  * thing the probe knows at the moment it decides and nothing downstream can re-derive.
  *
  * Supply `cause` when the reason has parts a consumer should render itself; `reason` when it is prose
- * this engine cannot interpret. Both are optional and independent, so a probe written against the
+ * this engine cannot interpret. All three are optional and independent, so a probe written against the
  * original bare `{ reversible }` shape remains valid.
  */
 export interface ReversibilityVerdict {
@@ -133,6 +133,27 @@ export interface ReversibilityVerdict {
     /** Structured account — see {@link import("./checkpoint-store.js").ProbeCause}. Validated by the gate;
      *  a malformed value costs the DISCLOSURE only, never the ask. */
     cause?: import("./checkpoint-store.js").ProbeCause;
+    /**
+     * #502 (additive) — this demotion is STRUCTURAL, not the probe hesitating: the call crosses a
+     * boundary the deployment declared, so a persisted allow rule must not retire the resulting ask.
+     * The gate folds it into the #144 mandate family ("allow rules silence the CLASSIFIER's questions,
+     * never a MANDATED one") beside an operator `shellGate:"always"` and the tool's own
+     * egress/irreversibility marks: a matching rule is DISCLOSED as shadowed instead of clearing the
+     * ask, and the card's "stop asking me this" offer is withheld rather than offered and then refused.
+     *
+     * Read on the demotion arm only — a `reversible: true` verdict ends the gate with no ask to mandate,
+     * and this member cannot make one. It is the one member a DEPLOYMENT-supplied probe may set that the
+     * engine acts on, and it is safe for the same reason the probe itself is: the effect is strictly
+     * TIGHTENING (one more question survives one more configuration), so an over-claiming probe costs
+     * its own deployment a re-confirmation and can never turn an ask into an allow.
+     *
+     * The built-in shell probe sets it for exactly one family: a listed reader naming a path outside the
+     * session's allowed directories. The engine's own out-of-root demotion has no clearing channel in
+     * this version other than confirming the call each time — a directory-scoped grant that WOULD clear
+     * it is a separate, later mechanism, and until it exists a surface must not word the refusal as
+     * though one already answers it.
+     */
+    mandated?: boolean;
 }
 export interface ToolSpec<TParams extends TSchema = TSchema> {
     /**
@@ -280,7 +301,9 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
      *  - `"maybe"` — reversibility depends on the args; the gate calls {@link reversibilityProbe} (when one is
      *     declared) on a surviving `allow` and tightens to `ask` UNLESS the probe reports reversible. A tool
      *     that declares a `reversibilityProbe` but omits `irreversibility` defaults to `"maybe"` (so it always
-     *     enters the activation set and is gated).
+     *     enters the activation set and is gated). Since #502 the probe ALSO runs over a surviving `ask`
+     *     — see {@link reversibilityProbe} for what that arm reads (only {@link ReversibilityVerdict.mandated})
+     *     and what it costs; it tightens nothing there, because an ask cannot be tightened into an ask.
      *  - `"always"` — irreversible; the gate ALWAYS tightens a surviving `allow` to `ask` (like {@link egress}).
      *
      * The tighten mirrors the egress tighten (it only ever tightens allow→ask; a `deny`/`ask` is untouched),
@@ -296,13 +319,28 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
     irreversibility?: "never" | "maybe" | "always";
     /**
      * design/77 §4: optional deployment-injected probe for an `irreversibility:"maybe"` tool. Given the call's
-     * (post-hook) args, it reports whether THIS specific call is reversible. The gate calls it ONLY when the
-     * surviving decision is `allow` and `irreversibility` resolves to `"maybe"`; it is time-bounded (the
+     * (post-hook) args, it reports whether THIS specific call is reversible. It is time-bounded (the
      * approval timeout when configured, a 30s default when absent — the probe wait is always finite) and
      * **fail-closed**: a non-`reversible` verdict, a timeout, or a throw all tighten to
      * `ask`. Declaring this probe defaults `irreversibility` to `"maybe"`. It is read from the spec at
      * prepare-time and captured in a closure — NOT a tool argument — so the model cannot monkey-patch it.
      *
+     * **WHEN THE GATE CALLS IT — two arms, and the second is newer than this paragraph's first draft**
+     * (#502; `irreversibility` must resolve to `"maybe"` for either):
+     *  1. the surviving decision is `allow` — the TIGHTEN arm: the verdict decides allow→ask, and a
+     *     tightening verdict's `reason`/`cause` ride the minted ask;
+     *  2. the surviving decision is already `ask` — the MANDATE arm: the probe is the only source of
+     *     {@link ReversibilityVerdict.mandated}, and an ask another layer raised needed it too. (Before
+     *     #502 a policy that asked FIRST skipped this block entirely, so an out-of-root read never
+     *     acquired its mandate and a covering allow rule retired the question — measured, not theorised.)
+     *     Here the `reversible` verdict is DISCARDED (a probe may never un-ask another layer's question),
+     *     `reason`/`cause` are not merged onto somebody else's ask, and only `mandated` is read.
+     * The TIGHTEN is still `allow`→`ask` only — a `deny`/`ask` is never re-minted — but the INVOCATION
+     * set is wider than the tighten's, and that difference is the deployment's to budget for: on an
+     * ask-first policy the probe is called (and awaited, to the bound above) on every `"maybe"`-tier
+     * call, and a probe that throws or times out reports through `onError` with `phase: "hook"` on
+     * those calls too. A probe should therefore be a cheap, side-effect-free inspection of the args.
+     *
      * **`reason` (optional, additive both ways)** — WHY this call was not proven reversible, in the probe's
      * own words, minted in the same pass that reached the verdict (so nothing downstream re-derives it).
      * Read ONLY on a tightening verdict: a `reversible: true` return ends the gate, and a timeout/throw
@@ -888,6 +926,43 @@ export interface ToolExecuteContext {
      * inference decides, exactly as before the seat existed.
      */
     memoryPersistenceCapable?: boolean;
+    /**
+     * design/383 §2.5 — TRUE ⇔ the spawning session is under a memory-capture OPT-OUT at the moment
+     * a delegation tool reads this seat (declared at its prepare, a standing record, or a mid-run
+     * flip — the seat is live, not a prepare-time snapshot). The delegation lanes forward it into
+     * every child's trusted internals as the capture FLOOR (`memoryCaptureFloor`): a child of an
+     * opted-out session captures nothing, whatever its chosen AgentDefinition says — the opt-out is
+     * a floor no selection loosens (the `memoryPersistenceCapable:false` floor's exact law, on the
+     * privacy axis). Trusted Runner-filled seat, never a model/tool argument.
+     */
+    memoryCaptureOptedOut?: boolean;
+    /**
+     * design/383 §2.5 (rescan post-6.0.0-RC) — the floor seat's THIRD state: TRUE ⇔ the spawning
+     * session's capture opt-out state is INDETERMINATE at the moment a delegation tool reads this
+     * seat (its capture record store is faulting, and no genuine record is known in-process). The
+     * delegation lanes forward it into the child's trusted internals as the floor's indeterminate
+     * twin (`memoryCaptureFloorIndeterminate`): the child's prepare re-resolves it against the live
+     * record query — an ancestor record found takes the ordinary floor arm; a still-faulting store
+     * runs the child under the same fail-closed suppression an own-store outage imposes (no
+     * irreversible record is ever minted off an unreadable state); a readable-and-clean answer
+     * proceeds clean. Never TRUE beside {@link memoryCaptureOptedOut} — a known opt-out is
+     * determinate. Trusted Runner-filled seat, never a model/tool argument.
+     */
+    memoryCaptureIndeterminate?: boolean;
+    /** design/383 §2.5 — the spawning session's write-plane control dir (the coordinate its capture
+     *  record is keyed under), forwarded beside the floor bit so a cross-plane child's record-query
+     *  leg reads the PARENT's carrier, not its own plane's. Trusted Runner-filled seat. */
+    memoryCaptureControlDir?: string;
+    /** design/383 §2.5 (codex round 3) — the WHOLE ancestor chain's capture-record coordinates
+     *  ({sessionId, controlDir?} per generation, root first), appended one row per spawn. The
+     *  record-query leg walks ALL of it: a root that flips after spawning an already-running child
+     *  AND grandchild is invisible to the grandchild's one-hop parent query (the clean middle
+     *  session has no record of its own to find), while the chain reaches the root directly.
+     *  Trusted Runner-filled seat, never a model argument. */
+    memoryCaptureAncestors?: ReadonlyArray<{
+        sessionId: string;
+        controlDir?: string;
+    }>;
     /**
      * the parent task's per-model auth hook ({@link TaskSpec.getApiKeyAndHeaders}), inherited
      * verbatim down the delegation tree like `principal`/`clientContext` (Runner-filled, read-only, NEVER
@@ -1155,6 +1230,48 @@ export type BeforeWriteResult = {
     reason: string;
 };
 export type BeforeWriteHook = (req: BeforeWriteRequest) => BeforeWriteResult | undefined | Promise<BeforeWriteResult | undefined>;
+/**
+ * design/381 — the hands band's FIRST-TOUCH HISTORY hook, called before EVERY file mutation in
+ * Write/Edit/NotebookEdit (after the `beforeWrite` content gate passed, immediately before the
+ * final env write) with the resolved canonical containment key. The Runner wires it to
+ * `FileHistoryStore.trackEdit` (backup-before-first-edit, the CC FileHistory trigger-point set
+ * minus the bash simulation arm sema does not have — DV-7); later calls for an already-tracked
+ * path are cheap store no-ops. `{ok:false}` carries the REFUSAL TEXT the tool must answer instead
+ * of writing (DV-14 default: no durable first-touch state ⇒ the edit is refused, typed and loud —
+ * any proceed-unprotected policy is resolved INSIDE the hook by the Runner, never by the band).
+ * A THROWING hook fails CLOSED (same posture as the write gate). Absent hook ⇒ byte-identical
+ * behavior (no history store wired).
+ */
+export interface TrackEditRequest {
+    tool: "Write" | "Edit" | "NotebookEdit";
+    /** The model-supplied path argument (for the error-message coordinate the model knows). */
+    path: string;
+    /** The resolved canonical containment key — the identity the history record is keyed on. */
+    key: string;
+    /** The tool call's abort signal, threaded into the store's env read. */
+    signal?: AbortSignal;
+}
+export type TrackEditResult = {
+    ok: true;
+    /**
+     * #491 — the compensating handle for the ordering the topology cannot avoid: the pre-image
+     * capture runs BEFORE the write, so a write that then FAILS (lost create race, ENOSPC,
+     * EACCES, read-only mount) would leave a first-touch record for an edit that never happened —
+     * and an `existed-not` record makes an untouched path a rewind DELETE target, removing bytes
+     * whoever writes them next (the user, a peer process) owns. Present ONLY when THIS call minted
+     * the record (an already-tracked path belongs to the edit that first touched it and must never
+     * be discarded); the band calls it on the write-failure arm of every mutation lane. `proof`
+     * says which retraction rule applies: `"proven"` = the write's own error code guarantees
+     * nothing was written, `"verify"` = ambiguous, so the history seat must re-read the path and
+     * retract only if it still matches what the first touch recorded. It never throws and never
+     * blocks the failure it accompanies — the original write error is the answer.
+     */
+    annul?: (proof: "proven" | "verify") => Promise<void>;
+} | {
+    ok: false;
+    refusal: string;
+};
+export type TrackFileEditHook = (req: TrackEditRequest) => Promise<TrackEditResult>;
 /**
  * design/141 件2 — the SAFE deployment-configurable subset of the hands toolkit ({@link RunnerDeps.hands}).
  * Only fields whose injection is purely additive for a deployment are here; Runner-internal orchestration
@@ -1845,11 +1962,13 @@ export interface TaskSpec {
      *   rewinding to before the very first message = start a NEW session. (A first-class branch-reset entry
      *   that could support this without a second root is a recorded design candidate, not built.)
      *
-     * E19 interaction: with {@link rewindFiles}, the `"before"` file anchor is NOT the target's own entry id
-     * (snapshots key turn-END leaves, and a user message never has one) — it is the nearest snapshotted
-     * ANCESTOR of the target, so files and context land on the same side of the cut. If no such snapshot
-     * exists, prepare fails loud (`rewind_snapshot.unresolvable`) instead of silently leaving the files at
-     * their pre-rewind state while the conversation moved back.
+     * File-history interaction (design/381): with {@link restoreFiles}, the `"before"` file anchor is the
+     * target's OWN entry id first — history boundaries are keyed by a turn's initial entry and mean "file
+     * state when that turn began", so B(target) IS the before-state. When the target carries no boundary
+     * (a mixed-epoch session, or a non-turn-initial target), the anchor falls back to the nearest
+     * boundary-carrying ANCESTOR, so files and context land on the same side of the cut. If no such
+     * boundary exists, prepare fails loud (`rewind_snapshot.unresolvable`) instead of silently leaving
+     * the files at their pre-rewind state while the conversation moved back.
      * Fail-loud: setting this without {@link resumeAt}, or an unknown mode value, rejects at prepare.
      */
     resumeAtMode?: "at" | "before";
@@ -1943,22 +2062,47 @@ export interface TaskSpec {
         role?: ModelRole;
     };
     /**
-     * design/101 §E19 — opt-in working-tree **rewind**: when this task uses {@link resumeAt} to branch at a prior
-     * message AND a snapshot was captured for that message, RESTORE the files to how they were at that message
-     * (pairs with E18: branch the session + restore the tree). Also makes every COMPLETED turn capture a
-     * snapshot keyed by its leaf `SessionTreeEntry.id`. Requires `RunnerDeps.fileSnapshotStore`. **v1 is
-     * LOCAL-only** — a remote ({@link RunnerDeps.executionEnvFactory}) env defers rewind to its own VM-snapshot
-     * backend behind the same seam. OFF/omitted = zero snapshot/restore work.
-     */
-    rewindFiles?: boolean;
-    /**
-     * design/101 §E19 + R8 (CC Rewind `code`-only mode) — restore the working tree to the snapshot captured at
-     * this prior message entryId WITHOUT forking the conversation (no {@link resumeAt} leaf-branch). This is CC's
-     * "Restore code" mode (vs "Restore code and conversation" = {@link resumeAt}+{@link rewindFiles}, and "Restore
-     * conversation" = {@link resumeAt} alone). Honored ONLY when {@link resumeAt} is ABSENT (with `resumeAt` set,
-     * that branch's own `rewindFiles` governs — they are different operations); a no-snapshot target is an
-     * expected no-op (same as `rewindFiles`). Requires `RunnerDeps.fileSnapshotStore`. The session leaf is
-     * untouched — the next turn continues the CURRENT conversation, only the files moved.
+     * design/381 (DV-9) — the RESTORE half of file rewind: when this task uses {@link resumeAt} to branch at
+     * a prior entry, ALSO converge the working tree's **agent-edited files** (the tracked set — files this
+     * session touched through Edit/Write/NotebookEdit; nothing else is ever visible to the history, so a
+     * user's parallel work is structurally untouchable) to the history boundary of that entry (pairs with
+     * E18: branch the session + restore the tracked files). SCOPE = THIS session: a delegated
+     * subagent runs under its own session and its edits land in its own history scope, so a parent
+     * rewind does not converge files only a subagent touched (the retired whole-tree restore did —
+     * a design/381 narrowing, disclosed here). Requires `RunnerDeps.fileHistoryStore`.
+     * Fail-loud: setting this without {@link resumeAt} rejects at prepare (`rewind.invalid_spec`) — a
+     * restore with no anchor is a contradiction, not a default.
+     *
+     * There is NO capture flag anymore: first-touch tracking is ALWAYS ON whenever a
+     * `RunnerDeps.fileHistoryStore` is wired (per-edited-file backups are near-zero cost — no tree walk,
+     * no size gate), which is what retired the old `rewindFiles` capture request. The retired
+     * `rewindFiles` spelling is handled at prepare: its capture sense (true, no `resumeAt`) is a
+     * tolerated no-op with a deprecation disclosure (the intent is structurally satisfied); its restore
+     * sense (true, with `resumeAt`) is a typed retirement rejection naming THIS field — the restore
+     * semantics genuinely changed (whole-tree ⇒ tracked set), so that migration must be explicit.
+     */
+    restoreFiles?: boolean;
+    /**
+     * design/381 (DV-15) — opt-in tolerance for a PARTIAL file restore: when the {@link restoreFiles} /
+     * {@link rewindFilesTo} convergence ends with ≥1 per-file refusal or failure (the others applied),
+     * the default is a loud terminal failure carrying the per-file ledger (`rewind.restore_failed`) —
+     * a silent continue would run the agent on a mixed-epoch tree without anyone knowing. Setting this
+     * `true` keeps the run going instead and discloses the same ledger as a `restore_partial` note on
+     * {@link TaskResult.rewindNotes} (the reference UI's "skipped files" seat in library form). The
+     * documented recovery either way: re-run the same restore — it is per-file idempotent and converges.
+     */
+    acceptPartialRestore?: boolean;
+    /**
+     * design/101 §E19 R8 + design/381 (CC Rewind `code`-only mode) — converge the tracked set (see
+     * {@link restoreFiles} for what that is and is not) to the history boundary of this prior entryId
+     * WITHOUT forking the conversation (no {@link resumeAt} leaf-branch). This is CC's "Restore code"
+     * mode (vs "Restore code and conversation" = {@link resumeAt}+{@link restoreFiles}, and "Restore
+     * conversation" = {@link resumeAt} alone). Legal ONLY when {@link resumeAt} is ABSENT — handing
+     * BOTH anchors is refused loud (`rewind.conflicting_targets`): two file targets is a
+     * contradiction, and silently preferring one is the silent-swallow family this seam refuses; a
+     * target with no history boundary fails loud (`rewind_snapshot.unresolvable`). Requires
+     * `RunnerDeps.fileHistoryStore`. The session leaf is untouched — the next turn continues the
+     * CURRENT conversation, only the files moved.
      */
     rewindFilesTo?: string;
     /**
@@ -2851,11 +2995,24 @@ export interface TaskSpec {
          * {@link budgetUsd}, and for the same reason): the lane only rides boundaries whose turn resolved
          * ≥1 tool call, so a boundary steer never EXTENDS a run that reached its natural end.
          *
-         * Default OFF like every other member of this family. NOTE: this relaxes the same design/74 "no
-         * budget language reaches the model" default that {@link budgetUsd} does — an opted-in deployment
-         * chooses CC parity (where, since 2.1.245, this readout is on by default).
+         * DEFAULT ON since design/374 slice 4 (ruled 2026-08-28) — boolean, not `true`: explicit
+         * `false` is the opt-out, the {@link backgroundTasks} / listing-family contract rather than the
+         * `true`-only 133 form. BREAKING for a deployment that declares a token ceiling: pre-flip it saw
+         * no `<total_tokens>` frame without opting in, and a probe pinning that absence reds.
+         *
+         * WHY THIS LANE AND NOT {@link budgetUsd}. CC 2.1.245+ ships the readout on by default (its own
+         * settings schema reads "Defaults to padded-countdown"), which is the fact that reopened the
+         * 2026-07-30 registration; the design/74 "no budget language reaches the model" default is
+         * relaxed here for the same reason CC relaxed it. The BYOM honesty objection does not survive
+         * either: core estimates nothing, publishes only the ceiling it already ENFORCES, and a task
+         * that declares no token ceiling never fires the countdown arms at all — so the flip is
+         * observable exactly in the deployments that asked for a ceiling. That property is EXACT, not
+         * approximate: CC's two CONSTANT arms (`fixed`/`infinite`) publish a number with no ceiling
+         * behind it, so the DEFAULT deliberately does not reach them — they stay behind an explicit
+         * `true` here (see the runner's lane gate). The $ twin keeps its opt-in
+         * default: CC has no equivalent default-on posture for it.
          */
-        totalTokensReminder?: true;
+        totalTokensReminder?: boolean;
         /**
          * RB-318 — which arm of the readout, CC 2.1.245's closed set (`off` / `infinite` / `fixed` /
          * `countdown` / `padded-countdown`); absent ⇒ CC's own default `"padded-countdown"`.
@@ -3038,6 +3195,30 @@ export type EffectiveMemoryScopes = {
 };
 export interface TaskResult {
     taskId: string;
+    /**
+     * #499 — the ENGINE-minted identity of THIS run (uuidv7), minted once at the top of prepare and
+     * never rewritten. The third id of the trio, and the only one the engine owns:
+     *  - {@link taskId} — the HOST's task identity, or (when the host named none) the session id: it is
+     *    `spec.taskId ?? sessionId` and therefore answers the SAME value for every run of one session;
+     *  - {@link sessionId} — the conversation, shared by every run that continues it;
+     *  - `runId` — this call. Two runs of one session ALWAYS differ here; a host-supplied `taskId` does
+     *    not change it (the host's handle and the engine's run are different questions).
+     *
+     * Use it to join a run's per-run disclosures (`task.user_steer_undrained` /
+     * `task.user_followup_undrained` / `route.fallback_to_primary` / `steering.parked_input_blocked` /
+     * `task.turn_interrupted` all carry `detail.runId`) and its `task.start`/`task.end` trace pair to
+     * the result they belong to. Do NOT use it as an aggregation key across runs — that is what
+     * `taskId`/`taskSignature` are for.
+     *
+     * **In-presence condition**: present on every terminal of a run that ENTERED prepare — a prepare-time
+     * refusal included. The id is minted and published at prepare's FIRST statement precisely so this
+     * holds: prepare itself emits run-scoped disclosures (`route.fallback_to_primary`), and a disclosure
+     * naming a run that no terminal ever names would be unjoinable on exactly the failure path it is
+     * about. It is absent only where no run was entered — a throw above the prepare call — and on
+     * stub/synthesized results a host assembles itself. Optional for that reason, never fabricated, and
+     * never the `"unknown"` sentinel `taskId`/`sessionId` fall back to on that path.
+     */
+    runId?: string;
     /** Use this to continue the same conversation on the next call. */
     sessionId: string;
     status: TaskStatus;
@@ -3204,6 +3385,36 @@ export interface TaskResult {
      *   the ceiling was never evaluated (typically a store or decorator that predates the cost arm).
      */
     errorCode?: string;
+    /**
+     * Present when this run's terminal failure came from the PROVIDER BOUNDARY — the transport or the
+     * provider failed the model call, as opposed to this deployment refusing to send one, a limit being
+     * reached, or the model's own output being unusable. Its PRESENCE is the assertion; the members are
+     * whatever the failing attempt actually stated about itself:
+     *   - `status`    — the failing HTTP status, when the provider answered with one. Absent for a
+     *     connect failure, a stall, a mid-stream tear, and an in-band error frame delivered inside a
+     *     200 — never zeroed, since 0 reads as a number a consumer may format.
+     *   - `requestId` — the provider's own request identifier for that attempt, when it stated one in a
+     *     shape worth carrying. This is the handle a provider's support channel asks for.
+     * Both may be absent together: that is a provider failure nobody could label further, which is a
+     * different statement from "not a provider failure" (the field itself absent).
+     *
+     * Nested rather than three loose keys so the assertion and its evidence cannot drift apart — there
+     * is no state in which a consumer sees the claim beside a status belonging to some other attempt.
+     * The same family rides the assistant message itself as `isApiErrorMessage` / `apiErrorStatus` /
+     * `requestId`; this seat is its RUN-LEVEL projection, lifted from that message at the one assembly
+     * point rather than re-derived, and the two spellings are named here so the mapping is written down
+     * instead of inferred.
+     *
+     * PRESENCE, deliberately narrow: filled only when the provider failure is the terminal that NAMED
+     * this result. A run that hit a provider failure and then a higher-ranked terminal (a budget
+     * ceiling, a walltime cut) reports that other cause and leaves this absent — the same rule
+     * {@link usageWindowRetryAfterMs} states for itself, and for the same reason: a diagnostic seat
+     * beside a cause it does not belong to is worse than a missing one.
+     */
+    apiFailure?: {
+        status?: number;
+        requestId?: string;
+    };
     /**
      * How long (milliseconds) until the deployment usage window that stopped this task frees up — the wait
      * hint a scheduler needs to decide WHEN to re-submit, rather than polling.
@@ -3259,24 +3470,32 @@ export interface TaskResult {
      *  `errorCode="output.invalid"`, and this stays undefined.) */
     structuredOutput?: unknown;
     /**
-     * design/101 §E19 — NON-FATAL rewind disclosures for this run: the legs where the rewind machinery did
-     * something other than what the request's plain reading implies, reported as data instead of silence.
-     * Present only when at least one applies (absent = nothing to disclose), so a consumer that ignores the
-     * field is unchanged. A rewind that could NOT be delivered as asked is NOT a note — it is a terminal
-     * failure (`rewind_snapshot.unresolvable` / `rewind.store_unconfigured` / `rewind.restore_failed`).
+     * design/101 §E19 + design/381 — NON-FATAL rewind disclosures for this run: the legs where the rewind
+     * machinery did something other than what the request's plain reading implies, reported as data instead
+     * of silence. Present only when at least one applies (absent = nothing to disclose), so a consumer that
+     * ignores the field is unchanged. A rewind that could NOT be delivered as asked is NOT a note — it is a
+     * terminal failure (`rewind_snapshot.unresolvable` / `rewind.store_unconfigured` /
+     * `rewind.restore_failed` / `rewind.invalid_spec` / `rewind.rewind_files_retired` /
+     * `rewind.conflicting_targets`).
      *
      * - `conversation_only` — {@link TaskSpec.resumeAt} branched the transcript WITHOUT
-     *   {@link TaskSpec.rewindFiles}, so the working tree was deliberately left where it was (CC's "Restore
-     *   conversation" mode). Legal and useful; the note is what makes the two axes' divergence visible.
-     * - `files_env_unsupported` — a capture or restore was requested but this deployment mounts no
+     *   {@link TaskSpec.restoreFiles}, so the working tree was deliberately left where it was (CC's
+     *   "Restore conversation" mode). Legal and useful; the note is what makes the two axes' divergence
+     *   visible.
+     * - `files_env_unsupported` — a file restore was requested but this deployment mounts no
      *   filesystem-capable `ExecutionEnv` (stub env), so the file axis was inert. Not an error: such a
      *   deployment has no working tree to rewind.
-     * - `snapshot_store_unconfigured` — `rewindFiles` asked for per-turn capture but no
-     *   {@link RunnerDeps.fileSnapshotStore} is wired, so this turn produced no snapshot and cannot be
-     *   rewound to later. (Requesting a RESTORE with no store is a fail-loud configuration error instead.)
+     * - `restore_partial` — {@link TaskSpec.acceptPartialRestore} tolerated a partial restore: ≥1 tracked
+     *   file was refused or failed while the others converged; the message carries the per-file ledger
+     *   summary (applied / identical / refused / failed). Present ONLY under that explicit opt-in — the
+     *   default posture is the loud terminal `rewind.restore_failed` (DV-15).
+     *
+     * (design/381 closed-set surgery: `snapshot_store_unconfigured` is RETIRED — its only producer was
+     * the per-task capture request, and capture is now always-on when a store is wired; a restore request
+     * with no store keeps the fail-loud terminal instead.)
      */
     rewindNotes?: Array<{
-        code: "conversation_only" | "files_env_unsupported" | "snapshot_store_unconfigured";
+        code: "conversation_only" | "files_env_unsupported" | "restore_partial";
         /** Human-readable statement of what did NOT happen and why — safe to show a user verbatim. */
         message: string;
     }>;
@@ -3293,6 +3512,27 @@ export interface TaskResult {
      * (a steer/follow-up) continued the run past the rejection and it later ended naturally.
      */
     haltedOnUserRejection?: true;
+    /**
+     * design/373 (#504) — present (`true`) exactly when a {@link TaskStream.halt} was ACCEPTED while
+     * this run was live: the person issued the bare user interrupt (the CC Esc form — cut the
+     * in-flight turn, stop at that boundary, wait for their next input). The ruled terminal form is
+     * completed-with-marker, this seat being the marker: `status` is `"completed"` on the ordinary
+     * path (a clean, resumable ending — nothing failed, nothing is suspended, the session continues
+     * via the ordinary next-run front door), and this field is what tells a person-stopped ending
+     * apart from a natural finish — same reading discipline as {@link haltedOnUserRejection}, its
+     * sibling seat ("stopped by the user, awaiting their direction", never "the task finished its
+     * work"). `result` is whatever the model had produced before the halt (possibly empty — a halt
+     * can land before any output; the run then completes empty rather than failing). Pass-through on
+     * EVERY terminal the run still reaches (a halt ACCEPTED first that then raced a real
+     * failure/limit truthfully says a person also stopped it), and — the stated honest window — on
+     * a natural completion the halt arrived too late to prevent (past the loop's final commit
+     * point): the fact reported is the ACCEPTED HALT, and the transcript says how far the model
+     * got. First-writer-wins against the run's abort (the `interrupt()` attribution law, the same
+     * gate): a halt landing AFTER the abort signal already fired neither cut nor stopped anything —
+     * that ending belongs to the abort, and this seat stays ABSENT rather than signing someone
+     * else's stop with the halt caller's name. Absent everywhere else; never `false`.
+     */
+    haltedByUser?: true;
     /**
      * The deliveries of AskUserQuestion calls a person ANSWERED but whose call never executed to collect
      * the answer (the leg ended first — abort, batch teardown, or a loop failure). Rides EVERY terminal
@@ -3307,6 +3547,52 @@ export interface TaskResult {
         deliveryId: string;
         toolCallId: string;
     }>;
+    /**
+     * #481 — HOST-SUPPLIED: the approval plane's report that this leg ended with human approvals still
+     * OUTSTANDING (the ask identities it is holding, and when the OLDEST of them was created).
+     *
+     * **Who writes it, and why not the engine.** Core mints no ask identity — an ask id belongs to the
+     * deployment's approval store, and `resolveAsk` only awaits the host's `onAsk` — and core starts no
+     * approval clock. So this seat is filled by the `Runner` a deployment hands to
+     * `runWorkflow`/`startWorkflow`: that call both RAN the leg and owns the pending-approval map, which
+     * is the only place the two facts meet without inventing an attribution. Core's own Runner never
+     * writes it. ABSENT is therefore the ordinary world — an older deployment, or one whose approvals are
+     * always answered inline — and every such leg behaves exactly as it did before this seat existed.
+     *
+     * **Three-state, deliberately.** Absent = "this deployment is not reporting outstanding approvals, or
+     * there are none"; present = "these asks are outstanding". An EMPTY `askIds` is neither and is
+     * refused: it would let a half-written record read as "waiting on nothing", which is precisely the
+     * misdiagnosis the seat exists to prevent. A present-but-malformed value is announced and then
+     * treated as no report — never silently folded into absence, and never granted the exemption below.
+     *
+     * **What core does with it** (`src/orchestration/workflow.ts`): a workflow agent leg whose progress
+     * watchdog fired while an approval was outstanding was NOT stalled — it was waiting on a person, by
+     * design — so that attempt is not charged against the stall-retry budget. The run's own
+     * `totalTimeoutMs` remains the backstop for a wait nobody ever answers.
+     */
+    pendingApproval?: {
+        askIds: readonly string[];
+        oldestCreatedAtMs: number;
+    };
+    /**
+     * #485 — HOST-SUPPLIED: how long this leg spent BLOCKED on human approvals, in ms, as the deployment's
+     * approval plane measured it. Same writer and same absence contract as {@link pendingApproval}: the
+     * approval clock belongs to whoever holds the ask, so the figure is SINGLE-SOURCED there and core neither
+     * estimates it nor accumulates it (two sides publishing two numbers for one wait is the drift this seat
+     * exists to avoid). ABSENT is the ordinary world.
+     *
+     * Already CUMULATIVE for the leg — a receipt states the leg's total wait so far, not that attempt's
+     * increment — so a later receipt SUPERSEDES an earlier one. Adding successive receipts double-counts.
+     *
+     * **Absence is not zero.** `0` is "nobody was waited on"; absent is "this deployment does not supply the
+     * fact". A consumer that defaults absence to `0` reports a deployment's silence as a measurement.
+     *
+     * What it is FOR: a workflow that hit its total timeout cannot otherwise say whether it was SLOW or
+     * WAITING. `WorkflowRun.timeoutInterruption.approvalWaitedMs` carries the largest leg's figure onto the
+     * terminal disclosure for exactly that reading — near `timeoutMs` ⇒ the window went on a person, not on
+     * work.
+     */
+    approvalWaitedMs?: number;
     /**
      * #240 (design/199 v1.1) — the READ-face this leg's read surfaces actually judged under, as an
      * engine-filled OBSERVATION (never a knob: writing it on a spec does nothing). It is the run's ONE
@@ -3512,7 +3798,7 @@ export interface TaskResult {
              *    byte change, always paired with a `marked` disclosure),
              *  · `envelope` (text shaped like one of the engine's OTHER authority envelopes — the DISCLOSED
              *    subset is `task-notification` / `new-diagnostics` / `user_memory` / `skills` /
-             *    `total_tokens`; `scope` is
+             *    `total_tokens` / `instruction-files`; `scope` is
              *    fenced but not disclosed, since `<scope>…</scope>` is also an ordinary build-file element.
              *    That family carries no mark, so its sentence is positional rather than byte-testable. It
              *    rides ON the reminder copy when both families hit, so `envelope` can be bumped alongside
@@ -3691,6 +3977,25 @@ export interface BrainStatus {
      *  A wait longer than the re-announce slice is re-emitted with the REMAINING time, so a consumer
      *  that simply overwrites its row always shows a live number instead of a stale one. */
     retryInMs?: number;
+    /**
+     * The WALL-CLOCK instant the announced wait is expected to end — `Date.now() + retryInMs`, read at
+     * the moment the frame is emitted, in the EMITTING core process's clock. Stamped centrally at the
+     * one emit point, so the invariant is total: present exactly when {@link retryInMs} is present, and
+     * absent on every frame that announces no wait (`recovered` / `gave_up`, and the immediate
+     * output-cap re-send, which takes no backoff).
+     *
+     * WHY IT IS PRODUCED HERE rather than derived by the consumer: `Date.now() + retryInMs` is only
+     * correct for a reader that received the frame instantly. A consumer several process hops away
+     * (serving layer → client) recomputes a deadline already shifted by the transit, so a countdown
+     * built that way restarts on every re-announced slice instead of converging. The producer is the
+     * only party that can state the instant, so it does.
+     *
+     * CLOCK DOMAIN, stated to remove the ambiguity: WALL CLOCK (`Date.now()`, epoch ms), NOT a
+     * monotonic reading. A consumer must not compare it against its own monotonic timers, and must
+     * treat it as approximate across a clock adjustment or a machine boundary — {@link retryInMs} stays
+     * the authoritative RELATIVE quantity, and this seat is the absolute convenience derived from it.
+     */
+    retryAtMs?: number;
     /** RB-420-c — 1-based index of the attempt that just failed (the wait precedes attempt `attempt + 1`);
      *  same numbering as the `brain.retry` telemetry frame. Absent on frames that are not a retry wait. */
     attempt?: number;
@@ -4200,7 +4505,7 @@ export type TaskEvent = ({
      * message-identity Phase 1 (the CC `SDKCompactBoundary` parity enabler): a persisted session-tree entry was
      * just COMMITTED for a RENDERABLE message the consumer has already streamed. `entryId` = `SessionTreeEntry.id`
      * (uuidv7, persisted, replica-stable) — the SAME id space as `compacted.preserved_segment.firstKeptEntryId`,
-     * E18 `resumeAt`, and E19 `rewindFiles`. `role` + (for a tool result) `toolCallId` let a consumer bind it to
+     * E18 `resumeAt`, and the design/381 `rewindFilesTo`. `role` + (for a tool result) `toolCallId` let a consumer bind it to
      * the message it rendered: a tool result by its `toolCallId`; an assistant/user message by stream order (this
      * is the terminal boundary for the content just streamed, after its deltas and before its tool results). A
      * consumer builds its own `entryId → message` map from these to resolve `preserved_segment` WITHOUT the
@@ -4639,12 +4944,125 @@ export interface TaskStream extends AsyncIterable<TaskEvent> {
      * landing after the tool finished is a no-op. Unknown toolCallIds are a no-op (nothing to detach).
      */
     detach(toolCallId: string): void;
+    /**
+     * design/383 §2.1 — the MID-SESSION memory-capture opt-out verb ("聊着聊着发现不该记" — the
+     * design's primary scenario): from this call on, the running session commits NOTHING to the
+     * long-term memory store, its already-committed contributions leave the consolidation candidate
+     * set (the retroactive A2 arm), and the session window's residue on the writable memory root is
+     * boundary-swept into control-plane quarantine (per-path named; a sweep failure REFUSES the call
+     * loudly — the one-way record stands either way, so the failure mode is "opt-out on, residue
+     * named", never a silent partial).
+     *
+     * ONE-WAY: no reverse verb exists at any layer; a repeat call is an idempotent `"existed"`. The
+     * way back to capture is a NEW session (a deliberate product cost — "which turns count" has no
+     * honest answer for a retroactive re-enable).
+     *
+     * AUTHORITY (steer-lane law): core does not authenticate — holding this stream IS the capability
+     * handle, exactly as with {@link steer}; a service exposing this verb over the wire owns the
+     * verified-principal / session-ownership check at its own face (a bare sessionId relay would let
+     * anyone switch off anyone's memory: an availability attack). The call re-adjudicates the
+     * per-principal entitlement AT FLIP TIME (`RuntimeCaps.allowMemoryOptOut` under
+     * {@link RunnerDeps.memoryCapturePolicy}, fresh resolve — a denied flip refuses typed
+     * `memory.capture_optout_denied` and leaves ZERO record residue). MODEL-UNREACHABLE by
+     * construction (§2.6): no tool face, no MCP face, and governed workflow specs cannot spell it —
+     * a model that could declare an opt-out could silently disable a user's memory; one that could
+     * revoke it would pierce the privacy control.
+     *
+     * Typed refusals (the closed set, one per arm — rescan post-6.0.0-RC completed the roster):
+     * `memory.capture_optout_denied` (entitlement), `memory.capture_optout_unpersisted` (the record
+     * could not be durably written — a store-mark failure OR a failing §2.7 consolidation-epoch
+     * bump, both refused rather than held in-process, which the first resume would silently break),
+     * `memory.capture_optout_unavailable` (this run mounted no memory session — nothing to opt out
+     * of), `memory.capture_optout_sweep_failed` (the record STANDS but the §2.3 boundary sweep could
+     * not contain named residue paths — a repeat call is the retry lane),
+     * `config.memory_capture_unsupported` (remote/per-run deployment shape with no
+     * {@link RunnerDeps.memoryCaptureRecordStore} — the record would not survive to a resume
+     * replica), `steering.invalid_content` (a non-string `options.reason`), plus the steer-family
+     * `steering.not_running` once the task has finished. Resolves `{ outcome }`: `"created"` = this
+     * call made the crossing (the `memory.capture_opted_out` notice minted); `"existed"` = already
+     * recorded (idempotent; no second notice).
+     */
+    optOutMemoryCapture(options?: {
+        reason?: string;
+    }): Promise<{
+        outcome: "created" | "existed";
+    }>;
     /**
      * Hard-**interrupt** the running task — a real abort (not a best-effort hint), equivalent to firing the
      * task's `signal` (design/47). No-op if the task already finished. For a SOFT redirect that lets the
-     * task keep running and adjust, use {@link steer} instead.
+     * task keep running and adjust, use {@link steer} instead. For the CC-Esc "stop and wait for my
+     * input" form — cut the turn, keep the ending clean and resumable — use {@link halt}.
      */
     interrupt(): Promise<void>;
+    /**
+     * design/373 (#504) — the BARE user interrupt, the CC Esc true form ("cut + stop"): CUT the
+     * in-flight turn and STOP the run at that manufactured boundary, collecting to a clean,
+     * resumable ending. The run-model equivalent of CC's session staying alive waiting for the
+     * user's next input. Three verbs, three powers: {@link interrupt} hard-aborts the run (the
+     * orphan-reconcile ending), {@link steer} with `priority:"now"` cuts the turn AND CONTINUES the
+     * run with the steer text, `halt` cuts the turn and lets the run END awaiting the user.
+     *
+     * The CUT half is the design/373 S1 turn-scoped settle, verbatim: finished tool calls keep their
+     * REAL results; never-started ones settle as paired interrupted results
+     * (`errorKind:"interrupted_never_started"`); the CC-verbatim interruption marker lands in the
+     * session as an engine-note user frame. Every REAL cut is announced (`task.turn_interrupted`
+     * notice, `detail.cause:"user_halt"` — the steer-now landing keeps its own message and no
+     * `cause` key). The STOP half: from acceptance on, NO new model turn starts — the loop ends at
+     * whichever boundary comes first (both boundary faces consult the latch, the pre-turn one
+     * included, so a halt landing between turns cannot buy one more turn). With nothing in flight
+     * the cut half is a no-op (`turnCut:false`) and the stop half alone answers — no false marker.
+     *
+     * **Terminal form (#504 detail ①, ruled completed-with-marker over a new status/stop-reason
+     * member):** the run ends `status:"completed"` with the additive result seat
+     * {@link TaskResult.haltedByUser} `: true` as the discriminator. CC anchor: 250 has NO typed
+     * "interrupted" terminal — Esc leaves a clean continuable session with the transcript marker as
+     * the record, and the SDK result taxonomy (`error_during_execution`/`error_max_turns`/…) gains
+     * no interrupt member; a new closed-set status/stop-reason row would therefore be a non-anchored
+     * invention, while completed-plus-marker is also this repo's own precedent seat
+     * ({@link TaskResult.haltedOnUserRejection} — "the model did not finish; the person stopped it
+     * and the run awaits their direction"). Consumers discriminating "user stopped it" vs "ran to
+     * completion" (billing, continuation copy) read the one boolean.
+     *
+     * **Queued-but-undelivered frames (#504 detail ②, ruled keep-don't-clear):** a halt clears
+     * NOTHING. CC anchor: 250's `control_request:"interrupt"` handler keeps the command queue by
+     * default and answers `still_queued`; clearing is the explicit `cancel_queued:true` opt-in
+     * (`cleared_on_cancel`) — destruction is never the interrupt's default meaning. The run-model
+     * translation: queued steer/follow-up frames stay queued through the cut, are NOT drained into a
+     * turn that will never start, and settle by the run's EXISTING terminal contract for
+     * accepted-but-undelivered input — durable park when a suspend seat exists, else the loud
+     * per-run accounts (`task.user_steer_undrained` / `task.user_followup_undrained`). The receipt
+     * semantics were always "queued = accepted, never consumed": the caller holds the bytes, the
+     * account tells it what to re-send, and `inputId` idempotency makes host-side re-delivery on the
+     * next run replay-safe. (A per-session durable park for non-suspend endings would be new storage
+     * machinery — out of this slice, recorded.)
+     *
+     * **Resume hand-off (#504 detail ③, ruled the ordinary user-lane front door):** the next input
+     * enters as the NEXT RUN's objective on the same session (`runTask`/`runTaskStream` with this
+     * result's `sessionId`) — no special lane, no checkpoint. The halted transcript ends with the
+     * interruption marker exactly where CC's session shows it (marker, then the user's next
+     * message), so the resumed model reads the same shape a CC session shows after Esc. A
+     * checkpoint-resume is neither minted nor needed: `"completed"` + `sessionId` IS the
+     * continuation contract, and a marker-less halted transcript (nothing was in flight to cut) is
+     * an ordinary clean boundary.
+     *
+     * Receipt: resolves `{ turnCut }` — `true` iff THIS call cut a live turn (the completion-race
+     * arm is stated, not hidden: a turn whose work finished as the abort landed ends normally and
+     * the run still stops at its boundary). Repeat calls are accepted and answer honestly
+     * (`turnCut:false` once the stop is already latched); the notice is per-cut, the result seat
+     * per-run. AUTHORITY (steer-lane law): holding this stream IS the capability — a deployment
+     * relaying this verb owns its own gate (relay IS authorization; it cancels in-flight tool work
+     * and ends the run's forward progress). No text ⇒ the `userPromptSubmit` screen has no domain
+     * here (nothing enters the model). Honest window, stated: a halt accepted in the run's last
+     * moments (past the loop's final commit point) finds the run completing naturally — the result
+     * then reports the natural completion WITH the `haltedByUser` seat (the person did press stop
+     * while it finished; the transcript says how far the model got). Typed refusals: the
+     * steer-family `steering.not_running` once the task has finished (teardown included); a halt
+     * issued BEFORE the run's first prompt polls the same bounded birth window as {@link steer} and
+     * then stops the run before its first model turn (an empty, cleanly-halted completed run).
+     */
+    halt(): Promise<{
+        turnCut: boolean;
+    }>;
     /**
      * Reap this task's resources — **callable after it finished**, idempotent, never throws (design/50 §3,
      * design/51). The fan-out (v2) cancel primitive: an orchestrator's `cancelAll` is the shared
@@ -4771,6 +5189,31 @@ export interface RuntimeCaps {
      * deployment resolves to a no-op (asks flow the original chain; no warn — the gate, not a mistake).
      */
     autoMode?: boolean;
+    /**
+     * design/383 §3.1 — may this principal declare a session memory-capture OPT-OUT
+     * (`TaskSpec.memory.capture: "off"` / the Runner flip verb)? `false` = the deployment REQUIRES
+     * capture for this principal (compliance / knowledge retention) — the declaration is refused
+     * terminal (`memory.capture_optout_denied`). `undefined` / `true` = no per-principal restriction.
+     *
+     * ⚠️ POLARITY REVERSAL — this member is the family's one deliberate exception to the
+     * fail-closed resolver degrade (`{allowWorkflows:false, allowFork:false}`): on the PRIVACY axis
+     * "deny" means "capture the session of a user who explicitly said no", which is the IRREVERSIBLE
+     * side (a wrongly-captured session has been read, may be folded into products, may have synced —
+     * deleting later does not unhappen it), while a wrongly-honored opt-out costs one uncaptured
+     * session (recoverable). Under the default/`"open"` posture a resolver FAULT therefore reads as
+     * ALLOW (+ a named `onError` disclosure), and only an explicit `false` denies; a deployment for
+     * which the compliance side is the heavier irreversibility declares `memoryCapturePolicy:
+     * "governed"`, which flips the fault arm to refuse-to-run (see {@link RunnerDeps.memoryCapturePolicy}).
+     *
+     * 🔒 FAULT-TRANSIT CONTRACT (server F2, written here because the resolver's habits run the other
+     * way): a resolver failure for THIS member must surface as the member being ABSENT (`undefined`)
+     * or as a THROW — both read as "fault". The resolver MUST NOT coin a stand-in explicit value on
+     * failure (the `{allowWorkflows:false}` degrade habit): an explicit `false` IS the denied
+     * verdict, and encoding an outage as one silently swaps the fault arm for the verdict arm — under
+     * `"open"` that is the exact polarity inversion this member exists to prevent. A non-boolean
+     * value here is treated as a fault (never truthiness-read) and disclosed.
+     */
+    allowMemoryOptOut?: boolean;
 }
 /**
  * design/129-B — one lifecycle event of a BACKGROUND delegation child, delivered to the
@@ -5071,7 +5514,9 @@ export interface EngineNotice {
      *    `autoCompactTokens` ABOVE its physical window; the trigger-side geometry was clamped to the
      *    physical window (an autocompact window only ever lowers the trigger) and the bad value is
      *    announced once per prepared task; `detail: { modelId, declaredAutoCompactTokens,
-     *    physicalWindow, sessionId }`.
+     *    physicalWindow, sessionId, runId }` — `runId` (#499) is what makes the "once per prepared
+     *    task" claim checkable: the session id beside it is shared by every run of the session, so two
+     *    runs clamping the same model used to mint byte-identical lines.
      *  - `"config.env_timeout_discarded"` — a Bash timeout knob (option or env) held a value that is not
      *    the value in force; `detail: { knob, raw, usedMs }`.
      *  - `"config.materialize_env_discarded"` — `SEMA_TOOL_MATERIALIZE_STRATEGY` held a value outside the
@@ -5079,35 +5524,61 @@ export interface EngineNotice {
      *  - `"tool_result.offload_put_failed"` (#167) — a clear-with-offload persist's fire-and-forget put
      *    failed; THIS attempt stored nothing (the failure arm reports, it never re-inserts under the
      *    ref) — an earlier attempt of the same idempotent re-put may already have stored the row, so
-     *    the notice claims a failed write, not an empty ref; `detail: { ref, sessionId, cause }`.
-     *    Per-occurrence, not per-process-deduplicated: each failed write is a distinct fact.
+     *    the notice claims a failed write, not an empty ref;
+     *    `detail: { ref, sessionId, cause, occurrenceId }`.
+     *    Per-occurrence, not per-process-deduplicated: each failed write is a distinct fact — and
+     *    `occurrenceId` (#495, uuidv7 minted at the failure) is what lets a consumer act on that:
+     *    `ref` names the ROW, and the same ref is attempted again on every later re-clear, so two
+     *    genuine losses of one ref were byte-identical notices. Dedup key: (code, occurrenceId).
      *  - `"workflow.governance_key_stripped"` (#235) — the fields of an LLM-authored workflow `agent(spec)`
      *    that did NOT cross the governed default-deny whitelist: an unrecognized/control-plane field, or a
      *    `readFace` value that is not the containment-tightening one. The spawn PROCEEDS on the deployment
      *    baseline (the strip is not a refusal in this window), which is why the drop is announced;
-     *    `detail: { total, stripped: [{ key, reason }], omitted? }`, the rendered key list bounded in count
-     *    and length because the names come from the untrusted script. One aggregated notice per governed
-     *    child build, not de-duplicated across builds: each spec is a distinct fact.
+     *    `detail: { total, stripped: [{ key, reason }], omitted?, occurrenceId }`, the rendered key list
+     *    bounded in count and length because the names come from the untrusted script. One aggregated
+     *    notice per governed child build, not de-duplicated across builds: each spec is a distinct fact —
+     *    `occurrenceId` (#495, uuidv7 minted at the announcement) carries that claim to the consumer,
+     *    which otherwise saw two builds of the same spec as one repeated notice. Dedup key:
+     *    (code, occurrenceId).
+     *  - `"workflow.agent_option_ignored"` (#505 ①) — the OPTIONS-object twin of the row above: keys of
+     *    `agent(spec, opts)`'s SECOND argument that were not applied (unrecognized, or a known option
+     *    whose value its type check rejected — `label: 42`). The spawn PROCEEDS without them, which is
+     *    why the drop is announced. A separate code because the two membranes accept different key
+     *    sets and the message names its own. `detail: { total, ignored: [key], omitted?, occurrenceId }`,
+     *    same bounding and same per-call (never de-duplicated) semantics as the spec-side row; dedup
+     *    key: (code, occurrenceId). NOT the whole family: a SPEC field written on the options object
+     *    (`model`, `modelName`, `thinking`, …) is REFUSED at the membrane instead — a silently ignored
+     *    `model` runs a different agent than the author asked for.
      *  - `"mcp.revocation_probe_failed"` (design/338) — the deployment's `mcpRevocations.isRevoked`
      *    probe threw; MCP dispatch FAILS OPEN (revocation is a tightening face) and this announces
-     *    once per materialization (a resume re-materializes and may announce again). `detail: { message }`
-     *    — no sessionId (a deployment wiring fact, not session-attributed), `"operator"` audience by
+     *    once per materialization (a resume re-materializes and may announce again).
+     *    `detail: { message, runId }` — still no sessionId (a deployment wiring fact, not
+     *    session-attributed); `runId` (#499) makes the once-per-materialization claim CHECKABLE without
+     *    attributing the line to a conversation, an opaque invocation id saying which materialization
+     *    rather than whose. `"operator"` audience by
      *    its explicit {@link NOTICE_AUDIENCE} row (#433 made the registry total over the catalog —
      *    no engine-minted code is audience-defaulted any more). The refusal itself
      *    (`mcp.server_revoked`) is a tool RESULT code, not a notice.
      *  - `"config.models_swapped"` — `Runner.swapModels` replaced the model catalog generation
-     *    (zero-restart model switching). `detail: { models, tiers }` — key COUNTS only, never the
+     *    (zero-restart model switching). `detail: { models, tiers, occurrenceId }` — key COUNTS only,
+     *    never the
      *    catalog itself. In-flight tasks finish on the models they resolved at prepare (natural
      *    snapshot); every later prepare resolves against the new generation. A failed swap (illegal
      *    tier binding) throws atomically and mints nothing.
+     *    `occurrenceId` (#495, uuidv7 minted at the announcement): the verb carries no run and no
+     *    session, and the payload is a pair of counts, so two swaps of the same shape were byte-
+     *    identical lines. Dedup key: (code, occurrenceId).
      *  - `"route.fallback_to_primary"` (key↔URL pairing, `src/brain/route-adjudicator.ts`) — a
      *    DERIVED-leg model (role/tier/system-default resolution, never a caller-explicit one) failed
      *    the pairing pre-flight and the seat fell back to the primary model instead of sinking the
      *    task; the notice is the loud half of that swap.
-     *    `detail: { seat, from, to, cause, fixHint, sessionId? }` — `cause` is the refusal code
+     *    `detail: { seat, from, to, cause, fixHint, sessionId?, runId? }` — `cause` is the refusal code
      *    (`route.credential_mismatch` / `route.credential_missing`); `sessionId` (#433, additive)
-     *    rides when the adjudicating seat knows its session — a correlation key only, the audience
-     *    stays `"operator"` (see the registry's entitlement-not-routability note).
+     *    rides when the adjudicating seat knows its session, and `runId` (#499, additive) names the
+     *    INVOCATION whose seats were being resolved — both correlation keys only, the audience
+     *    stays `"operator"` (see the registry's entitlement-not-routability note). Two runs of one
+     *    session falling back on the same seat used to mint byte-identical lines; `runId` is what
+     *    tells one task falling back twice apart from two tasks falling back once each.
      *    Explicitly-named models never mint this: they refuse at the brain's request gate instead.
      *  - `"route.base_url_changed_key_unchanged"` (key↔URL pairing) — `Runner.swapModels` moved a
      *    same-name entry's `baseUrl` while its Model-visible credential half (auth-bearing headers)
@@ -5115,8 +5586,11 @@ export interface EngineNotice {
      *    PROVIDER changed, the credential reference needs the same update. Advisory only, never a
      *    refusal; per-model-hook credentials are invisible to the catalog swap, so the notice is
      *    deliberately conservative (it may fire when a hook-side credential DID change in lockstep).
-     *    One aggregated notice per swap; `detail: { entries: [{ modelId, from, to }], total }`
-     *    (rendered list bounded, total always exact).
+     *    One aggregated notice per swap; `detail: { entries: [{ modelId, from, to }], total,
+     *    occurrenceId }` (rendered list bounded, total always exact). `occurrenceId` (#495, uuidv7
+     *    minted at the announcement, independent of the `config.models_swapped` line's own): the
+     *    bounded render makes two swaps moving the same first entries byte-identical.
+     *    Dedup key: (code, occurrenceId).
      *  - `"config.read_face_deployment_clamped"` (#237) — a deployment-wide `readFace: "open"` is not
      *    in force beside a read-only (verifier) mount: it clamps to "roots" without throwing
      *    (stricter-wins; the clamp verdict stands, only its occurrence was undisclosed). Announced
@@ -5152,10 +5626,13 @@ export interface EngineNotice {
      *    frame's two count keys). They are NOT redelivered (a steer aimed at a finished run must not
      *    fire at the next one — unlike ENGINE notes, which pend per session); the loud half of the
      *    #257 contract's "accepted = enqueued, not consumed" sentence;
-     *    `detail: { steer, taskId?, sessionId? }` / `{ followUp, taskId?, sessionId? }` (`sessionId`
-     *    = #433's routing half for these two `"user"`-audience rows — see
-     *    {@link undrainedUserInputNotices}; omitted when the caller has none, never fabricated).
-     *    Per-run, at most once per family (the terminal sweep is a single site).
+     *    `detail: { steer, taskId?, sessionId?, runId? }` / `{ followUp, taskId?, sessionId?, runId? }`
+     *    (`sessionId` = #433's routing half for these two `"user"`-audience rows; `runId` = #499's
+     *    per-run identity, the key this account is actually about — see
+     *    {@link undrainedUserInputNotices}; all omitted when the caller has none, never fabricated).
+     *    Per-run, at most once per family (the terminal sweep is a single site) — which is exactly why
+     *    `taskId`/`sessionId` cannot key it: both answer the same value for two runs of one session,
+     *    so two runs each stranding one steer folded into one indistinguishable row.
      *    **#389 (two corrections).** ① The family now fires on the INTERRUPT path too: `abort()` used
      *    to empty both queues before agent_end could count them, so the one loss path an operator most
      *    needs to hear about was the one path that stayed silent. ② On a DURABLE PARK the verdict is
@@ -5164,17 +5641,29 @@ export interface EngineNotice {
      *    — what is announced is the remainder that could NOT be carried, so a fully-migrated park says
      *    nothing at all and a queue-full / no-longer-pending row still says exactly what was lost.
      *
-     *  - `"task.turn_interrupted"` (design/373) — a caller-provenance steer with `priority: "now"`
-     *    ACTUALLY CUT the running turn: the in-flight provider stream / tool batch was aborted at a
-     *    manufactured boundary (finished tool calls keep their real results, never-started ones
-     *    settle as paired interrupted results, the interruption marker lands) and the run CONTINUES
-     *    with the steer at the queue head. One notice per REAL cut (a `now` that found nothing in
-     *    flight, or whose frame already rode the imminent boundary, announces nothing — no false
-     *    interrupt claims); every cut turn counts toward `maxTurns`, so an interrupt storm's cost is
-     *    bounded and each of its cuts is on the record. `detail: { inputId, sessionId, actorId?,
-     *    taskId? }` — `inputId` is the steer's own correlation key (the `human_input` frame's id),
-     *    `actorId` the caller's asserted identity when one rode the steer. Audience `"user"`: the
-     *    person whose input forced the boundary is the one entitled to see that it landed.
+     *  - `"task.turn_interrupted"` (design/373) — a running turn was ACTUALLY CUT at a manufactured
+     *    boundary: the in-flight provider stream / tool batch was aborted (finished tool calls keep
+     *    their real results, never-started ones settle as paired interrupted results, the interruption
+     *    marker lands). **TWO mint lanes, one code** — the CUT is lane-independent, so it is one fact
+     *    with one spelling, and `detail.cause` is the arm discriminator (a consumer that must tell
+     *    them apart reads that key; one that only cares "a turn was cut" reads neither):
+     *      · the STEER-NOW lane (design/373) — a caller-provenance steer with `priority: "now"` cut
+     *        the turn and the run CONTINUES with the steer at the queue head.
+     *        `detail: { inputId, sessionId, runId, actorId?, taskId? }`, NO `cause` key — `inputId` is
+     *        the steer's own correlation key (the `human_input` frame's id) and `actorId` the caller's
+     *        asserted identity when one rode the steer.
+     *      · the BARE-HALT lane (#504, {@link TaskStream.halt}) — the person's Esc-form stop cut the
+     *        turn and the run does NOT continue: it collects to a clean, resumable
+     *        `status:"completed"` ending carrying {@link TaskResult.haltedByUser}.
+     *        `detail: { cause: "user_halt", sessionId, runId, taskId? }` — no `inputId` and no
+     *        `actorId`, because no text entered the model and the verb carries no caller identity. A
+     *        consumer keying `detail.inputId` off this row must treat it as ABSENT on this lane.
+     *    In both lanes: one notice per REAL cut (a `now` that found nothing in flight or whose frame
+     *    already rode the imminent boundary, and a halt with nothing in flight, announce nothing — no
+     *    false interrupt claims); `runId` (#499) is the INVOCATION that was cut (the other two ids are
+     *    shared by every run of the session); every cut turn counts toward `maxTurns`, so an interrupt
+     *    storm's cost is bounded and each of its cuts is on the record. Audience `"user"`: the person
+     *    who forced the boundary is the one entitled to see that it landed.
      *    RETIRED here (BREAKING, named): `"task.injection_priority_unimplemented"` — the ladder is
      *    implemented, so the unhonored-knob disclosure it carried has no referent; consumers must
      *    judge ladder support by VERSION, never by that code's absence.
@@ -5187,8 +5676,10 @@ export interface EngineNotice {
      *    same fact is the entry's own `human_input` account with `delivery: "blocked"` — the two share
      *    the inputId, so "accepted at park, screened at redelivery" is auditable end to end. Audience
      *    `"user"` (the person whose instruction was withheld is the one entitled to re-issue it);
-     *    `detail: { inputId?, sessionId, taskId? }` — `inputId` is the parked entry's stored
-     *    correlation key.
+     *    `detail: { inputId?, sessionId, runId, taskId? }` — `inputId` is the parked entry's stored
+     *    correlation key (OPTIONAL: a row parked without one exists), and `runId` (#499) names the
+     *    resume leg that withheld it, so a session resumed twice does not report two withholdings as
+     *    one.
      *
      *  - `"memory.session_polluted"` (design/178 §3, #324a; message mode-aware since design/336) —
      *    this session's memory crossed into the one-way externally-exposed state (a tool classified
@@ -5216,8 +5707,13 @@ export interface EngineNotice {
      *    two numbers are read off the report's rows, never subtracted from each other). One notice PER
      *    HARVEST that withheld at least one entry file (a checkpoint harvest and the terminal harvest
      *    are distinct facts), never minted for a clean session; `detail: { count, moved, escalated,
-     *    reason?, sessionId? }` (`reason` absent ⇔ the pollution marker could not be re-read at report
-     *    time — the withheld count stays true either way). The formerly registered index-only gap is
+     *    reportId?, reason?, sessionId? }` (`reason` absent ⇔ the pollution marker could not be re-read
+     *    at report time — the withheld count stays true either way). `reportId` (#479) is the minting
+     *    harvest's own occurrence identity ({@link import("./memory-engine/types.js").HarvestReport}
+     *    `.reportId`, uuidv7): two harvests whose counts and paths coincide carry DISTINCT ids, a
+     *    durable replay of the same notice carries the SAME id, and the hold family below shares this
+     *    harvest's id — dedup on `(code, detail.reportId)`, never on `reportId` alone (absent only for
+     *    a hand-built report; every engine-minted report carries it). The formerly registered index-only gap is
      *    CLOSED under `memoryProvenance: "carry"` (design/336 §6.3, #331): the mint condition reads
      *    `HarvestReport.containment`, so a containment whose only act was the derived-index rollback
      *    announces with `count: 0` and `detail.indexRolledBack: true`; under `"off"` the pre-336
@@ -5226,15 +5722,18 @@ export interface EngineNotice {
      *    §4/§6.3) — the instruction-hold lifecycle, derived from the same structured
      *    `HarvestReport.containment` signal (hold seats are only ever filled under
      *    `memoryProvenance: "carry"`): a PENDING session's instruction-form entry files were captured
-     *    off the model-visible plane (`hold_opened`, `detail: { count, paths, sessionId? }` — paths
-     *    neutralized/length-bounded); previously held entries re-walked the full gate set and
+     *    off the model-visible plane (`hold_opened`, `detail: { count, paths, reportId?, sessionId? }`
+     *    — paths neutralized/length-bounded); previously held entries re-walked the full gate set and
      *    committed after their writer session settled clean or a host valve released them
-     *    (`hold_released`); held entries moved to control-plane quarantine (`hold_disposed`,
-     *    `detail.disposed: [{ path, terminal }]` with the closed terminal set
+     *    (`hold_released`, same detail shape); held entries moved to control-plane quarantine
+     *    (`hold_disposed`, `detail.disposed: [{ path, terminal }]` with the closed terminal set
      *    dirty/expired/conflict/capture_lost/discarded — an `expired` terminal is explicitly a
      *    TIMEOUT, not a conviction, and the message names `resolveHold` as the recovery valve). At
      *    most one notice per family per harvest report; wording is factual, never threat-flavored
-     *    (the design/336 §13-2 model-psyche guardrail).
+     *    (the design/336 §13-2 model-psyche guardrail). `detail.reportId` (#479) is shared by all
+     *    three families AND `"memory.harvest_quarantined"` when they derive from the same harvest
+     *    report — that sharing is the contract (one report, several distinct facts): dedup on
+     *    `(code, detail.reportId)`; a repeat with the same pair is a replay, a new pair is a new fact.
      *  - `"memory.delegation_static_mark_waived"` (design/324, #324 ruling ①) — the deployment set
      *    {@link RunnerDeps.memoryDelegationEvidence} to `"attested-only"` and a delegation call whose
      *    STATIC tool-face verdict would have marked this session's memory polluted (attestation
@@ -5248,7 +5747,9 @@ export interface EngineNotice {
      *    TASK LEG (a resume leg may announce again — a new leg's audit stream is a new fact;
      *    deliberately no durable once-per-session state), never on the `"static-face"` default, and
      *    never for a delivered `"external"` attestation (that mark still lands);
-     *    `detail: { reason, subagentType?, sessionId? }` — `reason` is the same sentence the waived
+     *    `detail: { reason, subagentType?, sessionId?, runId }` — `runId` (#499) is what makes the
+     *    ONCE-PER-LEG guarantee above checkable, since a resume leg may legitimately announce again and
+     *    the session id cannot tell the two legs apart; `reason` is the same sentence the waived
      *    mark would have carried, neutralized/length-bounded (tool and agent-type names are
      *    host/model-controlled inputs).
      *  - `"memory.content_class_declared"` (design/378) — an `McpServerSpec` entry carries an explicit
@@ -5263,7 +5764,10 @@ export interface EngineNotice {
      *    condition as the classification it talks about — a leg with no engine-memory session and no
      *    provenance recorder classifies nothing, so there is no posture to report and no line is
      *    minted. `detail: { server,
-     *    contentOrigin, toolCount, execIsExternalContent?, sessionId? }` — `server` is the
+     *    contentOrigin, toolCount, execIsExternalContent?, sessionId?, runId }` — `runId` (#499) names
+     *    the LEG, which is what "one line per declared entry per prepared task leg" is a claim about:
+     *    the session id beside it is shared by every leg of the session, so two legs reading one
+     *    declaration used to mint byte-identical rows. `server` is the
      *    host-authored entry name, neutralized/length-bounded; `toolCount` is what this entry actually
      *    mounted (0 for a server that failed to connect — the declaration still stands and is still
      *    disclosed); `execIsExternalContent` rides the `"execution"` value only and reports the strict
@@ -5273,11 +5777,60 @@ export interface EngineNotice {
      *    long after the dial, and D-10 already rules topology is not evidence of the lineage this line
      *    audits — connection facts live on `MaterializedMcp.statuses` instead.
      *
+     *  - `"memory.capture_opted_out"` (design/383 §2.8) — memory capture is OFF for this session and
+     *    the switch provably TOOK: nothing the session produces will be committed to the long-term
+     *    store and its contributions no longer enter consolidation. The user must be able to SEE the
+     *    switch land rather than infer it from silence, which is why it is announced rather than left
+     *    implicit. States three facts and an exit, and deliberately overclaims none of them: entries
+     *    committed BEFORE the opt-out remain in the library and stay retrievable, entries already
+     *    folded into consolidation products leave those products unaffected, and deleting committed
+     *    content is a separate host action (the erase valve), never a side effect of this switch.
+     *    `detail: { sessionId, origin }` — `origin` is the closed set
+     *    `"declaration" | "flip-verb" | "standing-record" | "delegation-floor" | "fork-origin"`, and
+     *    the message is written per value (a delegated child's inherited floor and a fork's inherited
+     *    one-way record say so, rather than claiming the session declared it). Audience `"user"`.
+     *    Dedup unit: once per SESSION — key `(code, detail.sessionId)`, so the standing-record resume
+     *    arm folds into the standing entry instead of double-announcing.
+     *  - `"memory.capture_optout_unpersisted"` (design/383 §2.8) — the OPPOSITE receipt, and a
+     *    separate code on purpose ("it is off for you" and "it could not be turned off" must never
+     *    share a spelling): the opt-out could NOT be durably recorded (the control-plane write
+     *    failed), so it is REFUSED rather than honored in-process under a switch that would silently
+     *    stop holding at the next resume. Minted only beside that refusal — the throw carrying the
+     *    same code — never beside a success, and no success notice is minted on this arm.
+     *    `detail: { sessionId }`. Audience `"user"` (the operator repairs the store, but the
+     *    entitlement to the fact belongs to whoever asked for the privacy). **TWO ingresses, and they
+     *    settle differently — a consumer must not read one as the other:**
+     *      · PREPARE-TIME (a declared/inherited opt-out, before the run starts) — the refusal is
+     *        TERMINAL: the task never runs and nothing is captured. Dedup unit: once per task, since
+     *        the refusal it rides settles the task.
+     *      · the LIVE FLIP VERB ({@link TaskStream.optOutMemoryCapture} mid-run) — the refusal is
+     *        SCOPED TO THAT CALL: it rejects the verb's promise and nothing else. The run keeps going
+     *        and capture is still ENABLED (the switch did not take), which is exactly why the notice
+     *        is owed. Because no record was retained, a retry can fail the same way, so this ingress
+     *        can announce ONCE PER ATTEMPT — a consumer de-duplicating per task would hide later
+     *        failures of a switch the person is still trying to throw.
+     *    Read the run's own outcome (or the verb's rejection) to tell the two apart; this code alone
+     *    does not say whether anything stopped.
      *  - `"memory.consolidation_incomplete"` (design/376, LLM consolidation driver) — a driver run
      *    settled without reaching the fixpoint: `detail` names the stop reason (the closed
      *    `ConsolidationRunStopReason` set), cycles done, and the residue (write-failure or
      *    fuse-refused groups by name). Advisory: committed cycles stand (add-only, never rolled
      *    back); the recovery verb is re-running the host driver, which resumes the same pending run.
+     *  - `"memory.consolidation_withheld"` (design/383 §1.4) — the exposure partition engaged on a
+     *    consolidation run, so the CLEAN arm's authoring prompts were composed WITHOUT the marked
+     *    rows: anything this run's clean products say was written without them, and their silence on a
+     *    topic therefore does not mean the library is silent on it (the withheld rows still stand and
+     *    are still readable). TWO counts, deliberately separate sentences and separate keys —
+     *    `withheld` rows were kept out of the clean arm's prompts, and `neverSent` of those were not
+     *    sent to the consolidation model AT ALL (a lone marked row has no group to fold, so it is
+     *    withheld from every call). "Withheld from the clean arm" and "never left this machine" are
+     *    different facts about a person's own data and must not be merged into one comforting number,
+     *    which is why `sentToProvider` is carried as its own member rather than left to subtraction.
+     *    `detail: { scope, runId, withheld, neverSent, sentToProvider }` — `scope` is
+     *    neutralized/length-bounded. Audience `"user"`: the ONE consolidation row that is a reader's
+     *    fact rather than an operator's (the other five report what a host-driven maintenance run DID;
+     *    this one reports what the products a person will READ were written without). Minted once per
+     *    run, beside the receipt — the dedup unit.
      *  - `"memory.consolidation_driver_superseded"` is an ERROR code, not a notice (named here only
      *    to keep the family's spellings in one place): a concurrent driver invocation took over this
      *    scope's run row (attempt fencing) and the losing worker's call THROWS with this `code` —
@@ -5298,7 +5851,9 @@ export interface EngineNotice {
      *    session count crossed the consolidation thresholds (time gate open ∧ enough distinct
      *    sessions); minted at most once per crossing (a completed run re-arms the edge), NEVER when
      *    the deployment leaves consolidation off. ADVISORY: the host owns the verbs, nothing runs
-     *    automatically; `detail: { scope, sessionsSince, sessionId? }`.
+     *    automatically; `detail: { scope, sessionsSince, reportId?, sessionId? }` — `reportId` (#479)
+     *    is the minting harvest report's occurrence identity, shared with the harvest/hold family's
+     *    notices of the same report (dedup on `(code, detail.reportId)`).
      *  - `"memory.consolidation_committed"` (design/339 §6.2) — a consolidation plan reached
      *    `completed`: products landed, superseded targets left the default read face (retained as
      *    evidence), intents settled; `detail: { planId, scope, products, superseded, intents }` —
@@ -5313,7 +5868,10 @@ export interface EngineNotice {
      *  - `"memory.consolidation_refused"` (design/339 §6.2) — the notice dialect of a consolidation
      *    verb's coded structured refusal (the verb itself throws
      *    {@link import("../core/memory-engine/consolidation.js").ConsolidationRefusedError});
-     *    `detail: { refusalCode, scope? }`.
+     *    `detail: { refusalCode, scope?, occurrenceId? }`. `occurrenceId` (#495) is the THROWN ERROR's
+     *    own id, minted once where the refusal happens and read off it by the notice factory — one
+     *    throw rendered twice keeps one id, two refusals sharing a code/scope/message get two. Omitted
+     *    (never fabricated) when the caller composes the line with no error in hand.
      *
      *  Deliberately NOT a notice family: brain retry/reconnect liveness (a rate limit, a 5xx, a
      *  transient network failure being retried). Those are per-attempt liveness frames with their own
@@ -5371,11 +5929,67 @@ export declare function deliverEngineNotice(onNotice: ((notice: EngineNotice) =>
  * — the one throat — lifts it to the typed top-level key and the two spellings cannot disagree.
  * Omitted when the caller has none (never fabricated: the message is what the run lost, and a made-up
  * routing key would deliver it to the wrong stream).
+ *
+ * `runId` (#499, additive and optional): THE key for this account. The two ids above name the task and
+ * the conversation, and both answer the same value for two runs of one session whenever the host
+ * supplies no task id — so two runs each stranding one steer produced two byte-identical rows, read as
+ * one repeated disclosure about one run. The account is per-RUN by its own contract sentence ("at most
+ * once per family, per run"), so it must carry the run's own id. Same omit-never-fabricate rule.
  */
 export declare function undrainedUserInputNotices(counts: {
     steer: number;
     followUp: number;
-}, taskId?: string, sessionId?: string): EngineNotice[];
+}, taskId?: string, sessionId?: string, runId?: string): EngineNotice[];
+/**
+ * design/380 O2 — the facts handed to a deployment's {@link RunnerDeps.resumePreflight}: the row's
+ * own recorded identity + placement record, read off the persisted checkpoint (never off the resume
+ * caller's bag), so the hook judges the SAME row the CAS is about to consume.
+ */
+export interface ResumePreflightInfo {
+    token: import("./checkpoint-store.js").CheckpointToken;
+    sessionId: string;
+    /** design/380 O1③ — the row's recorded placement root, when stamped. */
+    placementRootSessionId?: string;
+    /** The row's recorded identity ({@link import("./checkpoint-store.js").Checkpoint.principal}), when stamped —
+     *  the resume entry's identity-continuity rung already refused a contradicting supplied principal
+     *  before this hook runs, so a present value IS the resumed leg's identity. */
+    principal?: string;
+    /** provider / deviceId / mountPath — the placement facts. */
+    workspaceHandle?: import("./remote-env.js").WorkspaceHandle;
+    gateKind: import("./checkpoint-store.js").CheckpointGate["kind"];
+}
+/** design/380 O2 — a {@link RunnerDeps.resumePreflight} answer. */
+export type ResumePreflightVerdict = {
+    ok: true;
+}
+/** Transient obstacle (device offline, dependency briefly down): the checkpoint stays `pending`,
+ *  the SAME token is redeemable later; retryAfterMs threads the wait hint (the #449 G1 carrier). */
+ | {
+    ok: false;
+    disposition?: "retry_later";
+    message: string;
+    retryAfterMs?: number;
+}
+/** PERMANENT obstacle (binding revoked, placement identity gone): the row is settled TERMINALLY —
+ *  core CASes it out of `pending` before answering, so a dead binding cannot
+ *  be redialed forever (prose-terminal + mechanically-retriable = unbounded redeem). The `expire`
+ *  CAS is a pure STATUS flip — the row records no reason (the store seam has no seat for one);
+ *  the REASON travels on the typed `resume.preflight_rejected` refusal (the hook's `message`
+ *  inlined), the `onError` disclosure sink, and the deployment hook's own audit plane — it
+ *  authored the verdict and owns the durable record of why. The exact
+ *  terminal CAS form is the single-shot `expire` CAS (reaper parity — exactly one settler wins; a
+ *  LOST race is re-read and reported as concurrent movement, never claimed as this refusal's
+ *  settle); the CONTRACT is: terminal verdict ⇒ atomic single-shot settle, never a silent
+ *  pending-forever. PHYSICAL reclamation of a suspended workspace stays with the DEPLOYMENT that
+ *  ruled the binding dead — core holds no env pre-restore and a factory cannot reconnect to a
+ *  revoked target; the session pin follows the store contract's documented reap posture. Trust
+ *  grant is acceptable: the hook lives on RunnerDeps, the same deployment plane that owns the
+ *  checkpoint store itself. */
+ | {
+    ok: false;
+    disposition: "terminal";
+    message: string;
+};
 /** Runtime dependencies shared across tasks. */
 export interface RunnerDeps {
     brain: Brain;
@@ -5550,6 +6164,48 @@ export interface RunnerDeps {
      * never truthiness).
      */
     memoryProvenance?: "off" | "carry";
+    /**
+     * design/383 §3.1 — the deployment's memory-capture POSTURE (the frame the per-principal
+     * {@link RuntimeCaps.allowMemoryOptOut} verdict is read inside). Closed spellings, screened at
+     * the config doors (`config.memory_capture_policy` — a garbage value refuses the prepare, never
+     * folds to any posture):
+     *  - absent / `"open"` — an opt-out declaration takes effect at face value; only a resolver's
+     *    EXPLICIT `false` denies it (`memory.capture_optout_denied`, terminal). Resolver fault
+     *    (throw / non-boolean / absent-on-fault) ⇒ the opt-out STILL TAKES EFFECT, with a named
+     *    `onError({phase:"config"})` disclosure — the polarity-reversal arm: on this posture the
+     *    irreversible failure is capturing a session whose user said no, so the fail-safe faces the
+     *    other way from the caps family's deny-on-outage degrade. Under the ABSENT posture the first
+     *    opt-out actually honored additionally announces one operator line (once per process): the
+     *    switch is in use and no policy was ever configured.
+     *  - `"governed"` — the per-principal verdict is MANDATORY (the mixed-fleet compliance
+     *    deployment: some principals are retention-required). A verdict of `true` allows, `false`
+     *    denies; resolver fault / absent verdict ⇒ the task is REFUSED (fail-closed): this posture
+     *    is the deployment explicitly declaring the compliance side's irreversibility (a
+     *    retention-required user acquiring an opt-out during an outage window) the heavier one.
+     *  - `"capture-required"` — every opt-out declaration is refused (deployment-wide forced
+     *    retention, one line, resolver-independent).
+     * The two fault polarities are BOTH deliberate and BOTH pinned; the cost table lives beside the
+     * adjudicator. Authority vs record separation (§3.3): this posture governs whether a NEW
+     * declaration (or a resumed run) may proceed — it never retroactively re-enables capture for a
+     * session whose one-way opt-out record already stands (record wins for capture; under
+     * `"governed"`/`"capture-required"` a standing record whose entitlement has been revoked refuses
+     * to CONTINUE instead — zero capture and zero out-of-policy running, availability paid).
+     */
+    memoryCapturePolicy?: "open" | "governed" | "capture-required";
+    /**
+     * design/383 §2.1b — an optional host-supplied carrier for the session capture opt-out record
+     * (per memory plane, keyed by that plane's control dir). Absent = the control-plane file trio
+     * (single-process/single-host deployments: byte-identical behavior). A deployment whose control
+     * plane does not survive into resume replicas (the stateless multi-replica server form) supplies
+     * a durable store here; see {@link import("./memory-engine/layout.js").SessionCaptureRecordStore}
+     * for the per-leg fail-closed contract. Also the §2.1b capability signal: on a REMOTE-execution
+     * deployment with no store supplied here, a `capture:"off"` declaration is refused
+     * (`config.memory_capture_unsupported`) rather than accepted onto a carrier that the next resume
+     * cannot see — a false privacy promise is worse than a loud one.
+     */
+    memoryCaptureRecordStore?: (plane: {
+        controlDir: string;
+    }) => import("./memory-engine/layout.js").SessionCaptureRecordStore;
     /**
      * design/339 §6.1 — the v3 memory-consolidation switch, threaded verbatim to the engine seat
      * ({@link import("../core/memory-engine/engine.js").MemoryEngineOptions.consolidation} — same
@@ -5585,6 +6241,23 @@ export interface RunnerDeps {
      * author gets no channel to point the library's consolidation at a model of its choosing.
      * Absent alongside absent {@link memoryConsolidation} ⇒ nothing runs and nothing changes
      * (the v3 default posture).
+     *
+     * ⚠️ EGRESS — read this before configuring the seat (design/383 §1.5). Turning consolidation on
+     * SENDS MEMORY CONTENT TO A MODEL PROVIDER. Specifically:
+     *  - WHAT: that cycle's ELIGIBLE CANDIDATES — not the whole library (entries already superseded,
+     *    of an ineligible type, or held out by a governance gate are not in the set) — each rendered
+     *    as its `name`, `description` and `body`. The bodies are the user's own notes, verbatim.
+     *  - WHERE: the provider this seat resolves to. When `chat` is absent that is whatever the
+     *    `consolidate → summarize` role chain lands on, which MAY BE THE SAME PROVIDER AS THE MAIN
+     *    MODEL and may equally be a different vendor — the resolution is the deployment's, and the
+     *    driver announces the model id and endpoint it actually used at the moment of the first call.
+     *  - MARKED CONTENT: entries carrying an external-origin (or repo-ingest `trust`) marker are
+     *    withheld from the CLEAN products' prompts and minted through a separate marked-only call.
+     *    "Withheld from the clean arm" is NOT "not sent" — such rows still go to the provider in
+     *    their own call, except a lone marked row, which is sent nowhere. The run receipt reports the
+     *    two counts separately (`withheldFromCleanArm` / `withheldNeverSent`) and so should any UI.
+     *  - IRREVERSIBILITY: bytes that have already crossed to a provider cannot be recalled by any
+     *    later configuration change. Disabling the seat stops FUTURE egress and nothing else.
      */
     memoryConsolidationDriver?: {
         chat?: {
@@ -5640,13 +6313,84 @@ export interface RunnerDeps {
      */
     checkpointStore?: import("./checkpoint-store.js").CheckpointStore;
     /**
-     * design/101 §E19 — working-tree snapshot backend for {@link TaskSpec.rewindFiles}. A task with
-     * `rewindFiles` captures a snapshot per completed turn (keyed by the leaf `SessionTreeEntry.id`) and, when it
-     * also branches via {@link TaskSpec.resumeAt}, restores the snapshot for that entry. Omitted ⇒ rewind is OFF
-     * (no snapshot/restore work). The default reference impl is {@link InMemoryFileSnapshotStore}; a deployment
-     * supplies a durable / git / VM-snapshot backend behind the same seam (v1 restore is LOCAL-only).
-     */
-    fileSnapshotStore?: import("./file-snapshot-store.js").FileSnapshotStore;
+     * design/380 O2 — deployment-supplied resume preflight, called INSIDE the pre-CAS ladder (after the
+     * row-integrity rungs, immediately before the CAS) with a bounded deadline
+     * ({@link resumePreflightTimeoutMs}). Refusal / throw / timeout ⇒ typed `resume.preflight_rejected`
+     * (CheckpointError closed-set addition); the DEFAULT/absent disposition is `retry_later` (the safe
+     * arm — fail-closed hooks that just throw can never accidentally terminalize a row) — the
+     * entrance-screen posture of the wake-message hook (design/373 D2), generalized from "screen the
+     * wake message" to "screen the resume". A deployment binding runs to targets (a device lane) checks
+     * its placement/binding tables here: a transient obstacle answers `retry_later` (+`retryAfterMs`,
+     * the #449 G1 wait-hint carrier — the row stays `pending`, the SAME token redeems later); a
+     * PERMANENT one answers `terminal` (the row is settled by the single-shot `expire` CAS — never a
+     * silent pending-forever; bounded waiting for a target to come back also belongs HERE, inside the
+     * deadline, never in the env factory). Absent ⇒ no preflight, byte-identical resume behavior.
+     */
+    resumePreflight?: (info: ResumePreflightInfo, signal: AbortSignal) => Promise<ResumePreflightVerdict>;
+    /**
+     * design/380 O2 — the {@link resumePreflight} deadline in ms. Default 10s (its own bound,
+     * deliberately NOT the hooks-record default: a resume preflight sits on every redeem attempt of a
+     * parked row and must answer promptly or get out of the way). Bad values (non-finite, ≤ 0,
+     * non-number) are DISCLOSED loudly through `onError` and fall back to the default (the bad-value
+     * loudness default: announce, never silently absorb).
+     */
+    resumePreflightTimeoutMs?: number;
+    /**
+     * design/381 — the per-edited-file rewind history backend (CC FileHistory topology; replaces the
+     * E19 whole-tree `fileSnapshotStore`). WIRING IS THE OPT-IN (DV-9, the reference's own SDK
+     * posture): with a store present, every Edit/Write/NotebookEdit first-touch is backed up before
+     * the byte changes, every turn mints a history boundary keyed by its own initial session entry
+     * ("file state when this turn began"), and a {@link TaskSpec.resumeAt}+{@link TaskSpec.restoreFiles}
+     * (or {@link TaskSpec.rewindFilesTo}) run converges the tracked set back to a boundary. Omitted ⇒
+     * rewind is OFF: zero track calls, zero boundary work, zero disclosure noise; a restore request
+     * then fails loud (`rewind.store_unconfigured`). The reference impl is
+     * {@link InMemoryFileHistoryStore}; a deployment supplies a durable backend behind the same seam
+     * (backends MUST reuse the exported env-half helpers — see the contract JSDoc). Works against ANY
+     * ExecutionEnv (local or remote): bytes are read/written through the env's FileSystem face and
+     * stored host-side, so an env rebuild does not lose history.
+     */
+    fileHistoryStore?: import("./file-history-store.js").FileHistoryStore;
+    /**
+     * design/381 DV-14 (终审落锤) — what an Edit/Write/NotebookEdit does when its FIRST-TOUCH history
+     * record cannot be persisted (`FileHistoryStore.trackEdit` answered `{ok:false}` = NO durable
+     * first-touch state exists). Default **"refuse"**: the edit is refused with a typed tool error
+     * naming the history-store failure — proceeding would leave the path indistinguishable from
+     * never-touched, and the store's post-recovery retry would then mint already-modified bytes as
+     * pristine v1 (the fake-pristine hole this default welds shut).
+     *
+     * `"proceed-unprotected"` is the availability concession arm: the edit proceeds and the failure is
+     * disclosed via `onError` (phase "rewind"). ITS RESIDUAL, stated so the choice is informed: during
+     * a store outage NO durable trace of the touch can be written, so "the pristine promise is void"
+     * lives only in this process's memory — after a process restart the risk is exactly the default
+     * arm's nightmare again (the store recovers, the next edit mints already-modified bytes as v1).
+     * A deployment choosing this arm owns that window and is expected to record the disclosed events
+     * in its own audit surface. Values outside the two-member set refuse prepare loudly.
+     */
+    onTrackFailure?: "refuse" | "proceed-unprotected";
+    /**
+     * design/381 §5.3① / §10 S-1 — the ADDITIVE discriminant for the rewind refusal that this engine
+     * cannot decide on its own. When a restore finds no boundary for the requested entry, there are
+     * two very different worlds: the boundary NEVER existed (those turns ran with no history store, or
+     * it was reaped), or it exists in the RETIRED whole-tree snapshot epoch, which the per-edited-file
+     * seat deliberately does not restore. The engine holds no whole-tree state, so absent this probe
+     * the refusal honestly names BOTH possibilities rather than picking one — the default, and the
+     * only honest wording for a deployment that never had a whole-tree epoch at all.
+     *
+     * A deployment that DOES hold the retired epoch (its assembly layer can ask the old table whether
+     * that entry has a legacy row) supplies the bit here, and the refusal splits into the two precise
+     * messages. `true` = a whole-tree-era boundary exists for that entry; `false` = it definitively
+     * does not; `undefined` = the deployment cannot tell, which reads exactly like an absent probe.
+     *
+     * Consulted ONLY on the refusal path (never on a successful restore), so a slow probe costs
+     * nothing in the ordinary case. It is a DIAGNOSTIC input, never a control input: a probe that
+     * throws, hangs past the caller's own patience, or answers a non-boolean cannot change the outcome
+     * — the refusal still happens, the wording falls back to the honest both-possibilities form, and
+     * the bad value is disclosed through `onError` (phase "rewind") rather than silently absorbed.
+     */
+    legacyRewindBoundaryProbe?: (query: {
+        sessionId: string;
+        entryId: string;
+    }) => boolean | undefined | Promise<boolean | undefined>;
     /**
      * design/99 §E6 — DURABLE per-session permission rules (a deny-narrowing folded into the task-time tool
      * policy). Omitted ⇒ the feature is OFF (no rules read, zero behavior change). A deployment supplies a
@@ -5826,6 +6570,37 @@ export interface RunnerDeps {
             consecutiveFailures: number;
             lastCause: string;
         }) => void;
+        /**
+         * #503 — OPT IN to recording this arming's serializable criteria (an
+         * {@link import("./auto-mode-arming.js").AutoModeArmingRecipe}) on the constraint-chain entries a
+         * durable park freezes, so a CROSS-PROCESS redemption can rebuild an equivalent classifier over its
+         * own model leg ({@link import("./auto-mode-rebuild.js").rebuildAutoModeDecider}) instead of
+         * answering `unavailable` forever and parking the same approval for a human on every redemption.
+         *
+         * DEFAULT OFF, and the default is the safety story: a row minted without it is byte-identical to
+         * the pre-#503 shape, so a mixed-version fleet (a worker that predates this field resuming a row a
+         * newer worker minted) keeps the digest it can compute. Turn it on fleet-wide, not per-worker.
+         *
+         * What gets written down: the rule overrides, the settings-deny rules, the session-context facts,
+         * the window bounds and the two knobs — i.e. deployment-authored configuration, on a durable row.
+         * `sessionContext` is the one field that routinely carries per-session facts (a user-identity
+         * line); a deployment that treats those as sensitive at rest should keep them out of the arming
+         * face rather than out of this flag.
+         *
+         * Recording is CONDITIONAL on the session breaker still being closed at park time: a session that
+         * already fell back to non-auto hands nothing forward (the redemption must never run wider than the
+         * ancestor it inherits). A `true` here with a non-serializable face announces once and records
+         * nothing (`phase:"config"`).
+         */
+        persistArming?: boolean;
+        /**
+         * #503 — the deployment's auto-mode SETTINGS GENERATION (a config revision, a settings hash, a
+         * publish id — the string is opaque to the engine). Recorded in the arming recipe and compared at
+         * rebuild time against the REDEEMING deployment's own: it is a declaration axis that can only make
+         * the rebuild stricter (see {@link import("./auto-mode-arming.js").foldAutoModeArming}). Absent =
+         * undeclared, which the fold treats as "cannot assume unchanged".
+         */
+        settingsEpoch?: string;
     };
     /**
      * design/129-B — PROCESS-level observer for background delegation children (Agent/Fork
@@ -6257,8 +7032,11 @@ export interface RunnerDeps {
      *   unrepaired transcript.
      * - `"suggestions"` — the best-effort follow-up-suggestions pass failed or timed out; the result
      *   simply carries no suggestions.
-     * - `"rewind"` — the per-turn working-tree snapshot backing file rewind failed or was skipped (e.g. a
-     *   too-large root inside its cooldown window); turns without a snapshot cannot be rewound to.
+     * - `"rewind"` — the file-history machinery backing rewind reported a best-effort failure: a
+     *   turn-start boundary capture failed or timed out (that turn cannot be rewound to; the turn
+     *   itself proceeds), or a first-touch failure was tolerated under
+     *   `onTrackFailure:"proceed-unprotected"`. (design/381: the whole-tree size gate and its
+     *   `classification:"too_large"` payload are retired — per-edited-file history has no size axis.)
      * - `"hook"` — a deployment hook misbehaved: a callback threw, or returned a verdict it was not
      *   allowed to (e.g. a declared-observational hook). The engine applies the hook's own documented
      *   fallback (swallow, or fail-closed deny, per its contract) and reports the fact here.