@sema-agent/core 5.60.1 → 5.62.0

package/dist/core/runner/turn-attachments.d.ts

@@ -1,4 +1,5 @@
 import type { McpDroppedTool } from "../mcp.js";
+import type { TaskSpec } from "../types.js";
 import { type SkillListingEntry } from "./synthetic-tools.js";
 /**
  * design/133 §R3 — turn-boundary attachment seam: the PURE producer layer (CC `getContextAttachments`
@@ -28,6 +29,44 @@ export declare const TOOL_SEARCH_REMINDER_CONFIG: {
     readonly EVERY_N_TURNS: 15;
     readonly MAX_NAMES: 10;
 };
+/**
+ * RB-318 — the `total_tokens_reminder` mode set, CC 2.1.245-VERBATIM and in CC's declaration order
+ * (bundle `R9o`; the settings schema declares the same five for its `totalTokensReminder` key).
+ * Each arm names what the rendered number IS, per CC's own schema prose:
+ *  - `off` — the lane is silent. Kept as a member rather than folded into the opt-in flag because it
+ *    is the DEPLOYMENT-RESOLVED kill switch (CC resolves the mode from env
+ *    `CLAUDE_CODE_TOTAL_TOKENS_REMINDER` → settings → gate; sema keeps env resolution at the shell and
+ *    carries only the resolved mode — the {@link AttachmentInputs.config.todoReminderMode} contract
+ *    verbatim, where "wired on" and "silenced by policy" are also two independent bits).
+ *  - `infinite` — the literal text `Infinite`.
+ *  - `fixed` — the constant {@link TOTAL_TOKENS_FIXED_ARM_VALUE}. Together with `infinite` these are
+ *    CC's two CONSTANT arms: they consume no measurement at all, which is exactly why they exist
+ *    (they are the controls the countdown arms are measured against).
+ *  - `countdown` — the live remaining budget, raw.
+ *  - `padded-countdown` — the same, smoothed by a monotone floor so the number never jumps back.
+ */
+export declare const TOTAL_TOKENS_REMINDER_MODES: readonly ["off", "infinite", "fixed", "countdown", "padded-countdown"];
+/**
+ * RB-318 rider — the closed set is spelled TWICE (the public `TaskSpec.attachments.
+ * totalTokensReminderMode` literal union and this array), and only the TaskSpec→array direction had
+ * a compile chain (runtask's AttachmentInputs assignment). The config door widens this array to
+ * `readonly string[]` before `includes`, so a member added HERE and never to the public union used
+ * to compile clean, pass the door, and render — while the public type declared it illegal. Both
+ * directions now refuse at compile time (the governance-codes `satisfies` lockstep form):
+ *  - array ⊆ TaskSpec — the `satisfies` on the declaration above;
+ *  - TaskSpec ⊆ array — the conditional below collapses the exported type to `never` (the default-
+ *    mode constant two lines down errors immediately) when the public union grows an unlisted member.
+ */
+type TaskSpecTotalTokensReminderMode = NonNullable<NonNullable<TaskSpec["attachments"]>["totalTokensReminderMode"]>;
+export type TotalTokensReminderMode = [TaskSpecTotalTokensReminderMode] extends [(typeof TOTAL_TOKENS_REMINDER_MODES)[number]] ? (typeof TOTAL_TOKENS_REMINDER_MODES)[number] : never;
+/** RB-318 — CC 2.1.245's own default ("Defaults to padded-countdown"). The 2026-07-30 registration of
+ *  this lane rested on the 2.1.220 premise "OFF by default even in 220"; 245 flipped it, which is the
+ *  fact that reopened the ruling. Applies only ONCE the deployment has opted the lane in. */
+export declare const TOTAL_TOKENS_REMINDER_DEFAULT_MODE: TotalTokensReminderMode;
+/** RB-318 — CC's `fixed` arm constant (bundle `A9o`). A fixed anchor is the POINT of that arm (the
+ *  number is meant not to move), so it is copied as the constant it is rather than re-pointed at a
+ *  declared ceiling — a deployment that wants its own number picks a countdown arm instead. */
+export declare const TOTAL_TOKENS_FIXED_ARM_VALUE = 5000000;
 /** F5: per-boundary stat scan upper bound — at most this many most-recently-read files are stat'ed. */
 export declare const CHANGED_FILES_MAX = 20;
 /**
@@ -39,7 +78,7 @@ export declare const CHANGED_FILES_MAX = 20;
 export declare const CHANGED_FILES_MTIME_EPS_MS = 2000;
 /** Per-boundary payload byte cap over the whole bundle (weak-model context economics). */
 export declare const ATTACHMENT_BYTE_CAP: number;
-export type AttachmentSource = "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";
+export type AttachmentSource = "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";
 /** G1 续批 — one agent type on the delegation tool's roster (ToolSpec.agentListing, filled by
  *  createSubagentTool: defined agents + the built-in fork when offered). */
 export interface AgentListingEntry {
@@ -164,6 +203,33 @@ export interface AttachmentState {
      *  agent frame permanently starving the skills frame (each frame individually fits the cap by
      *  construction — agent roster ≤ cap by deployment size, skills block ≤ SKILLS_BLOCK_MAX_BYTES). */
     skillsListingStarved?: boolean;
+    /**
+     * RB-318 — the `padded-countdown` arm's SMOOTHING FLOOR: the highest usage figure this run has
+     * already published against. CC's `cumulativeUsed` (bundle: `Math.max(storedFloor, rolledOver +
+     * used − anchor)`, stored back) exists so the countdown never RUNS BACKWARDS when the live usage
+     * coordinate drops under it — a model that watched its budget shrink and then saw it grow again
+     * learns the number is noise.
+     *
+     * Two of CC's three maps are structurally degenerate here and that is a mapping, not a loss:
+     *  - the per-agent KEY — CC's tracker is session-scoped and keyed by `agentId ?? "main"` because one
+     *    CC session hosts the main agent and its subagents; a sema {@link AttachmentState} is already
+     *    per-RUN, and a delegated child is its own run with its own state, so this scalar IS that slot.
+     *  - the ANCHOR (`reanchorTaskBudget`, re-armed on every regular user prompt so a new user task
+     *    counts down from the full budget again) — a sema LEG is one task epoch, so the anchor is fixed
+     *    at 0 for the leg's whole life and the epoch reset is the next `runTask` invocation — a
+     *    durable-resume leg INCLUDED (it re-enters through `runTask`, rebuilds this state, re-derives
+     *    its slice window and restarts the spend coordinate, so its countdown re-anchors to the new
+     *    leg's real remaining — the CC re-anchor arm, not a floor violation; the floor deliberately
+     *    does NOT ride the checkpoint, since a carried floor against a fresh slice window would freeze
+     *    the readout at "0 tokens left" over an allowance the run genuinely holds). Same lifecycle
+     *    reasoning as the plan_mode lane's `countPlanModeAttachmentsSinceLastExit` note.
+     *  - the ROLLOVER (`rollOverContext`, which adds each compacted-away context back so the count keeps
+     *    advancing) is likewise not owed: sema feeds a CUMULATIVE spend coordinate (`stats.tokens`),
+     *    which a compaction never rewinds, where CC feeds the live context size.
+     * `undefined` = the padded arm has not rendered yet (an OFF lane, or a raw-countdown one, never
+     * allocates it).
+     */
+    totalTokensFloor?: number;
 }
 /**
  * A1-R — the date_change lane's OWN state, deliberately NOT an
@@ -314,6 +380,25 @@ export interface AttachmentInputs {
         used: number;
         total: number;
     };
+    /** RB-318 total_tokens_reminder lane (裁 B, 2026-08-26) — the TOKEN twin of {@link budgetUsd}, fed
+     *  from the same place for the same reason: `used` is the run's cumulative token spend
+     *  (`stats.tokens`) and `total` is the ceiling the budget gate enforces against it
+     *  (`rs.budget.maxTokensWindow` = min(`limits.maxTokens`, the cross-slice allocation's remainder)),
+     *  so a model-visible countdown can never disagree with an eventual `limits.max_tokens_exceeded`.
+     *  Core neither estimates nor discovers this pair: no ceiling declared ⇒ absent ⇒ the countdown arms
+     *  are silent (CC's own `maxBudgetUsd === void 0 → []` posture on the sibling lane).
+     *
+     *  COORDINATE NOTE (candidate divergence registration): CC's two countdown arms read two DIFFERENT
+     *  sources — `countdown` the live remaining context window, `padded-countdown` a synthetic task
+     *  budget (its default 15_000_000 is far larger than any real window). sema carries ONE pair, the
+     *  enforced spend coordinate, and lets the mode pick the arithmetic over it: publishing a context
+     *  window would mean publishing a figure core cannot make true (BYOM — the window, the tokenizer and
+     *  the accounting belong to the deployment's model), while the enforced ceiling is the one token
+     *  number core owns end to end. */
+    totalTokens?: {
+        used: number;
+        total: number;
+    };
     config: {
         todoReminder: boolean;
         /** 口径③ — CC `r2o()` kill-switch parity (pretty.js:479167-479171; consumed by both producers at
@@ -349,6 +434,36 @@ export interface AttachmentInputs {
          *  through a workflow governance baseline (`WorkflowGovernanceBaseline.base`, which explicitly
          *  snapshots `maxCostUsd` and every other governance field) reaches the lane. */
         budgetUsd?: boolean;
+        /**
+         * RB-318 (裁 B, 2026-08-26) — `total_tokens_reminder` (CC 2.1.245 producer `MPs`, renderer `Oje`,
+         * registered in the SHARED producer group beside `budget_usd`, so a subagent carrying its own
+         * ceiling sees it too — the RB-311 attribution verbatim). Opt-in, default OFF like every other 133
+         * member: an un-opted deployment renders no reminder frame — the ATTACHMENT lane itself is
+         * byte-identical to the pre-lane engine. (Scoped deliberately to this lane: registering
+         * `<total_tokens>` in ENGINE_ENVELOPES changed the SANITIZE/DISCLOSURE faces for every
+         * deployment, opted or not — untrusted text carrying that spelling is now defused on the fenced
+         * lanes and envelope-shaped external data trips the design/319 disclosure tail. That is the
+         * defensive direction and unconditional by design: the envelope family must be un-forgeable
+         * whether or not anyone renders the real frame.)
+         *
+         * WHY IT EXISTS NOW. The 2026-07-30 registration refused it as a product-face question and rested
+         * on "OFF by default even in 220". 245 flips exactly that premise — its settings schema reads
+         * "Defaults to padded-countdown", i.e. upstream now publishes a token countdown to the model by
+         * default. The BYOM honesty objection is answered by SHAPE rather than by dropping it: core
+         * estimates nothing. The numbers are the ones the engine already enforces against
+         * ({@link AttachmentInputs.totalTokens}), the ceiling is the deployment's own declared
+         * `limits.maxTokens`, and with no ceiling declared the countdown arms simply never fire.
+         *
+         * The arm is chosen by {@link totalTokensReminderMode} (default {@link
+         * TOTAL_TOKENS_REMINDER_DEFAULT_MODE}); `off` there silences the lane without un-wiring it.
+         */
+        totalTokensReminder?: boolean;
+        /** RB-318 — the RESOLVED mode (see {@link TOTAL_TOKENS_REMINDER_MODES}). CC resolves it from env /
+         *  settings / a server gate; sema keeps env resolution at the deployment shell and carries only the
+         *  resolved value, exactly like {@link todoReminderMode}. Absent ⇒ {@link
+         *  TOTAL_TOKENS_REMINDER_DEFAULT_MODE}. A value outside the closed set is refused at the config
+         *  door (`config.attachment_invalid`), never folded to the default. */
+        totalTokensReminderMode?: TotalTokensReminderMode;
         /** G1: post-compact background-task announce (opt-in, default OFF like the 133 members). */
         backgroundTasks?: boolean;
         /** G1: deferred-tool materialization announce (design/36 setTools delta → boundary notice). */
@@ -441,10 +556,11 @@ export interface AttachmentInputs {
  * done HERE because the caller only invokes this once per boundary after its injection gate passed —
  * splitting "decide" from "mark sent" would just invite a drift between the two.
  *
- * Returns attachments in EVIDENCE-STRENGTH order (todo/task → plan_mode → budget_usd →
- * background_tasks → tools_delta → agent_listing → skills_listing → mcp_instructions → changed_files), which is also the §R3 MED-6
- * truncation order read backwards: under the 8KB cap changed_files is sacrificed first, the todo/task
- * list last. The G1/续批 members are registry/engine ground truth (strong), but the
+ * Returns attachments in EVIDENCE-STRENGTH order (todo/task → tool_search_usage_reminder →
+ * plan_mode → budget_usd → total_tokens_reminder → background_tasks → tools_delta → agent_listing →
+ * skills_listing → mcp_instructions → mcp_dropped_tools → changed_files), which is also the §R3
+ * MED-6 truncation order read backwards: under the 8KB cap changed_files is sacrificed first, the
+ * todo/task list last. The G1/续批 members are registry/engine ground truth (strong), but the
  * todo/plan lane keeps priority: it carries the run's own work-tracking state, which the model can
  * least afford to lose.
  */
@@ -528,6 +644,21 @@ export declare function commitInstructionsChange(state: InstructionsChangeState,
     contentHash: string | null;
 }>): void;
 export declare function renderBudgetUsd(used: number, total: number): string;
+/**
+ * RB-318 — CC 2.1.245 `Oje` VERBATIM: the whole body is the one-line envelope
+ * `<total_tokens>N tokens left</total_tokens>`, where N is the arm's own substitution — the literal
+ * `Infinite`, the {@link TOTAL_TOKENS_FIXED_ARM_VALUE} constant, or the remaining count clamped at
+ * zero (CC's `Math.max(0, …)`: an over-spent run reads `0 tokens left`, never a negative number).
+ *
+ * `remaining` is ignored by the two constant arms — the caller passes whatever it has (the producer
+ * passes 0), matching CC, whose own producer computes `0` for them.
+ *
+ * The `<total_tokens>` tag is an ENGINE-MINTED authority envelope: it is registered in the
+ * `ENGINE_ENVELOPES` census (untrusted-text.ts) and is in the fenced family, so the same spelling
+ * arriving inside untrusted content is defused rather than read as this readout. Its own body needs no
+ * escaping in return — every byte here is engine copy or a finite number.
+ */
+export declare function renderTotalTokensReminder(mode: TotalTokensReminderMode, remaining: number): string;
 /**
  * SR-7 — CC 2.1.198 VERBATIM inner text (bundle pretty.js:698391-698398, `F6c`): the aggregated
  * orphaned-background-task notice a restarted/resumed leg injects ONCE (CC's own `<system-reminder>`
@@ -829,3 +960,4 @@ export declare function selectMcpDroppedBatch<T extends McpDroppedTool>(entries:
  * is unchanged: this is a pure function of (string, number).
  */
 export declare function clipToBytes(s: string, maxBytes: number): string;
+export {};

package/dist/core/runner/turn-attachments.js

@@ -15,15 +15,21 @@ export const TOOL_SEARCH_REMINDER_CONFIG = {
     EVERY_N_TURNS: 15,
     MAX_NAMES: 10,
 };
+export const TOTAL_TOKENS_REMINDER_MODES = ["off", "infinite", "fixed", "countdown", "padded-countdown"];
+export const TOTAL_TOKENS_REMINDER_DEFAULT_MODE = "padded-countdown";
+export const TOTAL_TOKENS_FIXED_ARM_VALUE = 5_000_000;
 export const CHANGED_FILES_MAX = 20;
 export const CHANGED_FILES_MTIME_EPS_MS = 2000;
 export const ATTACHMENT_BYTE_CAP = 8 * 1024;
 const PROJECTION_ITEMS_MAX = 50;
 const PROJECTION_CONTENT_MAX = 80;
 const ATTACHMENT_TAGS_DEFAULT = [...SHELLED_BODY_ENVELOPE_TAGS];
-const ATTACHMENT_TAGS_SKILLS_OWNER = SHELLED_BODY_ENVELOPE_TAGS.filter((t) => t !== "skills");
+const ATTACHMENT_TAGS_OWNED = {
+    skills_listing: SHELLED_BODY_ENVELOPE_TAGS.filter((t) => t !== "skills"),
+    total_tokens_reminder: SHELLED_BODY_ENVELOPE_TAGS.filter((t) => t !== "total_tokens"),
+};
 export function attachmentEnvelopeTags(source) {
-    return source === "skills_listing" ? ATTACHMENT_TAGS_SKILLS_OWNER : ATTACHMENT_TAGS_DEFAULT;
+    return ATTACHMENT_TAGS_OWNED[source] ?? ATTACHMENT_TAGS_DEFAULT;
 }
 export const INSTRUCTIONS_CHANGE_BYTE_CAP = 512;
 export function createAttachmentState() {
@@ -166,6 +172,19 @@ export function collectDueAttachments(state, inp) {
     if (inp.config.budgetUsd && inp.budgetUsd !== undefined) {
         (out ??= []).push({ source: "budget_usd", body: renderBudgetUsd(inp.budgetUsd.used, inp.budgetUsd.total) });
     }
+    if (inp.config.totalTokensReminder === true) {
+        const mode = inp.config.totalTokensReminderMode ?? TOTAL_TOKENS_REMINDER_DEFAULT_MODE;
+        if (mode === "infinite" || mode === "fixed") {
+            (out ??= []).push({ source: "total_tokens_reminder", body: renderTotalTokensReminder(mode, 0) });
+        }
+        else if ((mode === "countdown" || mode === "padded-countdown") && inp.totalTokens !== undefined) {
+            const { used, total } = inp.totalTokens;
+            if (Number.isFinite(used) && Number.isFinite(total) && used >= 0 && total >= 0) {
+                const effectiveUsed = mode === "padded-countdown" ? (state.totalTokensFloor = Math.max(state.totalTokensFloor ?? 0, used)) : used;
+                (out ??= []).push({ source: "total_tokens_reminder", body: renderTotalTokensReminder(mode, total - effectiveUsed) });
+            }
+        }
+    }
     if (inp.config.backgroundTasks && state.postCompactPending) {
         state.postCompactPending = false;
         if (inp.backgroundTasks !== undefined && inp.backgroundTasks.length > 0) {
@@ -362,6 +381,10 @@ export function commitInstructionsChange(state, announced) {
 export function renderBudgetUsd(used, total) {
     return `USD budget: $${used}/$${total}; $${total - used} remaining`;
 }
+export function renderTotalTokensReminder(mode, remaining) {
+    const shown = mode === "infinite" ? "Infinite" : mode === "fixed" ? TOTAL_TOKENS_FIXED_ARM_VALUE : Math.max(0, remaining);
+    return `<total_tokens>${shown} tokens left</total_tokens>`;
+}
 export function renderOrphanedBackgroundTasks(tasks) {
     const safe = (t) => sanitizeUntrustedText(t, SHELLED_BODY_ENVELOPE_TAGS);
     return (`The container was restarted. The following background tasks were running and are now stopped:\n` +

package/dist/core/store-contracts/checkpoint-store-contract.js

@@ -212,6 +212,25 @@ export async function checkpointStoreContract(make, runAssertion) {
         const stored = (await store.get(bitless.token)).pendingAction;
         assert.equal("hasBidiControls" in stored, false, "projection backfill must not write back to the row");
     });
+    run("#457 previewWithheld three-form matrix: a row's spelling survives + projects; absent stays absent; an out-of-contract spelling reads as absent", async () => {
+        const store = make();
+        const oversize = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "pw-oversize" });
+        oversize.pendingAction.previewWithheld = "oversize";
+        const unavailable = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "pw-unavailable" });
+        unavailable.pendingAction.previewWithheld = "unavailable";
+        const absent = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "pw-absent" });
+        const bogus = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "pw-bogus" });
+        bogus.pendingAction.previewWithheld = "shrugged";
+        for (const cp of [oversize, unavailable, absent, bogus])
+            await store.put(cp.token, cp);
+        const back = (await store.get(oversize.token)).pendingAction;
+        assert.equal(back.previewWithheld, "oversize", "the row's previewWithheld must survive the round-trip verbatim");
+        const byId = new Map((await store.listByScope("tenant-a")).map((s) => [s.sessionId, s]));
+        assert.equal(byId.get("pw-oversize")?.previewWithheld, "oversize");
+        assert.equal(byId.get("pw-unavailable")?.previewWithheld, "unavailable");
+        assert.equal("previewWithheld" in byId.get("pw-absent"), false, "absent must project the key OMITTED, not null/empty");
+        assert.equal("previewWithheld" in byId.get("pw-bogus"), false, "an out-of-contract spelling must read as absent, never project verbatim");
+    });
     await settle();
 }
 const sortByToken = (a, b) => a.token.localeCompare(b.token);

package/dist/core/task-notification.d.ts

@@ -148,28 +148,28 @@ export interface ExternalNotificationInput {
 export interface SystemInjection<TPayload = unknown> {
     kind: "task_notification";
     /**
-     * design/116 §7 — in THIS engine every priority delivers at the NEXT turn boundary via
-     * `harness.steer()`, mid-work included, in ARRIVAL order (consecutive frames batch); `priority`
-     * affects only the park/uplink path. A delivery that races the agent going idle parks on
-     * PendingSessionNotifications for the session's next run; `drain()` serves that parked lane.
+     * design/373 — the injection ladder is LIVE (all three values carry delivery semantics, the CC
+     * 2.1.223 form; the flat "every priority delivers at the next boundary" era ended with this
+     * design — its H-1 anchor-correction note is preserved in the design archive, and the ruled
+     * changes it named are exactly what landed here):
      *
-     * **Anchor correction (backlog #389 伴生 / hallucination audit H-1).** The 2026-08-05 re-anchor
-     * justified flattening the ladder with "CC's queued task-notification inputs are UNCONDITIONALLY
-     * deliverable at the boundary (CC 2.1.221)". That sentence is FALSE as a statement about CC, on
-     * 221 and 223 alike: the mid-turn fold is gated at `getCommandsByMaxPriority("next")`
-     * (`pretty221.js:449195` / `pretty223.js:415586`), which admits `now`+`next` and EXCLUDES `later`
-     * — and `enqueuePendingNotification` defaults to `later`. CC's background-completion notices fold
-     * mid-turn because they explicitly say `priority:"next"`; its ultraplan/artifact notices take the
-     * default and deliberately do NOT. So all three of CC's values carry live delivery semantics
-     * (`now` = abort the running turn, `next` = fold into it, `later` = wait for the next one).
+     *  - `"next"` — the running turn's NEXT boundary (mid-work included), arrival order, consecutive
+     *    engine-note frames batch. The pre-373 behavior, byte-identical (the regression baseline).
+     *  - `"later"` — never folded into the work in progress: delivered at the run's natural
+     *    would-otherwise-stop seat (its own closing turn). A run that never reaches that seat
+     *    (abort/maxTurns) re-pends the frame per session — the session's NEXT run delivers it at
+     *    turn-open. Structural honesty note: once parked, delivery depends on a next run HAPPENING
+     *    (this engine does not own an idle process the way the CC client does) — a recorded
+     *    weakening, not a bug.
+     *  - `"now"` — `"next"`'s delivery guarantee PLUS the boundary is manufactured early: on the
+     *    notification lane the frame takes the queue's class head and the earliest natural boundary
+     *    (NO turn interrupt — interrupt authority belongs exclusively to the caller-provenance
+     *    steer face, `TaskStream.steer({ priority: "now" })`; the external `notify()` verb REFUSES
+     *    `"now"` typed). An unknown value is refused at every entry (bad-value loudness).
      *
-     * The engineering conclusion the re-anchor reached — a background completion must reach a busy
-     * model at the boundary rather than starve behind a "deliver only when it would otherwise stop"
-     * rule — stands on its own. What does not stand is the claim that CC has no ladder. Restoring the
-     * `later` = "do not fold into the running turn" arm is a behavior-face change and `now` = "abort
-     * the running turn" is a new capability; both are ruled changes, not silent ones. Until then the
-     * gap is DISCLOSED at the injection funnel rather than left as a silently inert knob (`now` is
-     * announced, an unknown value is refused) — the bad-value loudness rule.
+     * Park/uplink: the pend store carries the frame's priority ({@link PendingSessionNotifications})
+     * and the turn-open batch delivers priority-major (pend order within a class); a record with no
+     * carried priority ranks AS `later` and its wire field stays honestly absent.
      */
     priority: SystemInjectionPriority;
     dedupKey: string;
@@ -180,6 +180,13 @@ export interface SystemInjection<TPayload = unknown> {
      *  fire-and-forget producer (no receipt to honor). */
     onDisposition?: (d: "queued" | "parked") => void;
 }
+/** design/373 (adversarial r3, recorded rule): the key deliberately EXCLUDES the injection tier.
+ *  The key names an EVENT's identity; `priority` is delivery metadata about one submission of it.
+ *  A repeat under an in-flight key therefore FOLDS regardless of the repeat's tier — the tier of
+ *  record is the FIRST accept's, and the folded caller's "queued" receipt is true of that standing
+ *  entry. A producer that wants a NEW occurrence delivered under a different tier mints a fresh
+ *  `seq` (the documented repeat discipline); silently migrating a queued frame between lanes on a
+ *  repeat, or refusing the repeat typed, would each turn a dedup fold into a delivery mutation. */
 export declare function taskNotificationDedupKey(n: Pick<TaskNotificationPayload, "task_id" | "task_type" | "status" | "seq">): string;
 /**
  * RB-142 — the lane-scoped identity of a task, extracted from {@link taskNotificationDedupKey} so every
@@ -247,9 +254,27 @@ export declare const MAX_PENDING_SESSIONS = 100;
  * preference applies, so "terminal" can never mean two things in this module.
  */
 export declare function isDelegatedAgentTerminal(n: Pick<TaskNotificationPayload, "task_type" | "status">): boolean;
+/**
+ * design/373 (#445 saturation prerequisite) — is this frame a TERMINAL notification (any lane)?
+ * Reuses {@link TERMINAL_STATUSES} — the same terminal-vs-event rule the pending store's eviction
+ * preference applies, so "terminal" can never mean two things in this module. The runner marks
+ * INTERNAL-lane terminal frames cap-preferred at the delivery queue's mouth: a watcher's event
+ * storm may delay its own batches, never crowd a completion out of the run waiting on it. The
+ * external lane never gets the preference (its `status` is caller-supplied — an untrusted injector
+ * must not be able to claim the internal completions' reservation); this predicate itself stays
+ * lane-blind, the trust cut is the marking site's.
+ */
+export declare function isTerminalTaskNotification(n: Pick<TaskNotificationPayload, "status">): boolean;
 export interface DrainedPendingNotifications {
-    /** Chronological (pend order) payloads still held when the session's next run drained. */
+    /** Payloads still held when the session's next run drained. design/373 §3.5: batch order is
+     *  PRIORITY-MAJOR (now < next < later; a record with no carried priority ranks AS later —
+     *  the conservative seat), pend order (chronological) within a class — the idle-dequeue form. */
     items: TaskNotificationPayload[];
+    /** design/373 §3.5 — the parked priority per item, keyed by payload identity, present exactly for
+     *  records whose pend CARRIED one. A missing key is a fact (a tier-unknown park — e.g.
+     *  the harness's undrained sweep hands payloads back without their lane's priority): the wire
+     *  field stays honestly absent rather than fabricating `later`. */
+    priorities?: Map<TaskNotificationPayload, SystemInjectionPriority>;
     /** task_id → notifications evicted by the bounds while pending (never delivered). `taskType` remembers
      *  the victim's lane so a survivors-none disclosure can still render an honest synthetic payload. */
     /** RB-142: keyed by {@link taskNotificationLaneKey}, NOT the bare `task_id` — the external lane's ids are
@@ -288,8 +313,10 @@ export declare class PendingSessionNotifications {
     /** RB-143: whole-session losses whose tombstone was itself evicted — the count survives, the attribution
      *  does not. Surfaced on the next session-level disclosure so it is never simply forgotten. */
     private unattributedDrops;
-    pend(sessionId: string, n: TaskNotificationPayload): void;
-    /** Remove and return the session's pendings (one-shot — the next run consumes them exactly once). */
+    pend(sessionId: string, n: TaskNotificationPayload, priority?: SystemInjectionPriority): void;
+    /** Remove and return the session's pendings (one-shot — the next run consumes them exactly once).
+     *  design/373 §3.5: the batch comes out PRIORITY-MAJOR (stable sort — pend order within a class;
+     *  a no-priority record ranks as later), the idle-dequeue min-value-first form. */
     drain(sessionId: string): DrainedPendingNotifications | undefined;
     get size(): number;
 }

package/dist/core/task-notification.js

@@ -92,12 +92,15 @@ const TERMINAL_STATUSES = new Set(["completed", "failed", "killed", "cancelled"]
 export function isDelegatedAgentTerminal(n) {
     return n.task_type === "background_agent" && TERMINAL_STATUSES.has(n.status);
 }
+export function isTerminalTaskNotification(n) {
+    return TERMINAL_STATUSES.has(n.status);
+}
 export class PendingSessionNotifications {
     sessions = new Map();
     droppedSessions = 0;
     evictedSessions = new Map();
     unattributedDrops = 0;
-    pend(sessionId, n) {
+    pend(sessionId, n, priority) {
         let s = this.sessions.get(sessionId);
         if (s === undefined) {
             if (this.sessions.size >= MAX_PENDING_SESSIONS) {
@@ -119,7 +122,7 @@ export class PendingSessionNotifications {
                     }
                 }
             }
-            s = { items: [], dropped: new Map(), keys: new Set() };
+            s = { items: [], dropped: new Map(), keys: new Set(), priorities: new Map() };
             this.sessions.set(sessionId, s);
         }
         const key = taskNotificationDedupKey(n);
@@ -127,6 +130,8 @@ export class PendingSessionNotifications {
             return;
         s.keys.add(key);
         s.items.push(n);
+        if (priority !== undefined)
+            s.priorities?.set(n, priority);
         const lane = taskNotificationLaneKey(n);
         let mine = 0;
         for (const i of s.items)
@@ -139,8 +144,14 @@ export class PendingSessionNotifications {
     }
     drain(sessionId) {
         const s = this.sessions.get(sessionId);
-        if (s !== undefined)
+        if (s !== undefined) {
             this.sessions.delete(sessionId);
+            const rank = (n) => {
+                const p = s.priorities?.get(n);
+                return p === "now" ? 0 : p === "next" ? 1 : 2;
+            };
+            s.items = [...s.items].sort((a, b) => rank(a) - rank(b));
+        }
         const tomb = this.evictedSessions.get(sessionId);
         if (tomb === undefined && this.unattributedDrops === 0)
             return s;
@@ -163,6 +174,7 @@ function evictOldest(s, match) {
         return;
     const victim = s.items.splice(idx, 1)[0];
     s.keys.delete(taskNotificationDedupKey(victim));
+    s.priorities?.delete(victim);
     const laneKey = taskNotificationLaneKey(victim);
     const prior = s.dropped.get(laneKey);
     s.dropped.set(laneKey, { count: (prior?.count ?? 0) + 1, taskType: victim.task_type, taskId: victim.task_id });
@@ -190,10 +202,14 @@ export function discloseDroppedPending(drained) {
         if (dropped === undefined || disclosed.has(lane))
             return n;
         disclosed.add(lane);
-        return {
+        const annotated = {
             ...n,
             summary: `[${n.task_id}] ${dropped.count} earlier pending notification(s) from this task were dropped (pending-queue overflow). ${n.summary}`,
         };
+        const priority = drained.priorities?.get(n);
+        if (priority !== undefined)
+            drained.priorities?.set(annotated, priority);
+        return annotated;
     });
     for (const [lane, dropped] of drained.dropped) {
         if (disclosed.has(lane))

package/dist/core/tool-errors.d.ts

@@ -118,7 +118,8 @@ export type WorkerErrorClass = "budget" | "limit" | "output" | "suspend" | "revi
  * The `limits.` namespace splits into the `budget` and `limit` classes by exact code — see
  * {@link EXACT_CODE_CLASS}. Operation-level dotted codes that are surfaced to a *caller* and never become a
  * task outcome are deliberately OUT of scope: `steering.*` (`steering.not_running`/`steering.invalid_content`/
- * `steering.duplicate_input_id`, rejected to the `steer()` caller) and `mcp.*` (`mcp.server_unavailable`, an `onWarn` warning code) — neither
+ * `steering.duplicate_input_id`/`steering.blocked_by_hook`, rejected to the `steer()` caller — the fourth also
+ * rides the resume face as a `CheckpointError` code) and `mcp.*` (`mcp.server_unavailable`, an `onWarn` warning code) — neither
  * reaches `TaskResult.errorCode`, so a caller will never pass them here. A genuinely unmapped code → `"unknown"` (which therefore means
  * "known-but-foreign or no code", e.g. a leaked fs/Node code, NOT "an OUR terminal class we forgot to add").
  */

package/dist/core/tool-policy.d.ts

@@ -853,6 +853,33 @@ export interface AskRequest {
      *  with contextual escaping and show {@link args} alongside — the preview can misrepresent the
      *  executable action and never replaces args. Never adjudication input. */
     readonly preview?: unknown;
+    /**
+     * #457 ② — PRESENT ⇔ this tool DECLARES an approval preview and the gate could not present a usable
+     * one, naming which way it failed: `"oversize"` (produced, but past the 16KiB display bound — the
+     * truncation stub still rides {@link preview}) or `"unavailable"` (the projection threw, or its value
+     * has no JSON serialization, so nothing was produced at all).
+     *
+     * ABSENT is the ordinary world and covers three cases that are NOT withholdings: the tool declares no
+     * preview, the projection declined to speak for these args, and the projection succeeded. A surface
+     * must therefore read presence, never absence: absence is not a claim that the preview is faithful.
+     *
+     * A DISCLOSURE, not a verdict and not a transform — the same posture as {@link hasBidiControls}. Core
+     * refuses nothing and narrows nothing on account of it: {@link args} and {@link boundInputHash} are
+     * always carried, so unlike a surface whose only content IS the projection, a core approval card can
+     * still show the person exactly what will run. What the bit buys is the honest sentence a card owes
+     * when it is rendering less than the tool meant it to — and the ground for a surface that chooses to
+     * withhold its own PERSISTENT "allow and stop asking me this" affordance while the action cannot be
+     * reviewed as intended (upstream's form: a withheld preview vetoes the standing row, leaving one-time
+     * approval only). Core deliberately does NOT apply that veto to {@link ruleOffers} itself — core's
+     * offers speak for shell COMMAND text, which rides `args` and is shown whatever the preview did.
+     *
+     * Filled at the ask MINT sites that resolve a preview (the synchronous gate leg), not at `resolveAsk`
+     * — the chokepoint receives an already-built request and has no tool table to project from. The
+     * durable park leg's twin is `PendingAction.tool_approval.previewWithheld` on the row, judged over
+     * that row's own fidelity-projected args snapshot; the two faces can honestly differ exactly as the
+     * bidi bit's two faces can.
+     */
+    readonly previewWithheld?: "oversize" | "unavailable";
     /** Canonical digest of {@link args} as presented in THIS ask, computed by the engine's one
      *  `boundInputHashOf` — the same digest a durable park binds its checkpoint to, so an aggregating
      *  approver can reconcile a synchronous ask row against a parked checkpoint row for the same call