@sema-agent/core 5.60.1 → 5.62.0

package/dist/core/types.d.ts

@@ -1032,7 +1032,7 @@ export interface ToolExecuteContext {
      * is a DISPLAY channel ONLY — the child stream is NEVER merged into the parent's MODEL context, and nothing
      * security-relevant consumes a forwarded event. Present ONLY when the deployment opted in. The tool-ctx wrapper
      * passes `task_progress` unconditionally and — when the deployment sets `forwardSubagentEvents: true` — the
-     * transcript classes too (text_delta/reasoning_delta/tool_start/tool_end); other event types never cross it.
+     * transcript classes too (text_delta/text_end/reasoning_delta/tool_start/tool_end); other event types never cross it.
      * The delegation lane's OWN tap is trusted and forwards the child's FULL event stream (bg frames tagged
      * with bgAgentId). ⚠️ Forwarded ticks are UNTRUSTED display hints — any
      * tool holding this ctx could self-declare one, so a consumer validates `parentTaskId` against its known runs.
@@ -2543,7 +2543,7 @@ export interface TaskSpec {
     /**
      * Subagent viewing pane (dogfood finding 2026-07-03): widen the opt-in display sink
      * (`RunInternals.onForwardEvent`) from `task_progress`-only to a SUBAGENT's live CONTENT events
-     * (`text_delta` / `reasoning_delta` / `tool_start` / `tool_end`), so a UI can render a delegated
+     * (`text_delta` / `text_end` (#447) / `reasoning_delta` / `tool_start` / `tool_end`), so a UI can render a delegated
      * child's transcript live. Default OFF (progress-only, prior behavior). The child stream is still
      * NEVER merged into the parent's model context — this is purely a render channel; forwarded events
      * carry `parentToolCallId` (attribution) and the same UNTRUSTED-RAW contract as the main stream's
@@ -2823,6 +2823,51 @@ export interface TaskSpec {
          * that judgment shaped the DEFAULT-OFF posture; an opted-in deployment chooses CC parity.
          */
         budgetUsd?: true;
+        /**
+         * RB-318 (ruled 2026-08-26) — `total_tokens_reminder` (CC 2.1.245 producer `MPs`, renderer `Oje`):
+         * the TOKEN twin of {@link budgetUsd}. One line per collected boundary,
+         * `<total_tokens>N tokens left</total_tokens>`, CC-verbatim bytes.
+         *
+         * Activation, CC-exact in shape and BYOM-honest in substance: opted in here AND — for the two
+         * COUNTDOWN arms — the task carries a token ceiling (`limits.maxTokens`, or a resource-slice
+         * allocation's remainder). No ceiling ⇒ permanently silent, because core does not know and will not
+         * guess your model's context window: the number it publishes is the one it already ENFORCES
+         * (`stats.tokens` against that ceiling), so the readout can never disagree with an eventual
+         * `limits.max_tokens_exceeded`. The two CONSTANT arms (`infinite` / `fixed`) read no measurement at
+         * all and need no ceiling.
+         *
+         * Cadence, CC-exact: no threshold ladder and no throttle — every collected boundary carries it, and
+         * the "progression" is the numbers advancing with spend. Recorded deviation (shared with
+         * {@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).
+         */
+        totalTokensReminder?: true;
+        /**
+         * 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"`.
+         *
+         *  - `countdown` — remaining = ceiling − spend, raw.
+         *  - `padded-countdown` — the same, through a monotone floor, so the number NEVER JUMPS BACK
+         *    within one engine leg (CC's per-agent smoothing floor; ONE `runTask` invocation is the
+         *    epoch). A durable-resume leg is a NEW epoch by design: the slice window, the spend
+         *    coordinate and the floor all restart, so the resumed leg's readout RE-ANCHORS to its own
+         *    real remaining — which may sit above the prior leg's last readout (the fresh slice window
+         *    is a genuine new allowance; CC's own re-anchor arm counts a new task epoch down from the
+         *    full budget again). Carrying the floor across legs would publish "0 tokens left" against a
+         *    window the run genuinely still holds — a frozen falsehood, deliberately not done.
+         *  - `off` — silences the lane while leaving it wired, for a deployment that resolves the mode from
+         *    its own env/settings the way CC does (core reads no env).
+         *  - `infinite` / `fixed` — CC's two constant arms: the literal `Infinite`, and the constant
+         *    5000000. They publish no measurement (that is what they are for) and need no ceiling.
+         *
+         * A value outside the set is REFUSED at prepare (`config.attachment_invalid`), never folded to the
+         * default — a near-miss spelling must not silently publish a different readout than the one asked for.
+         */
+        totalTokensReminderMode?: "off" | "infinite" | "fixed" | "countdown" | "padded-countdown";
         /** Post-compact background-task restatement — DEFAULT ON since 5.12.0 (boolean, not `true`:
          *  explicit `false` is the opt-out; same contract as the listing family below). CC hard-codes
          *  this behavior, and the opt-in default left every non-shell host (server-driven runs) with a
@@ -3123,8 +3168,10 @@ export interface TaskResult {
      *
      * 1.37+ terminal codes use a **dotted namespace** so a caller can prefix-match a whole class:
      * `"limits.max_tokens_exceeded"` / `"limits.max_cost_exceeded"` / `"limits.max_turns_exceeded"` /
-     * `"limits.max_walltime_exceeded"` / `"config.limit_invalid"` / `"config.limit_unknown_key"`
-     * (e.g. `errorCode.startsWith("limits.")`). 1.36 brain codes (`auth`/`network`/`rate_limit`/…)
+     * `"limits.max_walltime_exceeded"` / `"config.limit_invalid"` / `"config.limit_unknown_key"` /
+     * `"config.attachment_invalid"` (RB-318 — a mode-valued `TaskSpec.attachments` member outside its
+     * closed set, refused at the same door as the limits; e.g. a near-miss `totalTokensReminderMode`
+     * spelling) (e.g. `errorCode.startsWith("limits.")`). 1.36 brain codes (`auth`/`network`/`rate_limit`/…)
      * and `"conflict"` remain flat (unchanged, to avoid breaking existing consumers).
      *
      * design/164 件四/件五 added two codes for the EXTERNAL stop causes — neither is a `limits.` code,
@@ -3137,6 +3184,14 @@ export interface TaskResult {
      *   the wait hint rides the thrown error's `retryAfterMs` (delivered through `RunnerDeps.onError`) and
      *   the message text. Retrying before the window frees will be refused again.
      * Their config-time siblings are `"config.env_lifetime_invalid"` / `"config.usage_window_invalid"`.
+     * A governance window with a MONEY ceiling adds two more, both of which say "the ceiling could not be
+     * evaluated" rather than "the ceiling was reached" — neither is retryable without a config change:
+     * - `"config.usage_window_unpriced"` — a `UsageWindow.maxCostUsd` over a run with no cost figure (no
+     *   `RunnerDeps.pricing` entry and no `Model.cost`). Raised at the door for the run's own model, and at
+     *   the accounting point when a mid-run model switch loses the price table.
+     * - `"usage_window.store_cost_unanswered"` — the wired ledger does not carry the money arm: it either
+     *   dropped the cost supplied to a charge, or answered a $ window without the cost it holds. Both mean
+     *   the ceiling was never evaluated (typically a store or decorator that predates the cost arm).
      */
     errorCode?: string;
     /**
@@ -3446,7 +3501,8 @@ export interface TaskResult {
              *  · `defused` (an MCP/web segment's exact-mark bytes were rewritten — the lane's one sanctioned
              *    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`; `scope` is
+             *    subset is `task-notification` / `new-diagnostics` / `user_memory` / `skills` /
+             *    `total_tokens`; `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
@@ -3670,8 +3726,15 @@ export interface ToolActivity {
 export type HumanInputSource = "objective" | "steer" | "next_turn" | "wake" | "external" | "system";
 /** design/171 §6.2 — how a human input was disposed of when its event was emitted:
  *  `"applied"` = delivered into a model turn; `"queued"` = accepted, awaiting the next turn
- *  boundary; `"parked_for_wake"` = parked for the session's next run (torn-down lane). */
-export type HumanInputDelivery = "applied" | "queued" | "parked_for_wake";
+ *  boundary; `"parked_for_wake"` = parked for the session's next run (torn-down lane);
+ *  `"blocked"` (design/373 §4.3, additive — closed-set add, consumers named in the ship post) =
+ *  a PARKED entry was withheld at resume redelivery — the screen runs on EVERY resume kind that
+ *  drains parked steers (policy_ask / dry_run_review / plan_review / resource_limit, wake
+ *  included) — by the deployment's `userPromptSubmit` screen (block verdict, or a fail-closed
+ *  non-answer/crash): the row was consumed, the frame never reached the model, and the sibling
+ *  `steering.parked_input_blocked` notice names the same inputId — "park 时收下、redeliver 时被筛"
+ *  is auditable, never a silent disappearance. */
+export type HumanInputDelivery = "applied" | "queued" | "parked_for_wake" | "blocked";
 /**
  * The fleet-task kinds a DELEGATED run can honestly claim, derived from (never a second spelling of)
  * {@link TaskNotificationPayload}'s `task_type` vocabulary — the same axis a consumer already keys
@@ -3684,6 +3747,32 @@ export type DelegationTaskType = Extract<TaskNotificationPayload["task_type"], "
 export type TaskEvent = ({
     type: "text_delta";
     delta: string;
+} & TaskEventIdentity) | ({
+    /**
+     * #447 — the assistant's streaming PROSE SEGMENT is COMPLETE: the model closed the text content
+     * block whose bytes just streamed as `text_delta`s. This is the explicit segment boundary a
+     * REMOTE consumer needs so it never has to guess segment ends from wire silence (the idle-flush
+     * heuristic this retires cut one slow-model reply into N fragments). CC-aligned: CC's agent
+     * stream yields each finished content block as its own assistant-message unit at the provider's
+     * `content_block_stop` — block completion IS the segmentation signal there; a single-process
+     * consumer reads it off the provider stream natively, and this event is that same boundary
+     * surfaced on the TaskEvent wire (CC pays the byte cost of re-carrying the block at the stop;
+     * so does this event's `content`).
+     *
+     * `content` = the authoritative FULL text of the completed segment (byte-equal to that
+     * segment's accumulated deltas, from the brain's own accumulation) — a consumer commits the
+     * segment from it instead of trusting its own delta stitching. UNTRUSTED model output for
+     * display only, same contract as `text_delta`. Emitted only for a segment that holds bytes: an
+     * empty text block closes silently (a boundary with no segment would render phantom rows).
+     *
+     * Additive + ignorable. HONEST ABSENCE: the frame exists only when the serving Brain reports
+     * block ends (`text_end` on its event stream — all three first-party brains do; a custom brain
+     * that never emits them yields a wire without this frame). A consumer treats per-segment
+     * presence as the signal and falls back to its own heuristic only on streams that carry none —
+     * absence is "unreported", never "the segment did not end".
+     */
+    type: "text_end";
+    content: string;
 } & TaskEventIdentity) | ({
     type: "reasoning_delta";
     delta: string;
@@ -4064,7 +4153,7 @@ export type TaskEvent = ({
      * repo-controlled and must not enter the event telemetry plane through this echo.
      */
     type: "steering_injected";
-    source: "limit_approach" | "todo_reminder" | "task_reminder" | "tool_search_usage_reminder" | "changed_files" | "plan_mode" | "date_change" | "instructions_change" | "workflow_size_guideline_change" | "budget_usd" | "background_tasks" | "tools_delta" | "agent_listing" | "skills_listing" | "mcp_instructions" | "mcp_dropped_tools" | "final_verification" | "git_status";
+    source: "limit_approach" | "todo_reminder" | "task_reminder" | "tool_search_usage_reminder" | "changed_files" | "plan_mode" | "date_change" | "instructions_change" | "workflow_size_guideline_change" | "budget_usd" | "total_tokens_reminder" | "background_tasks" | "tools_delta" | "agent_listing" | "skills_listing" | "mcp_instructions" | "mcp_dropped_tools" | "final_verification" | "git_status";
     preview: string;
 } & TaskEventIdentity) | ({
     /**
@@ -4177,6 +4266,12 @@ export type TaskEvent = ({
      */
     type: "task_notification";
     notification: TaskNotificationPayload;
+    /** design/373 §3.6 — the frame's injection tier as DELIVERED (additive; consumers tolerate
+     *  absence): on the live lane, the tier the routing used (`next`/`now` → steer lane, `later`
+     *  → followUp lane); on the turn-open redelivery lane, the tier the park CARRIED. ABSENT is a
+     *  fact, not a default: a pre-373 producer event, or a parked record whose tier was not
+     *  carried (the terminal sweep's re-pend) — never read absence as `"later"`. */
+    priority?: import("./task-notification.js").SystemInjectionPriority;
 } & TaskEventIdentity) | ({
     /**
      * design/99 MF-10 — a SUBAGENT PROGRESS TICK: the delegated sub-run's usage ACCRUING
@@ -4380,11 +4475,60 @@ export interface TaskStream extends AsyncIterable<TaskEvent> {
      *    into this run's resume prompt) is NOT in it and WOULD inject again. A deployment that needs
      *    cross-leg or cross-process idempotency owns that half (its own key ledger), the same division
      *    of labor `notify`'s park-window dedup states.
+     *
+     * design/373 (additive) — `priority` is the steer face's injection tier, default `"next"`
+     * (= the pre-373 behavior, byte-identical):
+     *  - `"next"` — the running turn's next boundary (unchanged);
+     *  - `"later"` — never folded into work in progress: delivered at the run's natural
+     *    would-otherwise-stop seat (its own closing turn); a run that ends before that seat re-parks
+     *    the input via the existing durable/undrained lanes (receipt semantics unchanged — "queued"
+     *    still means accepted-at-this-moment, never "consumed"); a `"later"` steer rides the followUp
+     *    lane, so its stranded account is `task.user_followup_undrained` (the accounts are LANE-keyed
+     *    — same two-key split the settled frame uses);
+     *  - `"now"` — `"next"`'s delivery guarantee PLUS the boundary is manufactured early: the frame
+     *    takes the queue's class head and, when a turn is in flight, the engine CUTS that turn at a
+     *    reconciled boundary (finished tool calls keep their real results; never-started ones settle
+     *    as paired interrupted results; the CC-verbatim interruption marker lands) and the run
+     *    CONTINUES with this input — never the run-level `interrupt()`. Best-effort accelerator:
+     *    with nothing in flight (idle tail, between turns) delivery is exactly `"next"`'s. Every
+     *    real cut is announced (`task.turn_interrupted` notice) and counts toward `maxTurns` —
+     *    deliberately (the hard cap IS the interrupt storm's bound), which means a `now` issued at
+     *    the run's FINAL allowed turn spends the remaining budget on the cut and the run then ends
+     *    at the limit before the steer's own turn: the input takes the terminal lanes like any
+     *    accepted-but-undelivered steer (durable park when a resource-suspend seat is eligible —
+     *    redeemed on resume; otherwise the loud `task.user_steer_undrained` account). Same for the
+     *    other terminal gates (budget/walltime) firing at the cut's own `turn_end`. The receipt
+     *    never promised consumption; no budget is reserved for the interruptor.
+     *  ⚠️ POWER FACE (§5-4b): passing `priority` through to a third-party caller GRANTS it the power
+     *    to cut this run's in-flight turns (cancelling that turn's in-flight tool work). A deployment
+     *    relaying steer must gate this option at its own face — relay IS authorization.
+     *  An unknown value throws typed `steering.invalid_content` (bad-value loudness). The replay
+     *  identity (`inputId` idempotency) includes the NORMALIZED tier: the same text replayed under
+     *  the same id at a different tier refuses `steering.duplicate_input_id` — an "idempotent
+     *  success" that silently skipped the interrupt would be a disposition lie.
+     *
+     * design/373 §4.3 (D2, ruling of 2026-08-24) — a deployment `userPromptSubmit` hook SCREENS this verb:
+     * the steer face is a SERVICE entrance (third-party callers reach a running run through it), so
+     * the deployment's prompt filter sits at the entrance, `ctx.source:"steer"` + `ctx.inputId` +
+     * `ctx.actor` discriminated. Chain position: domain validation → liveness → `inputId` replay
+     * short-circuit → screen → accept/enqueue → (now) interrupt — an idempotent replay of an ACCEPTED
+     * id answers success WITHOUT re-running the hook (a re-run could answer differently and
+     * retro-falsify the standing receipt). Hook `block` ⇒ **typed throw `steering.blocked_by_hook`**
+     * (message carries the hook's own bounded reason); a hook timeout / cancellation / crash refuses
+     * with the SAME code, fail-closed (a screen that did not answer has not cleared the input —
+     * message discriminates the cause; the crash also reaches `onError` phase:"hook"). A blocked call
+     * was never accepted: no `human_input` frame, no undrained account, and the `inputId` stays
+     * UNBOOKED (retry freely, changed content included). `additionalContext` ⇒ prepended to the
+     * delivered frame as the engine's own reminder (never inside the untrusted mid-turn frame). The
+     * replay identity is over the CALLER's bytes — hook output never enters it. Engine-authored
+     * frames (task notifications, diagnostics) and external `notify()` text are OUT of the screen's
+     * domain (notifications are sanitized DATA, not prompts — the notify contract's ruling).
      */
     steer(text: string, options?: {
         trusted?: boolean;
         actor?: ActorAssertion;
         inputId?: string;
+        priority?: import("./task-notification.js").SystemInjectionPriority;
     }): Promise<void>;
     /**
      * design/144 §2 — inject an EXTERNAL structured event into this run's task-notification lane, as a
@@ -4392,19 +4536,37 @@ export interface TaskStream extends AsyncIterable<TaskEvent> {
      * the payload (`task_type` is cast to `"external"` — a caller can never impersonate an internal lane)
      * and every field is sanitized as UNTRUSTED data on the model face. Delivery rides the EXISTING
      * notification machinery, so the semantics are identical to internal producers:
-     *  - every priority is injected at the NEXT turn boundary (steer lane, mid-work included; ruled
-     *    2026-08-05 — the retired `"later"`→followUp mapping starved a busy run of its completions).
-     *    Delivery order is ARRIVAL order; consecutive buffered notifications drain as one boundary
-     *    batch. `priority` still rides the park/uplink path for torn-down lanes;
+     *  - design/373 — the injection LADDER is live on this lane (BREAKING vs the flat era, named):
+     *    `"next"` = the running turn's next boundary (mid-work included — the previous behavior of
+     *    every frame, now this tier's); `"later"` = never folded into work in progress — delivered at
+     *    the run's natural would-otherwise-stop seat (its own closing turn), and a run that ends
+     *    before that seat parks the frame per session for the NEXT run's turn-open (delivery then
+     *    depends on a next run happening — a recorded structural honesty note, this engine owns no
+     *    idle process); `"now"` is REFUSED typed (`notify.invalid_priority`) — turn-interrupt
+     *    authority belongs to the caller-provenance steer face, never to the notification lane
+     *    (callers wanting earliest-boundary delivery say `"next"`). ⚠️ The parameterless DEFAULT is
+     *    `"later"` (the CC pending-notification default): an omitted priority moved from
+     *    next-boundary to the closing seat with this design — callers that need boundary delivery
+     *    must say `"next"` explicitly. NOTE for the flat era's callers: `"later"` was silently inert
+     *    then (delivered at the boundary with no runtime signal saying otherwise) — the version is
+     *    the ONLY discriminator of which behavior a build has. Delivery order within a tier is
+     *    ARRIVAL order; consecutive buffered notifications drain as one boundary batch. `priority`
+     *    rides the park path (pend records carry it; the turn-open batch is priority-major) and the
+     *    uplink path;
      *  - duplicate events dedup on `task_id:status[:seq]` — pass a fresh `seq` per repeat event. The
      *    external lane keys in its OWN dedup domain (design/144 X1): an external event can never collide
-     *    with (or pre-occupy) an internal lane's key, and vice versa;
+     *    with (or pre-occupy) an internal lane's key, and vice versa. The key deliberately excludes
+     *    `priority` (tier = delivery metadata, not event identity): a repeat under an in-flight key
+     *    folds WHATEVER tier it names — the standing entry keeps the FIRST accept's tier — so
+     *    re-tiering requires a fresh `seq` (a new occurrence), never a same-key resend;
      *  - a notify landing AFTER the run ended PARKS per session and the session's NEXT run delivers it
      *    (unlike {@link steer}, a finished task does not reject — the park lane is the contract). The park
      *    leg dedups on the same key (design/144 X4) with an HONEST WINDOW LIMIT: the dedup set spans ONE
      *    parked batch — it does not reach back across the live-queue/park boundary, and it resets when the
      *    next run drains the batch (a repeat sent after that drain is deliverable again);
-     * Throws typed `notify.invalid_payload` on a malformed input and `notify.not_running` when the run
+     * Throws typed `notify.invalid_payload` on a malformed input, `notify.invalid_priority` on
+     * `priority: "now"` (see above — a KNOWN value this lane refuses, distinct from an unknown one),
+     * and `notify.not_running` when the run
      * never built its notification lane (prepare failed). Everything upstream of the event reaching this
      * process — transport, webhook/daemon wiring, inbound authn, durable parking for idle sessions — is
      * the DEPLOYMENT half (design/43: zero daemon semantics in core).
@@ -4992,19 +5154,31 @@ 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.injection_priority_unimplemented"` (#389 伴生, D-3) — a notification was injected with
-     *    `priority: "now"`. The three values are CC's names (`now`/`next`/`later`) but this engine
-     *    delivers all three identically at the next turn boundary: there is no arm that aborts the
-     *    running turn, so a caller writing `"now"` and expecting an interruption gets a plain queued
-     *    delivery. The frame IS delivered (this is disclosure, not a refusal — dropping an accepted
-     *    notification would be the worse error); what is announced is that the knob's promise is not
-     *    honored, so an operator can stop building on it. Once per run (the injection funnel is a
-     *    single site, and a busy lane must not narrate the same gap once per frame);
-     *    `detail: { priority, taskId?, sessionId }` — `sessionId` (#433, ALWAYS present: the funnel
-     *    sits past prepare, which owns a session unconditionally) is a correlation key only, the
-     *    audience stays `"operator"` (the party building on the unhonored knob is whoever called
-     *    notify, not the end user). An UNKNOWN priority value is a different fact with a
-     *    different posture — `TaskStream.notify` refuses it typed (`notify.invalid_payload`).
+     *  - `"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.
+     *    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.
+     *
+     *  - `"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, taskId? }` — `inputId` is the parked entry's stored
+     *    correlation key.
      *
      *  - `"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
@@ -5750,11 +5924,17 @@ export interface RunnerDeps {
      *  `SendMessageToolOptions.admission`; read per call (a value change governs the next message). */
     peerAdmission?: Partial<import("../agents/peer-admission.js").PeerAdmissionConfig>;
     /**
-     * design/164 件五 — DEPLOYMENT-level usage governance: token allowances that span TASKS, evaluated per
+     * design/164 件五 — DEPLOYMENT-level usage governance: allowances that span TASKS, evaluated per
      * principal (or once for the whole deployment when a task declares none). A different axis from
      * `TaskSpec.limits`, which is the allowance ONE task asked for — an operator granting "N tokens per 5
      * hours" cannot express it as a task limit, because nothing stops the next task from asking again.
      *
+     * A window carries a TOKEN ceiling and, optionally, a MONEY ceiling (`UsageWindow.maxCostUsd`, absolute
+     * USD — the `TaskLimits.maxCostUsd` quantity one governance level up). The two are independent and
+     * either one binds. A $ ceiling requires a PRICED run: a task whose model has neither a {@link pricing}
+     * entry nor a `Model.cost` declaration is refused at the door (`config.usage_window_unpriced`) rather
+     * than charged the fabricated 0 an unpriced run would otherwise file into an operator's ceiling.
+     *
      * Unset (the default) ⇒ NO governance: no ledger is read or written and no task can be refused for
      * usage. When set, every window is evaluated at two moments:
      *  - **entry** (before the first model call of a fresh task): an exhausted window REFUSES the task with
@@ -5771,7 +5951,7 @@ export interface RunnerDeps {
      * would take the deployment down instead of telling the operator).
      */
     usageWindows?: readonly import("./usage-window-store.js").UsageWindow[];
-    /** design/164 件五 — the cross-task token ledger {@link usageWindows} is evaluated against. Core bundles
+    /** design/164 件五 — the cross-task usage ledger {@link usageWindows} is evaluated against. Core bundles
      *  `InMemoryUsageWindowStore` (process-local) and `FileUsageWindowStore` (restart-surviving); a fleet
      *  deployment plugs a database behind the same two-method seam. Ignored when `usageWindows` is unset. */
     usageWindowStore?: import("./usage-window-store.js").UsageWindowStore;
@@ -6018,8 +6198,11 @@ export interface RunnerDeps {
     /**
      * Default in-process hooks for all tasks (design/37) — the FULL lifecycle seam of the `Hooks`
      * interface, not just the tool-call trio: `preToolUse` (rewrite/restrict args + inject context),
-     * `postToolUse` (rewrite output + inject context), `userPromptSubmit` (block/inject before the
-     * objective becomes a message), plus `stop` (push back when the run would otherwise end and continue
+     * `postToolUse` (rewrite output + inject context), `userPromptSubmit` (design/373 §4.3: screens
+     * EVERY user-lane entrance — the objective, a live `TaskStream.steer`, a wake resume's message,
+     * and a parked steer's redelivery, discriminated by `ctx.source`; a hook that blocks
+     * unconditionally refuses steers/wakes too — see the ⚠️ WIDENED INVOCATION SET banner on
+     * {@link import("./hooks.js").Hooks.userPromptSubmit}), plus `stop` (push back when the run would otherwise end and continue
      * it), `postToolUseFailure` / `postToolBatch` / `permissionDenied` (failure, batch-boundary and
      * deny observers), `preCompact` / `postCompact` (compaction gate + observer), `stopFailure`
      * (API-error terminal observer) and the `preToolUseObservational` declaration flag — each member's

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

@@ -100,10 +100,11 @@ export declare const FENCED_LANE_ENVELOPE_TAGS: readonly string[];
  *
  * These are not fences. They render deployment/server/model-supplied strings into a body the run loop
  * then wraps in engine authority, so a forged envelope inside one is laundered by the wrapper. The
- * wrapper itself cannot blanket-neutralize the family — it also shells the one body that legitimately
- * IS an envelope (`buildSkillsBlock`'s `<skills>` fence) — so containment is expressed as OWNERSHIP:
- * this full set for every body that owns nothing, minus its own tag for the one that does (see
- * `attachmentEnvelopeTags` in turn-attachments.ts).
+ * wrapper itself cannot blanket-neutralize the family — it also shells bodies that legitimately ARE
+ * envelopes (TWO owners today: `buildSkillsBlock`'s `<skills>` fence and `renderTotalTokensReminder`'s
+ * `<total_tokens>` body) — so containment is expressed as OWNERSHIP: this full set for every body that
+ * owns nothing, minus its own tag for each one that does (single source: `ATTACHMENT_TAGS_OWNED` in
+ * turn-attachments.ts, which the per-source `attachmentEnvelopeTags` derivation reads).
  *
  * Allocated ONCE so the sanitizer's memoized break-out regex is keyed by a stable value.
  */

package/dist/core/untrusted-text.js

@@ -48,6 +48,14 @@ export const ENGINE_ENVELOPES = Object.freeze([
         fenced: true,
         disclosed: true,
     },
+    {
+        tag: "total_tokens",
+        kind: "authority",
+        mint: "core/runner/turn-attachments.ts renderTotalTokensReminder (RB-318, CC 2.1.245-verbatim body)",
+        guard: "the body has no untrusted seat at all — every byte is engine copy or a finite number the producer validated; the fence below keeps the same spelling arriving from OUTSIDE from being read as this readout",
+        fenced: true,
+        disclosed: true,
+    },
     {
         tag: "working-file",
         kind: "framing",

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

@@ -13,9 +13,9 @@
  * backends equivalent by construction rather than by two hand-written copies that drift.
  */
 /**
- * One governed window. Both fields are allowances, not hints: `windowMs` is the window's WIDTH and
- * `maxTokens` the tokens it admits. `anchor` picks between the two window shapes that actually exist in
- * the wild:
+ * One governed window. Its fields are allowances, not hints: `windowMs` is the window's WIDTH and
+ * `maxTokens` / `maxCostUsd` the two CEILINGS it admits work under. `anchor` picks between the two window
+ * shapes that actually exist in the wild:
  *  - `"first-use"` — the window OPENS at the key's first charge and lasts `windowMs`; when it lapses with
  *    no further use, the next charge opens a fresh one. This is the "5 hours from when you started"
  *    shape: bursty use is admitted at full width, and an idle key is never penalized for old traffic.
@@ -29,6 +29,28 @@ export interface UsageWindow {
     /** Tokens the window admits before it is exhausted. Must be finite and >= 0; `0` is a real, always-full
      *  window (an operator lock-out), not "unset". */
     maxTokens: number;
+    /**
+     * OPTIONAL second ceiling: the MONEY the window admits before it is exhausted, in absolute USD — the
+     * same quantity and unit `TaskLimits.maxCostUsd` names, one governance level up (a task's own allowance
+     * vs the allowance an operator grants a principal across tasks). Must be finite and >= 0; `0` is a real,
+     * always-full window, exactly as it is for `maxTokens`.
+     *
+     * The two ceilings are INDEPENDENT and both bind: a window is exhausted when EITHER its tokens reach
+     * `maxTokens` or its cost reaches `maxCostUsd` — whichever fills first. Absent (the default, and every
+     * pre-existing deployment) means THIS window governs tokens only — its own reading never asks for or
+     * enforces a cost. Whether cost is tracked/recorded at all is a DEPLOYMENT-level fact, not a
+     * per-window one (the `UsageSlot.costMicroUsd` / `UsageBucketRow` in-presence condition: "while the
+     * deployment governs at least one `maxCostUsd` window"): in a MIXED declaration the shared ledger
+     * rows carry cost under every window's bucket, and only a deployment with NO $ window anywhere keeps
+     * its rows byte-identical to the pre-cost-arm shape.
+     *
+     * **Requires a PRICED run.** Cost is not a number the engine can invent: a run whose model has neither a
+     * `RunnerDeps.pricing` entry nor a `Model.cost` declaration produces NO cost figure at all (not a zero),
+     * so a $ ceiling over it is unevaluable and the task is refused at the door
+     * (`config.usage_window_unpriced`) rather than charged a fabricated 0 that would let the ceiling
+     * silently stop applying.
+     */
+    maxCostUsd?: number;
     /** Which of the two window shapes above this is. */
     anchor: "first-use" | "rolling";
 }
@@ -36,6 +58,19 @@ export interface UsageWindow {
 export interface UsageSlot {
     at: number;
     tokens: number;
+    /** The charge's cost in integer micro-USD. **In-presence condition:** written only while the deployment
+     *  governs at least one {@link UsageWindow.maxCostUsd} window AND the charge had a cost figure at all — a
+     *  token-only deployment's ledger rows are byte-for-byte what they were before the cost arm existed, and
+     *  so is the row for spend nothing could price. Absent therefore reads as "no money recorded here": a row
+     *  written BEFORE a $ window was declared, or one whose model had no price table, contributes 0 to the
+     *  money lane rather than back-dating a number nobody recorded. */
+    costMicroUsd?: number;
+    /** This charge's spend could NOT be priced (see {@link UsageWindowStore.charge}'s `null` arm).
+     *  **In-presence condition:** only ever `true`, only on a row written while a $ window was governed and
+     *  nothing could price the spend. It is what keeps "no money here" apart from "no money spent here": a
+     *  window holding one of these reports a money figure that is a LOWER BOUND, and says so
+     *  ({@link UsageWindowReading.costUnknown}). */
+    costUnknown?: true;
 }
 /** The OPEN first-use window for one `windowMs` on one key. Rows for other widths coexist, so a
  *  deployment governing 5h and 7d windows keeps one row per width rather than one blended counter. */
@@ -46,6 +81,11 @@ export interface UsageBucketRow {
     openedAt: number;
     /** Tokens charged into it since it opened. */
     tokens: number;
+    /** Integer micro-USD charged into it since it opened. Same in-presence condition as {@link UsageSlot.costMicroUsd}. */
+    costMicroUsd?: number;
+    /** Some spend in this open window could not be priced. Same meaning and in-presence condition as
+     *  {@link UsageSlot.costUnknown}; sticky for the life of the open bucket. */
+    costUnknown?: true;
 }
 /** Everything one key's governance state consists of: the rolling lane's slots and the first-use lane's
  *  open buckets. Persisted verbatim by every backend (plain JSON, no methods). */
@@ -59,7 +99,20 @@ export interface UsageWindowReading {
     window: UsageWindow;
     /** Tokens the window currently holds. */
     tokens: number;
-    /** `tokens >= window.maxTokens` — the window admits no further work. */
+    /** Integer micro-USD the window currently holds. **In-presence condition:** present exactly when
+     *  `window.maxCostUsd !== undefined` — a reading for a token-only window is byte-identical to what it
+     *  was before the cost arm existed, and a MISSING value on a $ window means the store did not evaluate
+     *  the ceiling at all (refused loudly by {@link usageRetryAfterMs}, never read as an open ceiling). */
+    costMicroUsd?: number;
+    /** The window holds spend nothing could price, so `costMicroUsd` is a LOWER BOUND rather than the total.
+     *  **In-presence condition:** only ever `true`, and only on a window that declares `maxCostUsd`. The
+     *  ceiling still binds on what IS countable (an under-count can only postpone exhaustion, never invent
+     *  it), and the engine announces the gap on every run that reads it — the alternative, treating the
+     *  whole window as exhausted until the unpriced charge ages out, would lock a key out for as long as
+     *  `windowMs` over one degraded turn, which is a larger outage than the gap it answers. */
+    costUnknown?: true;
+    /** The window admits no further work: `tokens >= window.maxTokens`, OR (when the window declares one)
+     *  `costMicroUsd >= window.maxCostUsd` — the two ceilings are independent and either one binds. */
     exhausted: boolean;
     /** Ms until this window next frees capacity: for `first-use`, when the open window lapses; for
      *  `rolling`, when its OLDEST in-window slot ages out (which frees that slot's tokens, not
@@ -82,8 +135,19 @@ export interface UsageWindowStore {
      * needs it to know which first-use buckets to keep open and how far back the rolling lane must
      * remember, so the ledger stays bounded instead of growing for the life of the deployment.
      * Called once per accounting point; never with a negative or non-finite `tokens`.
+     *
+     * `costMicroUsd` is the same charge's MONEY, in integer micro-USD, or `null` when the spend is real but
+     * NOTHING could price it. **In-presence condition:** one of the two is supplied exactly when the
+     * deployment governs at least one {@link UsageWindow.maxCostUsd} window — a token-only deployment is
+     * called with the pre-cost-arm argument list and must behave identically.
+     *
+     * A store that governs $ windows MUST FORWARD it (into `chargeUsageRecord`, or into its own equivalent)
+     * and answer {@link UsageWindowReading.costMicroUsd} from what it persisted. A decorator written against
+     * the pre-cost-arm signature drops the argument silently — which is why the arithmetic refuses an absent
+     * cost outright (`usage_window.store_cost_unanswered`) instead of folding it to a 0 that would leave the
+     * money ceiling open forever with nothing able to notice.
      */
-    charge(key: string, tokens: number, at: number, windows: readonly UsageWindow[]): Promise<void>;
+    charge(key: string, tokens: number, at: number, windows: readonly UsageWindow[], costMicroUsd?: number | null): Promise<void>;
     /** Read `key`'s state for each window as of `now`, in the order the windows were given. */
     read(key: string, windows: readonly UsageWindow[], now: number): Promise<readonly UsageWindowReading[]>;
 }
@@ -99,6 +163,10 @@ export declare const EMPTY_USAGE_WINDOW_RECORD: UsageWindowRecord;
  * would govern a deployment by a number nobody chose. Refuses with `config.usage_window_invalid`.
  */
 export declare function resolveUsageWindows(windows: readonly UsageWindow[] | undefined): readonly UsageWindow[] | undefined;
+/** Does the deployment govern MONEY at all? The one predicate that decides whether a cost figure is asked
+ *  of the engine, written into the ledger, or answered in a reading — so a token-only deployment stays
+ *  byte-for-byte what it was before the cost arm existed. */
+export declare function windowsGovernCost(windows: readonly UsageWindow[]): boolean;
 /**
  * Fold one charge into a key's record and return the NEW record (pure — the input is never mutated, so a
  * store that keeps records in a Map cannot be corrupted by a half-applied charge).
@@ -107,8 +175,23 @@ export declare function resolveUsageWindows(windows: readonly UsageWindow[] | un
  * can never be read again, and a first-use bucket for a width the deployment no longer governs can never
  * be read again either, so both are dropped here. A record therefore stays bounded by (charges within the
  * widest rolling window) + (one row per governed first-use width).
+ *
+ * `costMicroUsd` rides the same fold as `tokens` (integer micro-USD, never a float USD: the ledger sums
+ * thousands of charges and a float would accumulate error into a money ceiling), and it is a THREE-state
+ * argument while the deployment governs a $ window:
+ *  - a NUMBER — the charge's cost, folded into the money lane;
+ *  - `null` — the tokens are known but their cost is NOT (an unpriced model served the spend). The row is
+ *    written with its tokens and NO cost field: the token ceiling stays exact, and the money lane counts
+ *    nothing rather than a fabricated 0. The engine refuses such a run anyway — this keeps the ledger
+ *    honest about the spend that already happened before the refusal;
+ *  - `undefined` — REFUSED. Core always supplies one of the two above when a $ window is governed, so an
+ *    absent argument means some store in the chain (a pre-cost-arm decorator, most likely) dropped it, and
+ *    folding it to 0 would leave the money ceiling permanently open with nothing able to detect it.
+ * With NO $ window governed the argument is ignored entirely and rows keep their pre-cost-arm bytes.
+ * Rows that already carry a cost keep it, so removing and re-adding a $ window neither loses the history
+ * nor rewrites rows that predate it.
  */
-export declare function chargeUsageRecord(record: UsageWindowRecord, tokens: number, at: number, windows: readonly UsageWindow[]): UsageWindowRecord;
+export declare function chargeUsageRecord(record: UsageWindowRecord, tokens: number, at: number, windows: readonly UsageWindow[], costMicroUsd?: number | null): UsageWindowRecord;
 /**
  * Read a key's record against the governed windows as of `now` (pure). The `first-use` lane reads the open
  * bucket; the `rolling` lane sums the slots inside `(now − windowMs, now]`.
@@ -119,8 +202,26 @@ export declare function readUsageRecord(record: UsageWindowRecord, windows: read
  * window would admit work again. `undefined` when nothing is exhausted. The MAXIMUM (not the minimum) of
  * the exhausted windows' hints — resuming when the shortest one clears would immediately re-suspend on
  * the longer one.
+ *
+ * It is also the ONE choke point every governance read in the engine goes through, so the integrity
+ * checks live here, in two arms:
+ *  - **coverage** (when the caller supplies the declared `windows`): one reading per declared window,
+ *    in the order the windows were given, with the window echoed verbatim on the fields that name the
+ *    allowance (`windowMs`/`anchor`/`maxTokens`/`maxCostUsd`). The per-reading arm below is
+ *    structurally blind to a reading that is MISSING — a decorator store that maps only the windows
+ *    it recognizes, reorders the answer, or echoes a normalized copy with `maxCostUsd` stripped would
+ *    otherwise un-govern a declared ceiling with zero symptoms. Every engine read passes its windows
+ *    through; the parameter stays optional so a bare-readings caller keeps the pre-coverage face.
+ *  - **per-reading**: a reading for a window that DECLARES `maxCostUsd` while carrying no
+ *    `costMicroUsd` means the store never evaluated the money ceiling — its `exhausted` verdict then
+ *    covers the token axis alone.
+ * Both arms refuse with ONE code (`usage_window.store_cost_unanswered`) rather than read as an open
+ * ceiling — an unanswered window and an answered-without-cost window are the same fact ("the store
+ * never proved it evaluated the declared ceiling"): a governance ceiling that silently stops applying
+ * is worse than one that never existed, which is the same posture the file backend takes when its
+ * ledger is unreadable.
  */
-export declare function usageRetryAfterMs(readings: readonly UsageWindowReading[]): number | undefined;
+export declare function usageRetryAfterMs(readings: readonly UsageWindowReading[], windows?: readonly UsageWindow[]): number | undefined;
 /**
  * Process-local {@link UsageWindowStore} reference implementation. Governs correctly within ONE Runner
  * process and loses its ledger on restart — the right choice for tests and single-process deployments,
@@ -129,6 +230,6 @@ export declare function usageRetryAfterMs(readings: readonly UsageWindowReading[
  */
 export declare class InMemoryUsageWindowStore implements UsageWindowStore {
     private readonly records;
-    charge(key: string, tokens: number, at: number, windows: readonly UsageWindow[]): Promise<void>;
+    charge(key: string, tokens: number, at: number, windows: readonly UsageWindow[], costMicroUsd?: number | null): Promise<void>;
     read(key: string, windows: readonly UsageWindow[], now: number): Promise<readonly UsageWindowReading[]>;
 }