@sema-agent/core 5.60.1 → 5.61.0

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/types.d.ts

@@ -4177,6 +4177,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 +4386,43 @@ 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.
      */
     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 +4430,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 +5048,20 @@ 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.
      *
      *  - `"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

package/dist/engine/harness/agent-harness.d.ts

@@ -1,4 +1,4 @@
-import type { ActorAssertion, AssistantMessage, ImageContent, Model } from "../llm/index.js";
+import type { ActorAssertion, AssistantMessage, ImageContent, Model, UserMessage } from "../llm/index.js";
 import type { AgentMessage, AgentTool, LoopMalformedToolUseRecovery, LoopThinkingOnlyRecovery, LoopTruncatedOutputRecovery, QueueMode, ThinkingLevel } from "../loop/types.js";
 import { type EngineSegment } from "../../core/untrusted-text.js";
 import type { AbortResult, AgentHarnessEvent, AgentHarnessEventResultMap, AgentHarnessOptions, AgentHarnessOwnEvent, AgentHarnessResources, AgentHarnessStreamOptions, ExecutionEnv, PromptTemplate, Skill } from "./types.js";
@@ -47,6 +47,22 @@ export interface UserMessageProvenance {
      *  the parked-steer queue needs (pre-framing text + trust + inputId), which only the minting seam
      *  knows — hence opaque. */
     parkRecord?: unknown;
+    /** design/373 — an IMMEDIATE-class ("now") frame: the steer-lane enqueue inserts it ahead of the
+     *  first non-immediate frame (FIFO among immediates — the dequeue-priority form), the loop's
+     *  pre-request re-check sweeps it into the imminent turn, and {@link AgentHarness.interruptTurn}
+     *  may force the boundary for it. Class metadata only (a sidecar, judged at the mint) — it never
+     *  rides the message or the wire, and it grants NOTHING by itself: the interrupt is a separate,
+     *  caller-provenance verb. */
+    immediate?: true;
+    /** design/373 (#445 saturation prerequisite) — terminal-preference at the engine-note backlog
+     *  cap: when the target queue's engine-note count is AT the cap, a frame carrying this mark
+     *  displaces the OLDEST non-preferred engine-note frame instead of being refused — the displaced
+     *  payload is handed to the undrained sink (the runner's lossless per-session park lane), so a
+     *  watcher's event storm can delay its own batches but never crowd a terminal completion out of
+     *  the run that is waiting on it (the pend store's terminal-preferred eviction, mirrored at the
+     *  queue mouth). Only meaningful WITH `enginePayload`; a preferred frame among only preferred
+     *  frames still gets the cap refusal (nothing displaceable). */
+    capPreferred?: true;
 }
 /**
  * Harness-level recovery wiring (design/118 ④b/⑤). The loop's prompt-too-long seam wants a
@@ -190,6 +206,9 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     private loopRecovery?;
     /** roadmap #5 (CC Stop hook): the runner-wired stop gate — see {@link setStopGate}. */
     private stopGate?;
+    /** design/373 — the loop-published turn-scoped AbortController (live exactly while a main turn's
+     *  work phase is in flight; `undefined` between turns). Read by {@link interruptTurn} only. */
+    private turnInterruptSeat?;
     private handlers;
     constructor(options: AgentHarnessOptions<TSkill, TPromptTemplate, TTool>);
     private getHandlers;
@@ -264,12 +283,49 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
      *  engine lanes each check the halt fact before injecting, so this arm exists for the lane that
      *  does not — including the one not written yet. */
     private refuseHeldEngineInjection;
+    /** design/373 — returns the minted queue frame (or `undefined` on the empty-injection no-op), so
+     *  a caller-provenance immediate steer can hand the SAME frame to {@link interruptTurn} (the
+     *  consumption guard is identity-keyed). Additive: every existing caller awaited `void`. */
     steer(text: string, options?: {
         images?: ImageContent[];
-    } & UserMessageProvenance): Promise<void>;
+    } & UserMessageProvenance): Promise<UserMessage | undefined>;
     followUp(text: string, options?: {
         images?: ImageContent[];
     } & UserMessageProvenance): Promise<void>;
+    /**
+     * design/373 §3.4 — force the running turn's boundary FOR a queued immediate-class frame:
+     * abort the CURRENT main turn (provider stream + tool batch — never the run, never boundary
+     * housekeeping), whose loop-side settlement reconciles the cut and continues the run with the
+     * frame at the queue head. Best-effort accelerator by contract: `false` means no interruption
+     * happened AND none was needed — the frame is already consumed or already rides the imminent
+     * boundary — so delivery semantics are exactly the non-interrupting ones either way.
+     *
+     * Guards, in order:
+     *  - an unwinding run (`abort()` latched) owns its ending — never contest it;
+     *  - CONSUMPTION guard (r4/R3-1): the frame must still sit in the steer queue. Drained/consumed ⇒
+     *    it is already part of a turn's input — aborting THAT turn would cut the very delivery this
+     *    verb exists to speed up. Same-tick check-then-abort (single-threaded: no window);
+     *  - seat liveness: no published turn (idle tail / between turns / boundary housekeeping) ⇒ no-op,
+     *    the frame rides the next boundary; an already-fired seat ⇒ idempotent no-op (one boundary per
+     *    turn — later immediates join the same boundary batch).
+     */
+    interruptTurn(frame: AgentMessage): boolean;
+    /**
+     * design/373 §3.3 (the final-commit-point double check) — how many queued injection frames a
+     * boundary drain could deliver RIGHT NOW: both lanes, minus frames the current state refuses to
+     * drain (an unwinding run drains nothing — those frames belong to the terminal account; a live
+     * human-halt hold skips engine-authored frames). Synchronous and side-effect-free by contract:
+     * the loop reads it between its last drain and the terminal commit, with zero awaits.
+     */
+    pendingInjectionCount(): number;
+    /** design/373 §3.4-3 — the pre-request re-check's drain half (see the loop-config seam): sweep
+     *  queued immediate-class frames into the imminent turn's batch, merged at the class position
+     *  (after immediates already pending, ahead of everything else — FIFO within the class holds
+     *  across the drain/re-check split). Same booking discipline as {@link drainQueuedMessages}
+     *  (in-flight account, queue_update broadcast, consumption sink, throw-rollback); the hold skips
+     *  engine-authored immediates exactly as the boundary drain would (a theoretical lane today —
+     *  no engine mint issues immediates — held by construction rather than by remembering). */
+    private absorbImmediateSteering;
     nextTurn(text: string, options?: {
         images?: ImageContent[];
     } & UserMessageProvenance): Promise<void>;

package/dist/engine/harness/agent-harness.js

@@ -38,6 +38,8 @@ const engineNotePayloads = new WeakMap();
 const engineAuthoredInjections = new WeakSet();
 const userInputParkRecords = new WeakMap();
 const drainedFromLane = new WeakMap();
+const immediateClassInjections = new WeakSet();
+const capPreferredInjections = new WeakSet();
 function isEngineAuthoredInjection(options) {
     if (options === undefined)
         return false;
@@ -257,6 +259,7 @@ export class AgentHarness {
     nextTurnQueue = [];
     loopRecovery;
     stopGate;
+    turnInterruptSeat;
     handlers = new Map();
     constructor(options) {
         this.env = options.env;
@@ -598,6 +601,11 @@ export class AgentHarness {
                 };
             },
             getSteeringMessages: async () => this.drainQueuedMessages(this.steerQueue, this.steeringQueueMode),
+            publishTurnInterruptSeat: (seat) => {
+                this.turnInterruptSeat = seat;
+            },
+            recheckImmediateInjections: async (pending) => this.absorbImmediateSteering(pending),
+            pendingInjectionCount: () => this.pendingInjectionCount(),
             getFollowUpMessages: async () => {
                 const queued = await this.drainQueuedMessages(this.followUpQueue, this.followUpQueueMode);
                 if (queued.length > 0)
@@ -841,9 +849,16 @@ export class AgentHarness {
     }
     async enqueueInjection(queue, text, options) {
         if (AgentHarness.emptyInjection(text, options))
-            return;
+            return undefined;
+        let displaced;
         if (options?.enginePayload !== undefined && queue.filter((q) => engineNotePayloads.has(q)).length >= ENGINE_NOTE_STEER_BACKLOG_CAP) {
-            throw new AgentHarnessError("invalid_state", `engine-note backlog at cap (${ENGINE_NOTE_STEER_BACKLOG_CAP}) — park the payload for the session's next run`);
+            const victimIdx = options.capPreferred === true
+                ? queue.findIndex((q) => engineNotePayloads.has(q) && !capPreferredInjections.has(q))
+                : -1;
+            if (victimIdx === -1) {
+                throw new AgentHarnessError("invalid_state", `engine-note backlog at cap (${ENGINE_NOTE_STEER_BACKLOG_CAP}) — park the payload for the session's next run`);
+            }
+            displaced = { frame: queue.splice(victimIdx, 1)[0], at: victimIdx };
         }
         const m = createUserMessage(text, options?.images, options);
         if (options?.enginePayload !== undefined)
@@ -852,8 +867,43 @@ export class AgentHarness {
             engineAuthoredInjections.add(m);
         if (options?.parkRecord !== undefined)
             userInputParkRecords.set(m, options.parkRecord);
-        queue.push(m);
-        await this.emitQueueUpdate();
+        if (options?.immediate === true)
+            immediateClassInjections.add(m);
+        if (options?.capPreferred === true && options?.enginePayload !== undefined)
+            capPreferredInjections.add(m);
+        if (options?.immediate === true && queue === this.steerQueue) {
+            let at = 0;
+            while (at < queue.length && immediateClassInjections.has(queue[at]))
+                at++;
+            queue.splice(at, 0, m);
+        }
+        else {
+            queue.push(m);
+        }
+        try {
+            await this.emitQueueUpdate();
+        }
+        catch (error) {
+            const at = queue.indexOf(m);
+            if (at !== -1) {
+                queue.splice(at, 1);
+                if (displaced !== undefined)
+                    queue.splice(Math.min(displaced.at, queue.length), 0, displaced.frame);
+                throw error;
+            }
+        }
+        if (displaced !== undefined) {
+            const victimPayload = engineNotePayloads.get(displaced.frame);
+            engineNotePayloads.delete(displaced.frame);
+            if (victimPayload !== undefined && this.onUndrainedEngineNotes) {
+                try {
+                    this.onUndrainedEngineNotes([victimPayload]);
+                }
+                catch {
+                }
+            }
+        }
+        return m;
     }
     refuseHeldEngineInjection(options) {
         if (isEngineAuthoredInjection(options) && this.engineInjectionsHeld?.() === true) {
@@ -865,7 +915,7 @@ export class AgentHarness {
             throw new AgentHarnessError("invalid_state", "Cannot steer while idle");
         }
         this.refuseHeldEngineInjection(options);
-        await this.enqueueInjection(this.steerQueue, text, options);
+        return await this.enqueueInjection(this.steerQueue, text, options);
     }
     async followUp(text, options) {
         if (this.phase === "idle") {
@@ -874,6 +924,66 @@ export class AgentHarness {
         this.refuseHeldEngineInjection(options);
         await this.enqueueInjection(this.followUpQueue, text, options);
     }
+    interruptTurn(frame) {
+        if (this.aborting)
+            return false;
+        if (!this.steerQueue.includes(frame))
+            return false;
+        const seat = this.turnInterruptSeat;
+        if (seat === undefined || seat.signal.aborted)
+            return false;
+        seat.abort();
+        return true;
+    }
+    pendingInjectionCount() {
+        if (this.aborting)
+            return 0;
+        const held = this.engineInjectionsHeld?.() === true;
+        const drainable = (q) => held ? q.filter((m) => !engineAuthoredInjections.has(m)).length : q.length;
+        return drainable(this.steerQueue) + drainable(this.followUpQueue);
+    }
+    async absorbImmediateSteering(pending) {
+        if (this.aborting)
+            return pending;
+        const held = this.engineInjectionsHeld?.() === true;
+        const taken = [];
+        for (let i = 0; i < this.steerQueue.length; i++) {
+            const m = this.steerQueue[i];
+            if (!immediateClassInjections.has(m))
+                break;
+            if (held && engineAuthoredInjections.has(m))
+                continue;
+            taken.push(...this.steerQueue.splice(i, 1));
+            i--;
+        }
+        if (taken.length === 0)
+            return pending;
+        for (const m of taken)
+            drainedFromLane.set(m, "steer");
+        this.drainedPendingInjection.push(...taken);
+        try {
+            await this.emitQueueUpdate();
+            for (const m of taken) {
+                const payload = engineNotePayloads.get(m);
+                if (payload !== undefined) {
+                    try {
+                        this.onEngineNoteConsumed?.(payload);
+                    }
+                    catch {
+                    }
+                }
+            }
+        }
+        catch (error) {
+            this.steerQueue.unshift(...taken);
+            this.unbookInFlight(taken);
+            throw normalizeHookError(error);
+        }
+        let at = 0;
+        while (at < pending.length && immediateClassInjections.has(pending[at]))
+            at++;
+        return [...pending.slice(0, at), ...taken, ...pending.slice(at)];
+    }
     async nextTurn(text, options) {
         await this.enqueueInjection(this.nextTurnQueue, text, options);
     }