@sema-agent/core 7.18.0 → 7.20.0

package/dist/core/memory.d.ts

@@ -275,6 +275,25 @@ export declare class MemoryGateError extends Error {
     readonly code: string;
     constructor(code: string, detail?: string);
 }
+/**
+ * The same SHAPE as {@link MemoryGateError} — a stable `code` a caller switches on — for the opposite
+ * PHASE of a memory write, and deliberately NOT that class: a gate error means the write was REFUSED
+ * and never reached the backend, so a host branching on it would take exactly the wrong action here.
+ *
+ * @contract memory.projection_failure_is_post_durable — a store throws this ONLY after the note's own
+ * event is durably appended and fsync'd, so `committed` is always true and the note survives a restart:
+ * a caller that retries the write on this error stores the note a second time. Only the derived
+ * projection is missing, and the next mutation of the same scope rewrites it whole.
+ */
+export declare class MemoryProjectionError extends Error {
+    /** Stable, switchable — the phase this failure belongs to. */
+    readonly code = "memory.projection_failed";
+    /** Always true: this error only exists AFTER the durable append was fsync'd. Never retry the write. */
+    readonly committed = true;
+    /** The projection file that could not be rewritten. */
+    readonly path: string;
+    constructor(path: string, cause: unknown);
+}
 /**
  * Scan `text` for a high-confidence credential (CC-parity P0-2). Returns the matched pattern's stable
  * `label` (NEVER the matched secret value — labels are safe to log/surface), or `null` when clean.

package/dist/core/memory.js

@@ -22,6 +22,18 @@ export class MemoryGateError extends Error {
         this.code = code;
     }
 }
+export class MemoryProjectionError extends Error {
+    code = "memory.projection_failed";
+    committed = true;
+    path;
+    constructor(path, cause) {
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        super(`memory.projection_failed: the note IS durably committed — only the derived projection ${path} could not be rewritten: ${detail}. ` +
+            `Do not retry the write (it would store the note twice); the projection is rebuilt by the next mutation of this scope.`, cause !== undefined ? { cause } : undefined);
+        this.name = "MemoryProjectionError";
+        this.path = path;
+    }
+}
 function hasPromotableMarker(note) {
     return note.outcomeStats !== undefined;
 }

package/dist/core/read-root-candidate.d.ts

@@ -0,0 +1,12 @@
+/** The display bound on a grant candidate's directory: generous next to a real `PATH_MAX`, tight enough
+ *  that the seat cannot become an unbounded prose channel onto an approval card. */
+export declare const READ_ROOT_CANDIDATE_DIR_MAX = 1024;
+/**
+ * The validator for a probe's {@link import("./tool-spec.js").ReversibilityVerdict.readRootCandidate}: the
+ * errand `normalizeProbeCause` does for the cause, fail-closed on the disclosure alone — a malformed value
+ * yields `undefined`, the ask stands, the card carries no offer. It REFUSES where the cause NEUTRALIZES,
+ * per `shell.read_boundary.grant_candidate_is_the_grant`: the cause is prose, so folding a separator out of
+ * it keeps it true, while this string IS the grant, and a card showing one spelling while the deployment
+ * applies another is the failure the seat prevents.
+ */
+export declare function normalizeReadRootCandidate(value: unknown): import("./tool-spec.js").ReadRootGrantCandidate | undefined;

package/dist/core/read-root-candidate.js

@@ -0,0 +1,24 @@
+import { isPlainRecord, safeDataValue } from "./checkpoint-store.js";
+import { hasWin32AliasedComponent, isAbsolutePathForm, normalizeAbsPathLexically, pathFamilyOf, win32NamespaceScreen } from "../tools/fs/safety.js";
+export const READ_ROOT_CANDIDATE_DIR_MAX = 1024;
+export function normalizeReadRootCandidate(value) {
+    if (!isPlainRecord(value))
+        return undefined;
+    if (safeDataValue(value, "clearsThisAsk") !== true)
+        return undefined;
+    const dir = safeDataValue(value, "dir");
+    if (typeof dir !== "string" || dir.length === 0 || dir.length > READ_ROOT_CANDIDATE_DIR_MAX)
+        return undefined;
+    if (/[\u0000-\u001f\u007f\u2028\u2029]/.test(dir))
+        return undefined;
+    if (!isAbsolutePathForm(dir))
+        return undefined;
+    const folded = normalizeAbsPathLexically(dir);
+    if (folded !== dir || normalizeAbsPathLexically(`${dir}/..`) === dir)
+        return undefined;
+    if (hasWin32AliasedComponent(dir))
+        return undefined;
+    if (!win32NamespaceScreen(dir, pathFamilyOf({ root: dir })).ok)
+        return undefined;
+    return { dir, clearsThisAsk: true };
+}

package/dist/core/remote-env.d.ts

@@ -316,6 +316,16 @@ export interface RemoteExecutionEnv extends ExecutionEnv {
          *  without durable suspend instead (the human gate refuses it), or extend capabilities with an
          *  explicit workspace-durability flag before building one. */
         suspendable: boolean;
+        /** True iff this adapter's {@link FileSystem.canonicalPath} is the AUTHORITY on where a path lands —
+         *  it answers for the very filesystem the commands run on, and a failure to answer is a failure of
+         *  the resolver rather than a namespace it cannot see into. Optional, and absent is not a
+         *  declaration: an adapter that says nothing keeps the reading every adapter has had, in which a
+         *  chain nothing could be established about leaves the lexical verdict standing. Declaring it says
+         *  the opposite — that an unanswerable chain is a question, not an absence — and the read
+         *  boundary's execute-time recheck then refuses rather than passing the written spelling through.
+         *  Read STRICTLY through {@link canonicalPathIsAuthoritative}, like every other capability whose
+         *  `true` changes what a containment leg does; a wrong-SHAPE value reads absent and is announced. */
+        canonicalPathAuthoritative?: boolean;
     };
     /** Identity of the connected workspace (design/48 §5 gap 1). Synchronous: it is data the env already holds. */
     workspaceHandle(): WorkspaceHandle;
@@ -507,6 +517,9 @@ export declare function missingRestoreSurface(env: ExecutionEnv): readonly ("res
  *
  * A composite type guard (structural AND capability) so a `suspendVM` call site narrowed by THIS predicate
  * gets the {@link RemoteExecutionEnv} type without a cast — `true` always implies the structural check too.
+ * The capability is read STRICTLY, like the containment ones: a non-boolean reads as NOT suspendable and
+ * the census announces it. This took anything truthy, so `suspendable: "false"` was snapshotted — the one
+ * key of the three whose malformed reading fell on the unsafe side.
  *
  * It also requires the RESTORE surface ({@link missingRestoreSurface}). A suspend is only durable
  * if something can undo it; an adapter that offers `suspendVM` but no `resumeVM` used to pass this guard,
@@ -549,3 +562,22 @@ export declare function isIsolated(env: ExecutionEnv): boolean;
  * answers exactly, and reading the shape as containment made that deployment's boundary lexical-only.
  */
 export declare function boundaryIsTheSandbox(env: ExecutionEnv): boolean;
+/**
+ * Does this env DECLARE that its `canonicalPath` is the authority on where a path lands?
+ *
+ * The question the execute-time read boundary asks about its own resolver's SILENCE. Resolving a
+ * spelling walks it from the deepest answerable ancestor; when no ancestor answers at all, two
+ * different worlds produce the same `undefined`: a resolver that is authoritative and is FAILING (an
+ * RPC into the machine the command will run on, a transport that dropped), and an env that simply does
+ * not answer path questions (an in-memory double, an adapter with no resolution surface). The first is
+ * a question and the second is an absence, and reading both as the absence is what leaves a containment
+ * leg silently open on an RPC-backed lane.
+ *
+ * So the adapter says which it is, and says it the way {@link isIsolated} is said — strictly, because a
+ * `true` here makes a containment leg REFUSE where it used to pass. ABSENT is the reading every adapter
+ * has had, so no existing env moves; a PRESENT non-boolean reads absent HERE too but is announced at the
+ * env's admission point, once per key — this reader does not validate. A non-remote env keeps the same
+ * reading, which is why the local lane is unchanged: its resolver answers `/`, so the arm this gates
+ * has no case to fire on.
+ */
+export declare function canonicalPathIsAuthoritative(env: ExecutionEnv): boolean;

package/dist/core/remote-env.js

@@ -37,7 +37,7 @@ export function missingRestoreSurface(env) {
     return missing;
 }
 export function isSuspendable(env) {
-    return isRemoteExecutionEnv(env) && env.capabilities.suspendable && missingRestoreSurface(env).length === 0;
+    return isRemoteExecutionEnv(env) && env.capabilities.suspendable === true && missingRestoreSurface(env).length === 0;
 }
 export function isIsolated(env) {
     return isRemoteExecutionEnv(env) ? env.capabilities.isolation === true : false;
@@ -45,3 +45,6 @@ export function isIsolated(env) {
 export function boundaryIsTheSandbox(env) {
     return isIsolated(env);
 }
+export function canonicalPathIsAuthoritative(env) {
+    return isRemoteExecutionEnv(env) ? env.capabilities.canonicalPathAuthoritative === true : false;
+}

package/dist/core/roles.d.ts

@@ -1,6 +1,6 @@
 import type { ThinkingLevel } from "../internal/harness-types.js";
 import type { Model } from "../internal/llm.js";
-import type { ModelRef, ModelRole, ModelRoles } from "./types.js";
+import type { ModelRef, ModelRole, ModelRoles, RoleSpec } from "./types.js";
 export type { ModelRole, RoleSpec, ModelRoles } from "./types.js";
 /** Resolve a string ModelRef against the catalog (a Model object passes through). */
 export declare function resolveModel(ref: ModelRef, models?: Record<string, Model>): Model;
@@ -87,6 +87,14 @@ export declare function parseModelMention(text: string, allowedNames: Iterable<s
  * (即使 catalog 恰有裸模型名 `pro`/`flash` 也不入档位路由——INERT 靠配置成立,不靠键名运气)。
  */
 export declare const ROLE_TIER_DEFAULTS: Readonly<Partial<Record<ModelRole, string>>>;
+/**
+ * Whether a RoleSpec NAMES a model — a string ref, a Model object, or a config object carrying `model` or
+ * `select` — as opposed to a preset-only object (`{ thinking }`, `{ systemPrompt }`) that shapes the role's
+ * request but leaves its model to the defaults. The classifier seat's own default (the tier below the run's
+ * main model, `classifier-ladder.ts`) applies exactly when this is false: a `{select}` keeps its selection, a
+ * preset-only role does not disable the relative pick. One reader, the same parts {@link specParts} reads.
+ */
+export declare function roleSpecNamesModel(spec: RoleSpec | undefined): boolean;
 export interface ResolvedRole {
     model: Model;
     /** The effective thinking level: explicit `spec.thinking` wins, else the role's default. */

package/dist/core/roles.js

@@ -130,6 +130,10 @@ function specParts(s) {
     const cfg = s;
     return { model: cfg.model, select: cfg.select, thinking: cfg.thinking, systemPrompt: cfg.systemPrompt };
 }
+export function roleSpecNamesModel(spec) {
+    const parts = specParts(spec);
+    return parts.model !== undefined || parts.select !== undefined;
+}
 function toConfig(s) {
     if (s == null) {
         return undefined;

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

@@ -20,6 +20,11 @@
  * planted path is never written through); an advertiser whose directory is created elsewhere passes
  * no marker and an absent directory narrows.
  *
+ * A directory the fence already holds is never admitted as a HOLE in it: a candidate that resolves onto
+ * a root — or above one — would turn that whole root into the advertised, write-gate-exempt domain, so
+ * an ordinary source write inside the workspace would stop asking. One predicate
+ * ({@link swallowedFenceRoot}) states that, and the write gate's configured domains apply the same one.
+ *
  * 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 no
  * directory reaches the ROOTS FENCE through this seat without the prompt advertising it, and none
@@ -55,12 +60,65 @@ export interface AdvertisedWritableDir {
 }
 /** The skip announcement — the one loud outlet for a directory that was advertised but could not be admitted. */
 export type AdvertisedWritableDirSkipped = (dir: AdvertisedWritableDir, reason: string) => void;
+/**
+ * ONE rule for both halves of the auto-approved write surface: a directory offered as a WRITABLE DOMAIN
+ * (an advertised writable directory here; a configured `exemptDirs`/`acceptDirs` entry at the write
+ * gate) must not SWALLOW a root the fence already holds. Returns the first root the candidate equals or
+ * is an ancestor of — the one to name in the refusal — else `undefined`.
+ *
+ * Why a domain that contains a root is not a domain: the point of the domain is to exempt a small area
+ * the prompt (or the deployment) named. A candidate resolving onto the task root — a symlinked
+ * scratchpad or memory home is all it takes, and the resolution is what makes it invisible to the
+ * spelling — exempts the ENTIRE workspace instead, turning every ordinary source write from `ask` into
+ * `allow`. Refusing the admission is the fix; a special case inside the gate ("ignore this domain when
+ * it contains the root") would be the same rule written twice, in the place where it is easiest to
+ * forget. Both arguments must already be CANONICAL — this compares spellings, it does not resolve them.
+ */
+export declare function swallowedFenceRoot(domainCanonical: string, fenceRootsCanonical: readonly string[]): string | undefined;
 export declare class AdvertisedWritableDirs {
     private readonly env;
     private readonly onSkipped;
+    /** The extra fence roots the SPEC declares (`additionalDirectories` / `additionalReadDirectories`), as
+     *  spelled. Resolved by this seat rather than awaited from the hands phase — the memory advertiser is
+     *  admitted BEFORE that phase, so a list that only grew there made the rule depend on phase order. An
+     *  entry that does not resolve is not a fence root at all (the hands phase reads the SAME memoized
+     *  answer and skips it too, announcing it there), so there is nothing here for it to guard. */
+    private readonly declaredRootSpellings;
     private readonly admitted;
     private readonly verdicts;
-    constructor(env: ExecutionEnv, onSkipped: AdvertisedWritableDirSkipped);
+    /** The CANONICAL roots the fence holds: the task root at construction, plus every root the spec
+     *  DECLARES, resolved by this seat before it judges anything (see {@link resolveDeclaredRoots}) —
+     *  so which advertiser runs first cannot decide what the rule sees. */
+    private readonly fenceRoots;
+    /** Latched after the declared spellings have been resolved once (the resolution is per seat, not per call). */
+    private declaredRootsResolved;
+    /** ONE answer per declared spelling, for this seat AND for the hands phase that folds the same entries
+     *  into the allowlist ({@link canonicalizeDeclaredRoot}): two independent lookups of one path can
+     *  DISAGREE, and a root outside this rule's list while inside the fence is exactly the gap. */
+    private readonly declaredRootAnswers;
+    constructor(env: ExecutionEnv, onSkipped: AdvertisedWritableDirSkipped, 
+    /** The run's task root, CANONICAL (the driver's one resolution — see `task-root-canonical.ts`). */
+    taskRootCanonical: string, 
+    /** The extra fence roots the SPEC declares (`additionalDirectories` / `additionalReadDirectories`), as
+     *  spelled. Resolved by this seat rather than awaited from the hands phase — the memory advertiser is
+     *  admitted BEFORE that phase, so a list that only grew there made the rule depend on phase order. An
+     *  entry that does not resolve is not a fence root at all (the hands phase reads the SAME memoized
+     *  answer and skips it too, announcing it there), so there is nothing here for it to guard. */
+    declaredRootSpellings?: readonly string[]);
+    /** Declare one more CANONICAL root the fence holds (an `additionalDirectories` /
+     *  `additionalReadDirectories` entry, once the hands phase has resolved it). Declaring is
+     *  idempotent and order-free; a root declared after an advertiser was judged does not re-open it. */
+    declareFenceRoot(canonical: string): void;
+    /**
+     * The canonical form of a DECLARED fence-root spelling — resolved at most once per spelling and
+     * served from the memo thereafter. The hands phase calls this instead of canonicalizing the same
+     * entries again, so the list this rule judges against and the allowlist the fence ends up holding
+     * are built from ONE answer per path: a lookup that fails for this seat fails for that phase too,
+     * and a root cannot be outside the rule's view while being inside the fence.
+     */
+    canonicalizeDeclaredRoot(spelled: string): Promise<Awaited<ReturnType<ExecutionEnv["canonicalPath"]>>>;
+    /** Resolve the spec-declared root spellings into {@link fenceRoots}, exactly once per seat. */
+    private resolveDeclaredRoots;
     /** The admitted roots, CANONICAL, in admission order, deduplicated. The hands phase folds this list into the
      *  write-capable containment allowlist before the toolkit compiles; it is not a live view after that. */
     get roots(): readonly string[];

package/dist/core/runner/advertised-writable-dirs.js

@@ -1,11 +1,52 @@
+import { isWithin } from "./session-rule-policy.js";
+export function swallowedFenceRoot(domainCanonical, fenceRootsCanonical) {
+    for (const root of fenceRootsCanonical) {
+        if (root && isWithin(domainCanonical, root))
+            return root;
+    }
+    return undefined;
+}
 export class AdvertisedWritableDirs {
     env;
     onSkipped;
+    declaredRootSpellings;
     admitted = [];
     verdicts = new Map();
-    constructor(env, onSkipped) {
+    fenceRoots;
+    declaredRootsResolved;
+    declaredRootAnswers = new Map();
+    constructor(env, onSkipped, taskRootCanonical, declaredRootSpellings = []) {
         this.env = env;
         this.onSkipped = onSkipped;
+        this.declaredRootSpellings = declaredRootSpellings;
+        this.fenceRoots = [taskRootCanonical];
+    }
+    declareFenceRoot(canonical) {
+        if (canonical && !this.fenceRoots.includes(canonical))
+            this.fenceRoots.push(canonical);
+    }
+    async canonicalizeDeclaredRoot(spelled) {
+        const memo = this.declaredRootAnswers.get(spelled);
+        if (memo !== undefined)
+            return memo;
+        const c = await this.env.canonicalPath(spelled);
+        const first = this.declaredRootAnswers.get(spelled);
+        if (first !== undefined)
+            return first;
+        this.declaredRootAnswers.set(spelled, c);
+        if (c.ok)
+            this.declareFenceRoot(c.value);
+        return c;
+    }
+    resolveDeclaredRoots() {
+        this.declaredRootsResolved ??= (async () => {
+            for (const spelled of this.declaredRootSpellings) {
+                if (!spelled || !spelled.trim())
+                    continue;
+                await this.canonicalizeDeclaredRoot(spelled);
+            }
+        })();
+        return this.declaredRootsResolved;
     }
     get roots() {
         return this.admitted;
@@ -41,8 +82,15 @@ export class AdvertisedWritableDirs {
             this.onSkipped(dir, `the execution environment resolves it to ${c.value} while the advertiser's gates key on ${dir.expectCanonical} — a fence hole those gates cannot see is not opened`);
             return false;
         }
-        if (!this.admitted.includes(c.value))
-            this.admitted.push(c.value);
+        if (this.admitted.includes(c.value))
+            return true;
+        await this.resolveDeclaredRoots();
+        const swallowed = swallowedFenceRoot(c.value, [...this.fenceRoots, ...this.admitted]);
+        if (swallowed !== undefined) {
+            this.onSkipped(dir, `it resolves to ${c.value}, which covers ${swallowed === this.fenceRoots[0] ? "task root" : "root"} ${swallowed} — a directory that holds a root is not a hole in the fence but the whole of it, and admitting it would auto-approve every write under that root`);
+            return false;
+        }
+        this.admitted.push(c.value);
         return true;
     }
 }

package/dist/core/runner/announce-once-ledger.d.ts

@@ -27,6 +27,21 @@ export interface AnnounceOnceSession {
     getAnnouncedListing(): Promise<AnnouncedListingSnapshot | undefined>;
     appendAnnouncedListing(snapshot: AnnouncedListingSnapshotInput): Promise<string>;
 }
+/**
+ * Flush the PARKED announced-listing snapshot write (`FrameReceiptLedger.listingSnapshotOwed`, set by a
+ * frame receipt's commit inside the `message_end` walk) at a serialization point — the boundary's end,
+ * the prompt's settle. Best-effort: a lost append is a duplicate announcement next run. Never while
+ * prepare's branch read failed: a whole-snapshot write would replace the branch's record with this
+ * leg's partial view (the flag is cleared either way — nothing is owed on such a leg).
+ */
+export declare function flushOwedAnnouncedSnapshot(prepared: {
+    frameReceipts: {
+        listingSnapshotOwed: boolean;
+    };
+    announcedSnapshotRecovered: boolean;
+    announcedListingsRef: AnnouncedListingSnapshotInput;
+    session: Pick<AnnounceOnceSession, "appendAnnouncedListing">;
+}): Promise<void>;
 /** The run-local ledger — see the module header for the two commit disciplines it serves. */
 export interface AnnounceOnceLedger {
     /** The nearest announced snapshot on the branch as read at prepare (undefined = pre-entry

package/dist/core/runner/announce-once-ledger.js

@@ -29,6 +29,14 @@ export function withAnnounceDigests(existing, add) {
 function sameFailure(a, b) {
     return a.name === b.name && a.error === b.error;
 }
+export async function flushOwedAnnouncedSnapshot(prepared) {
+    if (!prepared.frameReceipts.listingSnapshotOwed)
+        return;
+    prepared.frameReceipts.listingSnapshotOwed = false;
+    if (!prepared.announcedSnapshotRecovered)
+        return;
+    await prepared.session.appendAnnouncedListing(prepared.announcedListingsRef).catch(() => undefined);
+}
 export async function loadAnnounceOnceLedger(session, checkpointMirror, onError) {
     let recovered = true;
     const entry = await session.getAnnouncedListing().catch(() => {

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

@@ -1,6 +1,8 @@
 /**
- * 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.
+ * The auto-mode classifier's CANDIDATE LADDER, as one module: which models a classification may be asked on
+ * (and which model stands in when no `classifier` role names one), its per-rung reasoning seat and the
+ * per-attempt user-message tail, how a rung's reply is read for a re-ask or a failure, and the once-per-run
+ * disclosures its first move and its broken contract mint.
  *
  * 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
@@ -30,7 +32,7 @@
  * `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 { AssistantMessage, Model } from "../../internal/llm.js";
 import { type AutoModeClassified } from "../auto-mode.js";
 import type { RunnerDeps } from "../types.js";
 /**
@@ -51,14 +53,74 @@ import type { RunnerDeps } from "../types.js";
  * loud refusal at the brain's request gate.
  */
 export declare function classifierLadderRungs(knob: unknown, classifier: Model, main: Model): readonly Model[];
+/**
+ * WHY the classifier seat is the model it is when no `classifier` role names one — the closed set behind the
+ * `classifier.role_defaulted` notice's `reason`. `tier_below_main` = the nearest directly-bound tier below the
+ * run's main model; `tier_table` = the static `flash` row (a main bound to no tier); `role_fallback` = the
+ * `summarize → default` chain (no tiers at all); `main_only` = the main model is the only model there is (a
+ * single-model catalog, or nothing bound below the main's tier); `role_unresolvable` = a `classifier` role
+ * NAMED a model the catalog cannot resolve (a stale or misspelled reference), so the main model stands in —
+ * the pre-#805 leg fell back the same way, silently.
+ */
+export declare const CLASSIFIER_ROLE_DEFAULT_REASONS: readonly ["tier_below_main", "tier_table", "role_fallback", "main_only", "role_unresolvable"];
+export type ClassifierRoleDefaultReason = (typeof CLASSIFIER_ROLE_DEFAULT_REASONS)[number];
+/** What {@link classifierSeatModel} returns: the model, and — when no role NAMED it — why it is that one. */
+export type ClassifierSeat = {
+    readonly model: Model;
+    readonly defaulted?: ClassifierRoleDefaultReason;
+};
+/**
+ * The model the classifier SEAT resolves to for this run — ONE resolver for "which model classifies":
+ *   · a `classifier` role that NAMES a model (`roleSpecNamesModel`: a string ref, a Model object, `{model}`,
+ *     `{select}`) ⇒ the role resolver's answer, exactly as before (a preset-only role — `{thinking}` alone —
+ *     does not name one and takes the default below);
+ *   · else, with tier bindings declared (`deps.tiers`) and a main model on a tier ⇒ the nearest tier strictly
+ *     BELOW the main's whose route differs from the main's — `tier_below_main`; the main's tier is the LOWEST
+ *     tier its route sits on (a route bound as both `max` and `flash` is a `flash` main: deterministic, and
+ *     the cheaper reading); nothing below ⇒ the main itself, `main_only`. Read off the expanded catalog's
+ *     tier keys, the Runner's own resolution of a tier word: a key synthesised for an unbound tier falls DOWN
+ *     to the next bound tier, which is the model this walk reaches anyway, and a catalog key spelled like a
+ *     tier shadows the binding here as it does everywhere. No thinking preference: whether a model's
+ *     thinking can be turned off is the SEAT's business ({@link classifierRungSeat}), not routing's;
+ *   · else the role resolver's own fallback (the static tier row `classifier → flash` when tiers are active,
+ *     `tier_table`; the `summarize → default` chain otherwise, `role_fallback`); a catalog with no roles at
+ *     all ⇒ the main model, `main_only`.
+ * The relative pick follows the run's MAIN model on purpose: a side channel that resolved without it is the
+ * misfit the ticket names (a `flash` classifier above a `lite` main; two tiers below a `max` main).
+ *
+ * @contract classifier.seat.one_resolver — this function is the ONE answer to "which model judges this run's
+ * gated calls". The engine's arming calls it and a host that DISPLAYS the seat (a capabilities face, an
+ * operator pane) calls the same exported function rather than re-deriving the pick from catalog, roles and
+ * tiers: a second derivation is a second answer, and the two drift the moment either side's rules move.
+ */
+export declare function classifierSeatModel(args: {
+    deps: Pick<RunnerDeps, "models" | "roles" | "tiers">;
+    main: Model;
+}): ClassifierSeat;
+/**
+ * The `classifier.role_defaulted` line — minted ONCE per run by the arming, AFTER the route pre-flight, so it
+ * names the seat actually asked (a pre-flight swap to the main model is its own line,
+ * `route.fallback_to_primary`, same run). Silent when a role named the model: nothing was defaulted.
+ */
+export declare function announceClassifierRoleDefaulted(args: {
+    onNotice: RunnerDeps["onNotice"];
+    seat: ClassifierSeat;
+    sessionId?: string;
+    runId?: string;
+}): void;
 /**
  * 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.
+ * does the wire SPELL off ({@link thinkingOffSpelled})? Yes ⇒ `off` + the verdict-sized cap (the request pays
+ * for the answer alone); no ⇒ `low` + the verdict cap + the low allowance (a model whose thinking the wire
+ * cannot turn off is asked for the least it can grade, in the room that costs — CC 2.1.259 `MU`: spell off,
+ * or leave thinking to the provider and pay 2048). A model that declares no reasoning at all is on the `low`
+ * seat too: its wire carries nothing either way, so the request is the gateway's default, and a default-on
+ * gateway thinks — the arm that used to read it as "never thinks" is the one the field report was about.
+ * PER RUNG, not once per arming: the second rung is a different model with its own wire.
+ *
+ * The THINK seat is the RE-ASK seat ({@link classifierReplyAsksAgain}): a first attempt that produced no
+ * verdict is asked once more with thinking allowed the room of CC's stage-2 classifier (8192) — an unknown
+ * model that answered NOTHING at its cap has just told us it thinks past it, and is re-asked as one that does.
  */
 export declare const CLASSIFIER_OFF_SEAT: {
     reasoning: "off";
@@ -68,11 +130,92 @@ export declare const CLASSIFIER_LOW_SEAT: {
     reasoning: "low";
     maxTokens: number;
 };
+export declare const CLASSIFIER_THINK_SEAT: {
+    reasoning: "low";
+    maxTokens: number;
+};
+export type ClassifierSeatRequest = typeof CLASSIFIER_OFF_SEAT | typeof CLASSIFIER_LOW_SEAT | typeof CLASSIFIER_THINK_SEAT;
+/**
+ * The seat for one rung's FIRST attempt — see the seat table above.
+ *
+ * @contract classifier.budget_is_room — every classifier output cap is ROOM the request asks for, never a
+ * bound the engine can vouch for: a gateway may exclude reasoning tokens from `max_tokens` (a vLLM-fronted
+ * Qwen gateway answered a cap of 128 with 938 output tokens and `stop`), so an over-long think is cut by the
+ * round-trip timeout (`unavailable` / `timeout`), not by the cap (`parse_error` on an empty reply), and the
+ * two are attested as the two different facts they are.
+ */
 export declare function classifierRungSeat(model: Model): typeof CLASSIFIER_OFF_SEAT | typeof CLASSIFIER_LOW_SEAT;
+/**
+ * The user-message TAIL of each attempt — CC 2.1.259's classifier suffixes, verbatim: the FIRST attempt
+ * carries the fast-mode suffix (`$ns`: the answer must begin with `<block>`, no preamble), the RE-ASK carries
+ * the thinking-stage suffix (`Uns`: think in `<thinking>` first, then answer). The base prompt (2.1.250 `KRg`)
+ * already says "no preamble" once; upstream repeats it at the END of the user message, and it is the repeat
+ * that lands — live 2026-09-15, a Qwen 3.8 with thinking off went from 70% tagged replies (1.2–3.9k chars of
+ * "Looking at this action…" prose) to 90% at 8 output tokens with the first suffix, and the re-ask suffix
+ * had it write its reasoning inside `<thinking>` (stripped by the reader) before the tag.
+ */
+export declare const CLASSIFIER_ATTEMPT_SUFFIX: {
+    readonly first: "\nErr on the side of blocking. Your ENTIRE response MUST begin with <block>. Do NOT output any analysis, reasoning, or commentary before <block>. No \"Looking at...\" or similar preamble.";
+    readonly reask: "\nReview the classification process and follow it carefully, making sure you deny actions that should be blocked. As a reminder, explicit (not suggestive or implicit) user confirmation is required to override blocks. Use <thinking> before responding with <block>. Think longer on ambiguous or borderline actions; keep reasoning brief for clear-cut ones.";
+};
+/** The classifier reply's answer text — every text block joined; thinking blocks are not the verdict. */
+export declare function classifierReplyText(reply: AssistantMessage): string;
+/**
+ * CC 2.1.259 `$Tt`: an EMPTY reply that stopped at the output cap is "unparseable" — a reply to ask for again,
+ * not a refusal and not a verdict. The engine's brains report that cut two ways: `stopReason:"length"` (an
+ * engine-shrunk cap) or `stopReason:"error"` with `errorKind:"length_empty"` (a static cap — the classifier's
+ * own). An empty reply with any OTHER stop is CC's `policy_refusal` arm: not re-asked.
+ */
+export declare function classifierReplyEmptyAtCap(reply: AssistantMessage): boolean;
+/**
+ * A reply that may answer in the TAG form only: its text is not a complete answer of its own. Output cut by the cap
+ * (`stopReason: "length"`), a dropped connection or a stalled stream (`partialFinalized`, with a synthesised
+ * `stop`), and a reply that CALLED A TOOL (`stopReason: "toolUse"`, or a tool-call block in the content — the
+ * classifier is given no tools, and the openai brain reports a length cut with a surviving call as `toolUse`):
+ * whatever text arrived is a prefix or a fragment — a `No` on its way to `No, this must be blocked` — so it may
+ * carry a verdict only through a `<block>` tag, which reads a `<block>no` prefix as CC does; the bare-answer arm
+ * never sees it.
+ */
+export declare function classifierReplyTagOnly(reply: AssistantMessage): boolean;
+/**
+ * The text the DECIDER reads for its verdict: the reply's answer text, except that a tag-only reply
+ * ({@link classifierReplyTagOnly}) whose text carries NO tagged answer reads as EMPTY — a cut prefix must not
+ * reach the bare-answer arm as if it were the whole reply (adversarial passes 2–3: a connection cut after `No`,
+ * and a scratch `<block>` mention before a cut `No`, executed the gated tool). Judged by the reader itself with
+ * its bare arm closed, so "no tagged verdict" and "no verdict" cannot drift. Only the MISSING form is emptied:
+ * a tag-only reply that carries a CONFLICT keeps its text, so the decider records the conflict and the leg
+ * does not re-ask it (adversarial pass 4: emptying every parse failure had turned a cut conflict into a
+ * missing reply, and the re-ask into an allow). The decider then records `parse_error` / `missing` for the
+ * emptied text, the same word an empty reply gets.
+ */
+export declare function classifierReplyVerdictText(reply: AssistantMessage): string;
+/**
+ * Whether a first attempt is asked AGAIN on the THINK seat — ONE rule: the reply is MISSING a verdict, either
+ * empty at the cap ({@link classifierReplyEmptyAtCap}), cut or fragmentary without a tagged verdict
+ * ({@link classifierReplyTagOnly}), or text in which the reader finds no answer at all (`parse_error` of form
+ * `missing`: prose, a thinking-only reply). Not a CONFLICT (two `<block>` answers — it carries a `yes`, and a second attempt that answered `no`
+ * would erase it: the fail-closed `parse_error` it is stands) and not an empty reply with a non-cap stop
+ * (CC's refusal arm). CC 2.1.259 `Vrr` re-asks an unparseable reply up to `maxRetries` times; sema re-asks
+ * ONCE, on the stage-2 room, so a rung costs at most two calls. A failed reply ({@link classifierReplyFailure})
+ * is judged before this and never reaches it.
+ */
+export declare function classifierReplyAsksAgain(reply: AssistantMessage): boolean;
+/**
+ * A reply that is a LEG FAILURE rather than an answer — the brains RETURN a provider error as a message
+ * (`stopReason: "error"` with the provider's text on `errorMessage`: an HTTP 4xx/5xx, a quota refusal, an
+ * overloaded gateway) and a cancelled request as `"aborted"`; neither is a reply the reader may judge. Read as
+ * text they were `parse_error` — a card saying "the classifier's reply carried no verdict" about a model that
+ * never answered, a ladder record blaming `parse_error` instead of `error`. The leg THROWS what this returns
+ * and the decider maps the throw to `unavailable` (`error`), as it maps every leg failure; the sibling
+ * side-channel legs (compaction, consolidation) already read an error stop this way. The cap-cut form
+ * (`errorKind: "length_empty"`) is not a failure: it is the empty-at-cap reply the re-ask owns.
+ */
+export declare function classifierReplyFailure(reply: AssistantMessage): Error | undefined;
 /**
  * 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.
+ * verdict, cause), the ladder's throttled `classifier.fallback` disclosure and the per-model
+ * `classifier.contract_broken` streak. All are observers — a throwing sink never reaches the gate (the decider
+ * swallows it), and none 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