@sema-agent/core 7.29.0 → 7.30.1

package/dist/core/runner-deps.d.ts

@@ -6,6 +6,7 @@
  */
 import type { Model } from "../internal/llm.js";
 import type { AgentDefinition } from "./agent-definition.js";
+import type { ContextSettings } from "./context-settings.js";
 import type { BackgroundChildEvent, DelegationLifecycleEvent } from "./delegation-frames.js";
 import type { EngineNotice } from "./engine-notice.js";
 import type { HandsBandOptions } from "./hands-band.js";
@@ -113,6 +114,22 @@ export interface RunnerDeps {
     brain: Brain;
     /** Catalog used to resolve string ModelRefs to Model objects. */
     models?: Record<string, Model>;
+    /**
+     * The deployment's per-model CONTEXT-WINDOW overlay, keyed by CATALOG WORD ({@link ContextSettings}):
+     * `contextTokens` / `autoCompactTokens` / `enabled` over what the model card declares.
+     *
+     * It is the ONE hot-swappable seat an IN-FLIGHT leg re-reads. Every other seat follows the snapshot law
+     * (a running task keeps the deps object it prepared under) because those seats are the routing card —
+     * endpoint, credentials, price, fence — and a request in flight must reach what it was priced for. The
+     * usable window is not the card: it is a setting, and an operator who lowers it is asking the legs
+     * running RIGHT NOW to compact sooner, which is exactly what they were unable to do while the number
+     * lived on the model object. Read at every turn boundary, every recovery pass, the end-of-task summary
+     * and every request build; clamped to the physical window by the one resolver.
+     *
+     * A leg that was handed a `Model` OBJECT (or resolved one through a `select` criteria) has no catalog
+     * word and therefore no overlay — the pin is the caller saying "this exact model, as declared".
+     */
+    contextSettings?: ContextSettings;
     /**
      * design/338 (mid-turn MCP revocation) — the HOST's revocation ledger, probed synchronously at
      * every MCP dispatch (tool call + the three resource tools) BEFORE the transport. The engine
@@ -512,9 +529,11 @@ export interface RunnerDeps {
      * {@link InMemoryFileHistoryStore}; a deployment supplies a durable backend behind the same seam
      * (backends MUST reuse the exported env-half helpers — see the contract JSDoc). Works against ANY
      * ExecutionEnv (local or remote): bytes are read/written through the env's FileSystem face and
-     * stored host-side, so an env rebuild does not lose history.
+     * stored host-side, so an env rebuild does not lose history. `"disabled"` = the deployment DECIDED
+     * not to capture: the omitted-key semantics minus the once-per-Runner `onError` advisory an omitted
+     * key earns on a filesystem-capable run (`classification: "file-history-no-store"`).
      */
-    fileHistoryStore?: import("./file-history-store.js").FileHistoryStore;
+    fileHistoryStore?: import("./file-history-store.js").FileHistoryStore | "disabled";
     /**
      * design/381 DV-14 (终审落锤) — what an Edit/Write/NotebookEdit does when its FIRST-TOUCH history
      * record cannot be persisted (`FileHistoryStore.trackEdit` answered `{ok:false}` = NO durable
@@ -877,12 +896,12 @@ export interface RunnerDeps {
         maxConcurrent?: number;
         maxCumulativePerSession?: number;
     };
-    /** design/176 — deployment tuning for the always-on peer-message admission gate (SendMessage entry
-     *  judgment: rate/dedup/hop-chain/queue bounds). Per-field range-validated against the upstream
-     *  table with out-of-range values falling back to that field's default; there is NO off switch —
-     *  absent means the default table, not "guard off". Threaded into the auto-mounted SendMessage as
-     *  `SendMessageToolOptions.admission`; read per call (a value change governs the next message). */
-    peerAdmission?: Partial<import("../agents/peer-admission.js").PeerAdmissionConfig>;
+    /** The peer lane's ONE knob table (`PeerLaneConfig`): the always-on admission gate (rate/dedup/hop-chain/
+     *  queue bounds), the wake and per-pass delivery budgets, and the `ListAgents` freshness window. Per-field
+     *  range-validated with out-of-range values falling back to that field's default, announced once; there
+     *  is NO off switch — absent means the default table. Threaded into the auto-mounted SendMessage as
+     *  `SendMessageToolOptions.lane` and into the session-box drain; read per call / per pass. */
+    peerLane?: Partial<import("../agents/peer-admission.js").PeerLaneConfig>;
     /**
      * design/385 §2.1 / §5.1 — the peer-session DIRECTORY: the discovery truth of the cross-session
      * lane (other sessions of this engine for the same user). A HOST implements the contract (cli: the
@@ -917,6 +936,16 @@ export interface RunnerDeps {
      * {@link peerDirectory}.
      */
     crossSessionDialogExpiry?: import("../agents/peer-notices.js").CrossSessionDialogExpiry | (() => import("../agents/peer-notices.js").CrossSessionDialogExpiry | undefined);
+    /**
+     * The deployment's CAPABILITY FLOOR for durable engine frames: `true` declares that EVERY process
+     * that drains this deployment's session boxes reads `engine_frame` records (this engine's codec or
+     * newer). With it, an engine-minted task-notification frame addressed to an idle session parks in
+     * the session's durable box (`MailboxPeerMeta.kind: "engine_frame"`) and survives a process restart;
+     * without it (absent / `false`) such a frame parks in process exactly as before. A deployment flips
+     * it only after every drainer is upgraded — a pre-codec drainer reads the record as a peer's words.
+     * Inert without a cross-process-safe {@link mailboxStore}.
+     */
+    sessionBoxEngineFrames?: boolean;
     /**
      * 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
@@ -1266,11 +1295,13 @@ export interface RunnerDeps {
         phase: "compaction" | "prompt-cache" | "prompt-constitution" | "degraded" | "config" | "memory" | "mcp" | "a2a" | "interrupt-reconcile" | "suggestions" | "rewind" | "hook";
         sessionId: string;
         /**
-         * Machine-readable sub-classification when the phase has one — currently the design/31
-         * cache-break detector's root cause (`"model-switch" | "tool-schema" | "tool-set" |
-         * "system-prefix" | "server-or-ttl"`). Lets the host pick its own log level: `"server-or-ttl"`
-         * is usually benign in agentic tasks (slow tools ⇒ 5min+ request gaps expire provider caches —
-         * service[64] flag②) and warrants info/warn, while the prefix-bug causes warrant attention.
+         * Machine-readable sub-classification when the site has one (a kebab-case word naming the arm) —
+         * e.g. the design/31 cache-break detector's root cause (`"model-switch" | "tool-schema" |
+         * "tool-set" | "system-prefix" | "server-or-ttl"`), or the file-history liveness arms
+         * (`"file-history-no-store"` / `"file-history-no-env"`). Lets the host pick its own log level:
+         * `"server-or-ttl"` is usually benign in agentic tasks (slow tools ⇒ 5min+ request gaps expire
+         * provider caches — service[64] flag②) and warrants info/warn, while the prefix-bug causes
+         * warrant attention.
          */
         classification?: string;
     }) => void;

package/dist/core/secret-env.js

@@ -1,4 +1,5 @@
-const SECRET_ENV_RE = /(^|_)(KEY|TOKEN|SECRET|SECRETS|PASSWORD|PASSWD|CREDENTIAL|CREDENTIALS|PRIVATEKEY|APIKEY|ACCESS_KEY|SESSION_TOKEN)(?:_(?:\d+|ID))?$/i;
+const TOKEN_COUNT_WORDS = ["MAX", "OUTPUT", "INPUT", "THINKING", "NUM", "TOTAL"];
+const SECRET_ENV_RE = new RegExp(`(^|_)(KEY|KEYS|TOKEN|(?<!(?:^|_)(?:${TOKEN_COUNT_WORDS.join("|")})_)TOKENS|SECRET|SECRETS|PASSWORD|PASSWORDS|PASSWD|CREDENTIAL|CREDENTIALS|PRIVATEKEY|APIKEY|ACCESS_KEY|SESSION_TOKEN)(?:_(?:\\d+|ID))?$`, "i");
 const SECRET_ENV_EXACT_NAMES = new Set([
     "DATABASE_URL", "CONNECTION_STRING", "DSN", "NPM_AUTH",
     "PGPASSWORD", "MYSQL_PWD", "SSHPASS", "GPG_PASSPHRASE", "GH_PAT", "GITHUB_PAT",

package/dist/core/swappable-deps.d.ts

@@ -12,11 +12,23 @@
  * the door refuses a key outside the set at run time (never a silent ignore — a hot-config driver
  * handing `{ brain }` must learn that the brain is not a swappable seat, not watch nothing happen).
  *
- * WHAT A SWAP MEANS — the natural snapshot, one sentence for every seat: a running task reads the deps
- * object it was handed at its prepare and holds that reference; a swap replaces the Runner's object, so
+ * WHAT A SWAP MEANS — the natural snapshot, one sentence for every ROUTING seat: a running task reads the
+ * deps object it was handed at its prepare and holds that reference; a swap replaces the Runner's object, so
  * every LATER prepare reads the new seat and every in-flight leg keeps the value it prepared under.
  * Nothing is re-routed, re-priced or re-fenced mid-run; the divergence window is exactly the in-flight
- * legs' lifetime, by design (the `swapModels` precedent, now the rule for the whole set).
+ * legs' lifetime, by design (the `swapModels` precedent).
+ *
+ * …WITH ONE SEAT OUTSIDE IT, and the boundary is the point rather than the exception: `contextSettings` is
+ * read LIVE by in-flight legs. The snapshot law protects the routing CARD — a request already in flight must
+ * reach the endpoint it was priced, credentialed and fenced for, and re-reading any of that mid-run buys
+ * nothing and breaks the request. A leg's usable WINDOW is not on that card: it is a setting about how much
+ * conversation may accumulate before the leg summarizes, the reference implementation keeps it off the model
+ * object for exactly this reason and re-reads it on every request (clamped to the model's physical window),
+ * and an operator who lowers it is asking the legs running RIGHT NOW to compact sooner — which is the whole
+ * request. So the window declarations live on their own seat (`context-settings.ts`), keyed by catalog word,
+ * and the legs read them at every boundary, every recovery pass, the end-of-task summary and every request
+ * build. Routing stays snapshotted; geometry follows the operator. The two are not the same question, and
+ * one law over both could only be wrong about one of them.
  *
  * KEY PRESENCE IS THE INSTRUCTION: a key present on the candidate is REPLACED (an explicit `undefined`
  * CLEARS an optional seat back to its engine default — `readFace: undefined` ⇒ the deployment declares
@@ -44,8 +56,11 @@ import type { RunnerDeps } from "./runner-deps.js";
  *                 deployment seat that resolution reads.
  *  - `writeFace` — the deployment's write-face declaration ({@link RunnerDeps.writeFace}); the read seat's
  *                 twin (same value gate, same in-flight snapshot rule, its own notice) and independent of it.
+ *  - `contextSettings` — the per-model context-window overlay ({@link RunnerDeps.contextSettings}); screened
+ *                 by the same value gate construction applies (`assertContextSettingsValue`). THE ONE SEAT
+ *                 IN-FLIGHT LEGS RE-READ — see the header: it carries geometry, not route.
  */
-export declare const SWAPPABLE_DEP_SEATS: readonly ["models", "tiers", "readFace", "writeFace"];
+export declare const SWAPPABLE_DEP_SEATS: readonly ["models", "tiers", "readFace", "writeFace", "contextSettings"];
 export type SwappableDepSeat = (typeof SWAPPABLE_DEP_SEATS)[number];
 /** The candidate a swap takes: the swappable seats of {@link RunnerDeps}, each optional (presence = instruction). */
 export type SwappableDeps = Pick<RunnerDeps, SwappableDepSeat>;
@@ -61,6 +76,7 @@ export declare const SWAP_SEAT_NOTICE: {
     readonly tiers: "config.models_swapped";
     readonly readFace: "config.read_face_swapped";
     readonly writeFace: "config.write_face_swapped";
+    readonly contextSettings: "config.context_settings_swapped";
 };
 /** The fence over the notice table: `never` while every seat has a row. */
 export type SwapNoticeTableCoversEverySeat = AssertAllKeysHandled<Exclude<SwappableDepSeat, keyof typeof SWAP_SEAT_NOTICE>>;

package/dist/core/swappable-deps.js

@@ -1,5 +1,6 @@
 import { assertContainmentFaceValue } from "../tools/fs/containment-face.js";
-export const SWAPPABLE_DEP_SEATS = ["models", "tiers", "readFace", "writeFace"];
+import { assertContextSettingsValue } from "./context-settings.js";
+export const SWAPPABLE_DEP_SEATS = ["models", "tiers", "readFace", "writeFace", "contextSettings"];
 const SWAPPABLE_DEP_SEAT_SET = new Set(SWAPPABLE_DEP_SEATS);
 export function isSwappableDepSeat(k) {
     return SWAPPABLE_DEP_SEAT_SET.has(k);
@@ -9,6 +10,7 @@ export const SWAP_SEAT_NOTICE = {
     tiers: "config.models_swapped",
     readFace: "config.read_face_swapped",
     writeFace: "config.write_face_swapped",
+    contextSettings: "config.context_settings_swapped",
 };
 export function screenSwappableDeps(next) {
     if (next === null || typeof next !== "object" || Array.isArray(next)) {
@@ -49,6 +51,9 @@ export function screenSwappableDeps(next) {
             case "writeFace":
                 candidate.writeFace = assertContainmentFaceValue(v, "write", "deps");
                 break;
+            case "contextSettings":
+                candidate.contextSettings = assertContextSettingsValue(v, "swapDeps");
+                break;
             default: {
                 const _exhaustive = seat;
                 throw new Error(`swapDeps: unhandled seat ${String(_exhaustive)}`);

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

@@ -629,6 +629,11 @@ export type TaskEvent = ({
     preserved_segment?: {
         firstKeptEntryId: string;
     };
+    /** Cross-session message frames that sat in the SUMMARIZED prefix of this pass — delivered
+     *  earlier and visible to the model for the turns since. A record still in the session's box is
+     *  handed over again by the engine (once; a second loss is disclosed `resupply_exhausted`), so
+     *  this counts what the summary swallowed, not what is gone. Present iff at least one. */
+    summarizedCrossSessionMessages?: number;
     /** CC post-compact file-restore parity (2026-07-03): the working files the engine
      *  re-read into the summary (attachWorkingFiles), attachment order. A shell renders CC's
      *  `Read {path} (…)` cards under the compaction divider from this. Absent when the feature is

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

@@ -107,6 +107,54 @@ export interface TaskNotificationPayload {
      *  semantics as the poll face's `partial_result` flag (one meaning across both surfaces). Absent on
      *  every other notification (a completed result is never flagged). */
     partial?: boolean;
+    /** Delegation lanes, terminal frames: the child's EXPLICIT `Agent({name})` spawn key — the same word
+     *  its `task_progress.spawnName`, roster row and hook identity carry, rendered as `<agent-name>` so
+     *  the parent can `SendMessage({to})` it by name. Minted from the identity the frame's producer holds
+     *  (never from the description); ABSENT = an unnamed delegation. */
+    spawnName?: string;
+    /** Delegation lanes, terminal frames — how the child's report reached this frame under the
+     *  hand-back contract: `send` = a report was delivered; `flagged` = delivered under the hand-back
+     *  screening's SECURITY WARNING; `withheld` = nothing was delivered (no result text, no partial text).
+     *  Absent on non-terminal frames and on the non-delegation lanes. The model face renders a
+     *  `<handback>` line only for `flagged` / `withheld` — the parent is told when a report did not
+     *  arrive plainly, and nothing for the ordinary case. */
+    handback?: HandbackState;
+    /** Delegation lanes, terminal frames, present iff the child's leg compacted its context at least once
+     *  or opened its compaction breaker: `passes` = landed compactions, `breakerOpen` = compaction was
+     *  disabled for the rest of the leg (later context was trimmed, not summarized), `kind` = the last
+     *  landed pass's trigger. The parent otherwise cannot tell that a child forgot. */
+    compaction?: {
+        passes: number;
+        breakerOpen: boolean;
+        kind?: CompactionKind;
+    };
+    /**
+     * The INBOX NOTICE carrier: one drain pass of this session's box stopped with records still waiting
+     * (the pass budget, an admission stop, a lane refusal). `pending` = records still leased and not yet
+     * injected when the pass ended; `delivered` = records injected this pass; `urgent` = how many of the
+     * waiting ones their sender marked urgent (absent = 0); `box` = the session box. Its PRESENCE is the
+     * render discriminator: the model reads ONE engine line (`[Inbox notice] …`), never a shell. Minted
+     * ONLY by the engine's session-box drain, keyed `task_id: "inbox:<box>"` with the pass counter as
+     * `seq` so it never collides with a message frame's key; absent when the pass emptied the box.
+     */
+    inboxNotice?: {
+        pending: number;
+        delivered: number;
+        urgent?: number;
+        resupplied?: number;
+        box: string;
+    };
+    /** #1036 — THIS occurrence is a RE-SUPPLY of a record the model was already shown once and
+     *  whose frame a compaction then summarized away. Same record, same `task_id`, same `seq`, a new
+     *  occurrence: `attempt` says which one. ABSENT = not a re-supply (a first delivery); there is no
+     *  `false` form. Only the session-box drain mints it. */
+    resupplied?: true;
+    /** #1036 — which DELIVERY ATTEMPT of this record's frame this occurrence is: 1 = the first
+     *  delivery, 2 = the one re-supply a summarized record gets. ABSENT = 1 (there is no `0`, and a
+     *  consumer must not read absence as "unknown"). It folds into the injection queue's dedup key
+     *  ({@link taskNotificationDedupKey}), which is what keeps a re-supply from collapsing into the
+     *  first occurrence's entry. Only the session-box drain mints it. */
+    attempt?: number;
     output_file?: string;
     /** Whatever the settling lane knows about its own spend, JSON-rendered verbatim into one `<usage>`
      *  tag. Deliberately untyped — the lanes report different quantities and nothing here should force
@@ -223,7 +271,7 @@ export interface SemaProvenance {
     /** `agent_message` = the same-process uplink (§1.4 d1); `cross_session_message` = the session-box
      *  drain (§4.1) — `from` is then the sender's ADDRESS, `taskId` the recipient's own box handle,
      *  `seq` the box seq, and the typed peer record rides in `peerMeta`. */
-    kind: "agent_message" | "cross_session_message" | "cross_session_notice";
+    kind: "agent_message" | "cross_session_message" | "cross_session_notice" | "inbox_notice";
     from: string;
     taskId: string;
     seq: number;
@@ -297,7 +345,7 @@ export interface SystemInjection<TPayload = unknown> {
  *  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;
+export declare function taskNotificationDedupKey(n: Pick<TaskNotificationPayload, "task_id" | "task_type" | "status" | "seq" | "attempt">): string;
 /**
  * The lane-scoped identity of a task, extracted from {@link taskNotificationDedupKey} so every
  * place that treats "same task" as one bucket applies the SAME lane rule.
@@ -349,7 +397,17 @@ export declare function renderCrossSessionMessageFrame(frame: NonNullable<TaskNo
  * defusal runs once more here so no carrier can smuggle a system-reminder into the model face.
  */
 export declare function renderCrossSessionNoticeLine(notice: NonNullable<TaskNotificationPayload["crossSessionNotice"]>): string;
+/** #1036 — the ONE preamble a re-supplied occurrence carries, ahead of whatever carrier it is
+ *  riding. It says the true thing (you read this once; the summary that replaced it did not keep it)
+ *  without asking the model to reconcile two copies: the first occurrence is gone from the context. */
+export declare const RESUPPLIED_FRAME_PREAMBLE = "[Re-supplied] You were shown this message once before; the compaction that replaced older context with a summary did not keep it, so the engine is handing it over again. It is the SAME message, not a new one \u2014 act on it once.";
 export declare function renderTaskNotificationXml(n: TaskNotificationPayload): string;
+/** The one sentence a parent reads about a child that compacted: how often, on what trigger, and
+ *  whether compaction gave up (after which older context was trimmed away rather than summarized). */
+export declare function renderCompactionDisclosure(c: NonNullable<TaskNotificationPayload["compaction"]>): string;
+/** The `[Inbox notice]` line — counts only, engine-authored; the records themselves arrive on their
+ *  own frames (this pass's) or the next passs', and the pull tool reads them on demand. */
+export declare function renderInboxNoticeLine(n: NonNullable<TaskNotificationPayload["inboxNotice"]>): string;
 /**
  * The BETWEEN-TURNS pending lane. A task notification born while the session has NO live lane at all
  * (every run of it is over, or the one that is live rejected the injection because its agent was
@@ -398,9 +456,75 @@ export interface SessionBoxBinding {
     handle: string;
     /** The session id the box belongs to — the `fromRoot` a durably parked child frame records. */
     sessionId: string;
+    /** The deployment's engine-frame floor (`RunnerDeps.sessionBoxEngineFrames`): `true` ⇒ an engine
+     *  frame parks in this box as an `engine_frame` record; otherwise it parks in process. */
+    engineFrames?: boolean;
     /** Where an append fault is disclosed (the frame then takes the in-process park — never lost). */
     onError?: (e: unknown) => void;
 }
+/** The hand-back contract's three words (see {@link TaskNotificationPayload.handback}). */
+export declare const HANDBACK_STATES: readonly ["send", "flagged", "withheld"];
+export type HandbackState = (typeof HANDBACK_STATES)[number];
+/** THE hand-back projection, one rule every terminal frame producer calls: a warning ⇒ `flagged`; any
+ *  report or partial text ⇒ `send`; neither ⇒ `withheld`. */
+export declare function handbackStateOf(facts: {
+    result?: string | undefined;
+    partialText?: string | undefined;
+    warning?: string | undefined;
+}): HandbackState;
+/** The three-way compaction trigger word a terminal frame carries (the wire's `forced` is `reactive` here). */
+export declare const COMPACTION_KINDS: readonly ["manual", "auto", "reactive"];
+export type CompactionKind = (typeof COMPACTION_KINDS)[number];
+/** The wire trigger word → the frame's kind word (`forced` = a reactive pass the run could not skip). */
+export declare function compactionKindOf(trigger: "auto" | "manual" | "forced"): CompactionKind;
+/**
+ * THE projection every delegation terminal frame calls for its identity + hand-back + context facets:
+ * the spawn key from the identity the producer holds (never the description), the hand-back state from
+ * the delivered text and the screening's warning, and the child's compaction record verbatim. Absent
+ * inputs stay absent; `handback` is always minted (a terminal always says how the report reached it).
+ */
+export declare function terminalFrameFacets(facts: {
+    spawnName?: string | undefined;
+    result?: string | undefined;
+    partialText?: string | undefined;
+    warning?: string | undefined;
+    compaction?: TaskNotificationPayload["compaction"] | undefined;
+}): Pick<TaskNotificationPayload, "spawnName" | "handback" | "compaction">;
+/** The codec version this engine writes into an `engine_frame` record and the highest it reads. */
+export declare const ENGINE_FRAME_CODEC_VERSION = 1;
+/** The engine's own lanes — the only frames the durable park may encode (an `external` event never is). */
+export declare const ENGINE_FRAME_TASK_TYPES: readonly ["background_agent", "monitor", "workflow"];
+/** May this frame take the durable engine-frame park? Its lane must be one of the engine's own and it
+ *  must wear no shell-less carrier. */
+export declare function isEngineFrameParkable(payload: TaskNotificationPayload): boolean;
+/** The record text of a durably parked engine frame: the codec version, the injection tier it was
+ *  submitted at, and the frame itself (its own `seq` is the lane's cycle count — a different domain
+ *  from the box seq, carried inside untouched). */
+export declare function encodeEngineFrame(payload: TaskNotificationPayload, priority: SystemInjectionPriority): string;
+export type EngineFrameDecode = {
+    ok: true;
+    payload: TaskNotificationPayload;
+    priority: SystemInjectionPriority;
+}
+/** A version this engine does not read: the record is a NEWER engine's; leave it for one. */
+ | {
+    ok: false;
+    reason: "newer";
+    codecVersion: number;
+}
+/** Not this codec at all (or a frame outside the engine's lanes): settle it without delivery. */
+ | {
+    ok: false;
+    reason: "malformed";
+    detail: string;
+};
+/** Read an `engine_frame` record back. Every field the lane reads is re-typed here; a carrier the
+ *  writer must never have encoded is dropped rather than trusted. */
+export declare function decodeEngineFrame(content: string): EngineFrameDecode;
+/** The durable form of an engine frame: the codec text under `kind: "engine_frame"`, stamped with
+ *  the box owner as `fromRoot` (the park seat's own fact, as for a peer-words record); no hop chain —
+ *  it is not a peer message and is never admitted as one. */
+export declare function engineFrameRecordOf(payload: TaskNotificationPayload, priority: SystemInjectionPriority, box: Pick<SessionBoxBinding, "sessionId">): MailboxAppendMessage;
 /**
  * RB-375 A2 (ruled 2026-08-03) — is this frame the TERMINAL of a delegated background agent?
  *
@@ -616,6 +740,24 @@ export declare class PendingSessionNotifications {
     markDelivered(sessionId: string, dedupKey: string): void;
     get size(): number;
 }
+/**
+ * The durable box appends ONE run leg caused — its obligations. Attribution is by execution: an append
+ * belongs to the leg whose execution (its tools, its producers, its teardown reap, a child terminal it
+ * hands up the delegation chain) reached the park seat, whichever lane's routing carried it there. A
+ * leg's teardown awaits its own obligations and nobody else's — another session's pending append is
+ * never a condition of this leg's completion. A park reached outside any leg is nobody's obligation.
+ */
+export declare class DurableAppendObligations {
+    private static readonly scope;
+    private readonly inFlight;
+    /** The obligations of the leg whose execution is running now; undefined outside every leg. */
+    static current(): DurableAppendObligations | undefined;
+    /** Run `body` as this leg (synchronous: the body's own return value, no added tick). */
+    run<R>(body: () => R): R;
+    track(p: Promise<unknown>): void;
+    /** Resolves when every append this leg caused has settled — the fault arm already re-parked in process. */
+    settle(): Promise<void>;
+}
 /**
  * WHERE A FRAME ADDRESSED TO ONE SESSION GOES — the single decision, so the two addresses that ask it
  * (a run's own session, and the delegation tree's root anchor) cannot drift apart. Three outcomes:

package/dist/core/task-notification.js

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { escapeEnvelopeTag, inlineUntrusted, sanitizeUntrustedText } from "./untrusted-text.js";
 import { PEER_MESSAGE_NOTICE } from "../agents/peer-admission.js";
 import { buildCrossSessionEnvelope, CROSS_SESSION_MESSAGE_NOTICE, neutralizePeerBody } from "../agents/cross-session-envelope.js";
@@ -24,6 +25,9 @@ const TASK_NOTIFICATION_TAGS = [
     "recent-steps",
     "edited-files",
     "resumable",
+    "agent-name",
+    "handback",
+    "context",
 ];
 function renderResidual(n) {
     const lines = [];
@@ -36,14 +40,22 @@ function renderResidual(n) {
     return lines.length > 0 ? lines.join("\n") : undefined;
 }
 function tag(name, value) {
-    const text = sanitizeUntrustedText(String(value), TASK_NOTIFICATION_TAGS)
+    let shown;
+    try {
+        shown = typeof value === "string" ? value : String(value);
+    }
+    catch {
+        shown = `[unrenderable ${typeof value}]`;
+    }
+    const text = sanitizeUntrustedText(shown, TASK_NOTIFICATION_TAGS)
         .replace(/&/g, "&")
         .replace(/</g, "&lt;")
         .replace(/>/g, "&gt;");
     return `<${name}>${text}</${name}>`;
 }
 export function taskNotificationDedupKey(n) {
-    return `task_notification:${taskNotificationLaneKey(n)}:${n.status}${n.seq !== undefined ? `:${n.seq}` : ""}`;
+    const attempt = n.attempt !== undefined && Number.isInteger(n.attempt) && n.attempt > 1 ? `:a${n.attempt}` : "";
+    return `task_notification:${taskNotificationLaneKey(n)}:${n.status}${n.seq !== undefined ? `:${n.seq}` : ""}${attempt}`;
 }
 export function taskNotificationLaneKey(n) {
     return n.task_type === "external" ? `external:${n.task_id}` : n.task_id;
@@ -64,13 +76,20 @@ export function renderCrossSessionMessageFrame(frame) {
 export function renderCrossSessionNoticeLine(notice) {
     return sanitizeUntrustedText(notice.text);
 }
+export const RESUPPLIED_FRAME_PREAMBLE = "[Re-supplied] You were shown this message once before; the compaction that replaced older context with a summary did not keep it, so the engine is handing it over again. It is the SAME message, not a new one \u2014 act on it once.";
 export function renderTaskNotificationXml(n) {
+    const body = renderTaskNotificationCarrier(n);
+    return n.resupplied === true ? `${RESUPPLIED_FRAME_PREAMBLE}\n\n${body}` : body;
+}
+function renderTaskNotificationCarrier(n) {
     if (n.agentMessage !== undefined)
         return renderAgentMessageFrame(n.agentMessage);
     if (n.crossSessionMessage !== undefined)
         return renderCrossSessionMessageFrame(n.crossSessionMessage);
     if (n.crossSessionNotice !== undefined)
         return renderCrossSessionNoticeLine(n.crossSessionNotice);
+    if (n.inboxNotice !== undefined)
+        return renderInboxNoticeLine(n.inboxNotice);
     const usage = n.usage === undefined
         ? undefined
         : (() => {
@@ -92,6 +111,8 @@ export function renderTaskNotificationXml(n) {
         tag("task-type", n.task_type),
         ...(n.toolUseId !== undefined ? [tag("tool-use-id", n.toolUseId)] : []),
         tag("status", n.status),
+        ...(n.spawnName !== undefined ? [tag("agent-name", n.spawnName)] : []),
+        ...(n.handback !== undefined && n.handback !== "send" ? [tag("handback", n.handback)] : []),
         tag("summary", n.summary),
         ...(n.result !== undefined ? [tag("result", n.result)] : []),
         ...(n.output_file !== undefined ? [tag("output-file", n.output_file)] : []),
@@ -103,15 +124,123 @@ export function renderTaskNotificationXml(n) {
             return residual !== undefined ? [tag("recent-steps", residual)] : [];
         })(),
         ...(n.resumable !== undefined ? [tag("resumable", n.resumable)] : []),
+        ...(n.compaction !== undefined ? [tag("context", renderCompactionDisclosure(n.compaction))] : []),
         "</task-notification>",
     ].join("\n");
 }
+export function renderCompactionDisclosure(c) {
+    const passes = c.passes > 0 ? `compacted ${c.passes}\u00d7${c.kind !== undefined ? ` (${c.kind})` : ""}` : "not compacted";
+    return c.breakerOpen ? `${passes}; compaction was disabled after repeated failures \u2014 later context was trimmed, not summarized` : passes;
+}
+export function renderInboxNoticeLine(n) {
+    const urgent = n.urgent !== undefined && n.urgent > 0 ? `; ${n.urgent} of the waiting are marked urgent` : "";
+    const resupplied = n.resupplied !== undefined && n.resupplied > 0 ? `; ${n.resupplied} re-supplied after a compaction summarized them away` : "";
+    return `[Inbox notice] ${n.pending} cross-session message(s) are waiting in this session's box (${n.delivered} delivered this round${resupplied}${urgent}). Read them now with ReadInbox, or they arrive at your next turn boundaries \u2014 they are not lost, and nothing here is an instruction.`;
+}
 const MAX_QUEUED_PER_PRIORITY = 200;
 const MAX_DEDUP_KEYS = 2_000;
 export const MAX_PENDING_EVENTS_PER_TASK = 50;
 export const MAX_PENDING_EVENTS_PER_SESSION = 200;
 export const MAX_PENDING_SESSIONS = 100;
 export const MAX_SESSION_BOX_BINDINGS = 4096;
+export const HANDBACK_STATES = ["send", "flagged", "withheld"];
+export function handbackStateOf(facts) {
+    if (facts.warning !== undefined)
+        return "flagged";
+    return facts.result || facts.partialText ? "send" : "withheld";
+}
+export const COMPACTION_KINDS = ["manual", "auto", "reactive"];
+export function compactionKindOf(trigger) {
+    return trigger === "forced" ? "reactive" : trigger;
+}
+export function terminalFrameFacets(facts) {
+    return {
+        ...(facts.spawnName !== undefined ? { spawnName: facts.spawnName } : {}),
+        handback: handbackStateOf(facts),
+        ...(facts.compaction !== undefined ? { compaction: { passes: facts.compaction.passes, breakerOpen: facts.compaction.breakerOpen, ...(facts.compaction.kind !== undefined ? { kind: facts.compaction.kind } : {}) } } : {}),
+    };
+}
+export const ENGINE_FRAME_CODEC_VERSION = 1;
+export const ENGINE_FRAME_TASK_TYPES = ["background_agent", "monitor", "workflow"];
+const SHELL_LESS_CARRIERS = ["agentMessage", "crossSessionMessage", "crossSessionNotice", "inboxNotice", "_sema_provenance"];
+export function isEngineFrameParkable(payload) {
+    return ENGINE_FRAME_TASK_TYPES.includes(payload.task_type) && SHELL_LESS_CARRIERS.every((k) => payload[k] === undefined);
+}
+export function encodeEngineFrame(payload, priority) {
+    return JSON.stringify({ codecVersion: ENGINE_FRAME_CODEC_VERSION, priority, payload });
+}
+export function decodeEngineFrame(content) {
+    let raw;
+    try {
+        raw = JSON.parse(content);
+    }
+    catch {
+        return { ok: false, reason: "malformed", detail: "not JSON" };
+    }
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return { ok: false, reason: "malformed", detail: "not an object" };
+    const r = raw;
+    const version = r["codecVersion"];
+    if (typeof version !== "number" || !Number.isInteger(version) || version < 1)
+        return { ok: false, reason: "malformed", detail: "codecVersion missing" };
+    if (version > ENGINE_FRAME_CODEC_VERSION)
+        return { ok: false, reason: "newer", codecVersion: version };
+    const priority = r["priority"];
+    if (!isSystemInjectionPriority(priority))
+        return { ok: false, reason: "malformed", detail: "priority outside the ladder" };
+    const p = r["payload"];
+    if (p === null || typeof p !== "object" || Array.isArray(p))
+        return { ok: false, reason: "malformed", detail: "payload missing" };
+    const f = p;
+    if (typeof f["task_id"] !== "string" || f["task_id"] === "")
+        return { ok: false, reason: "malformed", detail: "task_id missing" };
+    if (!ENGINE_FRAME_TASK_TYPES.includes(f["task_type"]))
+        return { ok: false, reason: "malformed", detail: "task_type outside the engine's lanes" };
+    if (typeof f["status"] !== "string" || typeof f["summary"] !== "string")
+        return { ok: false, reason: "malformed", detail: "status/summary missing" };
+    const facet = malformedFacet(f);
+    if (facet !== undefined)
+        return { ok: false, reason: "malformed", detail: facet };
+    const payload = { ...p };
+    for (const k of SHELL_LESS_CARRIERS)
+        delete payload[k];
+    return { ok: true, payload, priority };
+}
+const SPAWN_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+function malformedFacet(f) {
+    if (f["spawnName"] !== undefined && (typeof f["spawnName"] !== "string" || !SPAWN_NAME_RE.test(f["spawnName"])))
+        return "spawnName outside the spawn-name grammar";
+    if (f["handback"] !== undefined && !(typeof f["handback"] === "string" && HANDBACK_STATES.includes(f["handback"])))
+        return "handback outside its closed set";
+    const steps = f["recentSteps"];
+    if (steps !== undefined && !(Array.isArray(steps) && steps.every((s) => s !== null && typeof s === "object" && typeof s.tool === "string" && typeof s.target === "string" && typeof s.outcome === "string")))
+        return "recentSteps is not a list of steps";
+    const edits = f["editedFiles"];
+    if (edits !== undefined && !(Array.isArray(edits) && edits.every((e) => e !== null && typeof e === "object" && typeof e.path === "string" && typeof e.edits === "number")))
+        return "editedFiles is not a list of files";
+    if (f["lines"] !== undefined && !(Array.isArray(f["lines"]) && f["lines"].every((l) => typeof l === "string")))
+        return "lines is not a list of strings";
+    const c = f["compaction"];
+    if (c !== undefined) {
+        if (c === null || typeof c !== "object" || Array.isArray(c))
+            return "compaction is not an object";
+        const { passes, breakerOpen, kind } = c;
+        if (typeof passes !== "number" || !Number.isInteger(passes) || passes < 0)
+            return "compaction.passes is not a count";
+        if (typeof breakerOpen !== "boolean")
+            return "compaction.breakerOpen is not a boolean";
+        if (kind !== undefined && !(typeof kind === "string" && COMPACTION_KINDS.includes(kind)))
+            return "compaction.kind outside its closed set";
+    }
+    return undefined;
+}
+export function engineFrameRecordOf(payload, priority, box) {
+    return {
+        content: encodeEngineFrame(payload, priority),
+        sentAt: Date.now(),
+        peerMeta: { fromRoot: box.sessionId, kind: "engine_frame" },
+    };
+}
 const MAX_TOMBSTONES = 5_000;
 const TERMINAL_STATUSES = new Set(["completed", "failed", "killed", "cancelled"]);
 export function isDelegatedAgentTerminal(n) {
@@ -327,6 +456,24 @@ export class PendingSessionNotifications {
         return this.sessions.size;
     }
 }
+export class DurableAppendObligations {
+    static scope = new AsyncLocalStorage();
+    inFlight = new Set();
+    static current() {
+        return DurableAppendObligations.scope.getStore();
+    }
+    run(body) {
+        return DurableAppendObligations.scope.run(this, body);
+    }
+    track(p) {
+        this.inFlight.add(p);
+        void p.finally(() => this.inFlight.delete(p));
+    }
+    async settle() {
+        while (this.inFlight.size > 0)
+            await Promise.allSettled([...this.inFlight]);
+    }
+}
 export function routeOrParkNotification(store, sessionId, payload, priority, onDisposition) {
     const dedupKey = taskNotificationDedupKey(payload);
     if (store.holdsKey(sessionId, dedupKey)) {
@@ -337,9 +484,10 @@ export function routeOrParkNotification(store, sessionId, payload, priority, onD
     if (routed === "unavailable") {
         const box = store.sessionBoxFor(sessionId);
         const carrier = payload.agentMessage;
-        if (box !== undefined && carrier !== undefined) {
+        const durable = box !== undefined && (carrier !== undefined || (box.engineFrames === true && isEngineFrameParkable(payload)));
+        if (box !== undefined && durable) {
             store.noteDurablePark(sessionId, dedupKey);
-            const record = sessionBoxRecordOf({ ...payload, agentMessage: carrier }, box);
+            const record = carrier !== undefined ? sessionBoxRecordOf({ ...payload, agentMessage: carrier }, box) : engineFrameRecordOf(payload, priority, box);
             let appended;
             try {
                 appended = Promise.resolve(box.mailbox.append(box.scope, box.handle, record));
@@ -347,7 +495,7 @@ export function routeOrParkNotification(store, sessionId, payload, priority, onD
             catch (e) {
                 appended = Promise.reject(e);
             }
-            appended.then(() => onDisposition?.("parked_durably"), (e) => {
+            const settled = appended.then(() => onDisposition?.("parked_durably"), (e) => {
                 store.forgetDurablePark(sessionId, dedupKey);
                 try {
                     box.onError?.(e);
@@ -357,6 +505,7 @@ export function routeOrParkNotification(store, sessionId, payload, priority, onD
                 store.pend(sessionId, payload, priority);
                 onDisposition?.("parked");
             });
+            DurableAppendObligations.current()?.track(settled);
             return;
         }
         store.pend(sessionId, payload, priority);