@sema-agent/core 7.28.1 → 7.30.0

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", "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",
@@ -157,6 +158,7 @@ export const ENGINE_NOTICE_CODES = [
     "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",
@@ -197,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",
@@ -235,6 +238,7 @@ const NOTICE_AUDIENCE_TABLE = {
     "route.fallback_to_primary": "operator",
     "route.classifier_unroutable": "operator",
     "route.base_url_changed_key_unchanged": "operator",
+    "route.response_model_mismatch": "operator",
     "skills.listing_truncated": "operator",
     "agents.listing_truncated": "operator",
     "tool_result.offload_put_failed": "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;
 }

package/dist/core/mailbox-store.d.ts

@@ -44,6 +44,10 @@ export interface MailboxPeerMeta {
      *  — a delivery receipt's state (`kind: "delivery_notice"`) or an idle notice's kind
      *  (`kind: "idle_notice"`). The record's `content` is a human-readable mirror; THIS is the authority. */
     notice?: MailboxPeerNoticeMeta;
+    /** `peer_message` only — the SENDER marked it urgent. The recipient's drain presents an urgent record
+     *  ahead of the non-urgent ones of the same pass and counts it on the inbox notice; it never changes
+     *  WHEN the recipient reads (the recipient's setting decides that, never the sender). */
+    urgent?: boolean;
 }
 /** design/385 — the typed body of a notice-kind record. `state` is drawn from the receipt states on a
  *  `delivery_notice` (`held|denied|expired|delivered|refused|dropped`) and from the idle kinds on an
@@ -67,10 +71,23 @@ export interface MailboxPeerNoticeMeta {
 }
 export declare const MAILBOX_PEER_FROM_MODES: readonly ["bypass", "prompting"];
 export type MailboxPeerFromMode = (typeof MAILBOX_PEER_FROM_MODES)[number];
-/** design/385: `peer_message` runs the parity judgment; `idle_subscription` registers the sender as an
- *  idle subscriber of the box owner (§5.2, the store form of CC's `notify_when_idle` frame);
- *  `idle_notice` / `delivery_notice` land on the notice face (rendered, never enveloped as a peer's words). */
-export declare const MAILBOX_PEER_RECORD_KINDS: readonly ["peer_message", "idle_notice", "delivery_notice", "idle_subscription"];
+/**
+ * design/385: `peer_message` runs the parity judgment; `idle_subscription` registers the sender as an
+ * idle subscriber of the box owner (§5.2, the store form of CC's `notify_when_idle` frame);
+ * `idle_notice` / `delivery_notice` land on the notice face (rendered, never enveloped as a peer's words).
+ *
+ * @contract mailbox.engine_frame_is_not_a_peers_words — an `engine_frame` record is the ENGINE's own
+ * task-notification frame parked durably (a child's terminal, a monitor batch, a workflow settle),
+ * written by the park seat of the session that owns the box and only over a deployment that vouches
+ * every drainer of the box reads the codec (`RunnerDeps.sessionBoxEngineFrames`). Its `content` is the
+ * versioned codec text (`encodeEngineFrame`), never a message: the drain decodes it and re-injects the
+ * frame through the engine's own notification lane — no parity judgment, no admission gate, no peer
+ * envelope — and a codec version this engine does not read STOPS the drain at that record (the box
+ * waits for an engine that reads it) rather than rendering engine speech as a peer's words. Only the
+ * engine's own lanes (`background_agent` / `monitor` / `workflow`) may be parked this way; an
+ * `external` event never is.
+ */
+export declare const MAILBOX_PEER_RECORD_KINDS: readonly ["peer_message", "idle_notice", "delivery_notice", "idle_subscription", "engine_frame"];
 export type MailboxPeerRecordKind = (typeof MAILBOX_PEER_RECORD_KINDS)[number];
 /** The `notice.state` vocabulary the validator admits (the union of both notice families; the drain
  *  checks the kind↔state pairing). Spelled here, beside the record kinds, so the store contract is
@@ -183,7 +200,7 @@ export interface MailboxAppendMessage {
  *   persists it and hands it back on `claimLease` byte-for-byte (a detached copy), absent stays absent,
  *   and a malformed value is REFUSED with `"mailbox.invalid_peer_meta"` before any side effect
  *   (`readMailboxPeerMeta` is the one validator; bundled backends call it first). T1 cases in
- *   `mailboxStoreContract` cover the round trip, the refusal and the aliasing.
+ *   `mailboxStoreContract` cover the pass trip, the refusal and the aliasing.
  * - CROSS-PROCESS SAFETY (design/385, optional capability declared on the store): the session-box
  *   drain shares ONE box between several OS processes. A backend that is correct under that sharing —
  *   seq minted once across processes, lease/ack never crossing, one process's housekeeping never
@@ -192,6 +209,12 @@ export interface MailboxAppendMessage {
  *   that does not declare it is refused by the lane at mount time with a named reason
  *   ({@link mailboxCrossProcessMountVerdict}) — never silently mounted on luck.
  */
+/** #1036 — what {@link MailboxStore.ack} answers: did this call actually consume the prefix?
+ *  `false` = the lease fence refused it (this caller does not hold the box), so nothing was deleted
+ *  and the records are still parked for whoever does. */
+export interface MailboxAckResult {
+    readonly acked: boolean;
+}
 export interface MailboxStore {
     /** design/385 — cross-process safety declaration (see the interface notes). `true` = this backend
      *  passed `mailboxCrossProcessContract` over real OS processes; `false` = deliberately process-local
@@ -202,7 +225,18 @@ export interface MailboxStore {
      *  that its recipient is in the deployment's pre-delete state (see the interface notes above). */
     append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;
     claimLease(scope: string, handle: string, owner: string, ttlMs: number, now?: number): Promise<MailboxLease | null>;
-    ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<void>;
+    /**
+     * Consume the leased prefix up to `upToSeq` (the records are DELETED). Fenced by the current lease:
+     * a caller that does not hold it consumes nothing.
+     *
+     * #1036 — the fence's verdict is REPORTED (`{acked:false}`), not silent. The fence itself is
+     * older (MB1): it exists so a stale owner whose lease a live rival already took over cannot delete
+     * the rival's messages. What was missing is that a no-op and a success were the same `void` to the
+     * caller, so a drain that had lost its lease would clear its own watermark as if the store had
+     * obeyed it — the one shape where "the records stay parked" turns into "the records are forgotten".
+     * Implementations report `{acked:true}` only when they actually consumed the prefix.
+     */
+    ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<MailboxAckResult>;
     releaseLease(scope: string, handle: string, owner: string): Promise<void>;
     /** Observation face (the "N pending" receipt figure) — count of currently-visible messages. */
     peekCount(scope: string, handle: string): Promise<number>;
@@ -253,7 +287,7 @@ export declare class InMemoryMailboxStore implements MailboxStore {
     private box;
     append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;
     claimLease(scope: string, handle: string, owner: string, ttlMs: number, now?: number): Promise<MailboxLease | null>;
-    ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<void>;
+    ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<MailboxAckResult>;
     releaseLease(scope: string, handle: string, owner: string): Promise<void>;
     peekCount(scope: string, handle: string): Promise<number>;
     drop(scope: string, handle: string): Promise<void>;

package/dist/core/mailbox-store.js

@@ -1,6 +1,6 @@
 import { assertRetentionPolicy } from "./retention-policy.js";
 export const MAILBOX_PEER_FROM_MODES = ["bypass", "prompting"];
-export const MAILBOX_PEER_RECORD_KINDS = ["peer_message", "idle_notice", "delivery_notice", "idle_subscription"];
+export const MAILBOX_PEER_RECORD_KINDS = ["peer_message", "idle_notice", "delivery_notice", "idle_subscription", "engine_frame"];
 export const MAILBOX_PEER_NOTICE_STATES = ["held", "denied", "expired", "delivered", "refused", "dropped", "idle", "exited", "unavailable"];
 export const MAILBOX_INVALID_PEER_META_CODE = "mailbox.invalid_peer_meta";
 export const MAILBOX_CROSS_PROCESS_UNSAFE_CODE = "mailbox.cross_process_unsafe";
@@ -42,6 +42,11 @@ export function readMailboxPeerMeta(raw) {
         else if (k === "notice") {
             out.notice = readMailboxPeerNoticeMeta(v, refuse);
         }
+        else if (k === "urgent") {
+            if (typeof v !== "boolean")
+                return refuse("urgent must be a boolean");
+            out.urgent = v;
+        }
         else {
             return refuse(`carries an unknown key ${JSON.stringify(k)}`);
         }
@@ -171,12 +176,13 @@ export class InMemoryMailboxStore {
     async ack(scope, handle, owner, upToSeq) {
         const b = this.boxes.get(this.key(scope, handle));
         if (!b)
-            return;
+            return { acked: false };
         if (b.lease === undefined || b.lease.owner !== owner)
-            return;
+            return { acked: false };
         b.messages = b.messages.filter((m) => m.seq > upToSeq);
         if (b.lease.maxSeq <= upToSeq)
             b.lease = undefined;
+        return { acked: true };
     }
     async releaseLease(scope, handle, owner) {
         const b = this.boxes.get(this.key(scope, handle));

package/dist/core/message-utils.d.ts

@@ -3,6 +3,19 @@ import type { ToolResultMessage } from "../internal/llm.js";
 /** Read the (possibly absent) `role` off an AgentMessage defensively — the union doesn't expose it
  *  uniformly, so context passes narrow by role with a single cast in one place. */
 export declare function messageRole(m: AgentMessage): string | undefined;
+/**
+ * The PROVIDER's own name for the model that answered this assistant message, when it differs from the
+ * ENGINE-SELECTED id the message is stamped with — the ONE read of `AssistantMessage.responseModel`, so
+ * the per-turn frame, the result face, the side-query projection and the mismatch notice admit it on the
+ * same terms rather than on four. The READ twin of `noteResponseModel` (`brain/stream-shared.ts`), which
+ * states the same law on the write side; this side re-tests rather than trusting, because a HOST's own
+ * Brain mints these messages too. `undefined` ⇒ the provider named the stamped id, named nothing, or
+ * named something unreadable — ONE reading, never three.
+ */
+export declare function providerReportedModel(m: {
+    readonly model?: unknown;
+    readonly responseModel?: unknown;
+}): string | undefined;
 /** True if the message is a tool-result message (shared by the context-edit and context-guard passes).
  *  A TYPE PREDICATE, not a bare boolean: `role: "toolResult"` belongs to exactly one member of the
  *  union, so callers that check it can read `.content`/`.toolName` and rebuild the message directly

package/dist/core/message-utils.js

@@ -1,6 +1,12 @@
 export function messageRole(m) {
     return m.role;
 }
+export function providerReportedModel(m) {
+    const reported = m.responseModel;
+    if (typeof reported !== "string" || reported === "")
+        return undefined;
+    return reported === m.model ? undefined : reported;
+}
 export function isToolResult(m) {
     return messageRole(m) === "toolResult";
 }

package/dist/core/parent-spec-seat.d.ts

@@ -13,7 +13,7 @@ import type { Hooks } from "./hooks.js";
 import type { ToolExecuteContext } from "./tool-spec.js";
 import type { TaskSpec } from "./types.js";
 /** The fields of a spec the seat carries — one `Pick`, shared by the mint's input and the apply's target. */
-export type ParentSpecSeatFields = Pick<TaskSpec, "principal" | "oneShot" | "clientContext" | "onQuestion" | "hooks" | "additionalDirectories" | "additionalReadDirectories" | "envFacts" | "memoryPersistenceCapable" | "memory">;
+export type ParentSpecSeatFields = Pick<TaskSpec, "principal" | "oneShot" | "clientContext" | "onQuestion" | "hooks" | "additionalDirectories" | "additionalReadDirectories" | "envFacts" | "memoryPersistenceCapable" | "memory" | "compaction" | "skillListingBudgetFraction" | "skillListingMaxDescChars">;
 /**
  * The seat a run hands its children. Every member is the parent's own value, frozen at mint (arrays copied and
  * frozen; the facts object copied). Members present iff the parent carries them — an absent member is "nothing to
@@ -33,6 +33,16 @@ export type ParentSpecSeatFields = Pick<TaskSpec, "principal" | "oneShot" | "cli
  *    `true` a default a child's own declaration may narrow.
  *  · `memoryOff` — the request-level "memory is off" FACT (`spec.memory.enabled === false`): a REMOVAL
  *    (floor) that REWRITES the child's own memory declaration instead of travelling as a value.
+ *  · `compaction` — the request's CONTEXT-MANAGEMENT settings (enabled / withinTask / reserve / keepRecent /
+ *    instructions / attachWorkingFiles / staleToolResultOffload / clampTolerance). One set of settings for the
+ *    whole delegation tree, measured per leg against the leg's OWN window: the numbers are repaired against the
+ *    child's model by the same sanitizer every leg runs (`sanitizeCompactionSettings`), so a parent's 128k-tuned
+ *    reserve does not have to be re-tuned to be legal on a 6k child. `enabled: false` is NOT a removal — the
+ *    reference implementation shares one settings object down the tree rather than flooring children, and a
+ *    child that authors its own settings wins the whole object (an ORDINARY seat member).
+ *  · `skillListingBudgetFraction` / `skillListingMaxDescChars` — the listing-budget knobs, the same shape for the
+ *    same reason: a fraction the parent tuned is a fraction OF EACH LEG'S OWN window, so it travels as a number
+ *    and every leg multiplies it by its own.
  */
 export interface ParentSpecSeat {
     readonly principal?: string;
@@ -45,6 +55,9 @@ export interface ParentSpecSeat {
     readonly envFacts?: TaskSpec["envFacts"];
     readonly memoryPersistenceCapable?: boolean;
     readonly memoryOff?: true;
+    readonly compaction?: TaskSpec["compaction"];
+    readonly skillListingBudgetFraction?: number;
+    readonly skillListingMaxDescChars?: number;
 }
 /** Mint the seat off the parent's REBOUND spec and its frozen question face (spec over deps — the caller resolves it once,
  *  the same value the parent's own question routing reads). Absent fields stay absent; `oneShot` only when `true`. */

package/dist/core/parent-spec-seat.js

@@ -9,6 +9,9 @@ export function parentSpecSeatOf(spec, frozenOnQuestion) {
         ...(spec.additionalReadDirectories !== undefined ? { additionalReadDirectories: Object.freeze([...spec.additionalReadDirectories]) } : {}),
         ...(spec.envFacts !== undefined ? { envFacts: Object.freeze({ ...spec.envFacts }) } : {}),
         ...(spec.memoryPersistenceCapable !== undefined ? { memoryPersistenceCapable: spec.memoryPersistenceCapable } : {}),
+        ...(spec.compaction !== undefined ? { compaction: Object.freeze({ ...spec.compaction }) } : {}),
+        ...(spec.skillListingBudgetFraction !== undefined ? { skillListingBudgetFraction: spec.skillListingBudgetFraction } : {}),
+        ...(spec.skillListingMaxDescChars !== undefined ? { skillListingMaxDescChars: spec.skillListingMaxDescChars } : {}),
         ...(spec.memory?.enabled === false ? { memoryOff: true } : {}),
     });
 }
@@ -25,6 +28,9 @@ export function applyParentSpecSeat(child, seat) {
         ...fill("additionalDirectories", (seat.additionalDirectories !== undefined ? [...seat.additionalDirectories] : undefined)),
         ...fill("additionalReadDirectories", (seat.additionalReadDirectories !== undefined ? [...seat.additionalReadDirectories] : undefined)),
         ...fill("envFacts", (seat.envFacts !== undefined ? { ...seat.envFacts } : undefined)),
+        ...fill("compaction", (seat.compaction !== undefined ? { ...seat.compaction } : undefined)),
+        ...fill("skillListingBudgetFraction", seat.skillListingBudgetFraction),
+        ...fill("skillListingMaxDescChars", seat.skillListingMaxDescChars),
         ...(seat.oneShot === true ? { oneShot: true } : {}),
         ...(seat.memoryPersistenceCapable === false ? { memoryPersistenceCapable: false } : fill("memoryPersistenceCapable", seat.memoryPersistenceCapable)),
         ...(seat.memoryOff === true ? { memory: memoryTurnedOff(child.memory) } : {}),

package/dist/core/permission-rule-model.js

@@ -263,7 +263,7 @@ export function parseRuleText(text, behavior) {
     }
     const shape = ruleLaneShapeOf(body, MATCH_READING);
     if ("reject" in shape) {
-        if (body.trim() === "")
+        if (body.trim() === "" || shape.reject === "empty command")
             return reject("invalid.empty_command", `rule "${text}" names no command`);
         if (foldSpacing(body) === undefined)
             return reject("invalid.unbalanced_quotes", `rule "${text}" has unbalanced quoting, so the command it names is not determinable`);

package/dist/core/roles.d.ts

@@ -37,6 +37,13 @@ export declare function resolveModelDisplayLabel(ref: string): string;
  *   `resolveModel("best")` refuses like any unknown ref.
  */
 export declare function expandTiers(models: Record<string, Model> | undefined, tiers: Record<string, ModelRef> | undefined): Record<string, Model> | undefined;
+/**
+ * The words a catalog word stands in for under the tier layer, nearest first — what {@link expandTiers}
+ * recorded for a key IT wrote: the tier words its resolution passed through and the binding's own catalog
+ * word, each naming the model the key resolves to. A deployment's own key (a shadowing one included), and any
+ * catalog that was not tier-expanded, stands in for nothing.
+ */
+export declare function tierAliasVia(word: string, models: Record<string, Model> | undefined): readonly string[];
 export interface ModelMention {
     /** The matched model name — always one of `allowedNames` — or undefined if none was found. */
     model?: string;
@@ -98,6 +105,19 @@ export declare const ROLE_TIER_DEFAULTS: Readonly<Partial<Record<ModelRole, stri
 export declare function roleSpecNamesModel(spec: RoleSpec | undefined): boolean;
 export interface ResolvedRole {
     model: Model;
+    /**
+     * WHICH REF CHOSE {@link model} — the word, when a word chose it (the explicit `spec.model` string, the
+     * role's own `model` ref, or the role→tier default's catalog key), else the `Model` object itself (an
+     * explicit object, or one a `select` criteria picked: neither has a catalog word).
+     *
+     * The distinction is load-bearing wherever a LATER tick must ask the catalog the same question again: a
+     * word re-resolves against the catalog generation in force at that tick (a hot swap redirects it, a
+     * retirement refuses it loudly), while an object is pinned and never re-resolved. The engine-spawned
+     * child that inherits its parent's model inherits THIS, not the resolved object, so it lands on the
+     * generation its own prepare sees rather than on the one its parent started under; the same word keys
+     * the deployment's per-model context-window overlay.
+     */
+    modelRef: ModelRef;
     /** The effective thinking level: explicit `spec.thinking` wins, else the role's default. */
     thinking?: ThinkingLevel;
     /** The requested role's preset system prompt, if it set one (independent of model fallback). */

package/dist/core/roles.js

@@ -22,59 +22,75 @@ export function resolveModelDisplayLabel(ref) {
     return Object.hasOwn(CC_MODEL_TIER_ALIASES, ref) ? CC_MODEL_TIER_ALIASES[ref] : ref;
 }
 const TIERS_ACTIVE = Symbol.for("sema.tiersActive");
+const TIER_ALIAS_VIA = Symbol.for("sema.tierAliasVia");
 export function expandTiers(models, tiers) {
     if (!tiers || Object.keys(tiers).length === 0)
         return models;
     const out = { ...models };
     out[TIERS_ACTIVE] = true;
+    const aliasVia = new Map();
+    out[TIER_ALIAS_VIA] = aliasVia;
     const bound = (name) => {
         const b = Object.hasOwn(tiers, name) ? tiers[name] : undefined;
         return b === undefined ? undefined : resolveModel(b, models);
     };
-    const resolveTier = (name) => {
-        const direct = bound(name);
+    const ownKey = (k) => models !== undefined && Object.hasOwn(models, k) && Boolean(models[k]);
+    const landing = (t, self) => {
+        const m = bound(t);
+        if (!m)
+            return undefined;
+        const b = Object.hasOwn(tiers, t) ? tiers[t] : undefined;
+        return { model: m, via: [...(t !== self && !ownKey(t) ? [t] : []), ...(typeof b === "string" ? [b] : [])] };
+    };
+    const resolveTier = (name, self = name) => {
+        const direct = landing(name, self);
         if (direct)
             return direct;
         const at = DEFAULT_TIER_ORDER.indexOf(name);
         if (at === -1)
             return undefined;
         for (let i = at + 1; i < DEFAULT_TIER_ORDER.length; i++) {
-            const next = bound(DEFAULT_TIER_ORDER[i]);
+            const next = landing(DEFAULT_TIER_ORDER[i], self);
             if (next)
-                return next;
+                return { model: next.model, via: [...(name !== self && !ownKey(name) ? [name] : []), ...next.via] };
         }
         return undefined;
     };
     const shadowed = (key) => Object.hasOwn(out, key) && Boolean(out[key]);
-    const put = (key, m) => {
+    const put = (key, m, via) => {
         Object.defineProperty(out, key, { value: m, writable: true, enumerable: true, configurable: true });
+        aliasVia.set(key, via);
     };
     const tierNames = new Set([...DEFAULT_TIER_ORDER, ...Object.keys(tiers)]);
     for (const name of tierNames) {
         if (shadowed(name))
             continue;
-        const m = resolveTier(name);
-        if (m)
-            put(name, m);
+        const r = resolveTier(name);
+        if (r)
+            put(name, r.model, r.via);
     }
     for (const [alias, tier] of Object.entries(CC_MODEL_TIER_ALIASES)) {
         if (shadowed(alias))
             continue;
-        const m = resolveTier(tier);
-        if (m)
-            put(alias, m);
+        const r = resolveTier(tier, alias);
+        if (r)
+            put(alias, r.model, r.via);
     }
     if (!shadowed("best")) {
         for (const name of DEFAULT_TIER_ORDER) {
-            const m = bound(name);
-            if (m) {
-                put("best", m);
+            const r = landing(name, "best");
+            if (r) {
+                put("best", r.model, r.via);
                 break;
             }
         }
     }
     return out;
 }
+export function tierAliasVia(word, models) {
+    const via = models?.[TIER_ALIAS_VIA];
+    return via?.get(word) ?? [];
+}
 export function parseModelMention(text, allowedNames) {
     const allowed = new Map();
     for (const n of allowedNames)
@@ -181,6 +197,7 @@ export function resolveTaskModel(spec, deps) {
         const startParts = specParts(mergeRoles(deps.roles, spec.roles)[start]);
         return {
             model: resolveModel(spec.model, deps.models),
+            modelRef: spec.model,
             thinking: spec.thinking ?? startParts.thinking,
             systemPrompt: startParts.systemPrompt,
         };
@@ -190,9 +207,11 @@ export function resolveTaskModel(spec, deps) {
     const startSystemPrompt = specParts(merged[start]).systemPrompt;
     for (const role of [start, ...FALLBACK[start]]) {
         const parts = specParts(merged[role]);
-        const model = partsModel(parts, deps.models) ?? roleTierModel(role, deps.models);
+        const fromParts = partsModel(parts, deps.models);
+        const model = fromParts ?? roleTierModel(role, deps.models);
         if (model) {
-            return { model, thinking: spec.thinking ?? parts.thinking, systemPrompt: startSystemPrompt };
+            const modelRef = fromParts !== undefined ? (parts.model ?? model) : (ROLE_TIER_DEFAULTS[role] ?? model);
+            return { model, modelRef, thinking: spec.thinking ?? parts.thinking, systemPrompt: startSystemPrompt };
         }
     }
     throw new Error(`No model for role "${start}": set TaskSpec.model, or configure RunnerDeps.roles / TaskSpec.roles["${start}"] (or a "default" role). A "select" RoleSpec also fails here if no catalog model matches.`);

package/dist/core/runner/assemble-result.d.ts

@@ -165,6 +165,8 @@ export interface ResultFlags {
      *  `reasoning.resolved` trace frame carried (runtask resolves once per leg — two faces, one mint);
      *  absent when thinking was off/unset for the leg, so the key is omitted. */
     effectiveReasoning?: TaskResult["effectiveReasoning"];
+    /** The run's compaction record (see `TaskResult.compaction`); assembly omits the key when absent. */
+    compaction?: TaskResult["compaction"];
     /** ruled 2026-08-04 — the usage-governance wait hint carried by the platform terminal the run adopted
      *  (`undefined` for every other cause: an expiring environment has no return time to give, and a store
      *  failure is not a window). Passed as data rather than read back off `threw` so the seat has a typed

package/dist/core/runner/assemble-result.js

@@ -2,6 +2,7 @@ import { isDegenerateCutMessage } from "../../brain/terminal-cause.js";
 import { extractErrorCode, stripErrorCodePrefix } from "../../brain/errors.js";
 import { terminalProjection } from "./terminal-projection.js";
 import { haltConsumed } from "./halt-attribution.js";
+import { providerReportedModel } from "../message-utils.js";
 import { isErrorLike, readMember } from "../thrown-value.js";
 import { describeRejectedValue } from "../tool-search-setting.js";
 const SALVAGE_ELIGIBLE_TERMINALS = new Set([
@@ -153,6 +154,7 @@ export function terminalCauseOf(final, stats, flags) {
 export function assembleResult(spec, sessionId, final, stats, flags) {
     const taskId = spec.taskId ?? sessionId;
     const text = final ? assistantText(final) : "";
+    const responseModel = final === undefined ? undefined : providerReportedModel(final);
     if (!flags.unpricedSpend) {
         const compactionMicroUsd = stats.compactionMicroUsd ?? 0;
         const nestedSubagentMicroUsd = stats.nested?.costMicroUsd ?? 0;
@@ -176,5 +178,5 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
     if (flags.unpricedSpend)
         delete publicStats.costMicroUsd;
     const stampHaltedByUser = haltConsumed(flags.haltConsumption);
-    return { taskId, ...(flags.runId !== undefined ? { runId: flags.runId } : {}), sessionId, terminal, ...(flags.model !== undefined ? { model: flags.model } : {}), result: result.trim(), salvagedOutput, ...(apiFailure !== undefined ? { apiFailure } : {}), ...(retryAfterMs !== undefined ? { retryAfterMs } : {}), ...(flags.rewindNotes !== undefined && flags.rewindNotes.length > 0 ? { rewindNotes: flags.rewindNotes } : {}), ...(flags.editedFiles !== undefined && flags.editedFiles.length > 0 ? { editedFiles: flags.editedFiles } : {}), ...(flags.haltedOnUserRejection === true ? { haltedOnUserRejection: true } : {}), ...(stampHaltedByUser ? { haltedByUser: true } : {}), ...(flags.remoteEnvFailures !== undefined && flags.remoteEnvFailures.length > 0 ? { remoteEnvFailures: [...flags.remoteEnvFailures] } : {}), ...(flags.strandedHumanAnswers !== undefined && flags.strandedHumanAnswers.length > 0 ? { strandedHumanAnswers: flags.strandedHumanAnswers } : {}), ...(flags.effectiveReadFace !== undefined ? { effectiveReadFace: flags.effectiveReadFace } : {}), ...(flags.effectiveWriteFace !== undefined ? { effectiveWriteFace: flags.effectiveWriteFace } : {}), ...(flags.effectiveReadDenyPatterns !== undefined && flags.effectiveReadDenyPatterns.length > 0 ? { effectiveReadDenyPatterns: flags.effectiveReadDenyPatterns } : {}), ...(flags.effectiveMemoryScopes !== undefined ? { effectiveMemoryScopes: flags.effectiveMemoryScopes } : {}), ...(flags.effectiveReasoning !== undefined ? { effectiveReasoning: flags.effectiveReasoning } : {}), stats: publicStats };
+    return { taskId, ...(flags.runId !== undefined ? { runId: flags.runId } : {}), sessionId, terminal, ...(flags.model !== undefined ? { model: flags.model } : {}), ...(responseModel !== undefined ? { responseModel } : {}), result: result.trim(), salvagedOutput, ...(apiFailure !== undefined ? { apiFailure } : {}), ...(retryAfterMs !== undefined ? { retryAfterMs } : {}), ...(flags.rewindNotes !== undefined && flags.rewindNotes.length > 0 ? { rewindNotes: flags.rewindNotes } : {}), ...(flags.editedFiles !== undefined && flags.editedFiles.length > 0 ? { editedFiles: flags.editedFiles } : {}), ...(flags.haltedOnUserRejection === true ? { haltedOnUserRejection: true } : {}), ...(stampHaltedByUser ? { haltedByUser: true } : {}), ...(flags.remoteEnvFailures !== undefined && flags.remoteEnvFailures.length > 0 ? { remoteEnvFailures: [...flags.remoteEnvFailures] } : {}), ...(flags.strandedHumanAnswers !== undefined && flags.strandedHumanAnswers.length > 0 ? { strandedHumanAnswers: flags.strandedHumanAnswers } : {}), ...(flags.effectiveReadFace !== undefined ? { effectiveReadFace: flags.effectiveReadFace } : {}), ...(flags.effectiveWriteFace !== undefined ? { effectiveWriteFace: flags.effectiveWriteFace } : {}), ...(flags.effectiveReadDenyPatterns !== undefined && flags.effectiveReadDenyPatterns.length > 0 ? { effectiveReadDenyPatterns: flags.effectiveReadDenyPatterns } : {}), ...(flags.effectiveMemoryScopes !== undefined ? { effectiveMemoryScopes: flags.effectiveMemoryScopes } : {}), ...(flags.effectiveReasoning !== undefined ? { effectiveReasoning: flags.effectiveReasoning } : {}), ...(flags.compaction !== undefined ? { compaction: flags.compaction } : {}), stats: publicStats };
 }

package/dist/core/runner/compaction-call-options.d.ts

@@ -3,7 +3,9 @@ import type { MaybeCompactOptions } from "../auto-compaction.js";
 import type { StaleToolResultOffloadOptions, TaskSpec } from "../types.js";
 import type { Context } from "../../internal/llm.js";
 import { type ToolResultStore } from "../tool-result-store.js";
-import type { Prepared } from "./contracts.js";
+import type { Prepared, RunnerDepsSeat } from "./contracts.js";
+import { type ContextWindowOverlay } from "../context-settings.js";
+import { type CompactionSettings } from "../../internal/harness.js";
 /**
  * The maybeCompact call arguments that MUST be assembled identically on all three
  * of runtask's compaction lanes (turn boundary / prompt-too-long recovery / end-of-task).
@@ -17,7 +19,8 @@ import type { Prepared } from "./contracts.js";
  *
  * Every export is a free function: the turn-boundary lane assembles its call inside `createTurnBoundary`
  * (a module-level function with no `this`), so a method would not be reachable from all three sites.
- * Nothing here reads or writes runner state — pure assembly over `spec` + `Prepared`.
+ * Nothing here WRITES runner state; one export ({@link legContextOverlayOption}) READS the live deps seat,
+ * because reading it at the moment of the pass — not at prepare — is the whole of what it states.
  */
 /**
  * Opt-in working-file attachments (LONGRUN-2 / CC 198 post-compact restore parity).
@@ -142,3 +145,24 @@ writtenRefs: Set<string>): Promise<Context>;
  * scope inside `finish()`.
  */
 export declare function emitInputTruncated(tracer: TracerHook | undefined, taskId: string): NonNullable<MaybeCompactOptions["onInputTruncated"]>;
+/**
+ * The deployment's per-model window overlay in force for THIS pass — the one option of the three lanes that
+ * is deliberately a LIVE read rather than a prepared value.
+ *
+ * Two reads, both at the moment of the pass: the leg's own catalog word (the harness's current ref, so a
+ * mid-task degrade moves the key along with the model) and the Runner's current deps seat (so a `swapDeps`
+ * reaches a leg already running). An object-pinned leg has no word and therefore no overlay — the key is
+ * simply absent, which `maybeCompact` reads as "the model card's own declarations", the pre-seat behavior.
+ */
+export declare function legContextOverlayOption(prepared: Prepared, runner: RunnerDepsSeat): Pick<MaybeCompactOptions, "contextOverlay">;
+/**
+ * The compaction SETTINGS a pass runs under — the assembly all three lanes share.
+ *
+ * `{ ...DEFAULT_COMPACTION_SETTINGS, ...spec.compaction }` was hand-copied at each lane, and it is where the
+ * deployment's live `enabled` declaration belongs: `maybeCompact` has exactly one enablement gate (it reads
+ * `settings.enabled`), so folding the overlay in HERE makes the deployment's switch reach the boundary pass,
+ * the recovery pass and the end-of-task summary by one edit instead of three, and keeps "who decides whether
+ * compaction runs" a single expression ({@link compactionEnabled}: the request authored it > the deployment
+ * declared it > on).
+ */
+export declare function legCompactionSettings(spec: TaskSpec, overlay: ContextWindowOverlay | undefined): CompactionSettings;

package/dist/core/runner/compaction-call-options.js

@@ -1,5 +1,7 @@
 import { emitTrace } from "../trace.js";
 import { buildToolResultRef, OFFLOAD_TOOL_NAME, PERSISTED_OUTPUT_PREFIX, toolResultContentSegment, toolResultProvenanceOf, } from "../tool-result-store.js";
+import { compactionEnabled, contextOverlayFor } from "../context-settings.js";
+import { DEFAULT_COMPACTION_SETTINGS } from "../../internal/harness.js";
 export function buildWorkingFileAttachments(spec, prepared) {
     if (spec.compaction?.attachWorkingFiles === false || !prepared.readTaskFile)
         return undefined;
@@ -115,3 +117,10 @@ export function emitInputTruncated(tracer, taskId) {
         ts: Date.now(),
     }));
 }
+export function legContextOverlayOption(prepared, runner) {
+    const overlay = contextOverlayFor(runner.deps.contextSettings, prepared.harness.getModelRef(), runner.deps);
+    return overlay !== undefined ? { contextOverlay: overlay } : {};
+}
+export function legCompactionSettings(spec, overlay) {
+    return { ...DEFAULT_COMPACTION_SETTINGS, ...spec.compaction, enabled: compactionEnabled(spec.compaction?.enabled, overlay) };
+}

package/dist/core/runner/compaction-seams.d.ts

@@ -8,10 +8,11 @@ import type { Prepared, RunnerDepsSeat } from "./contracts.js";
  * Runner OWNS the consecutive-reuse counter (`prepared.compactionReuseRef`) so the
  * `maxConsecutiveProviderReuse` drift guard spans the whole task across both sites: it FEEDS the current
  * count in as `consecutiveProviderReuse`, and {@link recordCompactionReuse} updates it from the result.
- * Returns `undefined` when no provider is wired (so the call site spreads nothing → byte-identical to
- * the prior behavior).
+ * The provider half is absent when no provider is wired (byte-identical to the prior behavior at every
+ * call site); the #1036 `onCommitted` effect sink rides unconditionally, which is why the
+ * function itself always returns an object.
  */
-export declare function seamCCompactionOptions(runner: RunnerDepsSeat, prepared: Prepared): Pick<MaybeCompactOptions, "summaryProvider" | "onCompaction" | "maxConsecutiveProviderReuse" | "consecutiveProviderReuse"> | undefined;
+export declare function seamCCompactionOptions(runner: RunnerDepsSeat, prepared: Prepared): Pick<MaybeCompactOptions, "summaryProvider" | "onCompaction" | "maxConsecutiveProviderReuse" | "consecutiveProviderReuse" | "onCommitted">;
 /** Resolve the pre/postCompact lifecycle callbacks (whole-slot `spec.hooks ??
  *  deps.hooks`, same resolution as the stop hook) and wrap each in a SWALLOW+TRACE shell before
  *  threading them into maybeCompact. The wrapper owns the observability half of the R3 MED contract

package/dist/core/runner/compaction-seams.js

@@ -1,13 +1,20 @@
 import { hookSeatExpiredError, resolveHookTimeoutMs, runHookSeat } from "../hooks.js";
 import { asThrownError } from "../thrown-value.js";
 export function seamCCompactionOptions(runner, prepared) {
-    if (!runner.deps.summaryProvider)
-        return undefined;
     return {
-        summaryProvider: runner.deps.summaryProvider,
-        onCompaction: runner.deps.onCompaction,
-        maxConsecutiveProviderReuse: runner.deps.maxConsecutiveProviderReuse,
-        consecutiveProviderReuse: prepared.compactionReuseRef.consecutive,
+        ...(runner.deps.summaryProvider
+            ? {
+                summaryProvider: runner.deps.summaryProvider,
+                onCompaction: runner.deps.onCompaction,
+                maxConsecutiveProviderReuse: runner.deps.maxConsecutiveProviderReuse,
+                consecutiveProviderReuse: prepared.compactionReuseRef.consecutive,
+            }
+            : {}),
+        onCommitted: (effect) => {
+            if (prepared.frameSettlement.wantsEffects?.() !== true)
+                return;
+            prepared.frameSettlement.compactions.push(effect);
+        },
     };
 }
 export function compactionHookOptions(runner, spec, sessionId, trigger, identity, seatBound) {