@sema-agent/core 7.29.0 → 7.30.0

package/dist/core/auto-compaction.js

@@ -1,3 +1,4 @@
+import { CROSS_SESSION_MESSAGE_TAG } from "../agents/cross-session-envelope.js";
 import { DEFAULT_CHARS_PER_TOKEN, DEFAULT_CLAMP_TOLERANCE, DEFAULT_COMPACTION_SETTINGS, CompactionError, compact, computeFileLists, dryRunSummarizationClamp, estimateContextTokens, estimateTokens, formatFileOperations, formatPersistedOutputRefs, prepareCompaction, shouldCompact, } from "../internal/harness.js";
 import { fileArgPath } from "../tools/fs/safety.js";
 import { contextEditFrontier, resolveTriggerWindow } from "./context-edit.js";
@@ -81,9 +82,13 @@ export async function maybeCompact(opts) {
     const structuralTokens = ctx.messages.reduce((sum, m) => sum + estimateTokens(m, cpt), 0);
     const anchorStale = est.usageTokens > 0 && est.tokens > structuralTokens * STALE_ANCHOR_STRUCTURAL_MARGIN + overhead;
     const tokens = anchorStale || est.usageTokens === 0 ? structuralTokens + overhead : est.tokens;
-    const window = resolveTriggerWindow(opts.model).window;
+    const window = resolveTriggerWindow(opts.model, opts.contextOverlay).window;
     const windowKnown = Number.isFinite(window) && window > 0;
-    const windowField = opts.model.autoCompactTokens != null ? "autoCompactTokens" : opts.model.contextTokens != null ? "contextTokens" : "contextWindow";
+    const windowField = (opts.contextOverlay?.autoCompactTokens ?? opts.model.autoCompactTokens) != null
+        ? "autoCompactTokens"
+        : (opts.contextOverlay?.contextTokens ?? opts.model.contextTokens) != null
+            ? "contextTokens"
+            : "contextWindow";
     const settings = sanitizeCompactionSettings(rawSettings, window);
     const contextUsage = windowKnown
         ? { usedTokens: tokens, windowTokens: window, compactAtTokens: window - settings.reserveTokens }
@@ -459,6 +464,17 @@ export async function maybeCompact(opts) {
         ...(opts.activeTools !== undefined && opts.activeTools.length > 0 ? { activeTools: [...opts.activeTools] } : {}),
         ...(opts.gitRestate !== undefined ? { gitAnnouncement: { kind: opts.gitRestate.pending.kind, hash: opts.gitRestate.pending.hash, pending: true } } : {}),
     }, false);
+    if (opts.onCommitted !== undefined) {
+        const firstKeptIdx = branch.findIndex((e) => e.id === firstKeptEntryId);
+        const effect = firstKeptIdx >= 0
+            ? { summarizedEntryIds: new Set(branch.slice(0, firstKeptIdx).map((e) => e.id)) }
+            : { summarizedEntryIds: "unknown" };
+        try {
+            opts.onCommitted(effect);
+        }
+        catch {
+        }
+    }
     if (opts.gitRestate !== undefined) {
         try {
             await opts.gitRestate.land();
@@ -514,6 +530,7 @@ export async function maybeCompact(opts) {
         }), "compaction.postCompact");
     }
     const endAt = Date.now();
+    const summarizedCrossSessionMessages = countSummarizedCrossSessionMessages(branch, firstKeptEntryId);
     return {
         contextUsage,
         compacted: true,
@@ -522,6 +539,7 @@ export async function maybeCompact(opts) {
         triggerTokens: tokens,
         postTriggerTokens,
         firstKeptEntryId,
+        ...(summarizedCrossSessionMessages > 0 ? { summarizedCrossSessionMessages } : {}),
         reused,
         naturalTrigger,
         durationMs: endAt - compactStartAt,
@@ -558,9 +576,24 @@ export function mintCompactedEvent(comp, trigger, identity) {
         ...(comp.fallbackReason !== undefined ? { fallbackReason: comp.fallbackReason } : {}),
         ...(comp.clampedRatio !== undefined ? { clampedRatio: comp.clampedRatio } : {}),
         ...(comp.clampReason !== undefined ? { clampReason: comp.clampReason } : {}),
+        ...(comp.summarizedCrossSessionMessages !== undefined ? { summarizedCrossSessionMessages: comp.summarizedCrossSessionMessages } : {}),
         ...identity,
     };
 }
+export function countSummarizedCrossSessionMessages(branch, firstKeptEntryId) {
+    const firstKeptIdx = branch.findIndex((e) => e.id === firstKeptEntryId);
+    const summarized = firstKeptIdx >= 0 ? branch.slice(0, firstKeptIdx) : branch;
+    let n = 0;
+    for (const e of summarized) {
+        if (e.type !== "message" || e.message === undefined || e.message.role !== "user" || e.message.provenance !== "engine-note")
+            continue;
+        const c = e.message.content;
+        const text = typeof c === "string" ? c : Array.isArray(c) ? c.map((b) => (b !== null && typeof b === "object" && b.type === "text" ? String(b.text ?? "") : "")).join("") : "";
+        if (text.startsWith(`<${CROSS_SESSION_MESSAGE_TAG} `) || text.startsWith(`<${CROSS_SESSION_MESSAGE_TAG}>`))
+            n += 1;
+    }
+    return n;
+}
 export function nextTrimForceBackoff(prev, comp, trimForced = false) {
     if (trimForced && comp.naturalTrigger !== true && comp.compacted && comp.freedTokens !== undefined && comp.freedTokens <= 0) {
         return true;

package/dist/core/child-clamp-seats.d.ts

@@ -77,3 +77,14 @@ export interface ChildClampSource {
  * — so a clamp can never end one level deep, and a new seat cannot reach some constructors and not others.
  */
 export declare function childClampSeats(source: ChildClampSource): Partial<TaskSpec>;
+/**
+ * The OWN posture of an engine-built leg that never asks the person (the observer sidecar, the verifier): no
+ * human-facing tool is mounted AND the leg declares itself headless. Both, always together — the spec's posture
+ * outranks the one a leg inherits from its parent or its deployment, and the prepare door refuses an
+ * "interactive" posture paired with `interactiveTools: false`, so a leg that stated only the clamp was refused
+ * under every interactive parent. Spread ABOVE {@link childClampSeats}: a caller clamp can only tighten it.
+ */
+export declare function engineHeadlessLegSeats(): {
+    interactiveTools: false;
+    interactionPosture: "headless";
+};

package/dist/core/child-clamp-seats.js

@@ -27,3 +27,6 @@ export function childClampSeats(source) {
             : {}),
     };
 }
+export function engineHeadlessLegSeats() {
+    return { interactiveTools: false, interactionPosture: "headless" };
+}

package/dist/core/context-edit.d.ts

@@ -1,5 +1,6 @@
 import type { AgentMessage } from "../internal/harness.js";
 import type { Model } from "../internal/llm.js";
+import { type ContextWindowOverlay } from "./context-settings.js";
 /**
  * Small-window FLOOR fraction of the clearStale/compaction frontier (see {@link contextEditFrontier},
  * which is the single source for both the clearStale budget and the compaction-threshold clamp).
@@ -224,7 +225,7 @@ export interface TriggerWindowResolution {
  * chain is the drift this function exists to end. Non-finite/≤0 declared values keep their historic
  * meaning (each consumer's own unknown-window sentinel), deliberately untouched here.
  */
-export declare function resolveTriggerWindow(model: Model): TriggerWindowResolution;
+export declare function resolveTriggerWindow(model: Model, overlay?: ContextWindowOverlay): TriggerWindowResolution;
 /** The token budget at which context-editing begins for a model (below the harder guard trim).
  *  = {@link contextEditFrontier} of the model's AUTOCOMPACT window (CC-parity fixed deduction with
  *  a 0.7 small-window floor) — the same point the compaction threshold is clamped to. Dual-window
@@ -232,7 +233,7 @@ export declare function resolveTriggerWindow(model: Model): TriggerWindowResolut
  *  trim (`guardBudget`) stays on the physical window — which is why the window is read through
  *  {@link resolveTriggerWindow}: an autocompact window declared ABOVE the physical one would put
  *  this frontier above the guard (inverted geometry), so it is clamped there (slice 1b, X5). */
-export declare function editBudget(model: Model): number;
+export declare function editBudget(model: Model, overlay?: ContextWindowOverlay): number;
 /** Content fingerprint of an occurrence — a sha-256 digest over the FULL canonical content form
  *  (per block: type + complete text bytes, and for non-text blocks the mime type + payload length
  *  + a payload head), replay's mis-paint guard (adversarial rounds 1+2): ordinal mapping alone

package/dist/core/context-edit.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { DEFAULT_CHARS_PER_TOKEN, estimateTokens } from "../internal/harness.js";
 import { isToolResult } from "./message-utils.js";
+import { physicalWindowOf } from "./context-settings.js";
 import { PERSISTED_OUTPUT_PREFIX, offloadPagebackHint } from "./tool-result-store.js";
 import { assertNoRetiredKeys } from "./retired-keys.js";
 import { compactableToolNames } from "./tool-registry.js";
@@ -179,9 +180,9 @@ export function clearStaleToolResults(messages, opts) {
     reportCleared(opts.onCleared, clears, tokensSaved);
     return out;
 }
-export function resolveTriggerWindow(model) {
-    const physical = model.contextTokens ?? model.contextWindow;
-    const declared = model.autoCompactTokens;
+export function resolveTriggerWindow(model, overlay) {
+    const physical = physicalWindowOf(model, overlay);
+    const declared = overlay?.autoCompactTokens ?? model.autoCompactTokens;
     if (declared !== undefined &&
         Number.isFinite(declared) &&
         declared > 0 &&
@@ -192,8 +193,8 @@ export function resolveTriggerWindow(model) {
     }
     return { window: declared ?? physical, clamped: false };
 }
-export function editBudget(model) {
-    const window = resolveTriggerWindow(model).window;
+export function editBudget(model, overlay) {
+    const window = resolveTriggerWindow(model, overlay).window;
     if (!Number.isFinite(window) || window <= 0) {
         return Number.POSITIVE_INFINITY;
     }

package/dist/core/context-guard.d.ts

@@ -1,5 +1,6 @@
 import type { AgentMessage } from "../internal/harness.js";
 import type { Model } from "../internal/llm.js";
+import { type ContextWindowOverlay } from "./context-settings.js";
 /**
  * Last-resort, in-task context trim. Proper compaction (LLM summary) runs *between* tasks;
  * this prevents a single task whose internal tool-loop balloons from overflowing the window.
@@ -99,4 +100,4 @@ charsPerToken?: number): GitFrameGuardOutcome;
  *  above the compaction/clearStale frontier. Dual-window semantics: deliberately the PHYSICAL
  *  window (`contextTokens ?? contextWindow`), NOT `autoCompactTokens` — the guard protects the
  *  real request limit; a lowered autocompact window only moves the trigger-side geometry. */
-export declare function guardBudget(model: Model): number;
+export declare function guardBudget(model: Model, overlay?: ContextWindowOverlay): number;

package/dist/core/context-guard.js

@@ -1,5 +1,6 @@
 import { DEFAULT_CHARS_PER_TOKEN, estimateContextTokens, estimateTokens } from "../internal/harness.js";
 import { isToolResult, messageRole } from "./message-utils.js";
+import { physicalWindowOf } from "./context-settings.js";
 const GUARD_FRACTION = 0.85;
 const GUARD_HEADROOM_TOKENS = 23000;
 function isSummary(m) {
@@ -190,8 +191,8 @@ export function protectGitFrame(before, trimmed, budgetTokens, frame, charsPerTo
     }
     return { action: "over_budget" };
 }
-export function guardBudget(model) {
-    const window = model.contextTokens ?? model.contextWindow;
+export function guardBudget(model, overlay) {
+    const window = physicalWindowOf(model, overlay);
     if (!Number.isFinite(window) || window <= 0) {
         return Number.POSITIVE_INFINITY;
     }

package/dist/core/context-settings.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The deployment's per-model CONTEXT-WINDOW overlay — the one deployment seat an IN-FLIGHT leg re-reads.
+ *
+ * WHY IT IS NOT ON THE MODEL. `Model.contextTokens` / `Model.autoCompactTokens` are two things at once: the
+ * geometry a leg measures itself against, and part of the immutable routing card a leg was handed at its
+ * prepare. The hot-swap law (`swappable-deps.ts`) is right about the card — nothing is re-routed, re-priced or
+ * re-fenced mid-run, because a running request must reach the endpoint it was priced and credentialed for.
+ * It was wrong about the geometry: an operator who lowers a model's usable window is not re-routing anything,
+ * they are changing a SETTING, and a leg that keeps filling the retired window until it ends is the one thing
+ * they were trying to prevent. The reference implementation keeps that setting off the model card for exactly
+ * this reason and re-reads it on every request, clamping it to the model's physical window.
+ *
+ * So the overlay lives here, keyed by CATALOG WORD — the same word `ModelRef` already speaks. A leg carries
+ * the ref that chose its model (`ResolvedRole.modelRef` → the harness → `ToolExecuteContext.modelRef`), so
+ * the lookup is a plain read with no reverse search: an id→word search cannot answer (one model is reachable
+ * under several words, two words may route to one id, and an object-pinned model has no word at all), and a
+ * leg that knows its own word needs no search.
+ *
+ * WHAT IT DOES NOT DO. It carries no routing, credential, price or fence field, and never will: those are the
+ * card, and the card stays snapshotted. An OBJECT-pinned leg (a spec that named a `Model`, a `select` criteria)
+ * has no word and therefore no overlay — the pin is the caller saying "this exact model, as declared".
+ */
+import type { Model } from "../internal/llm.js";
+import type { ModelRef } from "./model-seat.js";
+/**
+ * One model's overlay. Every member is a DECLARATION the deployment may change between requests; an absent
+ * member means "whatever the model card says", never a value.
+ *  · `contextTokens` — the usable physical window (the model card's `contextTokens ?? contextWindow`).
+ *  · `autoCompactTokens` — the trigger-side window (dual-window semantics: lowers the compaction trigger and
+ *    the context-editing frontier without touching the physical request budget). Clamped to the physical
+ *    window by the one resolver, exactly as a model-card declaration is.
+ *  · `enabled` — compaction for legs on this model, the deployment's twin of `TaskSpec.compaction.enabled`
+ *    and with the same reach (the routine boundary pass, the recovery pass and the end-of-task summary —
+ *    one gate, inside `maybeCompact`, fed by one settings assembly). A request that states its own
+ *    `compaction.enabled` outranks it: the request is the author, this seat is the deployment's default —
+ *    the same "the spec's own value wins, the deployment fills an unset one" law every other seat follows.
+ */
+export interface ContextWindowOverlay {
+    readonly contextTokens?: number;
+    readonly autoCompactTokens?: number;
+    readonly enabled?: boolean;
+}
+/**
+ * The seat: catalog word → overlay. Words absent from the table are "nothing declared".
+ *
+ * @contract context_settings.geometry_is_read_live — this is the ONE deployment seat a leg re-reads while it
+ * runs: every window number a leg is measured against (the compaction trigger, the sanitize clamp, the
+ * context-editing frontier, the request guard, the disclosed `contextUsage`) is taken from the overlay in
+ * force at the moment of THAT question, keyed by the word that chose the leg's current model, so a swap
+ * reaches boundaries of legs already in flight; the leg's ROUTING — endpoint, credentials, price, fence, the
+ * `Model` object itself — stays the generation the leg prepared under, and this seat can never carry any of
+ * it. A leg whose model was pinned as an object has no word and is never overlaid.
+ */
+export type ContextSettings = Readonly<Record<string, ContextWindowOverlay>>;
+/**
+ * The overlay in force for a leg, read at the moment of the question. `ref` is the leg's own catalog word
+ * (`AgentHarness.getModelRef()` / `ResolvedRole.modelRef`); a `Model` OBJECT answers `undefined` because a
+ * pinned model has no word for the table to key on. OWN-property read: a word like `"constructor"` must mean
+ * "a key this deployment declared", never `Object.prototype`'s answer.
+ *
+ * The leg's own word first; when it declares nothing, the words it STANDS IN FOR — a tier word the default
+ * role answers with, a CC alias, `best` — as the tier expansion recorded them ({@link tierAliasVia}): only
+ * words that name the very model the leg's word resolves to, so a deployment key that a tier word passes by
+ * but that names ANOTHER model is never read. Nothing is found by searching for a model.
+ */
+export declare function contextOverlayFor(settings: ContextSettings | undefined, ref: ModelRef | undefined, catalog?: {
+    models?: Record<string, Model>;
+}): ContextWindowOverlay | undefined;
+/**
+ * Every word the overlay declares must be a word of the model catalog (the deployment's keys, the tier words
+ * and aliases its `tiers` expanded) — `config.context_settings_unknown_word`. A misspelled word keys a leg
+ * nobody can run, so it would govern nothing while reading as in force. Checked at construction and on every
+ * swap against the catalog the swap leaves in force, so a catalog swap that would orphan a declared word is
+ * refused too. Returns `settings`.
+ */
+export declare function assertContextSettingsWords<T extends ContextSettings | undefined>(settings: T, models: Record<string, Model> | undefined, where: string): T;
+/**
+ * The seat's VALUE GATE — the same one the hot-swap door and the construction path apply, so a value the door
+ * admits is a value every later read admits. A malformed overlay is refused LOUDLY rather than repaired
+ * quietly: a window silently dropped back to the model card's is the misconfiguration this seat exists to make
+ * visible. `undefined` (the seat cleared) passes through.
+ *
+ * `where` names the caller in the message (`"swapDeps"` / `"RunnerDeps"`), since the two paths are the two
+ * moments an operator can get it wrong.
+ */
+export declare function assertContextSettingsValue(v: unknown, where: string): ContextSettings | undefined;
+/** Does a REQUEST's own `compaction.enabled` stand, or does the deployment's overlay decide? One law, stated
+ *  once: the request is the author, the deployment fills an unset one, and nothing declared means ON. */
+export declare function compactionEnabled(specEnabled: boolean | undefined, overlay: ContextWindowOverlay | undefined): boolean;
+/**
+ * The overlay's view of a model's PHYSICAL window — the model card's chain with the deployment's live
+ * declaration CLAMPED over it. The single expression `guardBudget` and `resolveTriggerWindow` share.
+ *
+ * The clamp is the whole difference between a setting and a claim. An overlay says how much of a model a
+ * deployment wants used; it cannot say what the endpoint will accept, and the endpoint a leg talks to is the
+ * one it prepared under. Letting a declaration RAISE the window would let an operator publishing a larger
+ * model and its larger window in one step hand the bigger number to legs still routed at the smaller
+ * endpoint — the guard would stop protecting the limit it exists for. So: lower freely, never raise. (Same
+ * clamp the reference implementation applies to its configured window: `min(model window, configured)`.)
+ * A card with no usable window of its own has nothing to clamp against, and the declaration is then the only
+ * number there is.
+ */
+export declare function physicalWindowOf(model: Model, overlay: ContextWindowOverlay | undefined): number;

package/dist/core/context-settings.js

@@ -0,0 +1,60 @@
+import { tierAliasVia } from "./roles.js";
+export function contextOverlayFor(settings, ref, catalog) {
+    if (settings === undefined || typeof ref !== "string")
+        return undefined;
+    for (const word of [ref, ...tierAliasVia(ref, catalog?.models)])
+        if (Object.hasOwn(settings, word))
+            return settings[word];
+    return undefined;
+}
+export function assertContextSettingsWords(settings, models, where) {
+    const unknown = Object.keys(settings ?? {}).filter((w) => models === undefined || !Object.hasOwn(models, w));
+    if (unknown.length === 0)
+        return settings;
+    const e = new Error(`${where}: contextSettings declares ${unknown.map((w) => JSON.stringify(w)).join(", ")}, which ${unknown.length === 1 ? "is" : "are"} not a word of the model catalog (its keys, and the tier words and aliases \`tiers\` expanded) — an overlay no leg can be keyed by governs nothing; the current settings stay in force`);
+    e.code = "config.context_settings_unknown_word";
+    throw e;
+}
+export function assertContextSettingsValue(v, where) {
+    if (v === undefined)
+        return undefined;
+    if (v === null || typeof v !== "object" || Array.isArray(v)) {
+        throw new Error(`${where}: contextSettings must be a plain Record<string, {contextTokens?, autoCompactTokens?, enabled?}> (got ${v === null ? "null" : Array.isArray(v) ? "array" : typeof v})`);
+    }
+    const out = {};
+    for (const [word, raw] of Object.entries(v)) {
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+            throw new Error(`${where}: contextSettings[${JSON.stringify(word)}] must be a plain object (got ${raw === null ? "null" : Array.isArray(raw) ? "array" : typeof raw})`);
+        }
+        const o = raw;
+        const unknown = Object.keys(o).filter((k) => k !== "contextTokens" && k !== "autoCompactTokens" && k !== "enabled");
+        if (unknown.length > 0) {
+            throw new Error(`${where}: contextSettings[${JSON.stringify(word)}] carries ${unknown.map((k) => JSON.stringify(k)).join(", ")} — this seat declares window geometry only (contextTokens | autoCompactTokens | enabled); routing, pricing and fencing stay on the model card`);
+        }
+        for (const k of ["contextTokens", "autoCompactTokens"]) {
+            const n = o[k];
+            if (n !== undefined && (typeof n !== "number" || !Number.isFinite(n) || n <= 0)) {
+                throw new Error(`${where}: contextSettings[${JSON.stringify(word)}].${k} must be a positive finite number (got ${JSON.stringify(n)}) — an unusable window is a configuration defect, not a request to fall back to the model's own`);
+            }
+        }
+        if (o.enabled !== undefined && typeof o.enabled !== "boolean") {
+            throw new Error(`${where}: contextSettings[${JSON.stringify(word)}].enabled must be a boolean (got ${JSON.stringify(o.enabled)})`);
+        }
+        out[word] = Object.freeze({
+            ...(o.contextTokens !== undefined ? { contextTokens: o.contextTokens } : {}),
+            ...(o.autoCompactTokens !== undefined ? { autoCompactTokens: o.autoCompactTokens } : {}),
+            ...(o.enabled !== undefined ? { enabled: o.enabled } : {}),
+        });
+    }
+    return Object.freeze(out);
+}
+export function compactionEnabled(specEnabled, overlay) {
+    return specEnabled ?? overlay?.enabled ?? true;
+}
+export function physicalWindowOf(model, overlay) {
+    const card = model.contextTokens ?? model.contextWindow;
+    const declared = overlay?.contextTokens;
+    if (declared === undefined)
+        return card;
+    return Number.isFinite(card) && card > 0 ? Math.min(declared, card) : declared;
+}

package/dist/core/engine-notice.d.ts

@@ -172,6 +172,16 @@ export interface EngineNotice {
      *  - `"config.write_face_swapped"` — the same line for the WRITE seat (`RunnerDeps.writeFace`),
      *    same payload, same laws. A SEPARATE code rather than a face field on the line above: the audience
      *    table and every consumer table are keyed by code.
+     *  - `"config.context_settings_swapped"` — `Runner.swapDeps` replaced the deployment's per-model
+     *    context-window overlay (`RunnerDeps.contextSettings`, the `contextSettings` seat of the swappable
+     *    set) without a restart. Unlike every other swappable seat this one is read LIVE: a running leg
+     *    measures its next boundary (the compaction trigger, the sanitize clamp, the request guard, the
+     *    disclosed `contextUsage`) against the new windows, while its routing stays on the generation it
+     *    prepared under. `detail: { words, declared, previousDeclared, occurrenceId }` — the declared model
+     *    WORDS (the first eight) and the two counts, never the numbers: an overlay's values are deployment
+     *    configuration and this line is an operator breadcrumb, not a config dump. A candidate outside the
+     *    value gate (`assertContextSettingsValue`) throws atomically and mints nothing. Own `occurrenceId`
+     *    for the same reason as the catalog line. Dedup key: (code, occurrenceId).
      *  - `"route.fallback_to_primary"` (key↔URL pairing, `src/brain/route-adjudicator.ts`) — a
      *    DERIVED-leg model (role/tier/system-default resolution, never a caller-explicit one) failed
      *    the pairing pre-flight and the seat fell back to the primary model instead of sinking the
@@ -590,7 +600,7 @@ export interface EngineNotice {
      *    disposition table with the error dispositions. The loser MUST NOT retry into the winner's
      *    account. A consumer diffing its own table against the catalog must not add a row for it.
      *
-     *  - `"config.peer_admission_out_of_range"` (#551) — a `RunnerDeps.peerAdmission` field the
+     *  - `"config.peer_admission_out_of_range"` (#551) — a `RunnerDeps.peerLane` field the
      *    resolver could not use: outside its legal range, or not a finite number at all (a string off
      *    an untyped host's wiring, `NaN`, `Infinity`). THAT FIELD falls back to its own default (never
      *    a clamp to the nearest edge, never a whole-config reject) and every other field is unaffected.

package/dist/core/frame-settlement.d.ts

@@ -0,0 +1,97 @@
+/** What ONE landed compaction did to the transcript, recorded at its commit point. */
+export interface CompactionEffect {
+    /** The entry ids that went into the summarized prefix (everything before `firstKeptEntryId`), or
+     *  `"unknown"` when the kept-tail anchor could not be located in the branch — the conservative
+     *  reading is that the whole branch was summarized, so a reader treats `"unknown"` as "every
+     *  receipt this run holds is invalidated" (the same direction
+     *  {@link import("./auto-compaction.js").countSummarizedCrossSessionMessages} already takes). */
+    readonly summarizedEntryIds: ReadonlySet<string> | "unknown";
+}
+/**
+ * One receipt ASK: the carrier a frame rides, and — for a frame that rides a TOOL RESULT — the
+ * text {@link frameSurvivesInToolResult} must find in that result as committed. An injected frame is its
+ * own carrier (the committed message IS the frame), so it carries no text to check.
+ */
+export interface FrameReceiptAsk {
+    /** The injection queue's dedup key of the frame itself, or {@link toolResultReceiptKey} of the call whose result carries it. */
+    readonly carrier: string;
+    readonly frameText?: string;
+}
+/**
+ * The leg's settlement seam, one cell per run.
+ *
+ * `awaiting` is an ASK, not a log: only keys a consumer registered are ever given a receipt, an ask
+ * leaves when its carrier commits, so a run that delivers thousands of ordinary notification frames
+ * does not accumulate one map entry per frame. The key is the consumer's per-frame key.
+ */
+export interface FrameSettlement {
+    /** Receipt asks a consumer is waiting on (key → ask). The receipt sink records nothing for any other key. */
+    readonly awaiting: Map<string, FrameReceiptAsk>;
+    /** Receipts collected for awaited keys: key → the transcript entry id the frame landed in. */
+    readonly receipts: Map<string, string>;
+    /** Awaited keys whose carrier COMMITTED WITHOUT the frame and nothing the HOST did explains it (an engine-side
+     *  crop): shown nothing, so owed again — never a receipt. */
+    readonly withheld: Set<string>;
+    /** Carriers whose result a HOST hook rewrote (`postToolUse.updatedOutput`) before the commit — recorded only
+     *  for a carrier some ask rides ({@link noteHostRewrite}), consumed by the receipt at its commit: a frame the
+     *  rewrite kept gets an ordinary receipt, a frame it removed is host-withheld. */
+    readonly hostRewritten: Set<string>;
+    /** Awaited keys whose frame is not in the host's rewrite (removed, truncated, or reshaped beyond whitespace): the
+     *  host decided what the model reads, so the consumer settles the record as the host's decision (terminal),
+     *  discloses it loudly, and never hands it over again. */
+    readonly hostWithheld: Set<string>;
+    /** Compactions that LANDED this run and have not been consumed by a settlement pass yet, in landing
+     *  order. Recorded only while {@link FrameSettlement.wantsEffects} says a record could still be
+     *  broken by one, and cleared by the consumer's LOCAL settlement half — which needs no lease, so an
+     *  unclaimable or empty box cannot leave them piling up for the whole leg. */
+    readonly compactions: CompactionEffect[];
+    /**
+     * #1036 — "is this engine frame's record still parked in a DURABLE box?" Set by the
+     * session-box drain when it binds. The terminal sweep hands back engine-note payloads that never
+     * drained and the runner pends them PER SESSION (an in-process copy); for a frame whose record the
+     * drain no longer acks on delivery, that copy would be a second source of truth — the box already
+     * re-serves it to the session's next run. Absent (no drain bound) ⇒ the pre-1036 behavior, which is
+     * correct there: nothing else holds those frames.
+     */
+    boxBacked?: (payload: unknown) => boolean;
+    /**
+     * #1036 — "is there a record a landed compaction could still break?" Asked at the compaction
+     * COMMIT beat, before an effect is recorded at all. Absent (no drain bound) or `false` ⇒ the effect
+     * is not recorded: nothing would ever read it, and a leg that compacts many times would otherwise
+     * hold every landing's entry-id set until it ended.
+     */
+    wantsEffects?: () => boolean;
+}
+export declare function createFrameSettlement(): FrameSettlement;
+/** The carrier key of a TOOL RESULT (the `ReadInbox` pull face): its own domain, so it can never
+ *  collide with an injection queue dedup key. One tool result can carry SEVERAL frames, each asked for
+ *  under its own key with this carrier. */
+export declare function toolResultReceiptKey(toolCallId: string): string;
+/**
+ * THE rule for a frame that rides a TOOL RESULT: the result can be replaced (`postToolUse.updatedOutput`)
+ * or cropped (the aggregate result budget) after the frame was handed to it, so handing it over proves
+ * nothing — the frame counts as delivered only when its text is present in the result AS COMMITTED
+ * (a string, or the text blocks, each read whole), compared with every whitespace run on both sides folded
+ * to one space: a rewrite that only re-spaces, re-indents or re-wraps the frame kept it. Any other change
+ * (a word, an escape, the case) did not. Before the commit, nothing is proven. The inbox receipt
+ * below reads it; the listing ride (`prepare-listings.ts`) does not call it — it never commits announced
+ * state at ride time, the conservative answer for a frame whose commit has not happened yet.
+ */
+export declare function frameSurvivesInToolResult(committedContent: unknown, frameText: string): boolean;
+/** The station that applies a HOST hook's `updatedOutput` marks the carrier — only when an ask rides it, so an
+ *  ordinary rewritten result leaves nothing behind. */
+export declare function noteHostRewrite(seam: FrameSettlement, toolCallId: string): void;
+/** The receipt sink's ONE writer: every ask riding `carrier` is answered — a receipt when its frame is in
+ *  the committed content (or it is its own carrier); when it is not, host-withheld if a host hook rewrote the
+ *  carrier (the host's decision), withheld otherwise (owed again). */
+export declare function recordFrameReceipt(seam: FrameSettlement, carrier: string, committedContent: unknown, entryId: string): void;
+/** The carrier a committed frame was riding, as the harness reports it at the transcript append — a tool
+ *  result with the content it was committed with (after every result transformation). */
+export type CommittedFrameCarrier = {
+    kind: "engine_note";
+    payload: unknown;
+} | {
+    kind: "tool_result";
+    toolCallId: string;
+    content: unknown;
+};

package/dist/core/frame-settlement.js

@@ -0,0 +1,36 @@
+export function createFrameSettlement() {
+    return { awaiting: new Map(), receipts: new Map(), withheld: new Set(), hostRewritten: new Set(), hostWithheld: new Set(), compactions: [] };
+}
+export function toolResultReceiptKey(toolCallId) {
+    return `tool_result:${toolCallId}`;
+}
+const foldWhitespace = (text) => text.replace(/\s+/g, " ");
+export function frameSurvivesInToolResult(committedContent, frameText) {
+    const frame = foldWhitespace(frameText);
+    if (typeof committedContent === "string")
+        return foldWhitespace(committedContent).includes(frame);
+    if (!Array.isArray(committedContent))
+        return false;
+    return committedContent.some((b) => b.type === "text" && typeof b.text === "string" && foldWhitespace(b.text).includes(frame));
+}
+export function noteHostRewrite(seam, toolCallId) {
+    const carrier = toolResultReceiptKey(toolCallId);
+    for (const ask of seam.awaiting.values()) {
+        if (ask.carrier === carrier) {
+            seam.hostRewritten.add(carrier);
+            return;
+        }
+    }
+}
+export function recordFrameReceipt(seam, carrier, committedContent, entryId) {
+    const hostRewrote = seam.hostRewritten.delete(carrier);
+    for (const [key, ask] of seam.awaiting) {
+        if (ask.carrier !== carrier)
+            continue;
+        seam.awaiting.delete(key);
+        if (ask.frameText === undefined || frameSurvivesInToolResult(committedContent, ask.frameText))
+            seam.receipts.set(key, entryId);
+        else
+            (hostRewrote ? seam.hostWithheld : seam.withheld).add(key);
+    }
+}

package/dist/core/governance-codes.d.ts

@@ -119,7 +119,7 @@ export type NoticeAudience = "user" | "operator";
  * the union's catalog ({@link EngineNotice.code}). The groups below say only which family a row joins,
  * so the catalog is not written a second time here and the two cannot drift.
  */
-export declare const ENGINE_NOTICE_CODES: readonly ["config.autocompact_window_clamped", "config.env_timeout_discarded", "config.materialize_env_discarded", "config.models_swapped", "config.read_face_swapped", "config.read_face_deployment_clamped", "config.write_face_swapped", "config.write_face_deployment_clamped", "config.tool_model_gate_removed", "config.tool_model_gate_unknown_class", "config.tool_model_gate_env_invalid", "config.artifact_host_invalid", "config.task_root_not_canonical", "config.write_protection_target_view_absent", "config.write_protection_unresolved", "config.execution_env_capability_invalid", "config.tool_card_undeclared", "config.tool_face_undeclared", "config.tool_face_invalid", "config.forward_sink_failed", "config.durable_gate_unavailable", "config.peer_admission_out_of_range", "config.peer_lane_unmounted", "peer.inbound_disposition", "peer.held_settled", "peer.idle_subscription", "classifier.denial_limit", "classifier.fallback", "classifier.role_defaulted", "classifier.contract_broken", "checkpoint.execution_outcome_unrecorded", "delegation.transcript_integrity", "delegation.ask_unresolvable", "mcp.injection_dropped", "mcp.revocation_probe_failed", "mcp.server_redialed", "workflow.governance_key_stripped", "workflow.agent_option_ignored", "memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived", "memory.content_class_declared", "memory.hold_opened", "memory.hold_released", "memory.hold_disposed", "memory.consolidation_recommended", "memory.consolidation_committed", "memory.consolidation_conflict", "memory.consolidation_incomplete", "memory.consolidation_refused", "memory.consolidation_withheld", "memory.restore_withheld", "memory.project_scope_absent", "route.fallback_to_primary", "route.classifier_unroutable", "route.base_url_changed_key_unchanged", "route.response_model_mismatch", "task.user_steer_undrained", "task.user_followup_undrained", "steering.parked_input_blocked", "task.turn_interrupted", "task.halt_unconsumed", "task.late_approval", "task.interrupt_unconsumed", "memory.capture_opted_out", "memory.capture_optout_unpersisted", "skills.listing_truncated", "agents.listing_truncated", "tool_result.offload_put_failed"];
+export declare const ENGINE_NOTICE_CODES: readonly ["config.autocompact_window_clamped", "config.env_timeout_discarded", "config.materialize_env_discarded", "config.models_swapped", "config.context_settings_swapped", "config.read_face_swapped", "config.read_face_deployment_clamped", "config.write_face_swapped", "config.write_face_deployment_clamped", "config.tool_model_gate_removed", "config.tool_model_gate_unknown_class", "config.tool_model_gate_env_invalid", "config.artifact_host_invalid", "config.task_root_not_canonical", "config.write_protection_target_view_absent", "config.write_protection_unresolved", "config.execution_env_capability_invalid", "config.tool_card_undeclared", "config.tool_face_undeclared", "config.tool_face_invalid", "config.forward_sink_failed", "config.durable_gate_unavailable", "config.peer_admission_out_of_range", "config.peer_lane_unmounted", "peer.inbound_disposition", "peer.held_settled", "peer.idle_subscription", "classifier.denial_limit", "classifier.fallback", "classifier.role_defaulted", "classifier.contract_broken", "checkpoint.execution_outcome_unrecorded", "delegation.transcript_integrity", "delegation.ask_unresolvable", "mcp.injection_dropped", "mcp.revocation_probe_failed", "mcp.server_redialed", "workflow.governance_key_stripped", "workflow.agent_option_ignored", "memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived", "memory.content_class_declared", "memory.hold_opened", "memory.hold_released", "memory.hold_disposed", "memory.consolidation_recommended", "memory.consolidation_committed", "memory.consolidation_conflict", "memory.consolidation_incomplete", "memory.consolidation_refused", "memory.consolidation_withheld", "memory.restore_withheld", "memory.project_scope_absent", "route.fallback_to_primary", "route.classifier_unroutable", "route.base_url_changed_key_unchanged", "route.response_model_mismatch", "task.user_steer_undrained", "task.user_followup_undrained", "steering.parked_input_blocked", "task.turn_interrupted", "task.halt_unconsumed", "task.late_approval", "task.interrupt_unconsumed", "memory.capture_opted_out", "memory.capture_optout_unpersisted", "skills.listing_truncated", "agents.listing_truncated", "tool_result.offload_put_failed"];
 /** A code this engine mints (see {@link ENGINE_NOTICE_CODES}). NOT the type of
  *  `EngineNotice.code`, which stays `string` — a host forwarding its own notices through the same
  *  sink is a supported shape, and narrowing that field would break it. */

package/dist/core/governance-codes.js

@@ -105,6 +105,7 @@ export const ENGINE_NOTICE_CODES = [
     "config.env_timeout_discarded",
     "config.materialize_env_discarded",
     "config.models_swapped",
+    "config.context_settings_swapped",
     "config.read_face_swapped",
     "config.read_face_deployment_clamped",
     "config.write_face_swapped",
@@ -198,6 +199,7 @@ const NOTICE_AUDIENCE_TABLE = {
     "config.env_timeout_discarded": "operator",
     "config.materialize_env_discarded": "operator",
     "config.models_swapped": "operator",
+    "config.context_settings_swapped": "operator",
     "config.read_face_swapped": "operator",
     "config.read_face_deployment_clamped": "operator",
     "config.write_face_swapped": "operator",

package/dist/core/hooks.d.ts

@@ -540,16 +540,8 @@ export interface StopHookContext {
     /** Consecutive blocks so far in this run (resets when a stop() call lets the run proceed). */
     consecutiveBlocks: number;
     /**
-     * A view of the conversation this hook is being asked to judge.
-     *
-     * Until now a Stop hook received two counters and nothing else. That is enough for a hook that asks
-     * "have I blocked too often?", and structurally insufficient for the entire class of hooks that ask
-     * anything ABOUT THE RUN — which is what the prompt-shaped hooks a settings file can declare are for.
-     * Measured end to end downstream: the carrier was constructed, invoked, and returned without error, and
-     * the model answered "I don't have direct access to your file system…" — because nobody had given the
-     * evaluator the session. Every layer reported success and the feature could not work. A hook cannot
-     * judge a run it cannot see, so the gap belonged here rather than in any of the layers that were
-     * dutifully passing an empty view along.
+     * A view of the conversation this hook is being asked to judge — the counters alone cannot serve a
+     * hook that asks anything ABOUT THE RUN (the prompt-shaped hooks a settings file declares).
      *
      * LAZY on purpose: a hook that only reads the counters pays nothing, and a hook that needs the
      * conversation gets it in full rather than through a truncation policy the engine would have to invent
@@ -559,6 +551,14 @@ export interface StopHookContext {
      * Absent when the runner cannot supply one (a stop gate wired without a session).
      */
     getBranch?: () => Promise<readonly SessionTreeEntry[]>;
+    /** The run's background tasks still in flight (pending / running / parked under this run's owner triple — the
+     *  post-compaction reminder's projection; CC `SubagentStop.background_tasks`). LAZY like {@link getBranch};
+     *  `[]` = none in that projection, ABSENT = no view. A parked child here waits on an approval out of band. */
+    backgroundTasks?: () => ReadonlyArray<{
+        id: string;
+        description?: string;
+        status: string;
+    }>;
     /** {@link HookSeatSignal} — this invocation's own abort signal. */
     signal?: AbortSignal;
 }