@sema-agent/core 7.6.0 → 7.6.2

package/dist/core/engine-notice.d.ts

@@ -0,0 +1,555 @@
+/**
+ * A structured operator-facing notice ({@link RunnerDeps.onNotice}) — a fact the engine announces that
+ * is neither an error nor part of the task result: today, a configured value that was discarded in
+ * favor of another (the loud-bad-value discipline's announcement dialect). Structured so a host can
+ * FORWARD it to its own user surface instead of losing it in process stderr.
+ */
+export interface EngineNotice {
+    /** Stable machine-readable family, dot-namespaced. Current families:
+     *  - `"config.autocompact_window_clamped"` (design/374 slice 1b) — a model declared
+     *    `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, 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
+     *    closed set in a seat where it is not in force; `detail: { raw, specStrategy? }`.
+     *  - `"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, 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?, 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, 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, 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?, runId? }` — `cause` is the refusal code
+     *    (`route.credential_mismatch` / `route.credential_missing`); `sessionId` (#433, additive)
+     *    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)
+     *    did not change: legal (a provider changing domains), but worth one loud line — if the
+     *    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,
+     *    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
+     *    once per `onNotice` SINK at the prepare station (the verifier lane would otherwise repeat it
+     *    every spawn; the sink — not the deps object — is the unit because the Runner rebuilds its
+     *    deps and `runTask` builds a Runner per call), unwired console arm once per process;
+     *    a library-direct `createHandsToolkit` mount announces at toolkit creation (one per mount,
+     *    through the band-local `HandsToolkitOptions.onNotice` seat, absent ⇒ `console.warn`);
+     *    `detail: { seat, declared, inForce, cause }`.
+     *  - `"config.tool_model_gate_removed"` (design/277) — the model gate trimmed default-mounted
+     *    scaffold entries from a task's roster. One notice per (model, class), de-duplicated once per
+     *    `onNotice` SINK on the (modelId, class, canonical sorted removed-name set) line (same unit
+     *    as `config.read_face_deployment_clamped`: two deployments hosted in one process each hear
+     *    their own trim; unwired console arm once per process) — same class with a different removal
+     *    shape is a distinct fact and announces again;
+     *    `detail: { modelId, gateClass, removed, restore }` (`restore` names the three valves).
+     *  - `"config.tool_model_gate_unknown_class"` (design/277) — a `ToolSpec.modelGate` tag names a
+     *    class the merged gate table has no row for: the tag is inert (fail-open — the tool stays
+     *    mounted) and this is its loud half (a tag typo must not silently become "never gated" with
+     *    nobody told). Once per `onNotice` sink per class (console arm once per process);
+     *    `detail: { gateClass }`.
+     *  - `"config.tool_model_gate_env_invalid"` (design/277, the NOTICE dialect of the same fact the
+     *    refusal code carries) — `SEMA_TOOL_MODEL_GATE` holds a value outside `on|1|true|off|0|false`
+     *    in a seat where it is NOT in force (nothing this prepare would gate): announced once per
+     *    `onNotice` sink per value (console arm once per process) instead of lying in wait; where the
+     *    value IS in force the prepare refuses with the same code as `TaskResult.errorCode` (one
+     *    fact, one code, two loudness dialects); `detail: { raw }`.
+     *  - `"config.durable_gate_unavailable"` — the per-principal `forceDurableGate` entitlement is in
+     *    force on a leg whose deployment wired NO checkpoint store. The entitlement is a mandate
+     *    ("every interactive ask of this principal gates durably"), and a mandate with no park
+     *    facility cannot be honored: no ask of the leg can suspend, so each one resolves on the LIVE
+     *    chain — a live approver / question face answers in-stream, and with none the ask is denied
+     *    fail-closed — and NO durable approval record is written. The ask routing itself is not
+     *    changed by the notice (a store-less leg never could park); the notice is the loud half of a
+     *    posture that used to degrade silently, disclosed before the first ask of the leg. Audience
+     *    `"user"` (the person whose asks will not be recorded is entitled to that; the operator hears
+     *    it through the sink as always). Once per prepared task leg — a resume or a delegated child
+     *    is its own leg and says so again; `detail: { sessionId, runId, principal?, cause, liveApprover,
+     *    liveQuestionFace }` — `cause` is `"no_deployment_store"` (the deployment wired none) or
+     *    `"task_store_disabled"` (`TaskSpec.checkpointStore: "disabled"`, the per-run off switch, on a leg
+     *    whose deployment may well have a store: the fix is the task's); `liveApprover` /
+     *    `liveQuestionFace`: whether a live seat will EFFECTIVELY answer the leg's permission asks /
+     *    questions in-stream (a delegated child under an inherited content mandate reads `false`
+     *    even with a face wired — the marker withholds the question), or the fail-closed deny will.
+     *
+     *  - `"task.user_steer_undrained"` / `"task.user_followup_undrained"` (#259) — user steers /
+     *    follow-ups whose receipts said "queued" were still in their queue at agent_end: the run
+     *    ended before any turn could drain them. One notice PER family (a consumer routing on `code`
+     *    alone must not mistake a stranded follow-up for a stranded steer — same split as the settled
+     *    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?, 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
+     *    settled at the run tail instead of at agent_end, because the tail first carries the still-
+     *    undelivered input onto the committed checkpoint's parked-steer queue (the resume delivers it)
+     *    — 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 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.
+     *        Fence tension (design/384 slice 2): this notice asserts THE CUT only — when the cut
+     *        raced a durable park whose commit was already in flight, the gate's durable leg may
+     *        still collect to `suspended` (park wins, row redeemable, no `haltedByUser`); the notice
+     *        stands beside that terminal without contradiction, because a seat really was cut.
+     *    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.
+     *
+     *  - `"task.halt_unconsumed"` (design/384 slice 1) — the user's stop verb ({@link TaskStream.halt})
+     *    was ANSWERED (not refused) while the run's ending was already owned by its own abort: nothing
+     *    was cut and nothing was stopped by the halt, the run's own ending stands, and the result will
+     *    NOT carry `haltedByUser` for it (the attribution seat never signs someone else's stop). This
+     *    notice is the halt's only trace on that arm — without it the verb receipt (`{turnCut:false}`)
+     *    was the sole record and the caller could not tell "my stop did nothing because the run beat
+     *    me to ending" from "my stop is being honored at the next boundary". Minted once per such verb
+     *    call (each arrival is a distinct fact); `detail: { sessionId, runId, taskId? }` — `runId` is
+     *    the run whose ending the halt failed to claim. Audience `"user"` (the person who pressed
+     *    stop). A REFUSED halt (typed `steering.not_running` throw) mints nothing: the refusal itself
+     *    is the loud answer.
+     *
+     *  - `"task.late_approval"` (design/384 slice 1) — a synchronous ask approval was NOT CONSUMED:
+     *    a run or turn interrupt released the wait (the `resolveAsk` race arm detached the approver's
+     *    promise; an unconsumed resolve is the approver releasing its wait, never a verdict), so the
+     *    tool did NOT run and the approval was not honored. The notice asserts non-consumption ONLY —
+     *    never an arrival order: an approval and an abort settling close together read as the abort
+     *    (the resolver's documented one-directional residual — the engine never claims a person
+     *    decided something it cannot show they did, and it equally never claims which came first).
+     *    Minted only for a value that reads as an APPROVAL — an unconsumed
+     *    deny/refusal is an ordinary release and leaves no trace, and an unconsumed REJECTION goes to
+     *    `onError(phase:"hook")` instead (a failing callback, not an answer). One notice per
+     *    unconsumed approval; `detail: { toolName, toolCallId, sessionId, runId, taskId? }`. Audience `"user"`
+     *    (whoever answered the card is the one entitled to hear the answer ran nothing); a host may
+     *    forward it on its own wire.
+     *
+     *  - `"classifier.denial_limit"` (#548, CC 2.1.250 `FO`/"too many classifier denials in headless
+     *    mode") — the auto-mode classifier's DENIAL LIMIT was reached (3 consecutive blocks, or 20 in the
+     *    run; `RunnerDeps.autoMode.denialLimit`) and the fallback ask it turns into had NO approver to go
+     *    to: none wired, a blanket `onAsk:"allow"` (refused for a real-approval ask), or an approver that
+     *    reported unavailable with no durable park to take it. The run was STOPPED — `TaskResult.status`
+     *    `"failed"`, `errorCode` the same code, `errorMessage` the limit sentence — rather than kept
+     *    spending on a model the classifier denies without end; the triggering call's own result is the
+     *    deny that stood. Once per run (the first headless fallback owns the terminal);
+     *    `detail: { sessionId, runId, toolName, toolCallId, consecutive, total, limit }` — `limit` is
+     *    `"consecutive"` | `"total"`, the bound that tripped. Audience `"user"` (the person whose run
+     *    ended is the one entitled to hear why, and to review the transcript the sentence points at).
+     *    With an approver wired the same bound mints NO notice — the fallback ask reaches the person
+     *    instead (`AskRequest.denialLimitFallback`).
+     *
+     *  - `"steering.parked_input_blocked"` (design/373 §4.3) — a PARKED steer entry was withheld when
+     *    a resume redelivered it (any resume kind that drains parked steers — wake included) by the
+     *    deployment's `userPromptSubmit` screen (block verdict, or a fail-closed non-answer/crash):
+     *    the row was consumed with the checkpoint, the frame never reached the model, and the resume
+     *    itself proceeds (a blocked instruction must never wedge a wake). The lifecycle half of the
+     *    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, 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
+     *    as an external content source was invoked, directly or through a delegated child). Under
+     *    `memoryProvenance: "carry"` (default) the message states the tag-admit semantics (ordinary
+     *    writes commit with an origin marker; instruction-form files are withheld); under `"off"` it
+     *    keeps the pre-336 sentence — writes no longer eligible for the long-term library. The
+     *    notice states that VERDICT plus what a harvest does when it collects — it does
+     *    not promise quarantine, because a `writeScope`-null layering and a declared-unavailable
+     *    session both reach the zero-admission harvest arm (nothing collected ⇒ nothing captured), and
+     *    a mark landing after the pre-commit pollution read leaves already-committed rows to the
+     *    challenge sweep; what a harvest actually contained is the other code below. The challenge
+     *    clause is a policy statement, not a receipt — a sweep that cannot run announces
+     *    `"memory.challenge_sweep_failed"` on the engine's incident seat. Announced ONCE PER
+     *    SESSION, at the mark seat: a repeat mark inside the process and a resumed session whose
+     *    durable marker already exists stay quiet (the state is one-way, so a second line would carry
+     *    no new fact); a pollution state that cannot be read announces rather than assuming it was
+     *    already said. `detail: { reason, sessionId? }` — `reason` names the invoked tool and is
+     *    neutralized/length-bounded (the name comes from the host/protocol roster).
+     *  - `"memory.harvest_quarantined"` (design/178 §3, #324a) — a polluted session's harvest ran its
+     *    containment: `count` ENTRY files written or changed in the session were withheld from the
+     *    library, `moved` of them were physically moved into the control-plane quarantine directory,
+     *    and `escalated` of them carry a `HarvestReport.quarantineFailures` row (a failed capture, a
+     *    failed removal, or a file tombstoned in place — which counts as moved AND escalated, so the
+     *    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,
+     *    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
+     *    count>0 condition (and its silence on index-only containment) is kept byte-level.
+     *  - `"memory.hold_opened"` / `"memory.hold_released"` / `"memory.hold_disposed"` (design/336
+     *    §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, 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`, 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). `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
+     *    missing/unknown + face can reach external content) was not marked: the waiver is announced —
+     *    the explicit dual of `"memory.session_polluted"` for this arm, so the arm has a voice where a
+     *    mark used to land. MINT-side guarantee only: delivery rides the shared guarded form
+     *    ({@link deliverEngineNotice} — a wired sink that throws owns that loss, exactly as at every
+     *    de-duplicating station), and the leg latch is consumed at mint. Minted only when a pollution
+     *    face is mounted (a
+     *    recorder-only child's mark is a no-op — nothing is waived there), at most ONCE PER PREPARED
+     *    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?, 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
+     *    {@link McpServerSpec.contentOrigin}: the deployment declared this server's whole tool set to
+     *    be inside (or explicitly outside) its trust boundary, so the protocol namespace's structural
+     *    `"external"` no longer decides. The AUDIT line for a trust boundary an operator drew by
+     *    configuration — which is why it announces on the explicit `"external"` value too: pinning is
+     *    not a no-op (a declaration beats the `trustedTools` allowlist, so it forecloses the per-name
+     *    exemption for this server's tools). One line per DECLARED ENTRY per prepared task leg, minted
+     *    once at preparation and never per call (the declaration's whole effect is that calls stop
+     *    marking; narrating each call would trade the saved mark for equal noise). Armed on the SAME
+     *    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?, 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
+     *    knob AS RESOLVED FOR THIS RUN, because that arm's posture depends on it. The message's closing
+     *    clause is written per value so it can never describe a posture the run does not have. The
+     *    entry's TRANSPORT is deliberately absent: it is a claim about a mutable host-owned object made
+     *    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` —
+     *    it never crosses {@link deliverEngineNotice}, is deliberately absent from
+     *    {@link ENGINE_NOTICE_CODES}/{@link NOTICE_AUDIENCE}, and sits in the non-governance
+     *    disposition table with the error dispositions. The loser MUST NOT retry into the winner's
+     *    account. A consumer diffing its own table against the catalog must not add a row for it.
+     *
+     *  - `"config.peer_admission_out_of_range"` (#551) — a `RunnerDeps.peerAdmission` field the
+     *    resolver could not use: outside its legal range, or not a finite number at all (a string off
+     *    an untyped host's wiring, `NaN`, `Infinity`). THAT FIELD falls back to its own default (never
+     *    a clamp to the nearest edge, never a whole-config reject) and every other field is unaffected.
+     *    One notice PER FIELD — two bad fields in one config are two notices — deduped per SINK on
+     *    `(field, given)` rather than per call (the resolver runs on every SendMessage and every drain
+     *    round; the fact is about the wiring, not about the call). Per SINK, not per process: two
+     *    Runners in one process each own an `onNotice`, and a process-global ledger would deliver the
+     *    fact to whichever resolved first and leave the other silently without its own disclosure. The
+     *    unwired arm (no `onNotice`: the shared `console.warn` throat) latches per process instead —
+     *    the console IS one process-wide channel. `detail: { field, given, default,
+     *    range: [lo, hi], reason }`, where `reason` is `"out_of_range" | "not_a_finite_number"`.
+     *    Audience `"operator"` (a configuration fact; the fix is the deployment's).
+     *  - `"config.peer_lane_unmounted"` (design/385 §1.2⑥) — `RunnerDeps.peerDirectory` is wired but
+     *    the cross-session lane could not mount on this leg: no `mailboxStore`, or one that does not
+     *    declare `crossProcessSafe: true` (several terminals would share one session box on luck). The
+     *    seat is inert for the run (no ListAgents, peer addresses refuse with the same reason). Once per
+     *    prepared leg; `detail: { reason, code, mailboxWired, sessionId, runId }`. Audience `"operator"`
+     *    (a wiring fact; the fix is the deployment's).
+     *  - `"peer.inbound_disposition"` (design/385 §1.2④ / §4.6 / §4.4) — a message parked in THIS
+     *    session's own box was settled at the drain WITHOUT reaching the model. `detail.disposition` is
+     *    the arm (closed set `PeerInboundDisposition`): `"refused"` (this session's `crossSessionInbound`
+     *    setting, or a record whose typed fields cannot be rendered canonically), `"admission_refused"`
+     *    (the drain-stage admission re-check: duplicate / hop loop / runaway — `cause` names it),
+     *    `"notice_unrouted"` (a notice-kind record the notice face cannot render — no typed `notice`, or
+     *    a state that does not fit its kind — settled without delivery, never ridden through the
+     *    peer-message envelope), `"notice_user_only"` (a delivery receipt / idle notice whose sender this
+     *    session's parity would HOLD: surfaced here for the user, not read by the model — CC's
+     *    `modelVisible:false` arm; `cause` carries the rendered notice text), or `"held"` — the parity
+     *    judgment held it: the message ENTERED this session's process-level held queue and was acked
+     *    from the box (later messages are not blocked behind it), where it is re-judged at every
+     *    boundary, released or refused with a receipt, and expires WITH a receipt under `dialogExpiry`
+     *    (see `peer.held_settled`); `cause` is a `PeerInboundHoldCause` — the parity causes, or the
+     *    drain gate's TRANSIENT `rate_limited` (that one does NOT enter the queue: the message stays in
+     *    the box and the drain stops at its seq until the bucket refills). Disclosed once per seq per leg,
+     *    and again when a re-judgment moves a held entry's cause. `detail: { disposition, cause, seq, box,
+     *    fromSession?, sessionId, runId }`. Audience `"user"`: the session's user is the one who did
+     *    not receive it.
+     *  - `"peer.held_settled"` (design/385 §4.4, slice 4) — a message left THIS session's held queue.
+     *    `detail.settlement` names how: `"delivered"` (a re-judgment or an approval released it into
+     *    this session's model context), `"refused"` (the setting moved to refuse, or an approval met a
+     *    refusing policy), `"expired"` (the `dialogExpiry` deadline, an eviction when the 100-entry queue
+     *    was full, a cancelled review, or a graceful shutdown), `"denied"` (the review face), `"dropped"`
+     *    (the injection lane refused the released frame). `detail.reason` is the trigger
+     *    (`deadline | evicted | shutdown | rejudge | approved | denied | cancelled | inject_failed`); the
+     *    sender was sent the matching receipt whenever the record carried a reply address.
+     *    `detail: { settlement, reason, seq, box, fromSession?, heldCount, sessionId, runId }`. Audience
+     *    `"user"`: it is this session's user who held (or was holding) the message.
+     *  - `"peer.idle_subscription"` (design/385 §5.2, slice 4) — a peer session asked to be told when
+     *    THIS session next goes idle (`SendMessage … notify_when_idle`). `detail.outcome`: `"recorded"`
+     *    / `"refreshed"` (a same-requester re-ask; the subscription is one-shot and expires unfired after
+     *    12 h), `"full"` (the 32-entry table is full) or `"refused"` (this session's `crossSessionInbound`
+     *    is `refuse`) — the last two answered the requester with an `unavailable` notice. `detail:
+     *    { outcome, fromSession, live, seq, box, sessionId, runId }`. Audience `"user"`: the person whose
+     *    session is being watched is the one entitled to know (CC announces it in the session UI).
+     *
+     *  - `"delegation.transcript_integrity"` (subagent transcript persistence) — a durable agent row
+     *    with a BOUND transcript sessionId met a session store that attests `not_found` for it: the
+     *    deployment's declared transcript durability is being contradicted by reality. Announced at
+     *    most once per (scope, handle, process) — `detail: { handle, scope? }`, scope = the resolved
+     *    access scope of the read that found the gap — from the continuation read faces (SendMessage preflight /
+     *    AgentTranscript's durable leg); the per-call honest refusals are unchanged, and the declared
+     *    tier is NOT auto-downgraded (declaration-制 — observation reports, it never re-adjudicates).
+     *
+     *  - `"memory.consolidation_recommended"` (design/339 §2.2/§6.2) — the engine-minted per-scope
+     *    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, 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 }` —
+     *    counts and engine-minted ids only, zero content.
+     *  - `"memory.consolidation_conflict"` (design/339 §6.2) — a plan parked CONFLICT: at least one
+     *    target did not reach its planned state (a concurrent write, a patch the store declined, or a
+     *    target the re-judgment could no longer act on — the plan's audit rows carry the per-target
+     *    reason). The REFUSED targets were not overwritten; patches the plan had already applied
+     *    stand (discard rolls nothing back — the receipt's applied-vs-conflict counts say how many).
+     *    Affected intents stay pending and wait for the host valve
+     *    (`resolveConsolidationPlan` retry/discard); `detail: { planId, scope }`.
+     *  - `"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?, 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
+     *  frequency semantics and ride the wire `status` channel ({@link BrainStatus}), whose sink the
+     *  Runner establishes unconditionally around every brain-driving call — no host seat to wire, no
+     *  console fallback to flood. A reader looking for retry disclosure should look there, not here. */
+    code: string;
+    /** The exact human-readable line the unwired build prints via `console.warn` — same words, one text. */
+    message: string;
+    /** Machine-readable facts of the notice (knob names, arriving values, values in force). */
+    detail?: Record<string, unknown>;
+    /** The owning session, when the notice HAS one — an ATTRIBUTION/correlation key, never a
+     *  projection permission: whether a notice may be surfaced onto that session's user-facing
+     *  stream is decided by the code's {@link NOTICE_AUDIENCE} row alone ("audience is entitlement,
+     *  not routability" — several `"operator"` rows carry a sessionId purely for correlation, and a
+     *  projector keying on presence would push deployment facts at end users). Presence only makes
+     *  routing structurally POSSIBLE; a session-less code structurally cannot be routed at all.
+     *  Mint sites do not set this: {@link deliverEngineNotice} — the ONE delivery throat — lifts a
+     *  string `detail.sessionId` here, so the typed key and the detail carriage can never disagree.
+     *  Optional and absent for process/config-scoped codes. */
+    sessionId?: string;
+}
+/** Test seam (mirrors `__resetBashTimeoutAnnouncements`): never called by production code. */
+export declare function __resetMalformedNoticeSeatAnnouncement(): void;
+/**
+ * The ONE delivery form behind every {@link RunnerDeps.onNotice} emission point (#170: the form was
+ * triplicated across the emission stations, and every copy judged the seat with `!== undefined` — so a
+ * PRESENT non-function seat (null, a config typo, an untyped host's JSON wiring) entered the wired arm,
+ * threw `TypeError` on the call, and the swallow guard silenced BOTH channels at once). Contract:
+ *  · a FUNCTION seat REPLACES the console line (a host forwarding notices to its own surface must not
+ *    show every fact twice), swallow-guarded against both failure shapes the void-typed seat admits —
+ *    a synchronous throw and an async sink's rejected promise (unhandled, that rejection is a
+ *    process-level fault): a notice sink must never turn an announcement into a failure. Deliberately
+ *    NO console fallback on sink failure: loudness ownership transfers with the wiring, and a console
+ *    echo of a transient sink failure would double-send the fact. Corollary kept as-is: stations that
+ *    de-duplicate ledger the line BEFORE this call, so a true-function sink that throws can in
+ *    principle lose a ledgered line for the process lifetime — un-ledgering after the fact would race
+ *    an async sink's late rejection and re-announce (double-send) on transient failures.
+ *  · a PRESENT NON-function seat is a bad deployment value, and #123 (loud-bad-value law) forbids
+ *    folding it to silence: the notice itself falls back to `console.warn` (no line is lost), and the
+ *    seat defect — the one fact every fallback would otherwise repeat — is announced once per process.
+ *  · an ABSENT seat prints the historic `console.warn` line verbatim (byte-compat loudness).
+ */
+export declare function deliverEngineNotice(onNotice: ((notice: EngineNotice) => void) | undefined, notice: EngineNotice): void;
+/**
+ * #259 loud half, one notice PER FAMILY (`task.user_steer_undrained` / `task.user_followup_undrained`):
+ * a consumer routing on `code` alone must never mistake a stranded follow-up for a stranded steer, so
+ * the code carries exactly the semantics its name claims — the same two-key split the settled frame
+ * uses. Pure (the terminal sweep race window is not constructible deterministically; this seam is).
+ *
+ * `sessionId` (#433, additive and optional): these two codes are the `"user"` audience rows whose
+ * subject is the END USER's own lost input, and a disclosure that cannot say WHICH session lost it
+ * has nowhere to be delivered — the audience registry and the routing key are the two halves of one
+ * answer. Carried in `detail` like every other session-attributed code, so {@link deliverEngineNotice}
+ * — 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, runId?: string): EngineNotice[];

package/dist/core/engine-notice.js

@@ -0,0 +1,55 @@
+let malformedNoticeSeatAnnounced = false;
+export function __resetMalformedNoticeSeatAnnouncement() {
+    malformedNoticeSeatAnnounced = false;
+}
+export function deliverEngineNotice(onNotice, notice) {
+    if (notice.sessionId === undefined && typeof notice.detail?.["sessionId"] === "string") {
+        notice = { ...notice, sessionId: notice.detail["sessionId"] };
+    }
+    if (typeof onNotice === "function") {
+        try {
+            const r = onNotice(notice);
+            if (typeof r?.then === "function") {
+                r.then(undefined, () => {
+                });
+            }
+        }
+        catch {
+        }
+        return;
+    }
+    if (onNotice !== undefined) {
+        if (!malformedNoticeSeatAnnounced) {
+            malformedNoticeSeatAnnounced = true;
+            try {
+                console.warn(`The structured notice sink (RunnerDeps.onNotice) holds ${onNotice === null ? "null" : typeof onNotice} — not a ` +
+                    `function. Notices fall back to console.warn until the wiring is fixed (omit the key, or wire a function).`);
+            }
+            catch {
+            }
+        }
+    }
+    console.warn(notice.message);
+}
+export function undrainedUserInputNotices(counts, taskId, sessionId, runId) {
+    const tid = taskId !== undefined ? { taskId } : {};
+    const sid = sessionId !== undefined ? { sessionId } : {};
+    const rid = runId !== undefined ? { runId } : {};
+    const tail = `accepted as "queued" were never consumed — the run ended first. They are NOT redelivered; re-send against a live run if still wanted.`;
+    const out = [];
+    if (counts.steer > 0) {
+        out.push({
+            code: "task.user_steer_undrained",
+            message: `${counts.steer} user steer(s) ${tail}`,
+            detail: { steer: counts.steer, ...tid, ...sid, ...rid },
+        });
+    }
+    if (counts.followUp > 0) {
+        out.push({
+            code: "task.user_followup_undrained",
+            message: `${counts.followUp} user follow-up(s) ${tail}`,
+            detail: { followUp: counts.followUp, ...tid, ...sid, ...rid },
+        });
+    }
+    return out;
+}