@sema-agent/core 7.9.1 → 7.10.0

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

@@ -1,4 +1,4 @@
-import { type AutoModeDecider, type AutoModeDenialLimitOptions, type AutoModeDenialTracker, type DenialLimitFallback, type DenialLimitFallbackFace, type UnarmedDenialLimitFallback } from "../auto-mode.js";
+import { type AutoModeDecider, type AutoModeDenialLimitOptions, type AutoModeDenialTracker, type AutoModeUnavailableCause, type DenialLimitFallback, type DenialLimitFallbackFace, type UnarmedDenialLimitFallback } from "../auto-mode.js";
 import { type AutoModeArmingRecipe } from "../auto-mode-arming.js";
 import type { PermissionResult, ResolvedAsk, ToolCallRequest } from "../tool-policy.js";
 import { type EngineNotice } from "../types.js";
@@ -84,10 +84,14 @@ export type InheritedAsk = Extract<PermissionResult, {
 }>;
 /** 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 and its denial-limit fallback. */
+ *  they spell themselves: the ask's origin word, its denial-limit fallback and the classifier-unavailable
+ *  fact (#616). */
 export interface AskRequestCarry {
     origin?: AskOrigin;
     denialLimitFallback?: DenialLimitFallback;
+    classifierUnavailable?: {
+        readonly cause: AutoModeUnavailableCause;
+    };
 }
 /** The GATE's own mint station: both members are read off the surviving decision, which is the gate's
  *  OWN snapshot (its stamp point spreads the policy's object and stamps the word onto the copy), so the
@@ -99,7 +103,9 @@ export declare function gateAskCarry(decision: InheritedAsk, liveApprover: boole
  *  fallback member it captured — each read ONCE there and threaded here, never re-read off the
  *  caller-owned object (a stateful accessor could otherwise answer the card with one value and the
  *  settlement with another; a self-declared `origin` on the ancestor's decision is never read). */
-export declare function inheritedAskCarry(origin: AskOrigin, fallback: UnarmedDenialLimitFallback | undefined, liveApprover: boolean, tracker: AutoModeDenialTracker | undefined): AskRequestCarry;
+export declare function inheritedAskCarry(judged: Pick<Extract<InheritedClassifierJudgment<InheritedAsk>, {
+    kind: "resolve";
+}>, "origin" | "fallback" | "ask">, liveApprover: boolean, tracker: AutoModeDenialTracker | undefined): AskRequestCarry;
 /** What {@link judgeInheritedClassifier} hands back to the arm that called it. */
 export type InheritedClassifierJudgment<A extends InheritedAsk> = 
 /** The frozen classifier allowed — the arm returns its own allow shape (with or without the ask's rewrite). */
@@ -118,6 +124,11 @@ export type InheritedClassifierJudgment<A extends InheritedAsk> =
  *  unchanged-ask branches it is the SAME read the exclusion judged by (a caller-owned decision with a
  *  stateful accessor cannot answer the exclusion with one word and the card with another); on the
  *  bound branch it is derived from the re-spoken ask this station minted (its own object). */
+/** `ask` is the incoming ask unchanged — EXCEPT on an UNAVAILABLE round, where it is an engine-owned copy
+ *  carrying `classifierUnavailable: { cause }` (#616): the fact rides the ASK because the ask is what the
+ *  wrapper arms hand back to the gate when the frozen approver answers unavailable (the inherited-unavailable
+ *  float), and the gate's own park carry reads the fact off the decision it parks — a side member on this
+ *  judgment would have been lost on that route (codex r1). The request mint reads the same object. */
  | {
     kind: "resolve";
     ask: A;

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

@@ -60,10 +60,18 @@ function fallbackCarry(fallback, liveApprover, tracker) {
     return { denialLimitFallback: liveApprover && tracker !== undefined ? tracker.armTimedWindow(fallback) : unarmedWindow(fallback) };
 }
 export function gateAskCarry(decision, liveApprover, tracker) {
-    return { ...(decision.origin !== undefined ? { origin: decision.origin } : {}), ...fallbackCarry(decision.denialLimitFallback, liveApprover, tracker) };
+    return {
+        ...(decision.origin !== undefined ? { origin: decision.origin } : {}),
+        ...fallbackCarry(decision.denialLimitFallback, liveApprover, tracker),
+        ...(decision.classifierUnavailable !== undefined ? { classifierUnavailable: { cause: decision.classifierUnavailable.cause } } : {}),
+    };
 }
-export function inheritedAskCarry(origin, fallback, liveApprover, tracker) {
-    return { origin, ...fallbackCarry(fallback, liveApprover, tracker) };
+export function inheritedAskCarry(judged, liveApprover, tracker) {
+    return {
+        origin: judged.origin,
+        ...fallbackCarry(judged.fallback, liveApprover, tracker),
+        ...(judged.ask.classifierUnavailable !== undefined ? { classifierUnavailable: { cause: judged.ask.classifierUnavailable.cause } } : {}),
+    };
 }
 export async function judgeInheritedClassifier(opts) {
     const { autoMode, ask, req } = opts;
@@ -77,8 +85,10 @@ export async function judgeInheritedClassifier(opts) {
         autoMode.denialTracking?.recordAllow();
         return { kind: "allow" };
     }
-    if (verdict.kind !== "block")
-        return { kind: "resolve", ask, fallback: ask.denialLimitFallback, mintedHere: false, origin };
+    if (verdict.kind !== "block") {
+        const resolved = verdict.kind === "unavailable" ? { ...ask, classifierUnavailable: { cause: verdict.cause } } : ask;
+        return { kind: "resolve", ask: resolved, fallback: ask.denialLimitFallback, mintedHere: false, origin };
+    }
     const reason = verdict.reason ? inlineUntrusted(verdict.reason) : "";
     const category = verdict.category ? inlineUntrusted(verdict.category) : "";
     const tracked = autoMode.denialTracking?.recordBlock();

package/dist/core/runner/permission-rule-lanes.d.ts

@@ -107,7 +107,8 @@ export declare function pathRuleLaneAnswer(table: readonly PersistedRule[], req:
     root: string | undefined;
     sessionId: string | undefined;
     liveCwd: string | undefined;
-}): PersistedRuleHit | undefined;
+    home: string | undefined;
+}): PersistedRuleHit | PersistedRuleUnreadable | undefined;
 /** The two lanes prepare hands the gate. Each is `undefined` when its partition is not configured, so
  *  a deployment without one keeps a decision path byte-identical to a build without the feature. */
 export interface PermissionRuleLanes {
@@ -137,6 +138,11 @@ export declare function createPermissionRuleLanes(cfg: {
     /** The LIVE tracked working directory (adversarial-review P1): the base a relative cd resolves against
      *  after an earlier observable `cd`; read per call. */
     liveCwd: () => string | undefined;
+    /** #644 — the EXECUTION ENVIRONMENT's home directory (`ExecutionEnv.homeDir`, adapter-declared), the base a
+     *  `~/` path rule resolves against. `undefined` = the adapter declares none: a `~/` deny/ask row then reads
+     *  UNREADABLE for every call (a fail-closed ask), never the engine process's home. A declared value that is
+     *  not an absolute path is refused HERE, loudly (a bad declaration is a wiring defect, not an absence). */
+    home: string | undefined;
     /** True iff the reserved question-tool NAME resolves to the ENGINE's own content-ask tool on this leg. */
     questionToolMounted: boolean;
     questionToolName: string;

package/dist/core/runner/permission-rule-lanes.js

@@ -1,5 +1,6 @@
 import { persistedRuleMandateOf } from "../hooks.js";
 import { adjudicatePersistedPathRules, adjudicatePersistedRules, ruleToolGrammarOf, segmentCoverageOf, suggestRulesForCommand } from "../permission-rule-model.js";
+import { isAbsolutePathForm } from "../../tools/fs/safety.js";
 import { effectivePathTargetOf } from "../effective-path-target.js";
 import { declaredPathTargetOf, protectivePathTargetOf } from "../tool-registry.js";
 import { orgRuleVerdictFor } from "../permission-rule-org.js";
@@ -31,15 +32,20 @@ export function persistedRuleAnswerOf(verdict) {
     return persistedRuleHitOf(verdict);
 }
 export function pathRuleLaneAnswer(table, req, ctx) {
-    const bases = { ...(ctx.root !== undefined ? { root: ctx.root } : {}), ...(ctx.liveCwd !== undefined ? { cwd: ctx.liveCwd } : {}) };
+    const bases = { ...(ctx.root !== undefined ? { root: ctx.root } : {}), ...(ctx.liveCwd !== undefined ? { cwd: ctx.liveCwd } : {}), ...(ctx.home !== undefined ? { home: ctx.home } : {}) };
     const tighten = effectivePathTargetOf(req, protectivePathTargetOf(req), bases);
     const allow = effectivePathTargetOf(req, declaredPathTargetOf(req), bases);
     if (tighten === undefined && allow === undefined)
         return undefined;
-    return persistedRuleHitOf(adjudicatePersistedPathRules(table, { tool: req.toolName, cwd: ctx.root, sessionId: ctx.sessionId }, { ...(tighten !== undefined ? { tighten } : {}), ...(allow !== undefined ? { allow } : {}) }, bases));
+    return persistedRuleAnswerOf(adjudicatePersistedPathRules(table, { tool: req.toolName, cwd: ctx.root, sessionId: ctx.sessionId }, { ...(tighten !== undefined ? { tighten } : {}), ...(allow !== undefined ? { allow } : {}) }, bases));
 }
 export function createPermissionRuleLanes(cfg) {
     const provider = cfg.provider;
+    if (cfg.home !== undefined && !isAbsolutePathForm(cfg.home)) {
+        const e = new Error(`the execution environment declares homeDir ${JSON.stringify(cfg.home)}, which is not an absolute path — a \`~/\` permission rule could not be resolved against it; declare an absolute home directory or none`);
+        e.code = "config.execution_env_home_dir_invalid";
+        throw e;
+    }
     if (cfg.localOwnerDeclared) {
         if (provider === undefined || !provider.partitions.durable) {
             throw new Error("RunnerDeps.localOwnerRules is declared but no durable permission-rule partition is wired — there is no bucket for the local owner to hold rules in; refusing rather than running as if the declaration were absent");
@@ -127,7 +133,7 @@ export function createPermissionRuleLanes(cfg) {
                 const table = view.rules;
                 const liveCwd = cfg.liveCwd();
                 if (grammar === "path") {
-                    return pathRuleLaneAnswer(table, req, { root: cfg.root, sessionId: cfg.sessionId, liveCwd });
+                    return pathRuleLaneAnswer(table, req, { root: cfg.root, sessionId: cfg.sessionId, liveCwd, home: cfg.home });
                 }
                 const command = req.args?.command;
                 if (typeof command !== "string")

package/dist/core/runner/prepare-caps-and-workflow.d.ts

@@ -49,7 +49,7 @@ export interface PrepareCapsAndWorkflowInput {
     deps: RunnerDeps;
     /** borrowed-readonly — the trusted spawn-side channel; the Workflow mount forwards `rootSessionId`, `placementRoot`,
      *  `onTaskNotification`, `workflowDepth`, and the capture-floor getter reads `memoryCaptureAncestors`. */
-    internals: Pick<RunInternals, "rootSessionId" | "placementRoot" | "onTaskNotification" | "workflowDepth" | "memoryCaptureAncestors"> | undefined;
+    internals: Pick<RunInternals, "rootSessionId" | "placementRoot" | "onTaskNotification" | "workflowDepth" | "memoryCaptureAncestors" | "workflowParkedResume" | "autoModeBreakerLedger"> | undefined;
     /** borrowed-readonly — the acquired session; the classifier leg rebuilds its transcript window from `buildContext`. */
     session: Pick<StoredSession, "buildContext">;
     /** borrowed-readonly — the acquired session id (operator-line context, the refusal codes' phase record). */

package/dist/core/runner/prepare-caps-and-workflow.js

@@ -1,6 +1,6 @@
 import { isSyntheticApiErrorMessage } from "../../internal/harness.js";
 import { createHash } from "node:crypto";
-import { forkGovernanceDenial } from "../../agents/subagent.js";
+import { childThinkingSeat, deploymentSubagentThinking, deploymentSubagentTierModel, forkGovernanceDenial } from "../../agents/subagent.js";
 import { CROSS_SESSION_CLASSIFIER_RULE } from "../../agents/cross-session-envelope.js";
 import { createRunWorkflowTool } from "../../orchestration/run-workflow-tool.js";
 import { isSelfOrchestrationActive } from "../../orchestration/workflow-script-runner.js";
@@ -170,7 +170,10 @@ export async function prepareCapsAndWorkflow(input) {
         autoModeDecider = createAutoModeDecider({
             ...(am.timeoutMs !== undefined ? { timeoutMs: am.timeoutMs } : {}),
             ...(am.failureThreshold !== undefined ? { failureThreshold: am.failureThreshold } : {}),
-            ...(am.onBreakerOpen !== undefined ? { onBreakerOpen: am.onBreakerOpen } : {}),
+            onBreakerOpen: (info) => {
+                internals?.autoModeBreakerLedger?.record(sessionId, { openedAtMs: Date.now(), lastCause: info.lastCause, failures: info.consecutiveFailures, runId });
+                am.onBreakerOpen?.(info);
+            },
             onClassified: (info) => emitTrace(deps.tracer, () => ({
                 kind: "auto_mode.classified",
                 version: 1,
@@ -243,9 +246,16 @@ export async function prepareCapsAndWorkflow(input) {
             taskOwner: hostTaskId,
             limits: deps.workflowLimits,
             sourceTaskId: hostTaskId,
-            parentModel: () => harnessRef.current?.getModel(),
+            parentModel: () => deploymentSubagentTierModel(runnerSelf.agentCatalog) ?? harnessRef.current?.getModel(),
             ...(spec.getApiKeyAndHeaders !== undefined ? { parentGetApiKeyAndHeaders: spec.getApiKeyAndHeaders } : {}),
             ...(frozenOnAsk !== undefined ? { parentOnAsk: frozenOnAsk } : {}),
+            ...(spec.durableApproval !== undefined ? { parentDurableApproval: { ...spec.durableApproval } } : {}),
+            ...(internals?.workflowParkedResume !== undefined
+                ? { parkedResume: (resumeFromRunId) => {
+                        const mine = internals.workflowParkedResume.filter((d) => d.runId === resumeFromRunId).map(({ runId: _r, ...rest }) => rest);
+                        return mine.length > 0 ? mine : undefined;
+                    } }
+                : {}),
             principal: spec.principal,
             oneShot: spec.oneShot,
             ...(resolvedInteractionPosture !== undefined ? { parentInteractionPosture: resolvedInteractionPosture } : {}),
@@ -258,7 +268,7 @@ export async function prepareCapsAndWorkflow(input) {
             autoModeReview: () => (autoModeDecider !== undefined ? { decider: autoModeDecider } : undefined),
             workflowDepth: internals?.workflowDepth,
             parentCwd: taskRootFinal,
-            parentThinking: () => harnessRef.current?.getThinkingLevel() ?? thinking,
+            parentThinking: () => childThinkingSeat(undefined, deploymentSubagentThinking(runnerSelf.agentCatalog?.roles), harnessRef.current?.getThinkingLevel() ?? thinking).thinking,
             parentReadFace: () => carrierReadFace(),
             parentReadDenyPatterns: () => {
                 const readDenyAdditionsNormalized = input.readDenyAdditionsNormalized();

package/dist/core/runner/prepare-gate-stations.d.ts

@@ -49,8 +49,9 @@ export interface PrepareGateStationsInput {
      *  first-party tool's declared effect (never overrides a scanned one); the plan-mode deny reads it per call. */
     toolEffects: Map<string, ToolEffect>;
     /** borrowed-readonly — the deployment seats these stations read, as a Pick over the SAME `deps` object (receiver
-     *  preserved for `deps.onError?.()`): the write-protection table and its data root, the tracer, the error face. */
-    deps: Pick<RunnerDeps, "writeProtectedPaths" | "memoryEngineDir" | "tracer" | "onError">;
+     *  preserved for `deps.onError?.()`): the write-protection table and its data root, the tracer, the error face, and
+     *  the notice sink (#648: the gate's unresolvable-ask exit delivers `delegation.ask_unresolvable` through it). */
+    deps: Pick<RunnerDeps, "writeProtectedPaths" | "memoryEngineDir" | "tracer" | "onError" | "onNotice">;
     /** borrowed-mutable — the protocol-tools phase's arming belt. Writer here: `armed` ← the registration predicate, the
      *  one write; the refresh seam reads it. */
     toolCallGateArmedRef: {

package/dist/core/runner/prepare-gate-stations.js

@@ -5,6 +5,8 @@ import { PRESENT_PLAN_TOOL_NAME } from "../present-plan-tool.js";
 import { screenGateOutcome } from "../gate-outcome.js";
 import { directDeny } from "./gate-exit.js";
 import { emitTrace } from "../trace.js";
+import { deliverEngineNotice } from "../engine-notice.js";
+import { askUnresolvableNotice } from "../ask-unresolvable-notice.js";
 import { createWriteProtectionCheck } from "../write-protect.js";
 import { PATH_CONFINABLE_WRITE_TOOLS } from "./session-rule-policy.js";
 import { toolCallFaceOf } from "../tool-roster.js";
@@ -120,6 +122,7 @@ export function prepareGateStations(input) {
                         shellGated: (e.toolName === "Bash" && shellGatedBash) || (e.toolName === "Monitor" && shellGatedMonitor),
                         ...(autoModeDecider ? { autoMode: { decider: autoModeDecider, ...(autoModeDenialTracking !== undefined ? { denialTracking: autoModeDenialTracking } : {}) } } : {}),
                         onHeadlessDenialLimit: stopForDenialLimit,
+                        onAskUnresolvable: (info) => deliverEngineNotice(deps.onNotice, askUnresolvableNotice({ sessionId, ...info })),
                         ...(permissionRuleLane
                             ? {
                                 persistedRules: {

package/dist/core/runner/prepare-policy-chain.js

@@ -252,6 +252,7 @@ export async function preparePolicyChain(input) {
         sessionId,
         root: taskRootFinal,
         liveCwd: () => handsCwdRef?.current,
+        home: executionEnv.homeDir,
         questionToolMounted,
         questionToolName: ASK_USER_QUESTION_TOOL_NAME,
         onRevisionDefect: (message) => deps.onError?.(new Error(message), { phase: "config", sessionId }),
@@ -299,7 +300,7 @@ export async function preparePolicyChain(input) {
                 return { action: "allow", updatedInput: editArgs };
             if (judged.kind === "deny")
                 return judged.result;
-            const { ask: editAsk, fallback: editFallback, mintedHere: editMintedHere, origin: editOrigin } = judged;
+            const { ask: editAsk, fallback: editFallback, mintedHere: editMintedHere } = judged;
             re = editAsk;
             const rr = await resolveAsk({
                 toolName: creq.toolName,
@@ -311,7 +312,7 @@ export async function preparePolicyChain(input) {
                 ...riskAxesOf(creq.toolName),
                 ...(re.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
                 ...(re.persistedRuleShadowed !== undefined ? { persistedRuleShadowed: re.persistedRuleShadowed } : {}),
-                ...inheritedAskCarry(editOrigin, editFallback, isLiveApproverSeat(onAskOf), ancestorTracker),
+                ...inheritedAskCarry(judged, isLiveApproverSeat(onAskOf), ancestorTracker),
                 ruleEvidence: inheritedAskEvidence,
             }, onAskOf, csignal ?? abortController.signal, lateAskSettlementObserver({ toolName: creq.toolName, toolCallId: creq.toolCallId, sessionId, runId, ...(spec.taskId !== undefined ? { taskId: spec.taskId } : {}), onNotice: deps.onNotice, onError: deps.onError }));
             settleDenialLimitFallback({ fallback: editFallback, mintedHere: editMintedHere, tracker: ancestorTracker, resolved: rr, headless: headlessDenyAtRecheck, stop: stopForDenialLimit, toolName: creq.toolName, toolCallId: creq.toolCallId });
@@ -372,7 +373,7 @@ export async function preparePolicyChain(input) {
                         return { action: "allow" };
                     if (judged.kind === "deny")
                         return judged.result;
-                    const { ask: inheritedAsk, fallback, mintedHere, origin: inheritedOrigin } = judged;
+                    const { ask: inheritedAsk, fallback, mintedHere } = judged;
                     if (fallback === undefined && sandboxAdmissionArmed && policyAskClassOf(pc.policy) === "sandbox_local" && !sandboxBoundaryCapable(creq.toolName)) {
                         recordAncestorSandboxAdmission(creq.toolCallId, creq.toolName);
                         return { action: "allow" };
@@ -389,7 +390,7 @@ export async function preparePolicyChain(input) {
                         ...riskAxesOf(creq.toolName),
                         ...(inheritedAsk.action === "ask" && inheritedAsk.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
                         ...(inheritedAsk.action === "ask" && inheritedAsk.persistedRuleShadowed !== undefined ? { persistedRuleShadowed: inheritedAsk.persistedRuleShadowed } : {}),
-                        ...inheritedAskCarry(inheritedOrigin, fallback, isLiveApproverSeat(pc.onAsk), pc.autoMode?.denialTracking),
+                        ...inheritedAskCarry(judged, isLiveApproverSeat(pc.onAsk), pc.autoMode?.denialTracking),
                         ruleEvidence: inheritedAskEvidence,
                     }, pc.onAsk, csignal ?? abortController.signal, lateAskSettlementObserver({ toolName: creq.toolName, toolCallId: creq.toolCallId, sessionId, runId, ...(spec.taskId !== undefined ? { taskId: spec.taskId } : {}), onNotice: deps.onNotice, onError: deps.onError }));
                     const askWaitMs = Math.max(0, now() - askT0);
@@ -452,7 +453,7 @@ export async function preparePolicyChain(input) {
                         return decision.updatedInput !== undefined ? { action: "allow", updatedInput: decision.updatedInput } : { action: "allow" };
                     if (judged.kind === "deny")
                         return judged.result;
-                    const { ask: inheritedAsk, fallback, mintedHere, origin: inheritedOrigin } = judged;
+                    const { ask: inheritedAsk, fallback, mintedHere } = judged;
                     if (fallback === undefined && sandboxAdmissionArmed && policyAskClassOf(pc.policy) === "sandbox_local" && !sandboxBoundaryCapable(creq.toolName)) {
                         recordAncestorSandboxAdmission(creq.toolCallId, creq.toolName);
                         return decision.updatedInput !== undefined ? { action: "allow", updatedInput: decision.updatedInput } : { action: "allow" };
@@ -468,7 +469,7 @@ export async function preparePolicyChain(input) {
                         ...riskAxesOf(creq.toolName),
                         ...(inheritedAsk.action === "ask" && inheritedAsk.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
                         ...(inheritedAsk.action === "ask" && inheritedAsk.persistedRuleShadowed !== undefined ? { persistedRuleShadowed: inheritedAsk.persistedRuleShadowed } : {}),
-                        ...inheritedAskCarry(inheritedOrigin, fallback, isLiveApproverSeat(pc.onAsk), pc.autoMode?.denialTracking),
+                        ...inheritedAskCarry(judged, isLiveApproverSeat(pc.onAsk), pc.autoMode?.denialTracking),
                         ruleEvidence: inheritedAskEvidence,
                     }, pc.onAsk, csignal ?? abortController.signal, lateAskSettlementObserver({ toolName: creq.toolName, toolCallId: creq.toolCallId, sessionId, runId, ...(spec.taskId !== undefined ? { taskId: spec.taskId } : {}), onNotice: deps.onNotice, onError: deps.onError }));
                     const askWaitMs = Math.max(0, now() - askT0);

package/dist/core/runner/prepare-wiring-manifest.d.ts

@@ -46,7 +46,7 @@ export interface PrepareWiringManifestInput {
     deps: RunnerDeps;
     /** borrowed-readonly — the trusted spawn-side channel: `questionFaceStripped`, `isDelegatedChild`, `onTaskNotification`,
      *  `peerSelfRef`, `explicitAgentName` (the drain), `insideFork` / `agentName` / `parentToolCallId` (the identity). */
-    internals: Pick<RunInternals, "questionFaceStripped" | "isDelegatedChild" | "onTaskNotification" | "peerSelfRef" | "explicitAgentName" | "insideFork" | "agentName" | "parentToolCallId"> | undefined;
+    internals: Pick<RunInternals, "questionFaceStripped" | "isDelegatedChild" | "onTaskNotification" | "peerSelfRef" | "explicitAgentName" | "insideFork" | "agentName" | "parentToolCallId" | "autoModeBreakerLedger"> | undefined;
     /** borrowed-readonly — the resume leg, or undefined (the manifest's leg derivation reads presence only). */
     resume: Pick<PrepareResume, "seed"> | undefined;
     /** borrowed-readonly — the acquired session id. */

package/dist/core/runner/prepare-wiring-manifest.js

@@ -199,7 +199,14 @@ export function prepareWiringManifest(input) {
         memoryAdmissionWired: deps.memoryScopeAdmission !== undefined,
         retentionPolicyWired: deps.retentionPolicy !== undefined,
         ...(modelGateManifest !== undefined ? { modelGate: modelGateManifest } : {}),
-        autoMode: { armed: autoModeArmReason === "armed", reason: autoModeArmReason },
+        autoMode: {
+            armed: autoModeArmReason === "armed",
+            reason: autoModeArmReason,
+            ...(() => {
+                const trip = internals?.autoModeBreakerLedger?.lastTrip(sessionId);
+                return trip !== undefined ? { breaker: trip } : {};
+            })(),
+        },
         mcp: mcpManifestEntries(lockedPreflight.mcp, mcp.statuses),
         tools: toolRoster,
     });

package/dist/core/runner/runtask.d.ts

@@ -1,9 +1,10 @@
 import { type Model } from "../../internal/llm.js";
 import { type CheckpointToken, type ResumeOutcome } from "../checkpoint-store.js";
 import { type TaskOutcome } from "../task-outcome.js";
+import { type SwappableDeps } from "../swappable-deps.js";
 import { type SideQuerySpec, type SideQueryResult } from "../side-query.js";
 import type { SessionStore } from "../session.js";
-import type { AgentDefinition, ModelRef, RunnerDeps, TaskEvent, TaskResult, TaskSpec, TaskStream } from "../types.js";
+import type { AgentDefinition, ModelRoles, RunnerDeps, TaskEvent, TaskResult, TaskSpec, TaskStream } from "../types.js";
 import type { ResumeRun, ResumeTaskConfig, RunInternals, RunnerSelfSeat } from "./contracts.js";
 export type { ResumeTaskConfig } from "./contracts.js";
 /**
@@ -20,6 +21,9 @@ export declare class Runner implements RunnerSelfSeat {
      *  authority: a durable resume's checkpoint seed wins on its leg, and a miss (cross-process,
      *  evicted) falls back to the transcript-replay rung. See {@link SessionReadFileStates}. */
     private readonly sessionReadStates;
+    /** #616 — the per-session breaker read face's record (see {@link RunInternals.autoModeBreakerLedger}). Runner-lived:
+     *  a trip in one leg is what the session's next leg reports. */
+    private readonly autoModeBreakerLedger;
     /** task notifications born BETWEEN turns (run torn down / harness already idle), parked
      *  per session and drained into the session's next run at its first boundary. Runner-lived (outlives any
      *  single run, like the registry handles that produce into it); bounded + drop-disclosing, see
@@ -57,7 +61,7 @@ export declare class Runner implements RunnerSelfSeat {
     private readonly locallyClaimedTokens;
     private static readonly PARENT_CONSTRAINT_REGISTRY_CAP;
     /** The lanes' LIVE view of `deps` ({@link RunnerDepsSeat}): a getter, never a captured object, because
-     *  `swapModels` replaces the object and a rung reading after its own await must see the replacement. */
+     *  `swapDeps` replaces the object and a rung reading after its own await must see the replacement. */
     private readonly depsSeat;
     constructor(deps: RunnerDeps);
     /** design/73 §1 v1 — fire `RunnerDeps.onTaskOutcome` through the single swallow-guarded chokepoint
@@ -74,6 +78,7 @@ export declare class Runner implements RunnerSelfSeat {
         agents?: AgentDefinition[];
         builtinAgents?: boolean;
         models?: Record<string, Model>;
+        roles?: ModelRoles;
     };
     /** design/125 (实现审 B1) — the deployment-level gating baseline, exposed READ-ONLY so thin
      *  assemblers over the Runner (`runSpec`) can COMPOSE with it. The task-level engine semantic is a
@@ -87,38 +92,35 @@ export declare class Runner implements RunnerSelfSeat {
     /** Acquire the lock for a sessionId; returns a release fn. New (undefined) sessions need no lock. */
     private acquireSessionLock;
     /**
-     * Hot-swap the model catalog (and optionally the tier bindings) without restarting the process or
-     * rebuilding the Runner — the deployment seat that makes "switching models" a zero-restart
-     * operation, and the ONLY sanctioned generation change.
+     * Hot-swap the deployment seats a running Runner may change without a restart — the ONE door for every
+     * hot-swappable seat ({@link SWAPPABLE_DEP_SEATS}: the model catalog generation `models` + its `tiers`
+     * bindings, and the deployment's read-face declaration `readFace`), and the ONLY sanctioned way to
+     * change any of them after construction. It replaces the former `swapModels` verb (retired, no alias):
+     * one verb per seat restated the same laws with a list of verbs as the only record of what is swappable.
      *
-     * (Precisely: the constructor runs {@link expandTiers} once and keeps a private expanded copy **only
-     * when `RunnerDeps.tiers` is configured** — that is the arm where mutating the shared table after
-     * construction provably never took effect. A tiers-less deployment's Runner holds the caller's own
-     * `models` object BY REFERENCE, so mutating it after construction does leak through; that is an
-     * accident of the expansion being a no-op, not a contract, and this verb is still the supported way
-     * to change a generation — it is what validates, announces, and computes the pairing disclosure.)
-     *
-     * Semantics:
-     * - **Atomic**: the candidate catalog is tier-expanded and validated FIRST (an illegal tier
-     *   binding throws exactly like the constructor's boot error) — on any throw the current
-     *   generation stays in force, untouched.
-     * - **In-flight tasks keep their generation** (natural snapshot): a running task resolved its
-     *   `Model` object at prepare time and holds that reference; the swap changes what FUTURE
-     *   prepares (and auto-sourced agents' string refs — {@link agentCatalog} copies per read)
-     *   resolve. Same-name redirects therefore never re-route or re-price a task mid-run; the
-     *   divergence window is exactly the in-flight tasks' lifetime, by design.
-     * - `tiers` omitted ⇒ the current tier bindings are kept (and re-applied over the new models);
-     *   explicitly passed (including `undefined`) ⇒ replaced.
-     * - Success is announced via `config.models_swapped` (models/tiers counts — key material only,
-     *   never the catalog itself). A swap may additionally emit the advisory
-     *   `route.base_url_changed_key_unchanged` notice (deliberately conservative — see its entry in
-     *   the notice directory) for same-name entries whose URL moved while the Model-visible
-     *   credential fingerprint did not.
+     * The laws, stated once (see the vocabulary module for the seat-by-seat meaning):
+     * - **Screened first, written once — atomic.** The candidate is screened whole
+     *   ({@link screenSwappableDeps}: the key set is the closed one, at least one seat, `tiers` rides with
+     *   `models`, each seat's own value gate — `readFace` through the very `assertReadFaceValue` every
+     *   prepare door applies) and the catalog is tier-expanded on the candidate (an illegal binding throws
+     *   exactly like the constructor's boot error) BEFORE the deps object is replaced. On any throw the
+     *   current deps stay in force, byte-identical.
+     * - **In-flight legs keep their snapshot.** A running task read `this.deps` at its prepare and holds
+     *   that object: its `Model`, its resolved read face, everything. The swap changes what FUTURE prepares
+     *   (and auto-sourced agents' string refs — {@link agentCatalog} copies per read) resolve. Same-name
+     *   redirects never re-route or re-price a task mid-run; a read-face change never re-fences a mounted
+     *   band; the divergence window is exactly the in-flight legs' lifetime, by design.
+     * - **Presence is the instruction.** A key present on the candidate is replaced (an explicit
+     *   `undefined` clears an optional seat: `tiers: undefined` ⇒ no bindings, `readFace: undefined` ⇒ the
+     *   engine default); a key absent is kept. `tiers` omitted beside `models` ⇒ the current bindings are
+     *   re-applied over the new catalog.
+     * - **Announced per seat.** `config.models_swapped` (models/tiers counts — key material only, never the
+     *   catalog itself; plus the advisory `route.base_url_changed_key_unchanged` for same-name entries
+     *   whose URL moved while the Model-visible credential fingerprint did not) and
+     *   `config.read_face_swapped` (`{ from, to, occurrenceId }`, the seat's previous and new value, `null`
+     *   = no declaration) — the table {@link SWAP_SEAT_NOTICE} binds every seat to its line.
      */
-    swapModels(next: {
-        models: Record<string, Model>;
-        tiers?: Record<string, ModelRef>;
-    }): void;
+    swapDeps(next: SwappableDeps): void;
     /** one-shot brain-routed utility query (see {@link runSideQuery} for the full contract):
      *  preserves system/multi-turn messages/tool DEFINITIONS, routes through the deployment's brain with
      *  the same model resolution as tasks, returns real usage/model. No session, no tool execution, no

package/dist/core/runner/runtask.js

@@ -23,6 +23,8 @@ import { resolveReasoning } from "../../brain/reasoning.js";
 import { adjudicateDerivedRoute, authCarrierFingerprint, fallbackToPrimaryNotice, normalizeBaseUrl, sameRouteIdentity } from "../../brain/route-adjudicator.js";
 import { runWithBrainTelemetry, runWithReasoningWireFacts, runWithStatusSink } from "../../brain/status-sink.js";
 import { expandTiers, resolveModel, resolveTaskModel } from "../roles.js";
+import { screenSwappableDeps } from "../swappable-deps.js";
+import { AutoModeBreakerLedger } from "../auto-mode.js";
 import { runSideQuery } from "../side-query.js";
 import { generatePromptSuggestions } from "./prompt-suggestions.js";
 import { PushQueue } from "../push-queue.js";
@@ -82,6 +84,7 @@ export class Runner {
     sessions;
     sessionLocks = new Map();
     sessionReadStates = new SessionReadFileStates();
+    autoModeBreakerLedger = new AutoModeBreakerLedger();
     pendingSessionNotifications = new PendingSessionNotifications();
     parentConstraintRegistry = new Map();
     suspendedEnvReaps = new Map();
@@ -138,7 +141,7 @@ export class Runner {
         return {
             ...(this.deps.agents ? { agents: [...this.deps.agents] } : {}),
             ...(this.deps.builtinAgents !== undefined ? { builtinAgents: this.deps.builtinAgents } : {}),
-            ...(this.deps.models ? { models: { ...this.deps.models } } : {}),
+            ...(this.deps.models ? { models: { ...this.deps.models } } : {}), ...(this.deps.roles ? { roles: { ...this.deps.roles } } : {}),
         };
     }
     get gateBaseline() {
@@ -213,41 +216,67 @@ export class Runner {
             });
         };
     }
-    swapModels(next) {
-        if (next.models === null || typeof next.models !== "object" || Array.isArray(next.models)) {
-            throw new Error(`swapModels: models must be a plain Record<string, Model> (got ${next.models === null ? "null" : Array.isArray(next.models) ? "array" : typeof next.models}) — the current generation stays in force`);
-        }
-        const tiers = Object.hasOwn(next, "tiers") ? next.tiers : this.deps.tiers;
-        const expanded = tiers && Object.keys(tiers).length > 0 ? expandTiers({ ...next.models }, tiers) : { ...next.models };
+    swapDeps(next) {
+        const screened = screenSwappableDeps(next);
+        const { seats, candidate } = screened;
+        const catalogSwap = seats.includes("models");
+        let expanded;
+        let tiers;
         const movedEntries = [];
-        for (const [name, nextModel] of Object.entries(expanded ?? {})) {
-            const prior = this.deps.models?.[name];
-            if (!prior)
-                continue;
-            const from = normalizeBaseUrl(prior.baseUrl);
-            const to = normalizeBaseUrl(nextModel.baseUrl);
-            if (from !== to && authCarrierFingerprint(prior.headers) === authCarrierFingerprint(nextModel.headers)) {
-                movedEntries.push({ modelId: name, from, to });
-            }
-        }
-        this.deps = { ...this.deps, models: expanded, ...(tiers !== undefined ? { tiers } : {}) };
-        if (tiers === undefined)
-            delete this.deps.tiers;
-        deliverEngineNotice(this.deps.onNotice, {
-            code: "config.models_swapped",
-            message: `model catalog swapped: ${Object.keys(next.models).length} model(s), ${tiers ? Object.keys(tiers).length : 0} tier binding(s); in-flight tasks finish on their resolved models, new tasks resolve against the new catalog`,
-            detail: { models: Object.keys(next.models).length, tiers: tiers ? Object.keys(tiers).length : 0, occurrenceId: uuidv7() },
-        });
-        if (movedEntries.length > 0) {
-            const RENDER_CAP = 8;
-            const rendered = movedEntries.slice(0, RENDER_CAP);
+        if (catalogSwap) {
+            const models = candidate.models;
+            tiers = Object.hasOwn(candidate, "tiers") ? candidate.tiers : this.deps.tiers;
+            expanded = tiers && Object.keys(tiers).length > 0 ? expandTiers({ ...models }, tiers) : { ...models };
+            for (const [name, nextModel] of Object.entries(expanded ?? {})) {
+                const prior = this.deps.models?.[name];
+                if (!prior)
+                    continue;
+                const from = normalizeBaseUrl(prior.baseUrl);
+                const to = normalizeBaseUrl(nextModel.baseUrl);
+                if (from !== to && authCarrierFingerprint(prior.headers) === authCarrierFingerprint(nextModel.headers)) {
+                    movedEntries.push({ modelId: name, from, to });
+                }
+            }
+        }
+        const faceSwap = seats.includes("readFace");
+        const priorFace = this.deps.readFace;
+        const written = {
+            ...this.deps,
+            ...(expanded !== undefined ? { models: expanded } : {}),
+            ...(catalogSwap && tiers !== undefined ? { tiers } : {}),
+            ...(faceSwap && candidate.readFace !== undefined ? { readFace: candidate.readFace } : {}),
+        };
+        if (catalogSwap && tiers === undefined)
+            delete written.tiers;
+        if (faceSwap && candidate.readFace === undefined)
+            delete written.readFace;
+        this.deps = written;
+        if (catalogSwap) {
+            const modelCount = Object.keys(candidate.models).length;
+            deliverEngineNotice(this.deps.onNotice, {
+                code: "config.models_swapped",
+                message: `model catalog swapped: ${modelCount} model(s), ${tiers ? Object.keys(tiers).length : 0} tier binding(s); in-flight tasks finish on their resolved models, new tasks resolve against the new catalog`,
+                detail: { models: modelCount, tiers: tiers ? Object.keys(tiers).length : 0, occurrenceId: uuidv7() },
+            });
+            if (movedEntries.length > 0) {
+                const RENDER_CAP = 8;
+                const rendered = movedEntries.slice(0, RENDER_CAP);
+                deliverEngineNotice(this.deps.onNotice, {
+                    code: "route.base_url_changed_key_unchanged",
+                    message: `model catalog swap moved ${movedEntries.length} entry/entries to a new baseUrl while the Model-visible credential half stayed unchanged: ` +
+                        rendered.map((e) => `"${e.modelId}" ${e.from || "(config root)"} → ${e.to || "(config root)"}`).join("; ") +
+                        (movedEntries.length > rendered.length ? `; +${movedEntries.length - rendered.length} more` : "") +
+                        " — if the provider changed (not just its domain), update the credential reference in the same step",
+                    detail: { entries: rendered, total: movedEntries.length, occurrenceId: uuidv7() },
+                });
+            }
+        }
+        if (faceSwap) {
+            const to = candidate.readFace ?? null;
             deliverEngineNotice(this.deps.onNotice, {
-                code: "route.base_url_changed_key_unchanged",
-                message: `model catalog swap moved ${movedEntries.length} entry/entries to a new baseUrl while the Model-visible credential half stayed unchanged: ` +
-                    rendered.map((e) => `"${e.modelId}" ${e.from || "(config root)"} → ${e.to || "(config root)"}`).join("; ") +
-                    (movedEntries.length > rendered.length ? `; +${movedEntries.length - rendered.length} more` : "") +
-                    " — if the provider changed (not just its domain), update the credential reference in the same step",
-                detail: { entries: rendered, total: movedEntries.length, occurrenceId: uuidv7() },
+                code: "config.read_face_swapped",
+                message: `deployment read face swapped: ${priorFace ?? "(no declaration)"} → ${to ?? "(no declaration)"}; in-flight legs keep the face they prepared under, new legs resolve against the new declaration`,
+                detail: { from: priorFace ?? null, to, occurrenceId: uuidv7() },
             });
         }
     }
@@ -962,6 +991,7 @@ export class Runner {
             peerInboundChainRef,
             detachHub,
             sessionReadStates: this.sessionReadStates,
+            autoModeBreakerLedger: this.autoModeBreakerLedger,
             onTaskNotification: (notification, opts) => {
                 try {
                     upstreamTaskNotification?.(notification, opts);

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

@@ -400,6 +400,11 @@ export interface RunnerDeps {
      * may not. Beside a read-only (verifier) mount this seat's "open" silently CLAMPS to roots (a
      * deployment default cannot override a load-bearing containment wall) — TaskSpec.readFace's own
      * "open" there is the genuine per-task contradiction, and that one still refuses loudly (#123).
+     *
+     * A LIVE seat: `Runner.swapDeps({ readFace })` replaces it without a restart (the same natural
+     * snapshot the model catalog has — a leg reads the seat at its prepare and keeps that reading; every
+     * later prepare reads the new declaration; announced as `config.read_face_swapped`). A host whose
+     * declaration arrives late (a governance source read after boot) swaps it in rather than restarting.
      */
     readFace?: import("../tools/fs/read-face.js").ReadFace;
     /**
@@ -686,10 +691,12 @@ export interface RunnerDeps {
         timeoutMs?: number;
         /** Consecutive-failure threshold opening the one-way session breaker (default 3). */
         failureThreshold?: number;
-        /** Fired ONCE when the session breaker opens (the "退回非 auto" alarm — surface it to the operator). */
+        /** Fired ONCE when the session breaker opens (the "退回非 auto" alarm — surface it to the operator). The engine
+         *  records the trip on the session's breaker read face (`WiringManifest.autoMode.breaker`, #616) BEFORE calling
+         *  this hook, so a deployment that wires nothing here still gets the read face. */
         onBreakerOpen?: (info: {
             consecutiveFailures: number;
-            lastCause: string;
+            lastCause: import("./auto-mode.js").AutoModeBreakerCause;
         }) => void;
         /**
          * The classifier DENIAL LIMIT (CC 2.1.250 `FO`/`AKe`): a run whose classifier keeps blocking falls