@sema-agent/core 7.17.6 → 7.18.0

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

@@ -85,9 +85,12 @@ export interface EngineNotice {
      *    The SEAT is announced, not a leg's resolved face: resolution (task seat, governance, the
      *    read-only mount) still runs per prepare. In-flight legs keep the face they prepared under;
      *    every later prepare resolves against the new declaration. A candidate outside the value gate
-     *    (`assertReadFaceValue`) throws atomically and mints nothing. Own `occurrenceId` for the same
+     *    (`assertContainmentFaceValue`) throws atomically and mints nothing. Own `occurrenceId` for the same
      *    reason as the catalog line (no run, no session, a two-word payload). Dedup key:
      *    (code, occurrenceId).
+     *  - `"config.write_face_swapped"` — the same line for the WRITE seat (`RunnerDeps.writeFace`),
+     *    same payload, same laws. A SEPARATE code rather than a face field on the line above: the audience
+     *    table and every consumer table are keyed by code.
      *  - `"route.fallback_to_primary"` (key↔URL pairing, `src/brain/route-adjudicator.ts`) — a
      *    DERIVED-leg model (role/tier/system-default resolution, never a caller-explicit one) failed
      *    the pairing pre-flight and the seat fell back to the primary model instead of sinking the
@@ -100,6 +103,21 @@ export interface EngineNotice {
      *    session falling back on the same seat used to mint byte-identical lines; `runId` is what
      *    tells one task falling back twice apart from two tasks falling back once each.
      *    Explicitly-named models never mint this: they refuse at the brain's request gate instead.
+     *  - `"route.classifier_unroutable"` (same pre-flight, the other POSTURE) — the derived classifier seat
+     *    failed the same pairing pre-flight while the deployment had declared NO fallback
+     *    (`RunnerDeps.autoMode.classifierFallback: "none"`), so the seat was KEPT and its calls are refused at
+     *    the request gate rather than served by the primary model. The line is why "no swap" is still not "no
+     *    word". `detail: { seat, from, cause, fixHint, action: "refused", sessionId?, runId? }` — the twin
+     *    above's keys MINUS `to` (nothing moved, and a `to` naming a model that was not used is the one lie a
+     *    consumer cannot detect); `action` is the discriminator, so a reader never infers the posture from that
+     *    absence. Audience `operator`, same entitlement reading as its twin. Dedup key: (code, seat) per run.
+     *  - `"classifier.fallback"` (the classifier's candidate ladder, `src/core/runner/classifier-ladder.ts`)
+     *    — a gated call's classification did NOT rule on the classifier seat and was re-asked on the model
+     *    behind it. Sibling of `route.fallback_to_primary` one layer later: that one fires when the derived
+     *    model is not ROUTABLE at all, this one when it is routable and still does not answer.
+     *    `detail: { from, to, cause, sessionId?, runId? }` — `cause` is the `AutoModeFallbackCause` word, the
+     *    two ids are the rungs. Dedup key: (code, from, cause) PER RUN; a second CAUSE on the same rung is
+     *    its own line.
      *  - `"route.base_url_changed_key_unchanged"` (key↔URL pairing) — `Runner.swapDeps` moved a
      *    same-name entry's `baseUrl` while its Model-visible credential half (auth-bearing headers)
      *    did not change: legal (a provider changing domains), but worth one loud line — if the
@@ -120,6 +138,9 @@ export interface EngineNotice {
      *    a library-direct `createHandsToolkit` mount announces at toolkit creation (one per mount,
      *    through the band-local `HandsToolkitOptions.onNotice` seat, absent ⇒ `console.warn`);
      *    `detail: { seat, declared, inForce, cause }`.
+     *  - `"config.write_face_deployment_clamped"` — the write seat's twin of the line above, with the
+     *    same stations, the same once-per-sink ledger (its OWN ledger row) and the same detail shape. The
+     *    cause differs in prose only: that mount carries no write faces at all.
      *  - `"config.tool_model_gate_removed"` (design/277) — the model gate trimmed default-mounted
      *    scaffold entries from a task's roster. One notice per (model, class), de-duplicated once per
      *    `onNotice` SINK on the (modelId, class, canonical sorted removed-name set) line (same unit
@@ -629,6 +650,31 @@ export declare function deliverEngineNotice(onNotice: ((notice: EngineNotice) =>
  * one repeated disclosure about one run. The account is per-RUN by its own contract sentence ("at most
  * once per family, per run"), so it must carry the run's own id. Same omit-never-fabricate rule.
  */
+/**
+ * What this leg still OWES a person, one count per family — the input to {@link undrainedUserInputNotices}.
+ * TWO lanes accept caller input and either can be holding some when a run ends: the harness's live queue
+ * (`held`, the at-agent_end snapshot, minus what a durable park migrated onto the new checkpoint) and a resumed
+ * leg's undelivered continuation frames (`owedContinuation` — the checkpoint's parked steers and the caller's
+ * wake message, minus what the same migration carried). They are ONE book: a frame is owed for the same reason
+ * on either lane — accepted, and never in the transcript — and counting the live queue alone is what let a leg
+ * that committed no pause drop a person's instruction in silence (the original row is already spent by then).
+ */
+export declare function owedUserInputCounts(held: {
+    steer: number;
+    followUp: number;
+} | undefined, migrated: {
+    steer: number;
+    followUp: number;
+}, continuation: {
+    frames: ReadonlyArray<{
+        seq?: number;
+    }>;
+    carried: number;
+    rowMayReturn: boolean;
+}): {
+    steer: number;
+    followUp: number;
+};
 export declare function undrainedUserInputNotices(counts: {
     steer: number;
     followUp: number;

package/dist/core/engine-notice.js

@@ -31,6 +31,13 @@ export function deliverEngineNotice(onNotice, notice) {
     }
     console.warn(notice.message);
 }
+export function owedUserInputCounts(held, migrated, continuation) {
+    const owedContinuation = (continuation.rowMayReturn ? continuation.frames.filter((f) => f.seq === undefined).length : continuation.frames.length) - continuation.carried;
+    return {
+        steer: Math.max(0, (held?.steer ?? 0) - migrated.steer) + Math.max(0, owedContinuation),
+        followUp: Math.max(0, (held?.followUp ?? 0) - migrated.followUp),
+    };
+}
 export function undrainedUserInputNotices(counts, taskId, sessionId, runId) {
     const tid = taskId !== undefined ? { taskId } : {};
     const sid = sessionId !== undefined ? { sessionId } : {};

package/dist/core/gate-lanes.js

@@ -369,6 +369,7 @@ export async function runGateLanes(pass) {
             const verdict = await input.autoMode.decider
                 .decide({ req: pass.req, askMessage: decisionText(pass.decision) }, input.abortSignal)
                 .catch(() => ({ kind: "unavailable", cause: "error" }));
+            pass.classifierRound = verdict.classifier;
             if (verdict.kind === "allow") {
                 input.autoMode.denialTracking?.recordAllow();
                 pass.decision = {
@@ -381,7 +382,7 @@ export async function runGateLanes(pass) {
             else if (verdict.kind === "unavailable") {
                 pass.decision = attestClassifierDenyCause({
                     action: "deny",
-                    message: classifierUnavailableDenyMessage(toolName, verdict.cause),
+                    message: classifierUnavailableDenyMessage(toolName, verdict.cause, verdict.classifier),
                     decisionReason: "classifier",
                 }, "unavailable", pass.req);
             }

package/dist/core/gate-outcome.d.ts

@@ -8,6 +8,7 @@
  * verdict ended.
  */
 import { type AskOrigin, type AssertAllKeysHandled } from "./ask-origin.js";
+import { type AutoModeClassifierRound } from "./auto-mode.js";
 /**
  * How the wait an ask was in ENDED — the closed set. One word per way a wait can end; the `who` on the
  * record says which party ended it and is fixed BY the word (see {@link Settlement}).
@@ -189,13 +190,23 @@ export type CauseTableCoversEveryDeniedBy = AssertAllKeysHandled<Exclude<DeniedB
 /** The final disposition of a gate pass. `cause` is present exactly when the deny came out of an auto-mode
  *  classifier round that did not RULE ({@link ClassifierDenyCause}); a ruling block and every non-classifier
  *  deny carry none. Invariant I5 ({@link screenGateOutcome}): a cause stands only beside a layer word in
- *  {@link DENIED_BY_MAY_CARRY_CAUSE}. */
+ *  {@link DENIED_BY_MAY_CARRY_CAUSE}.
+ *
+ *  `classifier` — the classification's model attribution, on BOTH arms (a classification ends either way,
+ *  allow or deny): which model it was for, which one answered, and — only when the ladder moved — the rung it
+ *  left and why. ABSENT reads UNKNOWN, never "the seat answered" (that is `fallback` absent WITH the member
+ *  present), and a consumer cannot tell its three causes apart from the record alone: no classification
+ *  happened; one ran on a decider given no candidate ladder, which can name no model; or one ran on an
+ *  ANCESTOR's inherited chain, which carries the FORM (`cause`) but has no seat for the attribution yet.
+ *  Additive. Invariant I6 ({@link screenGateOutcome}) screens its shape. */
 export type GateDisposition = {
     kind: "allowed";
+    classifier?: AutoModeClassifierRound;
 } | {
     kind: "denied";
     deniedBy: DeniedBy;
     cause?: ClassifierDenyCause;
+    classifier?: AutoModeClassifierRound;
 };
 /**
  * The WHOLE record of one tool-gate pass: the final disposition, plus — when this pass settled an ask —
@@ -212,7 +223,11 @@ export type GateDisposition = {
  *      on the settlement (it is not the approver's refusal);
  *  I4  `disposition.kind === "allowed"` ⇒ `settlement` absent or `human_allowed`;
  *  I5  `disposition.cause` present ⇒ a member of {@link CLASSIFIER_DENY_CAUSES} beside a layer word
- *      {@link DENIED_BY_MAY_CARRY_CAUSE} admits (the classifier station, or the inherited chain's `policy`).
+ *      {@link DENIED_BY_MAY_CARRY_CAUSE} admits (the classifier station, or the inherited chain's `policy`);
+ *  I6  `disposition.classifier` present ⇒ both model ids are non-empty strings, and a `fallback` on it
+ *      names a `to` that IS `modelUsed` (the ladder landed where the record says) with a cause in
+ *      {@link import("./auto-mode.js").AUTO_MODE_FALLBACK_CAUSES} — a record whose `to` and `modelUsed`
+ *      disagree would let a reader answer "which model decided this call?" two ways.
  * Nothing here is read out of an ABSENCE: an ordinary allow with no ask is `{ disposition: { kind: "allowed" } }`,
  * a direct policy deny is `{ disposition: { kind: "denied", deniedBy: "policy" } }`, and neither carries a
  * settlement because neither settled one.

package/dist/core/gate-outcome.js

@@ -1,4 +1,5 @@
 import { isAskOrigin } from "./ask-origin.js";
+import { isAutoModeFallbackCause } from "./auto-mode.js";
 export const SETTLEMENT_KINDS = [
     "human_allowed",
     "human_refused",
@@ -89,5 +90,20 @@ export function screenGateOutcome(g) {
         else if (isDeniedBy(d.deniedBy) && !DENIED_BY_MAY_CARRY_CAUSE[d.deniedBy])
             defects.push(`I5: a classifier cause cannot stand beside deniedBy "${d.deniedBy}"`);
     }
+    const attribution = d.classifier;
+    if (attribution !== undefined) {
+        const named = (v) => typeof v === "string" && v !== "";
+        if (!named(attribution.modelRequested) || !named(attribution.modelUsed))
+            defects.push("I6: disposition.classifier must name both the model the round was for and the model that answered");
+        const fb = attribution.fallback;
+        if (fb !== undefined) {
+            if (!named(fb.from) || !named(fb.to))
+                defects.push("I6: disposition.classifier.fallback must name the rung it left and the rung it arrived at");
+            else if (fb.to !== attribution.modelUsed)
+                defects.push(`I6: the fallback landed on "${fb.to}" but the record names "${attribution.modelUsed}" as the model that answered`);
+            if (!isAutoModeFallbackCause(fb.cause))
+                defects.push(`I6: fallback cause "${String(fb.cause)}" is outside the closed set`);
+        }
+    }
     return defects;
 }

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

@@ -104,7 +104,7 @@ export type NoticeAudience = "user" | "operator";
  * src/ for notice mint shapes and names any code that is minted but unregistered, or registered but
  * no longer minted.
  */
-export declare const ENGINE_NOTICE_CODES: readonly ["config.autocompact_window_clamped", "config.env_timeout_discarded", "config.materialize_env_discarded", "config.models_swapped", "config.read_face_swapped", "config.read_face_deployment_clamped", "config.tool_model_gate_removed", "config.tool_model_gate_unknown_class", "config.tool_model_gate_env_invalid", "config.artifact_host_invalid", "config.tool_card_undeclared", "config.tool_face_undeclared", "config.tool_face_invalid", "config.durable_gate_unavailable", "config.peer_admission_out_of_range", "config.peer_lane_unmounted", "peer.inbound_disposition", "peer.held_settled", "peer.idle_subscription", "classifier.denial_limit", "checkpoint.execution_outcome_unrecorded", "delegation.transcript_integrity", "delegation.ask_unresolvable", "mcp.injection_dropped", "mcp.revocation_probe_failed", "workflow.governance_key_stripped", "workflow.agent_option_ignored", "memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived", "memory.content_class_declared", "memory.hold_opened", "memory.hold_released", "memory.hold_disposed", "memory.consolidation_recommended", "memory.consolidation_committed", "memory.consolidation_conflict", "memory.consolidation_incomplete", "memory.consolidation_refused", "memory.consolidation_withheld", "route.fallback_to_primary", "route.base_url_changed_key_unchanged", "task.user_steer_undrained", "task.user_followup_undrained", "steering.parked_input_blocked", "task.turn_interrupted", "task.halt_unconsumed", "task.late_approval", "task.interrupt_unconsumed", "memory.capture_opted_out", "memory.capture_optout_unpersisted", "tool_result.offload_put_failed"];
+export declare const ENGINE_NOTICE_CODES: readonly ["config.autocompact_window_clamped", "config.env_timeout_discarded", "config.materialize_env_discarded", "config.models_swapped", "config.read_face_swapped", "config.read_face_deployment_clamped", "config.write_face_swapped", "config.write_face_deployment_clamped", "config.tool_model_gate_removed", "config.tool_model_gate_unknown_class", "config.tool_model_gate_env_invalid", "config.artifact_host_invalid", "config.tool_card_undeclared", "config.tool_face_undeclared", "config.tool_face_invalid", "config.durable_gate_unavailable", "config.peer_admission_out_of_range", "config.peer_lane_unmounted", "peer.inbound_disposition", "peer.held_settled", "peer.idle_subscription", "classifier.denial_limit", "classifier.fallback", "checkpoint.execution_outcome_unrecorded", "delegation.transcript_integrity", "delegation.ask_unresolvable", "mcp.injection_dropped", "mcp.revocation_probe_failed", "workflow.governance_key_stripped", "workflow.agent_option_ignored", "memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived", "memory.content_class_declared", "memory.hold_opened", "memory.hold_released", "memory.hold_disposed", "memory.consolidation_recommended", "memory.consolidation_committed", "memory.consolidation_conflict", "memory.consolidation_incomplete", "memory.consolidation_refused", "memory.consolidation_withheld", "route.fallback_to_primary", "route.classifier_unroutable", "route.base_url_changed_key_unchanged", "task.user_steer_undrained", "task.user_followup_undrained", "steering.parked_input_blocked", "task.turn_interrupted", "task.halt_unconsumed", "task.late_approval", "task.interrupt_unconsumed", "memory.capture_opted_out", "memory.capture_optout_unpersisted", "tool_result.offload_put_failed"];
 /** A code this engine mints (see {@link ENGINE_NOTICE_CODES}). NOT the type of
  *  `EngineNotice.code`, which stays `string` — a host forwarding its own notices through the same
  *  sink is a supported shape, and narrowing that field would break it. */

package/dist/core/governance-codes.js

@@ -102,6 +102,8 @@ export const ENGINE_NOTICE_CODES = [
     "config.models_swapped",
     "config.read_face_swapped",
     "config.read_face_deployment_clamped",
+    "config.write_face_swapped",
+    "config.write_face_deployment_clamped",
     "config.tool_model_gate_removed",
     "config.tool_model_gate_unknown_class",
     "config.tool_model_gate_env_invalid",
@@ -116,6 +118,7 @@ export const ENGINE_NOTICE_CODES = [
     "peer.held_settled",
     "peer.idle_subscription",
     "classifier.denial_limit",
+    "classifier.fallback",
     "checkpoint.execution_outcome_unrecorded",
     "delegation.transcript_integrity",
     "delegation.ask_unresolvable",
@@ -137,6 +140,7 @@ export const ENGINE_NOTICE_CODES = [
     "memory.consolidation_refused",
     "memory.consolidation_withheld",
     "route.fallback_to_primary",
+    "route.classifier_unroutable",
     "route.base_url_changed_key_unchanged",
     "task.user_steer_undrained",
     "task.user_followup_undrained",
@@ -159,6 +163,7 @@ const NOTICE_AUDIENCE_TABLE = {
     "task.user_steer_undrained": "user",
     "task.user_followup_undrained": "user",
     "classifier.denial_limit": "user",
+    "classifier.fallback": "operator",
     "task.turn_interrupted": "user",
     "steering.parked_input_blocked": "user",
     "task.halt_unconsumed": "user",
@@ -175,6 +180,8 @@ const NOTICE_AUDIENCE_TABLE = {
     "config.models_swapped": "operator",
     "config.read_face_swapped": "operator",
     "config.read_face_deployment_clamped": "operator",
+    "config.write_face_swapped": "operator",
+    "config.write_face_deployment_clamped": "operator",
     "config.tool_model_gate_removed": "operator",
     "config.tool_model_gate_unknown_class": "operator",
     "config.tool_model_gate_env_invalid": "operator",
@@ -200,6 +207,7 @@ const NOTICE_AUDIENCE_TABLE = {
     "memory.consolidation_incomplete": "operator",
     "memory.consolidation_refused": "operator",
     "route.fallback_to_primary": "operator",
+    "route.classifier_unroutable": "operator",
     "route.base_url_changed_key_unchanged": "operator",
     "tool_result.offload_put_failed": "operator",
 };

package/dist/core/hook-seats.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The hook seam's SEAT discipline and its disclosure vocabulary: which callback seats exist, what a
+ * deployment is allowed to put in one, and how a wiring disclosure names the ones that are wired.
+ *
+ * Kept beside the interface rather than inside it: `hooks.ts` owns the seam's BEHAVIOUR, and this module owns
+ * the seat as a CONFIGURATION VALUE — the same split `wiring-manifest.ts` keeps for the ask/question seats.
+ */
+import type { Hooks } from "./hooks.js";
+import type { AssertAllKeysHandled } from "./ask-origin.js";
+import type { SeamProvenance } from "./wiring-manifest.js";
+/**
+ * The CALLBACK SEATS of {@link Hooks} as a word list — the vocabulary a wiring disclosure names a wired seam
+ * by (`WiringManifest.hooks[].family`), in declaration order. `preToolUseObservational` is deliberately NOT a
+ * member (it is a DECLARATION ABOUT `preToolUse`); `timeoutMs` is not a seat either.
+ */
+export declare const HOOK_FAMILIES: readonly ["preToolUse", "postToolUse", "userPromptSubmit", "stop", "postToolUseFailure", "postToolBatch", "preCompact", "postCompact", "stopFailure", "permissionDenied"];
+/**
+ * One hook seat's name.
+ *
+ * @contract hooks.family_vocabulary — {@link HOOK_FAMILIES} is the only spelling of a hook seat's name on any
+ * disclosure face, and {@link HookFamiliesCoverEverySeat} makes a new callback member of {@link Hooks} red at
+ * `tsc` until it has a word there — a disclosure that omits a seat under-states what runs on the critical path.
+ */
+export type HookFamily = (typeof HOOK_FAMILIES)[number];
+/** Every CALLBACK member of {@link Hooks} — derived from the interface, never a hand-kept second list. */
+type HookCallbackSeat = {
+    [K in keyof Hooks]-?: NonNullable<Hooks[K]> extends (...args: never[]) => unknown ? K : never;
+}[keyof Hooks];
+/** The closed-set fence: `never` while every callback seat has a word, the MISSING SEAT'S NAME when one does
+ *  not (the constraint form names it; a conditional type says only "something changed"). */
+export type HookFamiliesCoverEverySeat = AssertAllKeysHandled<Exclude<HookCallbackSeat, HookFamily>>;
+/** The typed refusal a hook seat holding a present NON-CALLBACK value raises at prepare. */
+export declare const HOOKS_INVALID_CODE = "config.hooks_invalid";
+/**
+ * Screen the resolved hook record's seats (`spec.hooks ?? deps.hooks`).
+ *
+ * @contract hooks.seat_value — a hook seat is a FUNCTION or it is absent. A PRESENT non-function
+ * (`preToolUse: null`, a string, a bare object) is a configuration error and refuses the whole prepare with
+ * {@link HOOKS_INVALID_CODE}, naming the family and the type received. It is not folded to "unwired": the tool
+ * gate arms on PRESENCE (`hooks?.preToolUse !== undefined`) and would invoke the non-function and fail closed
+ * on every call, while a callability-based disclosure reported no hooks at all. The sibling seams already
+ * refuse the same way (`resolveQuestionSeam` / `resolveElicitSeam`). `undefined` stays exactly what it was:
+ * an unwired seat, silent.
+ */
+export declare function assertHookSeatsCallable(hooks: Hooks | undefined, provenance: SeamProvenance): void;
+/**
+ * One WIRED HOOK SEAT of this leg. `family` is the seat's name; `owner` is WHICH SEAT supplied the record, the
+ * `spec > deps` provenance the ask/question seams report. Deliberately no third owner word: core mounts NO
+ * engine-owned hooks, and a delegated child's inherited `preToolUse` rides the gate's constraint fold.
+ */
+export interface WiringManifestHookEntry {
+    family: HookFamily;
+    owner: SeamProvenance;
+    /** Only on the `preToolUse` entry, and only when the deployment DECLARED the face observational
+     *  (`Hooks.preToolUseObservational`) — it still runs on every call but is not folded into a delegated
+     *  child's inherited constraints. Absence means "not declared", never "declared false". */
+    observational?: true;
+}
+/**
+ * The wiring manifest's hook read face ({@link WiringManifestHookEntry}): one entry per CALLBACK seat the
+ * resolved record wires, in the vocabulary's declaration order. The VOCABULARY is the judge — families are
+ * walked, never the record's own keys. `owner` is a property of the RECORD, so every entry agrees. Callability
+ * and presence cannot diverge here: {@link assertHookSeatsCallable} has already refused the leg where they would.
+ */
+export declare function wiredHookEntries(hooks: Hooks | undefined, owner: SeamProvenance, preToolUseObservational: boolean): WiringManifestHookEntry[];
+export {};

package/dist/core/hook-seats.js

@@ -0,0 +1,37 @@
+export const HOOK_FAMILIES = [
+    "preToolUse",
+    "postToolUse",
+    "userPromptSubmit",
+    "stop",
+    "postToolUseFailure",
+    "postToolBatch",
+    "preCompact",
+    "postCompact",
+    "stopFailure",
+    "permissionDenied",
+];
+export const HOOKS_INVALID_CODE = "config.hooks_invalid";
+export function assertHookSeatsCallable(hooks, provenance) {
+    if (hooks === undefined)
+        return;
+    for (const family of HOOK_FAMILIES) {
+        const seat = hooks[family];
+        if (seat === undefined || typeof seat === "function")
+            continue;
+        const e = new Error(`the resolved hooks record (${provenance}) holds ${seat === null ? "null" : typeof seat} at \`${family}\` — a hook seat is a callback or it is absent. ` +
+            `A present non-callback is not an unwired seat: the tool gate arms on presence and would refuse every call through it. Omit the key, or wire a function.`);
+        e.code = HOOKS_INVALID_CODE;
+        throw e;
+    }
+}
+export function wiredHookEntries(hooks, owner, preToolUseObservational) {
+    if (hooks === undefined)
+        return [];
+    const entries = [];
+    for (const family of HOOK_FAMILIES) {
+        if (typeof hooks[family] !== "function")
+            continue;
+        entries.push({ family, owner, ...(family === "preToolUse" && preToolUseObservational ? { observational: true } : {}) });
+    }
+    return entries;
+}

package/dist/core/runner/advertised-writable-dirs.d.ts

@@ -21,9 +21,14 @@
  * no marker and an absent directory narrows.
  *
  * Reverse check (the seat's own invariant): nothing enters `roots` except through `admit`, and every
- * caller of `admit` is an advertiser deciding its advertisement off the returned verdict — so there is
- * no directory the fence opens that the prompt does not advertise, and none the prompt advertises
- * that the fence refuses.
+ * caller of `admit` is an advertiser deciding its advertisement off the returned verdict — so no
+ * directory reaches the ROOTS FENCE through this seat without the prompt advertising it, and none
+ * the prompt advertises is refused by that fence.
+ *
+ * The invariant is about this seat, not about the whole write surface: under an open write face
+ * ({@link import("../../tools/fs/containment-face.js").ContainmentFace}) the roots fence judges
+ * nothing, so what the prompt advertises is a floor rather than the whole list — the `# Environment`
+ * block says so in its own line, and the advertisement stays true (these directories ARE writable).
  */
 import type { ExecutionEnv } from "../../internal/harness.js";
 export interface AdvertisedWritableDir {

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

@@ -153,11 +153,12 @@ export interface ResultFlags {
      *  distinct codes from arriving as one anonymous `limits.max_turns_exceeded`. Empty/absent ⇒ the field is omitted. */
     remoteEnvFailures?: TaskResult["remoteEnvFailures"];
     /** The run's effective read posture (resolved face + normalized deny
-     *  additions), echoed on `TaskResult.effectiveReadFace` / `.effectiveReadDenyPatterns`. Pure
+     *  additions), echoed on `TaskResult.effectiveReadFace` / `.effectiveWriteFace` / `.effectiveReadDenyPatterns`. Pure
      *  pass-through (assembly neither adds nor filters) and INDEPENDENT of the status/errorCode chain:
      *  the posture is a fact about the leg that ran, whatever terminal it reached — a post-completion
      *  spawner folds it stricter-wins into follow-on legs; every other consumer may ignore it. */
     effectiveReadFace?: TaskResult["effectiveReadFace"];
+    effectiveWriteFace?: TaskResult["effectiveWriteFace"];
     effectiveReadDenyPatterns?: TaskResult["effectiveReadDenyPatterns"];
     /** The memory-visibility observation, echoed on
      *  `TaskResult.effectiveMemoryScopes`. Pure pass-through on every terminal, same law as the

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

@@ -166,5 +166,5 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
     if (flags.unpricedSpend)
         delete publicStats.costMicroUsd;
     const stampHaltedByUser = haltConsumed(flags.haltConsumption);
-    return { taskId, ...(flags.runId !== undefined ? { runId: flags.runId } : {}), sessionId, terminal, ...(flags.model !== undefined ? { model: flags.model } : {}), result: result.trim(), salvagedOutput, ...(apiFailure !== undefined ? { apiFailure } : {}), ...(retryAfterMs !== undefined ? { retryAfterMs } : {}), ...(flags.rewindNotes !== undefined && flags.rewindNotes.length > 0 ? { rewindNotes: flags.rewindNotes } : {}), ...(flags.editedFiles !== undefined && flags.editedFiles.length > 0 ? { editedFiles: flags.editedFiles } : {}), ...(flags.haltedOnUserRejection === true ? { haltedOnUserRejection: true } : {}), ...(stampHaltedByUser ? { haltedByUser: true } : {}), ...(flags.remoteEnvFailures !== undefined && flags.remoteEnvFailures.length > 0 ? { remoteEnvFailures: [...flags.remoteEnvFailures] } : {}), ...(flags.strandedHumanAnswers !== undefined && flags.strandedHumanAnswers.length > 0 ? { strandedHumanAnswers: flags.strandedHumanAnswers } : {}), ...(flags.effectiveReadFace !== undefined ? { effectiveReadFace: flags.effectiveReadFace } : {}), ...(flags.effectiveReadDenyPatterns !== undefined && flags.effectiveReadDenyPatterns.length > 0 ? { effectiveReadDenyPatterns: flags.effectiveReadDenyPatterns } : {}), ...(flags.effectiveMemoryScopes !== undefined ? { effectiveMemoryScopes: flags.effectiveMemoryScopes } : {}), ...(flags.effectiveReasoning !== undefined ? { effectiveReasoning: flags.effectiveReasoning } : {}), stats: publicStats };
+    return { taskId, ...(flags.runId !== undefined ? { runId: flags.runId } : {}), sessionId, terminal, ...(flags.model !== undefined ? { model: flags.model } : {}), result: result.trim(), salvagedOutput, ...(apiFailure !== undefined ? { apiFailure } : {}), ...(retryAfterMs !== undefined ? { retryAfterMs } : {}), ...(flags.rewindNotes !== undefined && flags.rewindNotes.length > 0 ? { rewindNotes: flags.rewindNotes } : {}), ...(flags.editedFiles !== undefined && flags.editedFiles.length > 0 ? { editedFiles: flags.editedFiles } : {}), ...(flags.haltedOnUserRejection === true ? { haltedOnUserRejection: true } : {}), ...(stampHaltedByUser ? { haltedByUser: true } : {}), ...(flags.remoteEnvFailures !== undefined && flags.remoteEnvFailures.length > 0 ? { remoteEnvFailures: [...flags.remoteEnvFailures] } : {}), ...(flags.strandedHumanAnswers !== undefined && flags.strandedHumanAnswers.length > 0 ? { strandedHumanAnswers: flags.strandedHumanAnswers } : {}), ...(flags.effectiveReadFace !== undefined ? { effectiveReadFace: flags.effectiveReadFace } : {}), ...(flags.effectiveWriteFace !== undefined ? { effectiveWriteFace: flags.effectiveWriteFace } : {}), ...(flags.effectiveReadDenyPatterns !== undefined && flags.effectiveReadDenyPatterns.length > 0 ? { effectiveReadDenyPatterns: flags.effectiveReadDenyPatterns } : {}), ...(flags.effectiveMemoryScopes !== undefined ? { effectiveMemoryScopes: flags.effectiveMemoryScopes } : {}), ...(flags.effectiveReasoning !== undefined ? { effectiveReasoning: flags.effectiveReasoning } : {}), stats: publicStats };
 }

package/dist/core/runner/classifier-ladder.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The auto-mode classifier's CANDIDATE LADDER, as one module: which models a classification may be asked on,
+ * its per-rung reasoning seat, and the once-per-run disclosure its first move mints.
+ *
+ * Beside `derived-route-fallback.ts` and in the same family — both are seats the caps phase's classifier
+ * arming reaches DOWN for, and both answer "this leg's model did not work out" one layer apart. Which is why
+ * the rung comparison here borrows the route adjudicator's own identity law instead of inventing one.
+ *
+ * THE TWO LAYERS, since one sentence ("the classifier seat did not work out ⇒ use the run's main model") is
+ * spelled in two places. They are ordered, and each has its own trigger and its own record face:
+ *
+ *   ① PRE-FLIGHT — `derivedRouteFallsBack`, BEFORE any call. Trigger: the classifier model's route differs
+ *      from the primary's AND the brain's own route judge finds the credential/URL pairing broken. Effect:
+ *      the arming SWAPS the seat, so the ladder below is built from the main model and rung 0 IS the main
+ *      model. Record: the once-per-run operator notice `route.fallback_to_primary` (`detail.{seat, from, to,
+ *      cause}`) — and only that. `GateDisposition.classifier.modelRequested` reads the MAIN model's id,
+ *      because the ladder it describes never carried the configured seat; the gate record answers "which
+ *      model was asked", and "what did the deployment configure, and was it swapped" is the notice's
+ *      question. `classifierFallback` governs THIS layer too: under `"none"` the pre-flight does not swap —
+ *      it keeps the declared seat and announces `route.classifier_unroutable`, so the deployment that said
+ *      "deny rather than fall back" gets the denial (the seat's calls are refused at the request gate)
+ *      instead of a silent fallback the knob had just declined.
+ *   ② THE LADDER — here, AFTER a call. Trigger: the rung produced no RULING. Effect: the next rung is asked.
+ *      Record: `GateDisposition.classifier.fallback` on every classification this run's own gate decided (an
+ *      inherited-ancestor chain carries the form and no attribution) + the throttled `classifier.fallback`.
+ *
+ * They FOLD rather than stack: after a ① SWAP the seat and the main model are the same route, so
+ * {@link classifierLadderRungs} returns ONE rung and ② cannot fire in the same run (and under `"none"`, where
+ * ① does not swap, the ladder is one rung by the knob). The split's cost is the
+ * `modelRequested` reading above; the unification (the pre-flight as rung 0 under its own cause word, one
+ * record face for both) changes the notice set and is a ticket, not a repair.
+ */
+import type { Model } from "../../internal/llm.js";
+import { type AutoModeClassified } from "../auto-mode.js";
+import type { RunnerDeps } from "../types.js";
+/**
+ * The rungs a classification walks, in order: the classifier seat, and — under `classifierFallback: "main"` (the
+ * default) — the run's main model behind it. The knob is screened by `autoModeClassifierFallbackOf`, here and
+ * (idempotently) at the caps phase that reads the same word for the pre-flight's posture, so a value outside
+ * the closed set refuses the prepare loudly (`config.auto_mode_classifier_fallback_invalid`) instead of
+ * reading as the default.
+ *
+ * ONE RUNG when the two resolve to the SAME ROUTE. Route identity, not `Model.id`: two catalog entries may
+ * legitimately share a wire id while pointing at different endpoints (the route adjudicator's own law, and
+ * the split its pre-flight exists for) — an id-only comparison would collapse a healthy main endpoint and a
+ * broken classifier endpoint into one rung, turning the ladder off for the deployment that needs it most.
+ * The collapse where it does apply is deliberate: re-asking the SAME model is a retry, which is what CC's
+ * `unavailableOuterRetries` does and what this ladder is not. A catalog value the identity law cannot
+ * normalize (a non-string `baseUrl` — it throws) reads as TWO rungs: being wrong that way costs one extra
+ * call on a broken catalog, the other way turns the feature off invisibly, and the bad value still earns its
+ * loud refusal at the brain's request gate.
+ */
+export declare function classifierLadderRungs(knob: unknown, classifier: Model, main: Model): readonly Model[];
+/**
+ * The classifier's REASONING SEAT, read off the model a classification is actually asked on — ONE predicate:
+ * can the wire say off? Yes ⇒ `off` + the verdict-sized cap (the request pays for the answer alone); no ⇒
+ * `low` + the verdict cap + the low-reasoning budget (a model that thinks regardless is told to think the
+ * LEAST its wire can spell, in exactly the room that tier needs). PER RUNG, not once per arming: the second
+ * rung is a different model with its own wire, and asking it under the first rung's seat is how a correct
+ * fallback comes back with zero text. The `low` seat is also the re-ask seat: an unknown model that answers
+ * NOTHING at the `off` cap has just told us it thinks anyway, and is re-asked as one that does.
+ */
+export declare const CLASSIFIER_OFF_SEAT: {
+    reasoning: "off";
+    maxTokens: number;
+};
+export declare const CLASSIFIER_LOW_SEAT: {
+    reasoning: "low";
+    maxTokens: number;
+};
+export declare function classifierRungSeat(model: Model): typeof CLASSIFIER_OFF_SEAT | typeof CLASSIFIER_LOW_SEAT;
+/**
+ * The per-decision READ of a classification, as one seat: the `auto_mode.classified` trace frame (wall time,
+ * verdict, cause) and the ladder's throttled `classifier.fallback` disclosure. Both are observers — a
+ * throwing sink never reaches the gate (the decider swallows it), and neither changes a verdict.
+ *
+ * The frame's `model` is the model the classification RAN ON, which is what the field has always meant (its
+ * declaration reads "the resolved classifier role, or the main model it fell back to"): the route
+ * pre-flight's swap and the ladder's walk are two ways to reach that same sentence. `seatModelId` is the
+ * fallback for a classification that carries no attribution at all.
+ */
+export declare function classifierRoundObserver(args: {
+    tracer: RunnerDeps["tracer"];
+    onNotice: RunnerDeps["onNotice"];
+    taskId: string;
+    seatModelId: string;
+    sessionId?: string;
+    runId?: string;
+}): (info: AutoModeClassified) => void;

package/dist/core/runner/classifier-ladder.js

@@ -0,0 +1,65 @@
+import { sameRouteIdentity } from "../../brain/route-adjudicator.js";
+import { thinkingOffExpressible } from "../../brain/reasoning.js";
+import { AUTO_MODE_CLASSIFIER_LOW_REASONING_BUDGET_TOKENS, AUTO_MODE_CLASSIFIER_MAX_TOKENS } from "../auto-mode-defaults.js";
+import { autoModeClassifierFallbackOf } from "../auto-mode.js";
+import { emitTrace } from "../trace.js";
+import { deliverEngineNotice } from "../types.js";
+export function classifierLadderRungs(knob, classifier, main) {
+    if (autoModeClassifierFallbackOf(knob) === "none")
+        return [classifier];
+    let sameRoute;
+    try {
+        sameRoute = sameRouteIdentity(classifier, main);
+    }
+    catch {
+        sameRoute = false;
+    }
+    return sameRoute ? [classifier] : [classifier, main];
+}
+function classifierFallbackAnnouncer(args) {
+    const announced = new Set();
+    return (attribution) => {
+        const fallback = attribution?.fallback;
+        if (fallback === undefined)
+            return;
+        const key = `${fallback.from}\u0000${fallback.cause}`;
+        if (announced.has(key))
+            return;
+        announced.add(key);
+        deliverEngineNotice(args.onNotice, {
+            code: "classifier.fallback",
+            message: `the auto-mode classifier model "${fallback.from}" did not rule (${fallback.cause}) — this run re-asks each gated call on "${fallback.to}". ` +
+                'Check that the classifier role names a model this deployment\'s gateway serves; set RunnerDeps.autoMode.classifierFallback to "none" to deny instead of falling back.',
+            detail: {
+                from: fallback.from,
+                to: fallback.to,
+                cause: fallback.cause,
+                ...(args.sessionId !== undefined ? { sessionId: args.sessionId } : {}),
+                ...(args.runId !== undefined ? { runId: args.runId } : {}),
+            },
+            ...(args.sessionId !== undefined ? { sessionId: args.sessionId } : {}),
+        });
+    };
+}
+export const CLASSIFIER_OFF_SEAT = { reasoning: "off", maxTokens: AUTO_MODE_CLASSIFIER_MAX_TOKENS };
+export const CLASSIFIER_LOW_SEAT = { reasoning: "low", maxTokens: AUTO_MODE_CLASSIFIER_MAX_TOKENS + AUTO_MODE_CLASSIFIER_LOW_REASONING_BUDGET_TOKENS };
+export function classifierRungSeat(model) {
+    return thinkingOffExpressible(model) ? CLASSIFIER_OFF_SEAT : CLASSIFIER_LOW_SEAT;
+}
+export function classifierRoundObserver(args) {
+    const announce = classifierFallbackAnnouncer(args);
+    return (info) => {
+        emitTrace(args.tracer, () => ({
+            kind: "auto_mode.classified",
+            version: 1,
+            taskId: args.taskId,
+            toolCallId: info.toolCallId,
+            model: info.classifier?.modelUsed ?? args.seatModelId,
+            ms: info.ms,
+            verdict: info.verdict,
+            ...(info.cause !== undefined ? { cause: info.cause } : {}),
+            ts: Date.now(),
+        }));
+        announce(info.classifier);
+    };
+}