@sema-agent/core 7.54.1 → 7.56.0

package/dist/core/runner/cross-boundary-lane.d.ts

@@ -5,12 +5,16 @@
  * WHERE THE STATE LIVES. The tree's state is one object, reached from the tree's opaque token (`RunInternals.crossBoundaryTree`,
  * `ToolExecuteContext.crossBoundaryTreeForChildren`) through this module alone; each leg joins into it what it knows at prepare (its
  * environment's declaration, its session's newest record, its posture) and every bit an exit sets lands there before the call
- * runs. Each leg's session holds a record (`CROSS_BOUNDARY_RECORD_TYPE`) of the state its content was produced under — written only
- * for an armed tree: at prepare and at an exit (before the call runs) when the state grew past what the session already says, and at
- * a leg's end (before a suspend's row is put, when the leg settles) also when conversation content follows the newest record. A
- * write that fails refuses its call (or its row) on a governed tree; a prepare's or a settle's, and any write on a tree that is not
- * governed, mints `config.cross_boundary_record_unwritten`. A record covers the content before it: a leg that takes over a session
- * whose content no record covers (none on the branch, or after the newest), on an armed tree, reads that content as off-target.
+ * runs — after the record that carries it, so a call the exit refuses sets nothing. Each leg's session holds a record
+ * (`CROSS_BOUNDARY_RECORD_TYPE`) of the state its content is read under — written only for an armed tree: at prepare and at an
+ * exit (before the call runs) when the state grew past what the session already says, and at a leg's end (before a suspend's row is
+ * put, when the leg settles) also when conversation content follows the newest record. A write that fails refuses its call (or its
+ * row) on a governed tree; a prepare's or a settle's, and any write on a tree that is not governed, mints
+ * `config.cross_boundary_record_unwritten`, once per state. A record says how the content before it is READ: a leg's end record also
+ * carries what the session is still owed — each unfinished background task the leg's TaskOutput reaches, judged as the poll the
+ * session's next leg (another tree) would make of it, so its delivery is read under the bit it brings. A leg that takes over a
+ * session whose content no record covers (none on the branch, or after the newest), on an armed tree, reads that content as
+ * off-target.
  *
  * THE OBLIGATION of a call is read off three things at the moment it is asked ({@link crossBoundaryObligation}): the legs the
  * call travels (its roster row's declaration, or what the dispatching code gives per call), whether the environment the `env`
@@ -18,7 +22,7 @@
  */
 import type { AgentTool } from "../../internal/harness.js";
 import type { SessionTreeEntry } from "../../internal/harness-types.js";
-import { type CrossBoundaryCheck, type CrossBoundaryPosture, type CrossBoundaryTreeToken } from "../cross-boundary-taint.js";
+import { type CrossBoundaryCheck, type CrossBoundaryPosture, type CrossBoundaryTreeToken, type OwedDeliveries } from "../cross-boundary-taint.js";
 import { type ToolRoster } from "../tool-roster.js";
 import type { RunnerDeps } from "../types.js";
 /** A new tree with no bit set, and the token that names it — the one mint of a token. */
@@ -38,23 +42,24 @@ export interface CrossBoundaryLane {
     seat(view: CrossBoundaryLegView): CrossBoundaryCheck | undefined;
     /** The seat minted by {@link seat}, for the resumed call's exit. */
     readonly check: CrossBoundaryCheck | undefined;
-    /** Write the record the tree's state owes this leg's session: the new entry's id, or undefined when nothing was owed (or, on a tree
-     *  that is not governed, the write failed and was reported); throws when it cannot be written on a governed tree. With `atLeaf` (a
-     *  suspend: a leg's end), the record also covers the content after the newest one and is written only as the child of that leaf
-     *  (the row then points at it). */
-    owe(atLeaf?: string): Promise<string | undefined>;
+    /** A suspend (a leg's end) writes the record its row's leaf owes: the new entry's id, or undefined when nothing was owed (or, on a
+     *  tree that is not governed, the write failed and was reported); throws when it cannot be written on a governed tree. The record
+     *  covers the content after the newest one and what the session is still `owed`, and is written only as the child of `atLeaf` (the
+     *  row then points at it). */
+    owe(atLeaf: string, owed: OwedDeliveries): Promise<string | undefined>;
     /** The tree is armed, so the session OWES the tree's record and a parked row says a reader must read it — on a tree that is not
      *  governed a failed write leaves the record missing (the notice says so), and the reader then reads the content after the newest
      *  record as off-target. */
     recorded(): boolean;
-    /** The leg settles: the record that covers what it added is written, a failure reported loudly (the next leg then reads the
-     *  content after the newest record as off-target). */
-    settle(): Promise<void>;
+    /** The leg settles: the record that covers what it added and what the session is still `owed` is written, a failure reported
+     *  loudly (the next leg then reads the content after the newest record as off-target). */
+    settle(owed: OwedDeliveries): Promise<void>;
     /** How many times this leg's record writes have waited on the session store — a station that judged before an exit reads again
      *  when the count moved across it (the exit's own form: judged again after a wait). */
     storeWaits(): number;
 }
-/** What the seat reads per call: the live roster (the legs a row declares) and the mounted instances (a `"per_call"` resolver). */
+/** What the seat reads per call: the live roster (the legs a row declares) and the mounted instances (a `"per_call"` row's resolver,
+ *  read off the later mount under the row's name — the instance the row was minted from, but in a redial window: KL-2284-c). */
 export interface CrossBoundaryLegView {
     readonly tools: readonly AgentTool[];
     readonly roster: {

package/dist/core/runner/cross-boundary-lane.js

@@ -2,7 +2,7 @@ import { BOUNDARY_LEGS, CROSS_BOUNDARY_RECORD_TYPE, CROSS_BOUNDARY_TAINT_BITS, S
 import { deliverEngineNotice } from "../engine-notice.js";
 import { policyCannotAnswer } from "../real-approval.js";
 import { thrownText } from "../thrown-value.js";
-import { rosterEntryNamed } from "../tool-roster.js";
+import { rosterEntryNamed, survivorsByName } from "../tool-roster.js";
 import { emitTrace } from "../trace.js";
 const TREE_STATE = new WeakMap();
 export function mintCrossBoundaryTree() {
@@ -21,6 +21,7 @@ export function joinedCrossBoundaryTree(handed, report) {
     return token;
 }
 const EVERY_LEG = Object.freeze([...BOUNDARY_LEGS]);
+const ONE_OUTSIDE_READ = Object.freeze([Object.freeze({ legs: Object.freeze(["outside_read"]) })]);
 const bitsOf = (t) => CROSS_BOUNDARY_TAINT_BITS.filter((b) => t[b] === true);
 function legsOfCall(view, legEnv, token, call, report) {
     const roster = view.roster.current;
@@ -30,7 +31,7 @@ function legsOfCall(view, legEnv, token, call, report) {
     if (row.boundaryLegs !== "per_call")
         return { legs: row.boundaryLegs, env: legEnv };
     const strictest = (why) => (report(`tool "${row.name}" declares its boundary legs per call, and its boundaryLegsFor ${why} — the call reads as every leg, off the target (the strictest reading)`), { legs: EVERY_LEG, env: undefined });
-    const resolve = view.tools.find((t) => t.name === row.name)?.boundaryLegsFor;
+    const resolve = survivorsByName(view.tools).get(row.name)?.boundaryLegsFor;
     if (typeof resolve !== "function")
         return strictest("is missing");
     let given;
@@ -47,7 +48,13 @@ function legsOfCall(view, legEnv, token, call, report) {
 }
 export async function prepareCrossBoundaryLane(input) {
     const { posture, externalContentTargetActive, env, session, resumeLeg, sessionId, runId, hostTaskId, deps } = input;
-    const report = (message) => deps.onError?.(new Error(message), { phase: "config", sessionId });
+    const report = (message) => {
+        try {
+            deps.onError?.(new Error(message), { phase: "config", sessionId });
+        }
+        catch {
+        }
+    };
     const token = input.token ?? mintCrossBoundaryTree();
     const ref = TREE_STATE.get(token);
     if (ref === undefined)
@@ -70,52 +77,56 @@ export async function prepareCrossBoundaryLane(input) {
         tree = joinCrossBoundaryTree(tree, { offTargetReadObserved: true });
     ref.current = tree;
     const stationEngaged = posture !== undefined || externalContentTargetActive || crossBoundaryTreeGoverned(tree);
-    const unwritten = (phase, err) => deliverEngineNotice(deps.onNotice, crossBoundaryRecordUnwrittenNotice({ sessionId, runId, phase, governed: crossBoundaryTreeGoverned(ref.current), cause: thrownText(err) }));
+    let reported;
+    const unwritten = (phase, state, err) => {
+        if (reported !== undefined && crossBoundaryTreeCovers(reported, state))
+            return;
+        reported = state;
+        deliverEngineNotice(deps.onNotice, crossBoundaryRecordUnwrittenNotice({ sessionId, runId, phase, governed: crossBoundaryTreeGoverned(ref.current), cause: thrownText(err) }));
+    };
     let writing = Promise.resolve();
     let storeWaits = 0;
-    const write = (phase, atLeaf) => {
+    const write = (phase, atLeaf, joins = () => undefined) => {
         const next = writing.then(async () => {
-            let leafAt = atLeaf;
-            let cover = phase === "suspend" || phase === "settle";
+            const legEnd = phase === "suspend" || phase === "settle";
             let written;
             for (;;) {
-                const state = ref.current;
-                if (state.targetExecutionArmed !== true)
+                if (ref.current.targetExecutionArmed !== true)
                     return written;
+                const state = joinCrossBoundaryTree(ref.current, joins() ?? {});
                 const grown = !crossBoundaryTreeCovers(recorded, state);
-                if (!grown && !cover)
+                if (!grown && !legEnd)
                     return written;
                 try {
                     if (!grown) {
                         storeWaits++;
                         const now = readCrossBoundaryRecord((await session.getBranch()));
-                        if (now.kind !== "malformed" && !now.uncoveredContent) {
-                            cover = false;
-                            continue;
-                        }
+                        if (now.kind !== "malformed" && !now.uncoveredContent)
+                            return written;
                     }
-                    if (leafAt !== undefined) {
+                    if (atLeaf !== undefined) {
                         storeWaits++;
-                        if ((await session.getLeafId()) !== leafAt)
+                        if ((await session.getLeafId()) !== atLeaf)
                             throw new Error("the session moved past the row's leaf before its record could be written");
                     }
                     storeWaits++;
                     const entryId = await session.appendCustomEntry(CROSS_BOUNDARY_RECORD_TYPE, crossBoundaryRecordData(state));
                     if (typeof entryId !== "string" || entryId.length === 0)
                         throw new Error(`the session store answered the record's append with no entry id (${typeof entryId})`);
-                    if (leafAt !== undefined && (storeWaits++, await session.getLeafId()) !== entryId)
+                    if (atLeaf !== undefined && (storeWaits++, await session.getLeafId()) !== entryId)
                         throw new Error("the record the session store appended is not the session's new leaf");
                     recorded = state;
                     written = entryId;
-                    if (leafAt !== undefined)
-                        leafAt = entryId;
-                    cover = false;
+                    if (legEnd)
+                        return written;
                 }
                 catch (err) {
-                    if (crossBoundaryTreeGoverned(ref.current))
+                    const governed = crossBoundaryTreeGoverned(ref.current);
+                    if (governed && (phase === "exit" || phase === "suspend"))
                         throw err;
-                    unwritten(phase, err);
-                    recorded = state;
+                    unwritten(phase, state, err);
+                    if (!governed)
+                        recorded = state;
                     return written;
                 }
             }
@@ -123,13 +134,24 @@ export async function prepareCrossBoundaryLane(input) {
         writing = next.catch(() => undefined);
         return next;
     };
-    const owe = (atLeaf) => write(atLeaf !== undefined ? "suspend" : "exit", atLeaf);
+    const OBSERVED = Object.freeze({ offTargetReadObserved: true });
+    const addedBy = (record) => (record && ref.current.offTargetReadObserved !== true ? OBSERVED : undefined);
+    const owedBit = (owed) => {
+        const records = (given) => given.some((d) => crossBoundaryObligation(d.legs, d.env?.externalContentTarget === true, ref.current).record);
+        try {
+            return addedBy(records(owed()));
+        }
+        catch (err) {
+            report(`the deliveries this leg's session is still owed could not be read (${thrownText(err)}) — read as content from beyond the device`);
+            return addedBy(records(ONE_OUTSIDE_READ));
+        }
+    };
     const trace = (phase, call) => emitTrace(deps.tracer, () => ({ kind: "permission.cross_boundary_taint", version: 1, taskId: hostTaskId, runId, phase, taint: bitsOf(ref.current), governed: ref.current.governed === true, ...(call !== undefined ? { toolName: call.toolName, ...(call.toolCallId !== undefined ? { toolCallId: call.toolCallId } : {}) } : {}), ts: Date.now() }));
     if (tree.targetExecutionArmed === true) {
         trace(resumeLeg ? "resume" : "prepare");
         if (posture === undefined && tree.governed !== true)
             deliverEngineNotice(deps.onNotice, crossBoundaryPostureUndeclaredNotice({ sessionId, runId, tree }));
-        await write("prepare").catch((err) => unwritten("prepare", err));
+        await write("prepare");
     }
     let check;
     const lane = {
@@ -163,28 +185,30 @@ export async function prepareCrossBoundaryLane(input) {
                                 message: `tool "${call.toolName}" needs a person's confirmation: this run executes on a target device${ref.current.offTargetReadObserved === true ? " and has since let content from beyond it in, so a call that reaches beyond the device or back into it" : ", so a call that writes beyond the device"} is put to a person — this call was allowed by a configuration, not a person, and was not executed`,
                             };
                         }
-                        if (now.record && ref.current.offTargetReadObserved !== true) {
-                            ref.current = joinCrossBoundaryTree(ref.current, { offTargetReadObserved: true });
-                            trace("observed", call);
-                        }
+                        const adds = addedBy(now.record);
                         const judged = ref.current;
                         try {
-                            await owe();
+                            await write("exit", undefined, () => adds);
                         }
                         catch (err) {
                             return { kind: "unrecorded", message: `tool "${call.toolName}" was not executed: the session's cross-boundary record could not be written before it ran (${thrownText(err)}) — on a governed tree a call that owes its record does not run without it; refused fail-closed` };
                         }
-                        if (ref.current === judged)
-                            return undefined;
+                        if (ref.current !== judged)
+                            continue;
+                        if (adds !== undefined) {
+                            ref.current = joinCrossBoundaryTree(ref.current, adds);
+                            trace("observed", call);
+                        }
+                        return undefined;
                     }
                 },
             };
             return check;
         },
-        owe,
+        owe: (atLeaf, owed) => write("suspend", atLeaf, () => owedBit(owed)),
         storeWaits: () => storeWaits,
         recorded: () => ref.current.targetExecutionArmed === true,
-        settle: () => write("settle").then(() => undefined, (err) => unwritten("settle", err)),
+        settle: (owed) => write("settle", undefined, () => owedBit(owed)).then(() => undefined),
     };
     return lane;
 }

package/dist/core/runner/decide-continuation.d.ts

@@ -17,7 +17,7 @@
  */
 import { type AskOrigin } from "../ask-origin.js";
 import { type OnQuestion, type QuestionAnswer } from "../ask-question.js";
-import { type Checkpoint, type ResolvedOutcome, type ResumeOutcome } from "../checkpoint-store.js";
+import { type Checkpoint, type CheckpointErrorField, type ResolvedOutcome, type ResumeOutcome } from "../checkpoint-store.js";
 import { type GateOutcome, type HostDecisionFacts } from "../gate-outcome.js";
 import type { ResumeRun } from "./contracts.js";
 /**
@@ -130,10 +130,13 @@ export declare function mintDecideRecord(cp: Checkpoint, facts: HostDecisionFact
  * answer differently each time — the check passing on text it never inspected. Refused pre-CAS so the
  * row stays `pending` for a well-formed decide, exactly like the other capture-time domain refusals,
  * and BEFORE the hygiene check so no guard ever consults a value outside the domain. The rejected field
- * is named in the message only — `CheckpointError`'s structured `detail.field` is a closed set covering
- * the approval lane's payload names, and widening it is a wire-surface change of its own.
+ * is named in the message, and in `detail` where the caller hands the closed set's word for the cell
+ * (`CheckpointErrorField`: `feedback` has one; `reason` and `editedPlan` have none, and widening the set is a
+ * wire-surface change of its own).
  */
-export declare function assertOutcomeText(value: string | undefined, field: "editedPlan" | "reason" | "feedback"): void;
+export declare function assertOutcomeText(value: string | undefined, field: "editedPlan" | "reason" | "feedback", detail?: {
+    field: CheckpointErrorField;
+}): void;
 /**
  * The continuation prompt for a resumed run. The vendored harness only exposes
  * `prompt(text)` (it always appends a user message — there is no "continue from tool results" entry), so

package/dist/core/runner/decide-continuation.js

@@ -123,9 +123,9 @@ export function mintDecideRecord(cp, facts, verdict) {
     const settlement = settlementOfHostDecision(facts, verdict.allowed ? "allowed" : "refused", verdict.note);
     return mintGateOutcome({ ...(verdict.allowed ? {} : { deniedBy: "ask_resolution" }), settled: { settlement, origin } });
 }
-export function assertOutcomeText(value, field) {
+export function assertOutcomeText(value, field, detail) {
     if (value !== undefined && typeof value !== "string") {
-        throw new CheckpointError("checkpoint.invalid_outcome", `resume \`${field}\` is not a plain string (got ${typeof value}) — a decide's text payload is an operator's plain data, not a live object; refusing pre-CAS, the checkpoint stays pending`);
+        throw new CheckpointError("checkpoint.invalid_outcome", `resume \`${field}\` is not a plain string (got ${typeof value}) — a decide's text payload is an operator's plain data, not a live object; refusing pre-CAS, the checkpoint stays pending`, detail);
     }
 }
 function reorientClause(fullShellReachable) {

package/dist/core/runner/denial-limit-arms.d.ts

@@ -103,9 +103,9 @@ export type InheritedAsk = Extract<PermissionResult, {
  * {@link judgeInheritedClassifier} and threaded to every reader ({@link inheritedAskCarry}).
  * The MANDATE marks here are empty (the base names no seat): the policy-chain phase builds each call's facts over this
  * base with THIS task's tool seat — the seat the request's risk axes are read from — so a marked tool's ask is
- * classified by the seat at the station as at the gate. What the ancestor's ask carries on ITSELF still answers.
+ * classified by the seat at the station as at the gate. What the ancestor's ask carries on ITSELF still answers. No call either (each station's own).
  */
-export declare const INHERITED_STATION_FACTS: AskOriginFacts;
+export declare const INHERITED_STATION_FACTS: Omit<AskOriginFacts, "call">;
 /** The members of a surviving ask that ride onto the approval request with a COMPUTED value — what the
  *  four request mint stations (the gate's own and the three inherited-lane ones) spread after the seats
  *  they spell themselves: the ask's origin word, its class (the word and the set, carried together) and its
@@ -170,13 +170,13 @@ export type InheritedClassifierJudgment<A extends InheritedAsk> =
 };
 /**
  * The ancestor's frozen classifier, run BEFORE its frozen approver in the ancestor's own gate order,
- * with the denial-limit count folded in (CC 2.1.250 count-then-judge): `allow` ⇒ the classifier's
+ * with the denial-limit count folded in (count-then-judge): `allow` ⇒ the classifier's
  * auto-allow (and the streak resets); `block` below the bound ⇒ deny, the exact verdict the ancestor's
  * gate would have produced; `block` AT the bound ⇒ the ask is re-spoken in the classifier's voice as
  * the fallback (`decisionReason:"classifier"`, `requiresRealApproval`, the member carrying counts +
  * window) for the arm to resolve at the frozen approver; a classification that did not rule (`unavailable`, or a reply
  * with no verdict) ⇒ the gate's own exit (`classifierNoRulingArm`) on the frozen approver — a live one resolves the incoming
- * ask carrying why (never counted); none ⇒ the unavailable form is a DENY that says so (CC 2.1.250 form, never counted) and
+ * ask carrying why (never counted); none ⇒ the unavailable form is a DENY that says so (never counted) and
  * a reply with no verdict takes the block path with the CC parse-failure sentence (counted); a CONFLICTING reply takes the
  * block path too; excluded / no classifier ⇒ the incoming ask, unchanged. The member may ALREADY be on the incoming
  * ask (a deeper ancestor's fallback, minted inside the nested fold — the case the exclusion names):

package/dist/core/runner/denial-limit-arms.js

@@ -86,7 +86,7 @@ export function inheritedAskCarry(judged, liveApprover, tracker) {
 export const inheritedAskFallbackMessage = (toolName) => `approval required for "${toolName}" (inherited parent policy)`;
 export async function judgeInheritedClassifier(opts) {
     const { autoMode, req } = opts;
-    const facts = opts.facts ?? INHERITED_STATION_FACTS, m = facts.mandateMarks;
+    const facts = opts.facts ?? { ...INHERITED_STATION_FACTS, call: req }, m = facts.mandateMarks;
     const frames = [...(m.egress === true ? [markTightenMessage(req.toolName, "egress")] : []), ...(m.irreversibility === "always" ? [markTightenMessage(req.toolName, "irreversible")] : [])];
     const ask = (frames.length > 0 ? { ...opts.ask, message: [opts.ask.message ?? inheritedAskFallbackMessage(req.toolName), ...frames].join(" — ") } : opts.ask);
     const origin = askOriginOf(ask, facts);

package/dist/core/runner/derived-route-fallback.d.ts

@@ -1,22 +1,25 @@
 /**
- * The derived-leg route pre-flight shared by prepareTask's two derived seats: the compaction-summary model (the
- * driver's own seat, resolved before the offload prelude) and the auto-mode classifier model (the caps-and-workflow
- * phase's arming). Moved whole out of the orchestrator so the phase reaches DOWN for it instead of the two callers
- * spelling it twice. The judgment law and both announcements live in the brain's route adjudicator; this is the one
- * guarded seat around them.
+ * The derived-leg route pre-flight shared by prepareTask's derived seats: the compaction-summary model, the auto-mode
+ * classifier model and the advisor model. One guarded seat, reached DOWN for by each phase instead of spelled again; the
+ * judgment law and the announcements live in the brain's route adjudicator.
  */
-import type { Model } from "../../internal/llm.js";
+import type { Model, RouteRefusalCode } from "../../internal/llm.js";
 import type { RunnerDeps, TaskSpec } from "../types.js";
+/** What the pre-flight decided: keep the seat's model (same route as the primary, the pairing holds, the judge abstained, or
+ *  the deployment declined a fallback — the seat is kept and its calls refused), swap it for the primary, or take the seat
+ *  off this run. A move carries the refusal that caused it. */
+export type DerivedSeatOutcome = {
+    readonly action: "keep";
+} | {
+    readonly action: "fall_back" | "detach";
+    readonly cause: RouteRefusalCode;
+};
 /**
- * The derived-leg pairing pre-flight as ONE guarded seat: judge the derived model where its route
- * differs from the primary's, announce what a broken pairing means for THIS seat (`onBrokenPairing` —
- * one judgment, and the POSTURE is the deployment's), and ABSTAIN (keep the derived model) on ANY throw. The pre-flight is advisory — the brain's request gate re-runs the
- * same law — so neither a throwing judge face nor a garbage catalog value (the route-identity
- * normalization throws a TypeError on a non-string baseUrl) may widen into "task preparation
- * failed": at the compaction seat the session is already acquired and the throw-cleanup contract
- * is not yet armed, so a throw here would leak the acquired session view, and the garbage value
- * still earns its loud refusal at the request gate the moment the derived leg is actually used.
- * Returns whether the seat should fall back to the primary model.
+ * Judge the derived model where its route differs from the primary's, announce what a broken pairing means for THIS seat
+ * (`onBrokenPairing`), and ABSTAIN (keep) on ANY throw. The pre-flight is advisory — the brain's request gate re-runs the
+ * same law — so neither a throwing judge face nor a garbage catalog value may widen into "task preparation failed": at the
+ * compaction seat the session is already acquired and the throw-cleanup contract is not yet armed, and the garbage value
+ * still earns its loud refusal at the request gate the moment the derived leg is used.
  */
 export declare function derivedRouteFallsBack(args: {
     seat: string;
@@ -25,14 +28,11 @@ export declare function derivedRouteFallsBack(args: {
     brain: RunnerDeps["brain"];
     getApiKeyAndHeaders: TaskSpec["getApiKeyAndHeaders"];
     onNotice: RunnerDeps["onNotice"];
-    /** The run this seat resolution belongs to; carried onto the notice as its routing key
-     *  (the audience stays operator: correlation, not entitlement). Absent ⇒ nothing is fabricated. */
+    /** The session / INVOCATION this resolution belongs to: correlation keys on the notice (the audience stays operator). */
     sessionId?: string;
-    /** The INVOCATION this seat resolution belongs to. The session cannot stand in for it: two
-     *  runs of one session that both fall back on the same seat mint otherwise byte-identical lines. */
     runId?: string;
-    /** What this seat's DEPLOYMENT asked for on a broken pairing. Absent / `"fall_back"`: swap and announce `route.fallback_to_primary`
-     *  (the only posture a seat with no knob of its own has). `"refuse"`: keep the seat and announce `route.classifier_unroutable` — never
-     *  quietly granting a fallback the deployment declined (`autoMode.classifierFallback: "none"`); announcing is why no swap is not no word. */
-    onBrokenPairing?: "fall_back" | "refuse";
-}): Promise<boolean>;
+    /** Absent / `"fall_back"`: swap and announce `route.fallback_to_primary`. `"refuse"`: keep the seat and announce
+     *  `route.classifier_unroutable` (the deployment declined a fallback — never granted quietly). `"detach"`: take the seat
+     *  off the run and announce `route.seat_detached` (a seat the primary model cannot stand in for). */
+    onBrokenPairing?: "fall_back" | "refuse" | "detach";
+}): Promise<DerivedSeatOutcome>;

package/dist/core/runner/derived-route-fallback.js

@@ -1,21 +1,23 @@
-import { adjudicateDerivedRoute, fallbackToPrimaryNotice, sameRouteIdentity, unroutableSeatNotice } from "../../brain/route-adjudicator.js";
+import { adjudicateDerivedRoute, fallbackToPrimaryNotice, sameRouteIdentity, seatDetachedNotice, unroutableSeatNotice } from "../../brain/route-adjudicator.js";
 import { deliverEngineNotice } from "../types.js";
 export async function derivedRouteFallsBack(args) {
     try {
         if (sameRouteIdentity(args.derived, args.primary))
-            return false;
+            return { action: "keep" };
         const verdict = await adjudicateDerivedRoute({ brain: args.brain, model: args.derived, getApiKeyAndHeaders: args.getApiKeyAndHeaders });
         if (verdict === undefined || verdict.ok)
-            return false;
+            return { action: "keep" };
         const shared = { seat: args.seat, from: args.derived.id, verdict, ...(args.sessionId !== undefined ? { sessionId: args.sessionId } : {}), ...(args.runId !== undefined ? { runId: args.runId } : {}) };
-        const refuse = args.onBrokenPairing === "refuse";
-        if (refuse)
+        const posture = args.onBrokenPairing ?? "fall_back";
+        if (posture === "refuse")
             deliverEngineNotice(args.onNotice, unroutableSeatNotice({ ...shared, primary: args.primary.id }));
+        else if (posture === "detach")
+            deliverEngineNotice(args.onNotice, seatDetachedNotice(shared));
         else
             deliverEngineNotice(args.onNotice, fallbackToPrimaryNotice({ ...shared, to: args.primary.id }));
-        return !refuse;
+        return posture === "refuse" ? { action: "keep" } : { action: posture, cause: verdict.code };
     }
     catch {
-        return false;
+        return { action: "keep" };
     }
 }

package/dist/core/runner/file-history-request.d.ts

@@ -11,6 +11,24 @@ import type { RunnerDeps, TaskSpec } from "../types.js";
  * exactly as it was. What it resolves rides into the file-history phase (`prepareFileHistory`) unchanged.
  */
 export declare function resolveFileHistoryRequest(spec: Pick<TaskSpec, "resumeAt" | "resumeAtMode" | "restoreFiles" | "rewindFilesTo" | "fileHistory">, deps: Pick<RunnerDeps, "onTrackFailure" | "fileHistoryStore" | "fileHistoryCapture">): FileHistoryRequest;
+/**
+ * The DEPLOYMENT's file-history door — the three seats a deployment sets once (`RunnerDeps.onTrackFailure`,
+ * `RunnerDeps.fileHistoryStore`, `RunnerDeps.fileHistoryCapture`), each refused by name on a bad value. Read by
+ * every seat that touches file history: the run's request door above and the out-of-run `Runner.rewindFiles`, so a
+ * misconfigured deployment is refused the same way at both. `fileHistoryStore` is the store after the declared
+ * `"disabled"` word; `captureStore` additionally drops it when capture is `"off"` (recording stops, restore stays).
+ */
+export declare function resolveDeploymentFileHistory(deps: Pick<RunnerDeps, "onTrackFailure" | "fileHistoryStore" | "fileHistoryCapture">): {
+    onTrackFailure: "refuse" | "proceed-unprotected";
+    wiredSeat: FileHistoryStore | "disabled" | undefined;
+    captureOff: boolean;
+    fileHistoryStore: FileHistoryStore | undefined;
+    captureStore: FileHistoryStore | undefined;
+};
+/** A restore asked of a deployment that holds no history backend (none wired, or declared `"disabled"`). */
+export declare function storeUnconfiguredRefusal(wiredSeat: FileHistoryStore | "disabled" | undefined, target: string): Error & {
+    code?: string;
+};
 /** What {@link resolveFileHistoryRequest} resolved: the validated seats and words, the run's store (after every off
  *  switch) and its capture store, and the restore target (`undefined` = no restore asked). */
 export interface FileHistoryRequest {

package/dist/core/runner/file-history-request.js

@@ -1,13 +1,6 @@
 export function resolveFileHistoryRequest(spec, deps) {
-    const onTrackFailure = deps.onTrackFailure === undefined ? "refuse" : deps.onTrackFailure;
-    if (onTrackFailure !== "refuse" && onTrackFailure !== "proceed-unprotected") {
-        const e = new Error(`RunnerDeps.onTrackFailure must be "refuse" or "proceed-unprotected"; got ${JSON.stringify(deps.onTrackFailure)} — refusing prepare rather than silently defaulting a first-touch-failure policy.`);
-        e.code = "config.invalid_on_track_failure";
-        throw e;
-    }
-    const wiredSeat = resolveWiredFileHistoryStore(deps.fileHistoryStore);
+    const { onTrackFailure, wiredSeat, captureOff } = resolveDeploymentFileHistory(deps);
     const runDeclaredOff = resolveRunFileHistoryWord(spec.fileHistory);
-    const captureOff = resolveFileHistoryCaptureWord(deps.fileHistoryCapture, wiredSeat);
     const declaredOff = wiredSeat === "disabled" || runDeclaredOff;
     const fileHistoryStore = declaredOff ? undefined : wiredSeat;
     const captureStore = captureOff ? undefined : fileHistoryStore;
@@ -34,14 +27,29 @@ export function resolveFileHistoryRequest(spec, deps) {
     if (rewindTarget !== undefined && fileHistoryStore === undefined) {
         if (runDeclaredOff)
             throw captureDisabledRefusal(rewindTarget);
-        const e = new Error(wiredSeat === "disabled"
-            ? `rewind-files: restoring files to entry "${rewindTarget}" requires a history backend, but this deployment declared file history disabled (RunnerDeps.fileHistoryStore: "disabled"), so there is no history to restore — the files were NOT rewound`
-            : `rewind-files: restoring files to entry "${rewindTarget}" requires a history backend, but this deployment wired no RunnerDeps.fileHistoryStore — no file history was ever recorded, so the files were NOT rewound`);
-        e.code = "rewind.store_unconfigured";
-        throw e;
+        throw storeUnconfiguredRefusal(wiredSeat, rewindTarget);
     }
     return { onTrackFailure, wiredSeat, runDeclaredOff, captureOff, declaredOff, fileHistoryStore, captureStore, rewindTarget, rewindBefore };
 }
+export function resolveDeploymentFileHistory(deps) {
+    const onTrackFailure = deps.onTrackFailure === undefined ? "refuse" : deps.onTrackFailure;
+    if (onTrackFailure !== "refuse" && onTrackFailure !== "proceed-unprotected") {
+        const e = new Error(`RunnerDeps.onTrackFailure must be "refuse" or "proceed-unprotected"; got ${JSON.stringify(deps.onTrackFailure)} — refusing prepare rather than silently defaulting a first-touch-failure policy.`);
+        e.code = "config.invalid_on_track_failure";
+        throw e;
+    }
+    const wiredSeat = resolveWiredFileHistoryStore(deps.fileHistoryStore);
+    const captureOff = resolveFileHistoryCaptureWord(deps.fileHistoryCapture, wiredSeat);
+    const fileHistoryStore = wiredSeat === "disabled" ? undefined : wiredSeat;
+    return { onTrackFailure, wiredSeat, captureOff, fileHistoryStore, captureStore: captureOff ? undefined : fileHistoryStore };
+}
+export function storeUnconfiguredRefusal(wiredSeat, target) {
+    const e = new Error(wiredSeat === "disabled"
+        ? `rewind-files: restoring files to entry "${target}" requires a history backend, but this deployment declared file history disabled (RunnerDeps.fileHistoryStore: "disabled"), so there is no history to restore — the files were NOT rewound`
+        : `rewind-files: restoring files to entry "${target}" requires a history backend, but this deployment wired no RunnerDeps.fileHistoryStore — no file history was ever recorded, so the files were NOT rewound`);
+    e.code = "rewind.store_unconfigured";
+    return e;
+}
 function resolveWiredFileHistoryStore(candidate) {
     if (candidate === undefined || candidate === "disabled")
         return candidate;

package/dist/core/runner/file-history-restore.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The ONE restore of a session's tracked set and the ONE reading of its answer, reached DOWN for by the two seats that
+ * restore: the file-history phase's restore seat (`prepare-file-history.ts`, a `restoreFiles` / `rewindFilesTo` run)
+ * and the out-of-run rewind (`rewind-files.ts`, `Runner.rewindFiles`). A rewind outside a run is therefore the same
+ * history operation as the one a run performs, refused with the same codes and sentences, and handing the paths it
+ * moved to the same read-state channel.
+ */
+import type { ExecutionEnv } from "../../internal/harness.js";
+import type { FileHistoryRestoreResult, FileHistoryStore, RewindFilesResult } from "../file-history-store.js";
+import type { SessionReadFileStates } from "./session-read-file-states.js";
+/** A restore outcome a seat may accept: the ledger, with `failed` (the operation could not run) already refused —
+ *  the out-of-run rewind's answer carries exactly this. */
+export type AcceptedFileHistoryRestore = Extract<RewindFilesResult, {
+    dryRun: false;
+}>["restore"];
+/**
+ * The ONE restore of a session's tracked set and the ONE reading of its answer — the run's restore seat and the
+ * out-of-run `Runner.rewindFiles` both call it, so the two cannot disagree about what a restore means:
+ *  · every path the attempt may have moved (`filesChanged` ∪ `failed[].path`, whatever the outcome) goes to the
+ *    session's read-state channel (`noteRestored`), because a read record of the old bytes must stop vouching
+ *    for them on the session's next leg;
+ *  · `not_found` is "no boundary for that entry" — `rewind_snapshot.unresolvable` (in a "before" restore, the
+ *    before-specific sentence);
+ *  · any other `failed` outcome is `rewind.restore_failed` carrying the ledger and the store's own judgment on
+ *    the coded `detail` channel (a host reads it, never the prose).
+ * A `complete` or `partial` answer is returned for the caller to accept: only a run goes on to work on the tree,
+ * so only the run seat has a partial-restore policy.
+ */
+export declare function settleFileHistoryRestore(input: {
+    store: FileHistoryStore;
+    sessionId: string;
+    target: string;
+    before: boolean;
+    env: ExecutionEnv;
+    root: string;
+    signal: AbortSignal | undefined;
+    readStates: Pick<SessionReadFileStates, "noteRestored"> | undefined;
+}): Promise<AcceptedFileHistoryRestore>;
+/** The per-file ledger as one sentence (counts, then each refused / failed path with its reason). */
+export declare function fileHistoryRestoreLedgerLine(r: FileHistoryRestoreResult): string;
+/** A restore whose entry has no boundary on the session; a PREVIEW's form says "usable" — its probe
+ *  (`canRestore`) cannot tell a boundary never made from one that is there and unreadable, a real restore can. */
+export declare function noBoundaryRefusal(target: string, sessionId: string, preview?: boolean): Error & {
+    code?: string;
+};

package/dist/core/runner/file-history-restore.js

@@ -0,0 +1,46 @@
+import { resolveTrackKey } from "../file-history-store.js";
+import { isGovernanceRetryClass } from "../governance-codes.js";
+export async function settleFileHistoryRestore(input) {
+    const { store, sessionId, target, env, root } = input;
+    const restored = await store.restore(sessionId, target, env, root, input.signal);
+    input.readStates?.noteRestored(sessionId, restoredAbsPathsOf(restored, root));
+    if (restored.outcome !== "failed")
+        return restored;
+    if (restored.error?.code === "not_found") {
+        if (input.before)
+            throw beforeWithoutBoundaryRefusal(target, sessionId);
+        throw noBoundaryRefusal(target, sessionId);
+    }
+    const e = new Error(`rewind-files restore failed (${restored.error?.code ?? "restore_failed"}): ${restored.error?.message ?? "unknown"} — ledger: ${fileHistoryRestoreLedgerLine(restored)}`);
+    e.code = "rewind.restore_failed";
+    if (restored.error !== undefined)
+        e.detail = { code: restored.error.code, ...(isGovernanceRetryClass(restored.error.permanence) ? { permanence: restored.error.permanence } : {}) };
+    throw e;
+}
+export function fileHistoryRestoreLedgerLine(r) {
+    return `applied ${r.filesChanged.length}, identical ${r.identicalSkipped.length}, refused ${r.refused.length}${r.refused.length > 0 ? ` (${r.refused.map((f) => `${f.path}: ${f.reason}`).join("; ")})` : ""}, failed ${r.failed.length}${r.failed.length > 0 ? ` (${r.failed.map((f) => `${f.path}: ${f.reason}`).join("; ")})` : ""}`;
+}
+export function noBoundaryRefusal(target, sessionId, preview = false) {
+    const e = new Error(preview
+        ? `rewind-files: no usable file-history boundary exists for entry "${target}" on session "${sessionId}" (never made, reaped, or there but unreadable — a real rewind names which), so there is nothing to preview. ${rewindRefusalTail()}`
+        : `rewind-files: no file-history boundary exists for entry "${target}" on session "${sessionId}" — the working tree was NOT rewound. ${rewindRefusalTail()}`);
+    e.code = "rewind_snapshot.unresolvable";
+    return e;
+}
+function restoredAbsPathsOf(restored, root) {
+    const out = [];
+    for (const key of [...restored.filesChanged, ...restored.failed.map((f) => f.path)]) {
+        const abs = resolveTrackKey(root, key);
+        if (abs.ok)
+            out.push(abs.abs);
+    }
+    return out;
+}
+function rewindRefusalTail() {
+    return `Boundaries are keyed by a turn's INITIAL entry and exist only for turns that recorded history (a RunnerDeps.fileHistoryStore wired, capture on, and the run's file history not disabled); a boundary from the retired whole-tree snapshot era is not restorable by this seat, and reaped boundaries have none.`;
+}
+function beforeWithoutBoundaryRefusal(target, sessionId) {
+    const e = new Error(`rewind-files: entry "${target}" has no file-history boundary on session "${sessionId}" — a before-restore needs the target's own boundary and never crosses into an earlier turn, so the working tree was NOT rewound. ${rewindRefusalTail()}`);
+    e.code = "rewind_snapshot.unresolvable";
+    return e;
+}