@sema-agent/core 7.17.6 → 7.18.0

package/dist/brain/route-adjudicator.js

@@ -184,6 +184,22 @@ export function fallbackToPrimaryNotice(args) {
         },
     };
 }
+export function unroutableSeatNotice(args) {
+    return {
+        code: "route.classifier_unroutable",
+        message: `derived model "${args.from}" (${args.seat}) is not routable (${args.verdict.code}) and this deployment declared no fallback — ` +
+            `the seat is kept and its calls are refused rather than served by "${args.primary}". ${args.verdict.detail.fixHint}`,
+        detail: {
+            seat: args.seat,
+            from: args.from,
+            cause: args.verdict.code,
+            fixHint: args.verdict.detail.fixHint,
+            action: "refused",
+            ...(args.sessionId !== undefined ? { sessionId: args.sessionId } : {}),
+            ...(args.runId !== undefined ? { runId: args.runId } : {}),
+        },
+    };
+}
 export function authCarrierFingerprint(headers) {
     if (!headers)
         return "";

package/dist/core/agent-definition.d.ts

@@ -169,4 +169,14 @@ export interface SkillSpec {
         path: string;
         content: string;
     }>;
+    /**
+     * The skill's own DIRECTORY on the machine the tools run on, so the model can reach its bundled material
+     * by path instead of searching the workspace. Core does not resolve it, read it, or check that it exists
+     * (the brain-outside posture {@link files} states). Core does exactly two textual things with it: the
+     * result opens with `Base directory for this skill: <baseDir>`, and both root placeholder spellings
+     * (`${SKILL_ROOT}`, `${CLAUDE_PLUGIN_ROOT}`) are substituted for it in the body and in every attachment's
+     * content, with `files[].path` then read RELATIVE to it. Absent ⇒ no line, no substitution, a
+     * byte-identical result; a placeholder with no directory stays verbatim.
+     */
+    baseDir?: string;
 }

package/dist/core/artifact-host.d.ts

@@ -1,3 +1,11 @@
+/**
+ * The Artifacts hosting seam: the deployment-injected `ArtifactHost` (the `RunnerDeps.artifactHost` seat),
+ * its capability declaration, the call context the engine mints for every host call, the request /
+ * outcome shapes, and the closed word sets the tool face is assembled from. A host declares WHAT it
+ * supports (`capabilities()`); the engine assembles the `Artifact` tool from that declaration alone and
+ * never inspects the implementation. `localArtifactStub` (src/tools/artifact/local-stub.ts) is the first
+ * implementation of this interface; a server's hosting plane is the second.
+ */
 import type { AssertAllKeysHandled } from "./ask-origin.js";
 /** The model-facing action words. `publish` is the default action and the one every host must declare. */
 export declare const ARTIFACT_ACTIONS: readonly ["publish", "list", "read", "list_files", "read_file"];
@@ -6,6 +14,17 @@ export type ArtifactAction = (typeof ARTIFACT_ACTIONS)[number];
  *  `"hosted"` = a hosting plane that mints its own URLs. Declared by the host, never detected. */
 export declare const ARTIFACT_PLANES: readonly ["hosted", "local-stub"];
 export type ArtifactPlane = (typeof ARTIFACT_PLANES)[number];
+/** How a throw out of `publish` relates to the host's commit point. `"throw_means_uncommitted"`: every fallible
+ *  step precedes the commit, so a throw proves nothing was committed; `"uncertain"`: a throw may follow it. */
+export declare const ARTIFACT_COMMIT_CERTAINTIES: readonly ["throw_means_uncommitted", "uncertain"];
+export type ArtifactCommitCertainty = (typeof ARTIFACT_COMMIT_CERTAINTIES)[number];
+/** The `artifact.host_error` outcome word the tool reports when the host THREW, by declaration. An aborted or
+ *  malformed answer is `"unknown"` under every declaration: the throw guarantee says nothing about those arms. */
+export declare const ARTIFACT_COMMIT_THROW_OUTCOME: {
+    readonly throw_means_uncommitted: "not_executed";
+    readonly uncertain: "unknown";
+};
+export type ThrowOutcomeTableCoversEveryCommitCertainty = AssertAllKeysHandled<Exclude<ArtifactCommitCertainty, keyof typeof ARTIFACT_COMMIT_THROW_OUTCOME>>;
 /** The `publishContext` word a publish carries (default `"plain"`). */
 export declare const ARTIFACT_PUBLISH_CONTEXTS: readonly ["pr_review", "workshop", "whiteboard", "prototype", "plain"];
 export type ArtifactPublishContext = (typeof ARTIFACT_PUBLISH_CONTEXTS)[number];
@@ -31,6 +50,16 @@ export declare const ARTIFACT_ACTION_HOST_METHOD: {
     readonly read_file: "readFile";
 };
 export type HostMethodTableCoversEveryAction = AssertAllKeysHandled<Exclude<ArtifactAction, keyof typeof ARTIFACT_ACTION_HOST_METHOD>>;
+/** Whether a call of the action may run inside a parallel batch: the read family is (host reads, no host write); a
+ *  publish is not (it writes the host and the tool's path-binding state). Read by the tool's `isConcurrencySafe`. */
+export declare const ARTIFACT_ACTION_CONCURRENCY_SAFE: {
+    readonly publish: false;
+    readonly list: true;
+    readonly read: true;
+    readonly list_files: true;
+    readonly read_file: true;
+};
+export type ConcurrencyTableCoversEveryAction = AssertAllKeysHandled<Exclude<ArtifactAction, keyof typeof ARTIFACT_ACTION_CONCURRENCY_SAFE>>;
 /** The typed failure words a host outcome may carry (`ok: false`). */
 export declare const ARTIFACT_HOST_FAILURE_CODES: readonly ["conflict", "url_foreign", "forbidden", "payload_too_large", "not_found", "force_refused", "refused"];
 export type ArtifactHostFailureCode = (typeof ARTIFACT_HOST_FAILURE_CODES)[number];
@@ -56,11 +85,16 @@ export declare const ARTIFACT_CARD = "artifact";
  * containing `"publish"`; `plane: "local-stub"` ⇒ `actions` is exactly `["publish"]`;
  * `defaultVisibility` is `"private"`; both byte limits are positive finite integers; `multiFile` is a
  * boolean; every declared action's host method exists; `plane: "local-stub"` ⇒ `storageDir` is a non-empty
- * absolute path.
+ * fully qualified path under its own spelling family (`C:\\…` / UNC / `/…` — read from the spelling, never from
+ * `process.platform`); `commit` is a word of {@link ARTIFACT_COMMIT_CERTAINTIES} (no default — an undeclared
+ * commit protocol is an invalid declaration, never read as either word).
  */
 export interface ArtifactHostCapabilities {
     plane: ArtifactPlane;
     actions: ReadonlyArray<ArtifactAction>;
+    /** What a throw out of `publish` proves about the commit (see {@link ARTIFACT_COMMIT_CERTAINTIES}); the tool words
+     *  its host-fault result from this and from nothing else about the host. */
+    commit: ArtifactCommitCertainty;
     /** The on-disk store of a `"local-stub"` plane (required there; ignored on `"hosted"`). Contract: the store
      *  must lie OUTSIDE every root the run may write or read (the task root, `additionalDirectories`,
      *  `additionalReadDirectories`) — a store the model can reach through the fs tools is not a trust boundary;
@@ -77,9 +111,12 @@ export interface ArtifactHostCapabilities {
  * Engine-minted call attribution and idempotency keys — closure-supplied, never a tool parameter.
  * `taskId` / `sessionId` / `agentName` are audit attribution, never an authorization subject: a host
  * instance is bound to one principal at construction. `runId` and `attemptId` are engine-minted trusted
- * keys: `runId` is the same value `onMount` received; `attemptId` is one opaque value per tool call,
- * stable across any host retry of that call, so a host MUST replay the first outcome for a repeated
- * `attemptId` (a fresh publish never mints a second page, an update never advances twice).
+ * keys: `runId` is the same value `onMount` received; `attemptId` is one opaque value per HOST CALL — the
+ * engine mints a fresh one for every call it makes, so two calls of a single tool invocation (the probing
+ * `read` that establishes ownership and the `list_files` it gates, say) never arrive under one key — and it
+ * is stable across any retry the HOST makes of that call, so a host MUST replay the first outcome for a
+ * repeated `attemptId` (a fresh publish never mints a second page, an update never advances twice). The rule
+ * is keyed on the value alone: a host may hold one attempt ledger for all its methods.
  */
 export interface ArtifactCallContext {
     taskId: string;

package/dist/core/artifact-host.js

@@ -1,6 +1,11 @@
-import { isAbsolute } from "node:path";
+import { isAbsoluteForFamily, pathFamilyOf } from "../tools/fs/safety.js";
 export const ARTIFACT_ACTIONS = ["publish", "list", "read", "list_files", "read_file"];
 export const ARTIFACT_PLANES = ["hosted", "local-stub"];
+export const ARTIFACT_COMMIT_CERTAINTIES = ["throw_means_uncommitted", "uncertain"];
+export const ARTIFACT_COMMIT_THROW_OUTCOME = {
+    throw_means_uncommitted: "not_executed",
+    uncertain: "unknown",
+};
 export const ARTIFACT_PUBLISH_CONTEXTS = ["pr_review", "workshop", "whiteboard", "prototype", "plain"];
 export const ARTIFACT_LIST_SCOPES = ["mine", "shared", "all"];
 export const ARTIFACT_PLANE_CONTENT_ORIGIN = {
@@ -14,6 +19,13 @@ export const ARTIFACT_ACTION_HOST_METHOD = {
     list_files: "listFiles",
     read_file: "readFile",
 };
+export const ARTIFACT_ACTION_CONCURRENCY_SAFE = {
+    publish: false,
+    list: true,
+    read: true,
+    list_files: true,
+    read_file: true,
+};
 export const ARTIFACT_HOST_FAILURE_CODES = ["conflict", "url_foreign", "forbidden", "payload_too_large", "not_found", "force_refused", "refused"];
 export const ARTIFACT_FAILURE_RESULT_CODE = {
     conflict: "artifact.publish_conflict",
@@ -59,6 +71,9 @@ export function readArtifactHostCapabilities(host) {
         return { ok: false, problem: 'capabilities.actions must include "publish"' };
     if (plane === "local-stub" && (actions.length !== 1 || actions[0] !== "publish"))
         return { ok: false, problem: 'a "local-stub" plane must declare exactly ["publish"]' };
+    const commit = c["commit"];
+    if (!wordOf(ARTIFACT_COMMIT_CERTAINTIES, commit))
+        return { ok: false, problem: `capabilities.commit must be one of ${ARTIFACT_COMMIT_CERTAINTIES.join(" | ")}` };
     if (c["defaultVisibility"] !== "private")
         return { ok: false, problem: 'capabilities.defaultVisibility must be "private"' };
     if (!isPositiveInt(c["maxFileBytes"]))
@@ -68,7 +83,7 @@ export function readArtifactHostCapabilities(host) {
     if (typeof c["multiFile"] !== "boolean")
         return { ok: false, problem: "capabilities.multiFile must be a boolean" };
     const storageDir = c["storageDir"];
-    if (plane === "local-stub" && (typeof storageDir !== "string" || storageDir.length === 0 || !isAbsolute(storageDir)))
+    if (plane === "local-stub" && (typeof storageDir !== "string" || storageDir.length === 0 || !isAbsoluteForFamily(pathFamilyOf({ root: storageDir }), storageDir)))
         return { ok: false, problem: 'a "local-stub" plane must declare its absolute storageDir' };
     if (storageDir !== undefined && typeof storageDir !== "string")
         return { ok: false, problem: "capabilities.storageDir must be a string when present" };
@@ -82,6 +97,7 @@ export function readArtifactHostCapabilities(host) {
         capabilities: Object.freeze({
             plane,
             actions: Object.freeze([...actions]),
+            commit,
             defaultVisibility: "private",
             maxFileBytes: c["maxFileBytes"],
             maxTotalBytes: c["maxTotalBytes"],

package/dist/core/auto-mode.d.ts

@@ -10,37 +10,117 @@ export declare const AUTO_MODE_UNAVAILABLE_CAUSES: readonly ["error", "timeout"]
 export type AutoModeUnavailableCause = (typeof AUTO_MODE_UNAVAILABLE_CAUSES)[number];
 /** Whether a value is a member of the unavailable-cause set — the screen a row reader applies to a stored word. */
 export declare function isAutoModeUnavailableCause(v: unknown): v is AutoModeUnavailableCause;
-/** The classifier's verdict over one pending `ask`. */
-export type AutoModeVerdict = {
+/**
+ * WHY a classification moved DOWN the candidate ladder — the closed set behind
+ * {@link AutoModeClassifierRound}'s `fallback.cause`, i.e. the ways a candidate produces NO RULING
+ * ({@link rungDidNotRule}). Two words are the unavailable causes verbatim (the leg threw / rejected; the
+ * round-trip cap elapsed); `parse_error` is the candidate that ANSWERED without a verdict. A ruling is not a
+ * member: the ladder stops at a verdict either way.
+ */
+export declare const AUTO_MODE_FALLBACK_CAUSES: readonly ["error", "timeout", "parse_error"];
+export type AutoModeFallbackCause = (typeof AUTO_MODE_FALLBACK_CAUSES)[number];
+/** Whether a value is a member of the fallback-cause set — the screen a row reader applies to a stored word. */
+export declare function isAutoModeFallbackCause(v: unknown): v is AutoModeFallbackCause;
+/**
+ * The deployment's answer to "what happens when the classifier seat does not rule?"
+ * (`RunnerDeps.autoMode.classifierFallback`) — the closed set behind the candidate ladder's LENGTH:
+ * `main` = [classifier seat, the run's main model]; `none` = [classifier seat].
+ */
+export declare const AUTO_MODE_CLASSIFIER_FALLBACKS: readonly ["main", "none"];
+export type AutoModeClassifierFallback = (typeof AUTO_MODE_CLASSIFIER_FALLBACKS)[number];
+/** Whether a value is a member of the classifier-fallback set. */
+export declare function isAutoModeClassifierFallback(v: unknown): v is AutoModeClassifierFallback;
+/** Read the knob: absent ⇒ the default `main`; a member ⇒ itself; ANYTHING ELSE ⇒ a loud refusal carrying
+ *  `config.auto_mode_classifier_fallback_invalid`. A typo'd knob must not read as the default: `"non"` would
+ *  keep paying for the rung it meant to turn off. */
+export declare function autoModeClassifierFallbackOf(v: unknown): AutoModeClassifierFallback;
+/** The classifier's verdict over one pending `ask`. Every arm may carry the classification's model
+ *  attribution ({@link AutoModeClassifierRound}), present iff the decider was wired with a candidate ladder. */
+export type AutoModeVerdict = ({
     kind: "allow";
-}
+} & AutoModeRoundAttributed)
 /** `category` is the matched BLOCK rule name (207 output contract); `reason` starts with `[Rule Name]`. */
- | {
+ | ({
     kind: "block";
     category: string;
     reason: string;
-}
+} & AutoModeRoundAttributed)
 /** The classifier could not run: the model leg threw / rejected, or ran past the cap. NOT a decision — the
  *  gate denies and says so ({@link classifierUnavailableDenyMessage}). */
- | {
+ | ({
     kind: "unavailable";
     cause: AutoModeUnavailableCause;
-}
+} & AutoModeRoundAttributed)
 /** The model responded but not in the `<block>…` contract shape. Handled as a BLOCK with the CC
  *  parse-failure sentence ({@link CLASSIFIER_PARSE_FAILURE_DENY_MESSAGE}), counted by the denial limit. */
- | {
+ | ({
     kind: "parse_error";
     raw: string;
+} & AutoModeRoundAttributed);
+/** The member every verdict arm shares: WHICH MODEL this classification asked and which one answered. */
+export interface AutoModeRoundAttributed {
+    /** Absent when the decider was given no candidate ladder (a hand-built decider, the cross-process rebuild's
+     *  single fresh leg): it ran on whatever model the leg is bound to and can vouch for no name. Never faked. */
+    readonly classifier?: AutoModeClassifierRound;
+}
+/**
+ * WHICH MODEL answered one classification — the record a walk of the CANDIDATE LADDER
+ * ({@link AutoModeDeciderOptions.candidates}) hands its consumers: `modelRequested` = the ladder's FIRST rung
+ * (the seat the classification was for); `modelUsed` = the rung whose answer the gate acted on, and where NO
+ * candidate ruled, the last rung ATTEMPTED (stated, not implied by absence); `fallback` = present exactly
+ * when the ladder MOVED to reach `modelUsed` — which rung it left, which it arrived at, and why
+ * ({@link AutoModeFallbackCause}); absent = the first rung answered.
+ */
+export interface AutoModeClassifierRound {
+    readonly modelRequested: string;
+    readonly modelUsed: string;
+    readonly fallback?: {
+        readonly from: string;
+        readonly to: string;
+        readonly cause: AutoModeFallbackCause;
+    };
+}
+/**
+ * The classify hook's word for "this classification was NEVER PUT TO A MODEL" — the failure is in assembling
+ * the QUESTION (the transcript window every rung shares), not in a rung's answer.
+ *
+ * WHY IT EXISTS. The ladder advances on "the rung produced no ruling", and a hook that rejects looks exactly
+ * like that. But a classification whose prompt could not be built fails IDENTICALLY on every rung (the build is one
+ * shared promise, by contract — "the same prompt, re-asked" is literal), so the walk recorded a fallback
+ * `{from: seat, to: main, cause: "error"}` and a deny sentence naming two models, for a classification in which NO
+ * MODEL WAS EVER DISPATCHED: a transcript-store outage read, on every face a person can see, as a broken
+ * classifier seat. The verdict is unchanged (fail-closed `unavailable`); what changes is that the record
+ * stops attributing it to models that were never asked.
+ *
+ * Carried as a `code` on the thrown error rather than a class so any classify hook — including one this
+ * package never constructed — can raise it without importing a constructor.
+ *
+ * WHAT IT DOES NOT COVER, stated: a build that OUTRUNS a rung's cap is still recorded as that rung's
+ * `timeout`. The cap bounds the whole classify call, assembly included, so at that point nothing distinguishes
+ * a slow transcript store from a slow model. Moving the per-classification build outside the rung cap is a
+ * seam change, filed for a later version.
+ */
+export declare const AUTO_MODE_ROUND_NOT_ASKED_CODE = "auto_mode.round_not_asked";
+/** Mint the marker above around whatever failed, keeping the original as `cause` for the host's own logs.
+ *  TOTAL by construction: the failure it wraps is an arbitrary value, and an `instanceof` or a `.message` read
+ *  on a revoked proxy (or a throwing getter) THROWS — which would replace the marker with an ordinary error and
+ *  hand the walk back the attribution this whole seat exists to remove. So the detail is a guarded read that
+ *  must already be a string, and the total describer otherwise. */
+export declare function autoModeRoundNotAsked(reason: unknown): Error & {
+    code: string;
 };
+/** Why a rung did not settle the classification, or `undefined` when it RULED and the ladder stops — the ONE
+ *  predicate behind the advance (there is no `if (fallback)` arm anywhere). */
+export declare function rungDidNotRule(v: AutoModeVerdict): AutoModeFallbackCause | undefined;
 /**
  * The model-facing deny text for an `unavailable` verdict — CC 2.1.250 `x1t`, with the parenthetical `EIt`
  * spells for the causes this engine distinguishes (a wall-clock / connection timeout reads " (timed out)";
- * an error of unknown kind reads nothing — CC spells HTTP statuses it has, and this decider does not). The
- * subject is the classifier itself rather than a model id: the decider does not know which model answered,
- * and the sentence must not name one it cannot vouch for. One writer for every deny site (the gate's own
- * station and the inherited-lane arms).
+ * an unknown kind reads nothing). The subject is the classifier itself rather than a model id: without a
+ * candidate ladder the decider cannot vouch for a name. One writer for every deny site. ROOT CAUSE, when
+ * `attribution.fallback` is present: the sentence names BOTH rungs that failed to answer; a ladder that did
+ * NOT move keeps the CC text byte for byte.
  */
-export declare function classifierUnavailableDenyMessage(toolName: string, cause: AutoModeUnavailableCause): string;
+export declare function classifierUnavailableDenyMessage(toolName: string, cause: AutoModeUnavailableCause, attribution?: AutoModeClassifierRound): string;
 /** The model-facing deny text for a `parse_error` verdict — CC 2.1.250 `Ure` over the R3t stem: the classifier
  *  answered, but not with a verdict, and auto mode blocks what it could not evaluate. */
 export declare const CLASSIFIER_PARSE_FAILURE_DENY_MESSAGE = "Auto mode could not evaluate this action and is blocking it for safety \u2014 the classifier's reply carried no verdict.";
@@ -63,13 +143,11 @@ export declare const CLASSIFIER_PARSE_FAILURE_DENY_MESSAGE = "Auto mode could no
  * no whitespace inside (the word-boundary form — `<block>yesterday` is not a hit) and case does not matter.
  *
  * A stated BLOCK stands with or without its tail: `<category>` (the BLOCK rule NAME the prompt asked
- * for, read case-insensitively as free text — the deployment authors those names, so there is no
- * fixed vocabulary to screen them against) and `<reason>` (first `<reason>…</reason>` pair on the
- * stripped text, the tag spelled as the prompt spells it, trimmed) are carried when present and `""`
- * when absent; the consumers render their
- * own fallback line from the tool name in that case. The block intent is unambiguous either way, and
- * downgrading a stated block to `parse_error` (a block with the generic parse-failure sentence instead
- * of the classifier's own reason) would lose the classifier's explicit verdict on the exact calls it flagged.
+ * for, read case-insensitively as free text — the deployment authors those names, so there is no fixed
+ * vocabulary to screen them against) and `<reason>` (first `<reason>…</reason>` pair on the stripped
+ * text, trimmed) are carried when present and `""` when absent; the consumers render their own fallback
+ * line from the tool name in that case. Downgrading a stated block to `parse_error` would lose the
+ * classifier's explicit verdict on the exact calls it flagged.
  *
  * `parse_error` is fail-closed: the gate handles it as a BLOCK (CC 2.1.250's own outcome for a reply with no
  * verdict) that the denial limit counts like any other — never a silent allow, and never a question handed
@@ -84,19 +162,42 @@ export interface AutoModeClassifyInput {
     /** The human-readable text of the ask being decided (policy/safety message), when present. */
     askMessage?: string;
 }
-/** The pluggable model leg: given the classify input, return the model's raw text response.
- *  Deployment-injected (roster cheap tier per); MAY throw / reject — the decider fail-closes. */
-export type AutoModeClassifyFn = (input: AutoModeClassifyInput, signal?: AbortSignal) => Promise<string>;
+/** One rung of the ladder, as the leg is told about it. `index` is the ADDRESS (a ladder may carry two rungs
+ *  whose model id is the same string), while `model` is the NAME the record will carry. */
+export interface AutoModeLadderRung {
+    readonly index: number;
+    readonly model: string;
+}
+/** The pluggable model leg: given the classify input and the RUNG the ladder is on, return that model's raw
+ *  text response. Deployment-injected; MAY throw / reject — the decider fail-closes. A rejection carrying
+ *  {@link AUTO_MODE_ROUND_NOT_ASKED_CODE} says the failure was in assembling the QUESTION rather than in this
+ *  rung's answer, and stops the walk instead of blaming the next rung. `rung` is `undefined`
+ *  for a decider wired with no ladder. Both trailing parameters are OPTIONAL, not `| undefined`: a caller
+ *  INVOKING it with one or two arguments must keep compiling. */
+export type AutoModeClassifyFn = (input: AutoModeClassifyInput, signal?: AbortSignal, rung?: AutoModeLadderRung) => Promise<string>;
 export interface AutoModeDeciderOptions {
     classify: AutoModeClassifyFn;
-    /** Hard cap on one classification round-trip. Default 15_000 ms (sema 裁量 — CC's constant is not
-     *  established; a permission gate must not stall the whole run on a slow classifier). */
+    /**
+     * The CANDIDATE LADDER this decider walks, in order — the models a classification may be asked on, NOT a
+     * second way to say what `classify` says (that hook is the DISPATCH; this is the sequence it dispatches
+     * to). Rung 0 is the seat the classification is for; every later rung is consulted only when the one
+     * before it produced NO RULING ({@link rungDidNotRule}). The FIRST ruling ends the walk and is the
+     * verdict; when no rung rules, the LAST rung's own non-ruling verdict stands.
+     *
+     * Omitted = a one-rung anonymous ladder: the leg as wired, no attribution on the verdict. An EMPTY array,
+     * or a rung that is not a non-empty string, is REFUSED loudly at construction (a deployment that computed
+     * its ladder and got nothing has a bug, not a default). COST: {@link timeoutMs} bounds ONE rung, so the
+     * worst case is the cap times the rungs actually walked.
+     */
+    candidates?: readonly string[];
+    /** Hard cap on one classification round-trip — one LADDER RUNG, not the whole classification (see
+     *  {@link candidates}). Default 15_000 ms: a permission gate must not stall the whole run on a slow classifier. */
     timeoutMs?: number;
     /**
-     * Fired once per `decide` call with the verdict the gate is about to act on and the wall time it
-     * waited (`ms`, integer ≥ 0; a timed-out round reads the deadline). `cause` is present iff the verdict
-     * is `unavailable`. The engine's own wiring turns this into the `auto_mode.classified` trace frame; a
-     * hand-built decider need not implement it. A throwing hook never breaks the gate.
+     * Fired once per `decide` call with the verdict the gate is about to act on and the wall time it waited
+     * (`ms`, integer ≥ 0; a timed-out classification reads the deadline, one that walked two rungs the whole
+     * walk). `cause` is present iff the verdict is `unavailable`; `classifier` iff a ladder was wired. A
+     * throwing hook never breaks the gate.
      */
     onClassified?: (info: AutoModeClassified) => void;
 }
@@ -110,16 +211,17 @@ export interface AutoModeClassified {
     cause?: Extract<AutoModeVerdict, {
         kind: "unavailable";
     }>["cause"];
+    /** The classification's model attribution, present exactly when the decider was wired with a candidate ladder
+     *  ({@link AutoModeClassifierRound}) — the same object the verdict carries. */
+    classifier?: AutoModeClassifierRound;
 }
 export interface AutoModeDecider {
     /** Never rejects. Any internal failure surfaces as `unavailable`/`parse_error` (fail-closed). */
     decide(input: AutoModeClassifyInput, signal?: AbortSignal): Promise<AutoModeVerdict>;
 }
-/**
- * The per-run decider: timeout + fail-closed error mapping, and nothing carried between rounds. One instance
- * per run (it binds the run's model leg and assembled prompt); a round that failed says nothing about the
- * next one, which asks the model again.
- */
+/** The per-run decider: timeout + fail-closed error mapping, nothing carried between rounds. One instance per
+ *  run (it binds the run's model leg and assembled prompt); a round that failed says nothing about the next,
+ *  which asks the model again. */
 export declare function createAutoModeDecider(opts: AutoModeDeciderOptions): AutoModeDecider;
 /** The deployment's bounds for the denial limit (`RunnerDeps.autoMode.denialLimit`). Every member
  *  optional; an omitted member takes its CC default. A present member with a bad value is REFUSED
@@ -152,24 +254,18 @@ export interface DenialLimitCounts {
  * The DECISION-layer member of a denial-limit fallback ask (`PermissionResult` ask arm): the counts
  * that tripped the bound, and NOTHING about a window. A window is a fact of the ask's ROUTE — a live
  * function approver can count down, a durable park row and a headless deny cannot — and the route is
- * chosen downstream of the count, so the decision that carries these counts is by construction not in
- * a position to state one. The type says so: there is no window member to write here, and the only
+ * chosen downstream of the count. The type says so: there is no window member to write here, and the only
  * ways to reach a {@link DenialLimitFallback} (the member an {@link
  * import("./tool-policy.js").AskRequest} carries) are the two route stations,
- * {@link AutoModeDenialTracker.armTimedWindow} and {@link unarmedWindow}. A host that builds its own
- * gate adapter therefore cannot forward a decision's member straight into an approval request: the
- * compiler stops it and names the station it skipped.
+ * {@link AutoModeDenialTracker.armTimedWindow} and {@link unarmedWindow}.
  */
 export interface UnarmedDenialLimitFallback extends DenialLimitCounts {
     /** FORBIDDEN on a decision, and stated rather than merely omitted. Leaving the member out would only
      *  stop a FRESH object literal (TypeScript's excess-property check); a policy that writes its window
      *  through a `const`, an `as const`, or an annotated return type would still compile — and would then
-     *  have its number silently replaced at whichever route station the ask reached, turning a bounded
-     *  wait into an unbounded one with no diagnostic. `never` makes the old shape a compile error at the
-     *  policy boundary instead, so the retirement of the self-declared window is a migration a host is
-     *  TOLD about rather than one it discovers when nobody is auto-denied. (A host that casts past the
-     *  type still meets the route stations' runtime belt: they write the route's number, never the
-     *  decision's.) */
+     *  have its number silently replaced at whichever route station the ask reached. `never` makes the old
+     *  shape a compile error at the policy boundary instead. (A host that casts past the type still meets
+     *  the route stations' runtime belt: they write the route's number, never the decision's.) */
     readonly autoDenyAfterMs?: never;
 }
 /** The REQUEST-layer member (`AskRequest`, a durable park row, a checkpoint summary's echo): the same

package/dist/core/auto-mode.js

@@ -1,12 +1,65 @@
 import { AUTO_MODE_DEFAULT_TIMEOUT_MS, AUTO_MODE_DENIAL_AUTO_DENY_DEFAULT_MS, AUTO_MODE_DENIAL_LIMIT_DEFAULTS } from "./auto-mode-defaults.js";
+import { describeRejectedValue } from "./tool-search-setting.js";
 export const AUTO_MODE_UNAVAILABLE_CAUSES = ["error", "timeout"];
 const AUTO_MODE_UNAVAILABLE_CAUSE_SET = new Set(AUTO_MODE_UNAVAILABLE_CAUSES);
 export function isAutoModeUnavailableCause(v) {
     return AUTO_MODE_UNAVAILABLE_CAUSE_SET.has(v);
 }
-export function classifierUnavailableDenyMessage(toolName, cause) {
+export const AUTO_MODE_FALLBACK_CAUSES = ["error", "timeout", "parse_error"];
+const AUTO_MODE_FALLBACK_CAUSE_SET = new Set(AUTO_MODE_FALLBACK_CAUSES);
+export function isAutoModeFallbackCause(v) {
+    return AUTO_MODE_FALLBACK_CAUSE_SET.has(v);
+}
+export const AUTO_MODE_CLASSIFIER_FALLBACKS = ["main", "none"];
+const AUTO_MODE_CLASSIFIER_FALLBACK_SET = new Set(AUTO_MODE_CLASSIFIER_FALLBACKS);
+export function isAutoModeClassifierFallback(v) {
+    return AUTO_MODE_CLASSIFIER_FALLBACK_SET.has(v);
+}
+export function autoModeClassifierFallbackOf(v) {
+    if (v === undefined)
+        return "main";
+    if (isAutoModeClassifierFallback(v))
+        return v;
+    const e = new Error(`RunnerDeps.autoMode.classifierFallback must be one of ${AUTO_MODE_CLASSIFIER_FALLBACKS.map((x) => `"${x}"`).join(" | ")} ` +
+        `(got ${describeRejectedValue(v)}) — omit it for the default "main"`);
+    e.code = "config.auto_mode_classifier_fallback_invalid";
+    throw e;
+}
+export const AUTO_MODE_ROUND_NOT_ASKED_CODE = "auto_mode.round_not_asked";
+export function autoModeRoundNotAsked(reason) {
+    let detail;
+    try {
+        const m = reason.message;
+        if (typeof m === "string")
+            detail = m.slice(0, 200);
+    }
+    catch {
+    }
+    const e = new Error(`the auto-mode classification could not be assembled: ${detail ?? describeRejectedValue(reason)}`, { cause: reason });
+    e.code = AUTO_MODE_ROUND_NOT_ASKED_CODE;
+    return e;
+}
+function isAutoModeRoundNotAsked(e) {
+    try {
+        return typeof e === "object" && e !== null && e.code === AUTO_MODE_ROUND_NOT_ASKED_CODE;
+    }
+    catch {
+        return false;
+    }
+}
+export function rungDidNotRule(v) {
+    if (v.kind === "unavailable")
+        return v.cause;
+    if (v.kind === "parse_error")
+        return "parse_error";
+    return undefined;
+}
+export function classifierUnavailableDenyMessage(toolName, cause, attribution) {
     const parenthetical = cause === "timeout" ? " (timed out)" : "";
+    const fb = attribution?.fallback;
+    const rootCause = fb === undefined ? "" : `The classifier model "${fb.from}" did not answer (${fb.cause}) and neither did the model it fell back to, "${fb.to}" (${cause}). `;
     return (`The auto-mode classifier is temporarily unavailable${parenthetical}, so auto mode cannot determine the safety of ${toolName} right now. ` +
+        rootCause +
         "Wait a moment and then try this action again. " +
         "If it keeps failing, continue with other tasks that don't require this action and come back to it later. " +
         "Note: reading files, searching code, and other read-only operations do not require the classifier and can still be used.");
@@ -31,6 +84,15 @@ export function parseAutoModeResponse(text) {
 }
 export function createAutoModeDecider(opts) {
     const timeoutMs = opts.timeoutMs ?? AUTO_MODE_DEFAULT_TIMEOUT_MS;
+    if (opts.candidates !== undefined) {
+        if (opts.candidates.length === 0) {
+            throw new Error("AutoModeDeciderOptions.candidates must name at least one model — omit the member for the leg's own model, never an empty ladder");
+        }
+        const bad = opts.candidates.findIndex((m) => typeof m !== "string" || m.trim() === "");
+        if (bad >= 0)
+            throw new Error(`AutoModeDeciderOptions.candidates[${bad}] must be a non-empty model id (got ${JSON.stringify(opts.candidates[bad])})`);
+    }
+    const ladder = opts.candidates ?? [undefined];
     const decide = async (input, signal) => {
         const startedAt = performance.now();
         const verdict = await decideUnreported(input, signal);
@@ -41,6 +103,7 @@ export function createAutoModeDecider(opts) {
                     ms: Math.max(0, Math.round(performance.now() - startedAt)),
                     verdict: verdict.kind,
                     ...(verdict.kind === "unavailable" ? { cause: verdict.cause } : {}),
+                    ...(verdict.classifier !== undefined ? { classifier: verdict.classifier } : {}),
                 });
             }
             catch {
@@ -50,6 +113,37 @@ export function createAutoModeDecider(opts) {
     };
     return { decide };
     async function decideUnreported(input, signal) {
+        const causes = [];
+        const round = { notAsked: false };
+        let verdict = { kind: "unavailable", cause: "error" };
+        let i = 0;
+        for (; i < ladder.length; i++) {
+            const name = ladder[i];
+            verdict = await askRung(input, signal, name !== undefined ? { index: i, model: name } : undefined, round);
+            const cause = rungDidNotRule(verdict);
+            if (cause === undefined)
+                break;
+            causes.push(cause);
+            if (round.notAsked || signal?.aborted)
+                break;
+        }
+        const landed = round.notAsked ? 0 : Math.min(i, ladder.length - 1);
+        const requested = ladder[0];
+        const used = ladder[landed];
+        if (requested === undefined || used === undefined)
+            return verdict;
+        const from = landed > 0 ? ladder[landed - 1] : undefined;
+        const movedBy = landed > 0 ? causes[landed - 1] : undefined;
+        return {
+            ...verdict,
+            classifier: Object.freeze({
+                modelRequested: requested,
+                modelUsed: used,
+                ...(from !== undefined && movedBy !== undefined ? { fallback: Object.freeze({ from, to: used, cause: movedBy }) } : {}),
+            }),
+        };
+    }
+    async function askRung(input, signal, rung, round) {
         let timer;
         const inner = new AbortController();
         const onOuterAbort = () => inner.abort();
@@ -69,7 +163,7 @@ export function createAutoModeDecider(opts) {
                         reject(new AutoModeTimeout());
                     }
                 }, timeoutMs);
-                opts.classify(input, inner.signal).then((v) => {
+                opts.classify(input, inner.signal, rung).then((v) => {
                     if (!settled) {
                         settled = true;
                         resolve(v);
@@ -84,9 +178,13 @@ export function createAutoModeDecider(opts) {
             return parseAutoModeResponse(raw);
         }
         catch (e) {
+            if (isAutoModeRoundNotAsked(e)) {
+                round.notAsked = true;
+                return { kind: "unavailable", cause: "error" };
+            }
             if (signal?.aborted)
                 return { kind: "unavailable", cause: "error" };
-            return { kind: "unavailable", cause: e instanceof AutoModeTimeout ? "timeout" : "error" };
+            return { kind: "unavailable", cause: isAutoModeTimeout(e) ? "timeout" : "error" };
         }
         finally {
             if (timer !== undefined)
@@ -101,6 +199,14 @@ class AutoModeTimeout extends Error {
         super("auto-mode classify timeout");
     }
 }
+function isAutoModeTimeout(e) {
+    try {
+        return e instanceof AutoModeTimeout;
+    }
+    catch {
+        return false;
+    }
+}
 export function readDenialLimitFallback(v) {
     if (typeof v !== "object" || v === null)
         return undefined;

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

@@ -969,6 +969,16 @@ export interface CheckpointState {
          *  scope for any in-row invariant). Absent = the row was minted ungoverned. */
         realApproval?: true;
     };
+    /**
+     * The WRITE-face containment state at suspend: the RESOLVED write face, written ONLY when it is
+     * non-default ("open"). An absent section IS "roots" for every reader — which is why it carries NO
+     * version stamp: losing it can only make a resume STRICTER. Resume folds STRICTER-WINS, the read seat's
+     * law: roots unless the section says open AND the live resolution says open. No deny half and no
+     * governance marker.
+     */
+    writeFace?: {
+        face: "open" | "roots";
+    };
     /**
      * design/319 (A ticket) — the session's reminder provenance mark
      * ({@link import("./reminder-mint.js").mintReminderMark}), persisted so a durable resume keeps
@@ -1961,10 +1971,14 @@ export declare function summarizeCheckpoint(cp: Checkpoint): CheckpointSummary;
  *    parks a steer in the retired pre-queue single seat — terminal for the row's bytes; no worker version
  *    reads that seat, the host decides the parked instruction itself).
  *  · `invalid_outcome` pre-CAS row-integrity arms: `"real_approval_damaged"`, `"real_approval_forged"`,
- *    `"read_face_damaged"`, `"read_face_forged"`, `"constraint_chain_missing"` (all terminal for the row's
+ *    `"read_face_damaged"`, `"read_face_forged"`, `"write_face_damaged"`, `"constraint_chain_missing"` (all terminal for the row's
  *    current bytes — no worker version redeems a damaged row).
  */
-export type CheckpointErrorReason = "version_newer" | "env_factory_missing" | "governed_unwired" | "origin_missing" | "ledger_event_unknown" | "seat_retired" | "real_approval_damaged" | "real_approval_forged" | "read_face_damaged" | "read_face_forged" | "constraint_chain_missing";
+export type CheckpointErrorReason = "version_newer" | "env_factory_missing" | "governed_unwired" | "origin_missing" | "ledger_event_unknown" | "seat_retired" | "real_approval_damaged" | "real_approval_forged" | "read_face_damaged" | "read_face_forged"
+/** `state.writeFace` is present but not a well-formed section. No `_forged` twin: the section is
+ *  legal-and-absent at every version, so there is no version to judge a fabrication against — and a
+ *  fabricated "open" still needs the LIVE resolution to say open too. */
+ | "write_face_damaged" | "constraint_chain_missing";
 /** A typed checkpoint-store error so callers branch on `code` (mirrors `SessionError`). */
 export declare class CheckpointError extends Error {
     readonly code: "checkpoint.already_exists" | "checkpoint.already_resolved" | "checkpoint.not_found"