@sema-agent/core 5.61.0 → 5.63.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
@@ -2658,9 +2658,12 @@ export interface TaskSpec {
      * Scope caveat (design/141 examples 批实测): `instructions` rides the WHOLE-TURN summarization
      * request only; a split-turn cut point (mid-turn prefix summarization) uses the engine-owned
      * turn-prefix prompt and does not carry it (same A2 boundary as `RunnerDeps.summaryProvider`).
-     * `withinTask: false` keeps end-of-task compaction but disables the within-task (turn-boundary)
-     * trigger — the escape hatch for the §25 (A) control-flow change; the system prompt then stops
-     * claiming mid-task summarization (§6.3 honesty).
+     * `withinTask: false` keeps end-of-task compaction but disables the ROUTINE within-task
+     * (turn-boundary) trigger — the escape hatch for the §25 (A) control-flow change; the system
+     * prompt then stops claiming ROUTINE mid-task summarization (§6.3 honesty). It does NOT silence
+     * the recovery-class forced lanes (design/374 slice 3): a prompt-too-long recovery or the guard
+     * chain's arm B may still legitimately compact WITHIN the task — error/pressure recovery is not
+     * a routine boundary pass, so a within-task compaction under this flag is contract-conforming.
      * `attachWorkingFiles` (LONGRUN-2; **default ON since 2026-07-03** — CC 198 hard-codes its
      * post-compact file restore, and LONGRUN-2 measured ≈2.3 extra read round-trips per compaction
      * without it): after each compaction, re-read the task's most recently READ files (CC
@@ -2823,6 +2826,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 +3171,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 +3187,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 +3504,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 +3729,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 +3750,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 +4156,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) | ({
     /**
@@ -4417,6 +4509,23 @@ export interface TaskStream extends AsyncIterable<TaskEvent> {
      *  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;
@@ -5063,6 +5172,17 @@ export interface EngineNotice {
      *    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
      *    as an external content source was invoked, directly or through a delegated child). Under
@@ -5807,11 +5927,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
@@ -5828,7 +5954,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;
@@ -6075,8 +6201,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
@@ -6219,22 +6348,26 @@ export interface RunnerDeps {
      */
     toolResultThresholdChars?: number;
     /**
-     * design/374 — microCompact machine-alignment knobs (EXPERIMENTAL until the slice-3 default
-     * flip; both default OFF so a deployment that never touches this bag runs the pre-374 machine
-     * byte for byte).
+     * design/374 — microCompact machine-alignment knobs. Since the slice-3 default flip BOTH knobs
+     * default ON (`machine: "cc"`, `clearOnRejection: true`); the pre-374 behavior is the explicit
+     * opt-out `{ machine: "legacy", clearOnRejection: false }`.
      *
      *  - `machine`: which stale-tool-result clearing machine the request pipeline runs —
-     *    `"legacy"` (default; the historical keep-3 / clear-to-budget machine) or `"cc"` (the CC
-     *    2.1.223 rejection-leg form: keep 5, ≥20k minimum-savings gate, one deep clear beyond the
-     *    keep window, CC marker bytes). ⚠️ Read the P-form warning on
-     *    {@link import("./context-edit.js").ContextEditMachine} before selecting `"cc"`: until the
-     *    slice-3 fallback re-ordering ships, the 20k gate sits in front of the only reduction while
-     *    the message-dropping guard trim still backstops — opting in is accepting that trade.
+     *    `"cc"` (default: the CC 2.1.223 rejection-leg form — keep 5, ≥20k minimum-savings gate, one
+     *    deep clear beyond the keep window, CC marker bytes), `"legacy"` (the historical keep-3 /
+     *    clear-to-budget machine, kept as the compatibility opt-out; it also keeps the pre-374
+     *    backstop order — guard trim as the ordinary second line), or `"off"` (no proactive frontier
+     *    clearing at all — the D-2 off switch; the unified machine then gets its ONE shot at the
+     *    blocking point instead, the slice-3 arm A, trace trigger `"blocking"`). The pre-flip P-form
+     *    warning on {@link import("./context-edit.js").ContextEditMachine} is resolved: the slice-3
+     *    fallback re-ordering shipped with this default (blocking-point re-run → in-turn forced
+     *    compaction behind the adopt seam → trim demoted to the disaster-only last resort), so an
+     *    under-20k refusal no longer falls straight into a message-dropping trim.
      *  - `clearOnRejection` (MC-R, slice 2): on a provider input-too-long rejection, run ONE cheap
      *    deterministic clear over the rejected projection (same cc machine, savings ≥20k or nothing)
-     *    and retry inside the turn BEFORE the forced-compaction recovery. Default false (X2: the
-     *    machinery lands dark; the default flips together with the machine in slice 3). Independent
-     *    of `machine` — an enabled MC-R always clears in the cc form (the rejection arm has no
+     *    and retry inside the turn BEFORE the forced-compaction recovery. Default true (flipped with
+     *    the machine default in slice 3; X2's dark-landing clause is spent). Independent of
+     *    `machine` — an enabled MC-R always clears in the cc form (the rejection arm has no
      *    budget coordinate for the legacy incremental form to stop at). BUDGET ACCOUNTING (design/374
      *    §3.2.1, stated here because it is otherwise invisible to a deployment): a successful MC-R
      *    clear-and-retry SPENDS one attempt of the shared prompt-too-long recovery budget (default 2
@@ -6246,10 +6379,11 @@ export interface RunnerDeps {
      *  A declaration outside the closed vocabulary (a `machine` string not in the union, a
      *  non-boolean `clearOnRejection` — JSON/env-derived config the type cannot guard) refuses the
      *  whole prepare loudly (`code: "config.microcompact_invalid"`, no silent re-default): folding it
-     *  would run the pre-374 machine while the deployment believes it opted in.
+     *  would silently run the DEFAULT machine while the deployment believes its declaration took
+     *  effect.
      */
     microCompact?: {
-        machine?: "legacy" | "cc";
+        machine?: "off" | "legacy" | "cc";
         clearOnRejection?: boolean;
     };
     /**

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[]>;
 }