clearotron 0.3.2-beta.7 → 0.3.2-beta.9

package/driver/engine/CONTRACT.md

@@ -41,6 +41,8 @@ ladder consumes it without knowing which engine produced it ([gateway.mjs](../ga
   sessionRef: string | null,         // opaque resume handle (claude session_id | codex thread_id)
   modelWire:  string | null,         // MODEL GAUGE — the served model id this turn observed (§3);
                                      // null = nothing was observed, never the requested alias
+  providerWire: string | null,       // PROVIDER GAUGE — the program's own word for who served the turn
+                                     // ("firstParty", "foundry"); null = not said, or said inconsistently
   signals:    { stalled?, noProgress?, hardWall?, rateLimited?, rateLimitBasis?, resetsAt?,
                 resetsAtBasis?, usageStreamed?, noStreamEvents?, thought: bool|null },
                                      // THINKING GAUGE — see below.
@@ -139,8 +141,8 @@ Stages must name **abstract tiers**, not provider aliases. Per-engine maps:
 
 | tier | role (stage examples) | anthropic-agent (claude alias) | openai-agent (codex `-m`) |
 |---|---|---|---|
-| `judgment` | matter-frame, register-digest, synthesis, narrative-refutation | `claude-opus-5` (pinned) | `$CLEAROTRON_OPENAI_MODEL_JUDGMENT` |
-| `sweep` | register-unit, case-law, skeptic, report-overview, report-card | `claude-sonnet-5` (pinned) | `$CLEAROTRON_OPENAI_MODEL_SWEEP` |
+| `judgment` | matter-frame, register-digest, synthesis, narrative-refutation | `opus` | `$CLEAROTRON_OPENAI_MODEL_JUDGMENT` |
+| `sweep` | register-unit, case-law, skeptic, report-overview, report-card | `sonnet` | `$CLEAROTRON_OPENAI_MODEL_SWEEP` |
 | `cheap` | saturation-probe | `haiku` | `$CLEAROTRON_OPENAI_MODEL_CHEAP` |
 
 **AN UNHONOURED OVERRIDE IS AN ERROR, NOT A SUBSTITUTION** ( corruption 3, 2026-08-03). This
@@ -150,7 +152,12 @@ anthropic engine, "grade-moving, validated only in the paid A/B". The substituti
 and could not be: the telemetry logged the alias that was ASKED FOR, so an arm run at gemini reported
 gemini and ran sonnet. Both tiers are gone — the failover chain was deleted in and both stages
 declare an anthropic tier in `STAGES` — and every engine's model map now **refuses** an alias it cannot
-run (`claudeModel`, `openaiModel`). A concrete provider id passes through; anything else throws.
+run (`claudeModel`, `openaiModel`). On the anthropic engine a tier goes as the vendor's alias, a catalog
+id in the table (`anthropic/claude-opus-5`) goes as itself, a bare or dated `claude-*` id goes as its
+family's alias, and anything else throws. To hold a tier on one model, set the vendor's own
+`ANTHROPIC_DEFAULT_OPUS_MODEL` / `_SONNET_MODEL` / `_HAIKU_MODEL`, or `ANTHROPIC_DEFAULT_FABLE_MODEL` for
+`fable`, which no stage asks for unless an override names it, as `CLEAROTRON_SYNTHESIS_MODEL=fable` does; each
+reaches the CLI through the stage's environment.
 
 **Model provenance — two fields, never collapsed.** Every dispatch row (`_driver/<stage>.jsonl`) and
 every `attempt` row (`_driver/run.jsonl`) carries:

package/driver/engine/README.md

@@ -13,7 +13,7 @@ does not exist — that is the design, and [`CONTRACT.md`](CONTRACT.md) is the d
 | [`CONTRACT.md`](CONTRACT.md) | **The adapter contract.** What an engine must implement, the model-tier map, and what a turn is allowed to assume. Read this before either adapter |
 | `anthropic-agent.mjs` | Spawns `claude -p`. Skill-reference absolutization, `--add-dir` grants, rate-limit and no-progress handling |
 | `openai-agent.mjs` | Spawns `codex exec`. A per-run `CODEX_HOME` carrying a rendered `config.toml`, and the session-rollout reader that recovers the turn's usage |
-| `auth.mjs` | `resolveAuthMode()` — subscription or API key, resolved once per turn and stamped on the telemetry |
+| `auth.mjs` | `resolveAuthMode()` — subscription, API key or (Claude only) cloud account, resolved once per turn and stamped on the telemetry |
 | `probe.mjs` | Drives one cheap turn through whichever adapter is configured, to prove the engine can complete a turn at all. What `npm run setup` spends |
 | `common.mjs` | Helpers both adapters share |
 | `deny-authority-write.mjs` | A PreToolUse hook. `--add-dir` has no read-only form, so the read-only intent over the skills tree is enforced here |
@@ -27,7 +27,7 @@ succeeding on the other one. A run's manifest records which engine served it.
 
 ## Billing mode is resolved here, and it fails loud
 
-`resolveAuthMode()` is the single place "subscription or API key" is decided, and it is deliberately
+`resolveAuthMode()` is the single place a turn's billing mode (subscription, API key or cloud account) is decided, and it is deliberately
 unforgiving in one direction:
 
 ```

package/driver/engine/anthropic-agent.mjs

@@ -6,7 +6,7 @@
 //
 // Contract: engine/CONTRACT.md. runTurn() returns the registry-standard normalized tuple
 // (`{code, killed, wall, stdout, stderr, laneWaitMs, json, usage, reads, readsTruncated, modelWire,
-// sessionRef, signals}`), with a SYNTHESIZED `json` envelope in the classifier's shape so every downstream
+// providerWire, sessionRef, signals}`), with a SYNTHESIZED `json` envelope in the classifier's shape so every downstream
 // classifier in gateway.mjs (payloadText, json.status check, isEmbeddedFallback, isTimeout,
 // isLaneWedge) works unchanged.
 //
@@ -21,12 +21,18 @@ import { tmpdir } from "node:os";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { resolveSpawnCwd, spawnGraceMs } from "./common.mjs";
-import { envFrom } from "../../shared/env-aliases.mjs";   // — resolves EITHER spelling; names the retired one because that is the live-writable half
+import { resolveEngineProgram } from "../driver.config.mjs";   // — the one place that finds the program; it reads every spelling of the setting
 import { authorityTrees } from "../authority-trees.mjs";
 import { recordEngineChild, clearEngineChild } from "./child-record.mjs";   //
+import { billingMode } from "./auth.mjs";   // — the one parse of the billing word (see spawnEnv)
 
 // Read per-call (not module-level) so tests can drive a short stall timeout / a mock binary.
-const claudeBin = () => envFrom(process.env, "CLEAROTRON_CLAUDE_PATH") || "claude";
+// ONE place knows how to find the program (driver.config.mjs resolveEngineProgram): the explicit setting,
+// then PATH, then the copy Clearotron installed. What it found is spawned by ABSOLUTE path, because a
+// bare word lets spawn(2) walk PATH on its own and never reach the installed copy. When nothing resolved,
+// what was asked for is spawned unchanged, so that failure reads exactly as it always has; the run door
+// (preflightEngineBinary) refuses that case before any stage runs.
+const claudeBin = () => { const r = resolveEngineProgram("anthropic-agent"); return r.resolved ?? r.bin; };
 
 // AUTH TOGGLE (config, not code). The subscription path is the cost-saving default: claude -p with NO
 // ANTHROPIC_API_KEY in its env falls back to the OAuth subscription credentials (apiKeySource:"none" →
@@ -34,10 +40,15 @@ const claudeBin = () => envFrom(process.env, "CLEAROTRON_CLAUDE_PATH") || "claud
 // .env, and a present API key OVERRIDES the subscription — so we must STRIP it from the claude subprocess
 // env. CLEAROTRON_AI_BILLING=api-key keeps the key (the standing fallback for when the subscription is
 // revoked — Anthropic's advance notice = today's per-call API cost). Default = subscription.
+//
+// `cloud` strips it too, as that mode's acceptance asks: a key has no part in a turn the vendor's switches
+// send to the reader's cloud account, and dropping it means a leftover key can never be what bills. A
+// gateway's credential is its own ANTHROPIC_AUTH_TOKEN, which rides through like every other name. The
+// word is parsed by auth.mjs (billingMode), the one place that reads it. This never validates and never
+// throws, because the doors that do (the top of runStage, the probe, the jx runner) have already run.
 export function spawnEnv(base = process.env) {
   const env = { ...base };
-  const mode = (base.CLEAROTRON_AI_BILLING || "subscription").toLowerCase();
-  if (mode !== "api-key") delete env.ANTHROPIC_API_KEY;   // subscription: force OAuth/subscription billing
+  if (billingMode(base) !== "api-key") delete env.ANTHROPIC_API_KEY;   // subscription and cloud
   return env;
 }
 // 120s of ZERO streamed output = the silent-provider-stall abort. A healthy turn
@@ -110,15 +121,20 @@ const killEscalateMs = () => Math.max(50, Number(process.env.CLEAROTRON_KILL_ESC
 // clock, so the watchdog never trips). Default 64MB (gateway parity); CLEAROTRON_ENGINE_MAX_BUFFER shrinks it for tests.
 const engineMaxBufferChars = () => Math.max(1024, Number(process.env.CLEAROTRON_ENGINE_MAX_BUFFER || 64 * 1024 * 1024));
 
-// tier/alias → claude -p model alias. haiku passes straight through (claude understands the alias —
-// the 2026-06-16 capture used `--model haiku`). opus and sonnet are PINNED to their full model names
-// (claude-opus-5 / claude-sonnet-5) rather than the bare "opus"/"sonnet" aliases, so they no longer
-// silently drift to whatever Anthropic/the CLI currently calls "opus"/"sonnet" — matching the driver's
-// reproducibility conventions (warm-resume same-model, PURE-FILE replay). opus was bumped off the
-// floating "opus" alias to the pinned claude-opus-5 on 2026-07-27: the bare alias still resolved to
-// claude-opus-4-8 on the live CLI (2.1.209) at the time, so this is a real, GRADE-MOVING model change
-// validated in the paid A/B (CONTRACT §3), never on $0 replay — same price as 4.8 ($5/$25). The
-// non-anthropic tiers (gemini skeptic, deepseek refutation, azure) have no claude equivalent →
+// tier/alias → claude -p model alias. EVERY TIER GOES AS THE VENDOR'S OWN ALIAS — opus, sonnet, haiku,
+// fable — so the CLI serves the newest model of that family, and a new one arrives with no edit here.
+// opus and sonnet were pinned to claude-opus-5 / claude-sonnet-5 from 2026-07-27, when the bare "opus"
+// still resolved to Opus 4.8 on the live CLI (2.1.209). The pin was reversed on 2026-09-14, for two
+// reasons. A hand-pinned id is a silent downgrade on every clearance from the day a better model ships.
+// And on Bedrock, Vertex and Foundry the CLI resolves an alias through the vendor's own
+// ANTHROPIC_DEFAULT_OPUS_MODEL / _SONNET_MODEL / _HAIKU_MODEL / _FABLE_MODEL, which an exact id bypasses:
+// a cloud with no deployment of that exact name refuses the turn. The cost is that a model can move under a
+// clearance without a test; the witness is the id the CLI reports, recorded on every attempt row
+// (`modelActual`) and on the published run. To hold a tier still, set the vendor's variable in the env file
+// (ANTHROPIC_DEFAULT_OPUS_MODEL=<id>): the stage's environment is the driver's, so it reaches the CLI
+// with no setting of Clearotron's own. ANTHROPIC_DEFAULT_FABLE_MODEL holds fable, which no stage asks for
+// unless an override names it, as CLEAROTRON_SYNTHESIS_MODEL=fable does. A catalog id a caller names
+// (anthropic/claude-opus-5) still goes as that exact id. The non-anthropic tiers (gemini skeptic, deepseek refutation, azure) have no claude equivalent →
 // substituted with an anthropic model (also GRADE-MOVING, A/B-only); their bare-alias substitutes
 // (e.g. deepseek → "opus") are legacy aliases no stage names today, intentionally left un-pinned. They
 // stay registered so a stage that names one is SUBSTITUTED loudly rather than caught by the regex
@@ -141,7 +157,7 @@ const engineMaxBufferChars = () => Math.max(1024, Number(process.env.CLEAROTRON_
 // non-GPT id. That is the issue's requirement in one line: an unhonoured model override is an error,
 // not a substitution.
 const CLAUDE_MODEL = {
-  opus: "claude-opus-5", sonnet: "claude-sonnet-5", haiku: "haiku", fable: "fable",
+  opus: "opus", sonnet: "sonnet", haiku: "haiku", fable: "fable",
   "anthropic/claude-opus-5": "claude-opus-5", "anthropic/claude-sonnet-5": "claude-sonnet-5",
   "anthropic/claude-sonnet-4-6": "sonnet", "anthropic/claude-haiku-4-5": "haiku",
 };
@@ -552,7 +568,16 @@ export const anthropicAgentEngine = {
       // It never falls back to the requested alias — a record that says "actual: <what we asked for>"
       // when nothing was observed is precisely the absence-read-as-a-pass this issue exists to end. The
       // comparison and the policy live in gateway.mjs; this reports, it does not judge.
-      let wireModelInit = null, wireModelAssistant = null;
+      //
+      // A MESSAGE THE CLI WROTE ITSELF NAMES NO MODEL. The CLI labels such a message `<synthetic>` in the
+      // model field, measured in testing on Azure Foundry (2026-09-14): with the opus pin naming a
+      // deployment that did not exist, the turn exited 1 with the CLI's own error and its assistant event
+      // said `<synthetic>`. No model served that turn, so the label is never taken as a served id, and
+      // `answeredItself` stops init's answer from standing in for one: init says what the session was
+      // configured with, and naming it here would name a model for a turn no model served. A real id on
+      // an earlier assistant event of the same turn now stands, because that model did serve a call;
+      // before the label was refused, the label that followed overwrote it.
+      let wireModelInit = null, wireModelAssistant = null, answeredItself = false;
       // READS GAUGE (AD-4, 2026-07-30 addendum): which files this turn actually OPENED, from the stream's
       // completed Read tool_use blocks. The stage prompt OFFERS a set of documents (declared inputs +
       // skill refs); nothing recorded whether the turn could and did read them — and one review
@@ -703,11 +728,14 @@ export const anthropicAgentEngine = {
         else if (ev.type === "rate_limit_event") rateLimitEvent = ev;
         else if (ev.type === "system" && ev.subtype === "init") {
           // MODEL GAUGE — the session's configured model, the earliest wire statement of what will run.
-          if (typeof ev.model === "string" && ev.model) wireModelInit ??= ev.model;
+          if (typeof ev.model === "string" && ev.model && !isCliLabel(ev.model)) wireModelInit ??= ev.model;
         }
         else if (ev.type === "assistant") {
           // MODEL GAUGE — the model that served THIS API call. Authoritative over init (see above).
-          if (typeof ev.message?.model === "string" && ev.message.model) wireModelAssistant = ev.message.model;
+          if (typeof ev.message?.model === "string" && ev.message.model) {
+            if (isCliLabel(ev.message.model)) answeredItself = true;
+            else wireModelAssistant = ev.message.model;
+          }
           // THINKING GAUGE — block presence + signature, never the text (display defaults to "omitted",
           // so an engaged block carries a zero-length `thinking` string). See the declaration above.
           if (!thought && ev.message?.content?.some?.((b) => b?.type === "thinking")) thought = true;
@@ -1077,8 +1105,13 @@ export const anthropicAgentEngine = {
           toolWaitUnmeasurable: [...unmeasurable],
           // MODEL GAUGE: the id the WIRE reported, or null when the stream never said. Assistant
           // message first (what served the call), init second (what the session was configured with).
-          // Never the requested alias — see the declaration above.
-          modelWire: wireModelAssistant ?? wireModelInit ?? null,
+          // Never the requested alias, and never init's answer for a turn only the CLI answered — see the
+          // declaration above.
+          modelWire: wireModelAssistant ?? (answeredItself ? null : wireModelInit),
+          // PROVIDER GAUGE: the program's own word for who served the turn, read from the result's per-model
+          // usage ("firstParty" on Anthropic's own API and "foundry" on Azure Foundry, measured 2026-09-14),
+          // or null when the stream never said or its models disagree. Recorded, never inferred from config.
+          providerWire: providerOf(resultEvent),
           sessionRef: resultEvent?.session_id ?? resumeRef ?? null,
           // The raw result event's total_cost_usd is a provider-side field and stays in the provider's
           // own stream; the tuple carries no currency (tokens-only directive 2026-07-11) — `usage` is
@@ -1116,6 +1149,29 @@ function errResult(t0, e, resumeRef) {
     // reads: a spawn error means NO turn ran — [] is the true observation (nothing was read), not a gap.
     // modelWire: null for the opposite reason — no turn ran, so the wire said nothing about a model, and
     // the record must say UNKNOWN rather than inherit the alias that was asked for.
-    json: null, usage: null, reads: [], readsTruncated: false, modelWire: null, sessionRef: resumeRef ?? null,
+    json: null, usage: null, reads: [], readsTruncated: false, modelWire: null, providerWire: null, sessionRef: resumeRef ?? null,
   };
 }
+
+/**
+ * The program's own word for which provider served a turn, from the result event's per-model usage:
+ * `modelUsage[<model>].provider`, "firstParty" on Anthropic's own API and "foundry" on Azure Foundry
+ * (measured 2026-09-14, CLI 2.1.263). One word when every model the turn used names the same provider;
+ * null when none does or they disagree, because a single word would then be a guess.
+ */
+export function providerOf(resultEvent) {
+  const words = new Set();
+  for (const u of Object.values(resultEvent?.modelUsage ?? {})) {
+    const w = typeof u?.provider === "string" ? u.provider.trim() : "";
+    if (w) words.add(w);
+  }
+  return words.size === 1 ? [...words][0] : null;
+}
+
+/**
+ * Whether a model field holds one of the CLI's own bracketed labels, such as `<synthetic>` on a message
+ * it wrote itself, rather than the id of a model. The reports skip the same shape when they name models.
+ */
+function isCliLabel(id) {
+  return /^<.*>$/.test(String(id).trim());
+}

package/driver/engine/auth.mjs

@@ -20,28 +20,147 @@
 // spelling list let the OpenAI half decide how an Anthropic run bills. deleted the old names, so
 // there is one variable, only the selected engine is ever consulted, and the hazard has no route left.
 //
-// And deliberately written OUT at each site rather than through a helper: the guard in
-// `env-governance.test.mjs` finds a product read by the literal `env.NAME`, so a helper taking the
-// name as an argument makes both reads invisible to it — measured, it turned them harness-only and
-// put both names on the "no longer read by product code" list. The repetition is what keeps them
-// visible to the census that has to see them.
+// And deliberately written OUT as a literal rather than passed to a helper as an argument: the env
+// audit finds a product read by the literal `env.NAME`, so a helper taking the name as an argument makes
+// the read invisible to it — measured, it turned the reads harness-only and put the name on the "no
+// longer read by product code" list. `billingMode` below spells the name out, which keeps it visible.
+
+// THREE MODES FOR CLAUDE, AND NOTHING ELSE IS A MODE. `cloud` bills Claude through the reader's own
+// Google, Microsoft or Amazon account, or through a gateway in front of one (ANTHROPIC_BASE_URL). The
+// vendor's program already routes on its own switches, which reach it because the stage environment is
+// the driver's; what was missing was a billing word that says so. Without it a cloud machine had two
+// choices and both were wrong: `api-key` refused for want of an Anthropic key the machine does not have,
+// and `subscription` ran and stamped every row as billed to a subscription nobody was paying.
+//
+// AN UNKNOWN WORD IS REFUSED. It used to run as `subscription` on both engines, so a typo in the one
+// setting that decides who pays was a quiet bill to the wrong account. It refuses here, at the top of
+// runStage, in the probe and in the jx runner, before any turn runs.
+export const BILLING_MODES = Object.freeze(["subscription", "api-key", "cloud"]);
+
+/**
+ * The billing word as the environment writes it, normalised and NOT validated: unset or blank reads as
+ * the default. The one parse of the word. `resolveAuthMode` validates it; the anthropic adapter's
+ * `spawnEnv`, which must never throw, reads it through here rather than parsing it a second way.
+ */
+export function billingMode(env = process.env) {
+  return String(env.CLEAROTRON_AI_BILLING ?? "").trim().toLowerCase() || "subscription";
+}
+
+// The vendor's own switches, read the way its program reads them: "1", "true", "yes" or "on" switches
+// one on. Spelled out one per line for the reason given above. The order is only the order a refusal
+// names them in.
+const switchedOn = (v) => ["1", "true", "yes", "on"].includes(String(v ?? "").trim().toLowerCase());
+export const CLOUD_SWITCH = Object.freeze({ vertex: "CLAUDE_CODE_USE_VERTEX", foundry: "CLAUDE_CODE_USE_FOUNDRY", bedrock: "CLAUDE_CODE_USE_BEDROCK" });
+
+// EVERY NAME THE PROGRAM READS TO REACH AND PAY A CLOUD, as setup writes them and the install page lists
+// them: each cloud's switch and its least settings, the gateway pair, and the four model pins a cloud
+// deployment is named by. A run takes every line of its settings file, so it has these already. Setup's
+// proof turn and doctor read the file name by name, and carry these so a check proves the account a run
+// bills rather than whatever the shell happened to hold.
+//
+// THE FABLE PIN IS ON IT, THOUGH SETUP NEVER ASKS FOR IT. The program reads a pin for every tier it takes as
+// an alias, fable included, and no stage asks for fable unless an override names it. On Foundry that
+// alias resolves to nothing unless the pin names a deployment, so a reader who sets the override sets the
+// pin by hand, and doctor, setup's proof turn and a background start must carry it like the other three.
+//
+// THE STANDARD AWS KEY VARIABLES ARE ON IT. A machine with no AWS profile and no instance role keeps its
+// Amazon keys in the settings file, and a search reads them from there. Without these three names doctor's
+// proof turn ran without the keys and reported a fault on a machine whose searches worked.
+export const CLOUD_SETTINGS = Object.freeze([
+  ...Object.values(CLOUD_SWITCH),
+  "ANTHROPIC_VERTEX_PROJECT_ID", "CLOUD_ML_REGION", "GOOGLE_APPLICATION_CREDENTIALS",
+  "ANTHROPIC_FOUNDRY_RESOURCE", "ANTHROPIC_FOUNDRY_API_KEY",
+  "AWS_REGION", "AWS_PROFILE", "AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN",
+  "ANTHROPIC_BASE_URL", "ANTHROPIC_AUTH_TOKEN",
+  "ANTHROPIC_DEFAULT_OPUS_MODEL", "ANTHROPIC_DEFAULT_SONNET_MODEL", "ANTHROPIC_DEFAULT_HAIKU_MODEL", "ANTHROPIC_DEFAULT_FABLE_MODEL",
+]);
+
+// THE ONES THAT HOLD A SECRET, by name. Wherever a cloud setting is shown, one of these is shown as set and
+// never with its value. Named rather than matched by suffix: AWS_ACCESS_KEY_ID ends like the Google project
+// id beside it, and only one of the two is a credential.
+export const CLOUD_SECRETS = Object.freeze([
+  "ANTHROPIC_FOUNDRY_API_KEY", "AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN", "ANTHROPIC_AUTH_TOKEN",
+]);
+
+// WHAT A READER CHECKS WHEN A CLOUD REFUSES THE CREDENTIALS, per cloud: who refused, by the name a reader
+// knows it by, and the settings and sign-in that decide it. Names only, never a value. The remedy for a
+// subscription, run the program once and sign in, means nothing on a machine that pays through a cloud, and
+// it was the only remedy the checks gave. Every setting named here is on CLOUD_SETTINGS, so doctor and
+// setup's proof turn carry what this tells a reader to check.
+export const CLOUD_CREDENTIAL_CHECK = Object.freeze({
+  vertex: Object.freeze({ who: "Google Cloud",
+    check: "ANTHROPIC_VERTEX_PROJECT_ID, CLOUD_ML_REGION, and the Google sign-in on this machine (gcloud's, or the key GOOGLE_APPLICATION_CREDENTIALS names)" }),
+  foundry: Object.freeze({ who: "Microsoft Azure",
+    check: "ANTHROPIC_FOUNDRY_API_KEY, or the Azure sign-in on this machine, and ANTHROPIC_FOUNDRY_RESOURCE" }),
+  bedrock: Object.freeze({ who: "Amazon Bedrock",
+    check: "AWS_REGION and the AWS credentials on this machine (a profile, an instance role, or AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY)" }),
+  gateway: Object.freeze({ who: "the gateway", check: "ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN" }),
+});
+
+export function cloudsSwitchedOn(env = process.env) {
+  const on = [];
+  if (switchedOn(env.CLAUDE_CODE_USE_VERTEX)) on.push("vertex");
+  if (switchedOn(env.CLAUDE_CODE_USE_FOUNDRY)) on.push("foundry");
+  if (switchedOn(env.CLAUDE_CODE_USE_BEDROCK)) on.push("bedrock");
+  return on;
+}
+
+// Every refusal below carries `billingRefusal: true`, so a reader classifies it by what it is rather than
+// by its wording: the probe does, and a sign-in error that also names this setting is not one of these.
+const refuse = (message) => Object.assign(new Error(message), { billingRefusal: true });
+const notAMode = (mode, modes) => refuse(
+  `CLEAROTRON_AI_BILLING=${mode} is not a billing mode — refusing to guess, because the guess would bill ` +
+  `the subscription. One of: ${modes.join(", ")}.`);
 
 export function resolveAuthMode({ engineName, env = process.env } = {}) {
   const name = String(engineName || "").toLowerCase();
 
   if (name === "anthropic-agent") {
-    const mode = (env.CLEAROTRON_AI_BILLING || "subscription").toLowerCase() === "api-key" ? "api-key" : "subscription";
+    const mode = billingMode(env);
     if (mode === "api-key" && !env.ANTHROPIC_API_KEY)
-      throw new Error(
+      throw refuse(
         `CLEAROTRON_AI_BILLING=api-key but ANTHROPIC_API_KEY is not set — refusing to silently bill the ` +
         `subscription instead. Set the key, or use CLEAROTRON_AI_BILLING=subscription.`);
-    return { provider: "anthropic", mode, apiBilled: mode === "api-key" };
+    const on = cloudsSwitchedOn(env);
+    // A cloud's switch sends the program to that cloud whatever the billing word says. Measured on Foundry,
+    // 2026-09-14: with the switch on and the word unset, the program reported Foundry as its provider and
+    // the row was stamped as the subscription's. So a switch beside `subscription` or `api-key` is refused,
+    // after a missing key, which is the fault the config page names first.
+    if ((mode === "subscription" || mode === "api-key") && on.length)
+      throw refuse(
+        `${on.map((c) => CLOUD_SWITCH[c]).join(" and ")} ${on.length > 1 ? "are" : "is"} on, which sends Claude to ` +
+        `that cloud account, while CLEAROTRON_AI_BILLING says ${mode} — refusing rather than record the wrong ` +
+        `account. Use CLEAROTRON_AI_BILLING=cloud, or ${on.length > 1 ? "turn them off" : "turn the switch off"}.`);
+    if (mode === "subscription") return { provider: "anthropic", mode, apiBilled: false };
+    if (mode === "api-key") return { provider: "anthropic", mode, apiBilled: true };
+    if (mode === "cloud") {
+      if (on.length > 1)
+        throw refuse(
+          `CLEAROTRON_AI_BILLING=cloud but more than one cloud is switched on ` +
+          `(${on.map((c) => CLOUD_SWITCH[c]).join(", ")}) — set exactly one, so the run can say which account it bills.`);
+      // A switch names the cloud. ANTHROPIC_BASE_URL alone is the gateway form: a cloud reached through the
+      // reader's own proxy. With a switch also set, the switch is what the program routes on.
+      const cloud = on[0] ?? (env.ANTHROPIC_BASE_URL ? "gateway" : null);
+      if (!cloud)
+        throw refuse(
+          `CLEAROTRON_AI_BILLING=cloud but none of CLAUDE_CODE_USE_VERTEX, CLAUDE_CODE_USE_FOUNDRY, ` +
+          `CLAUDE_CODE_USE_BEDROCK or ANTHROPIC_BASE_URL is set — refusing to silently bill the subscription ` +
+          `instead. Set the one for your cloud (INSTALL.md), or use CLEAROTRON_AI_BILLING=subscription.`);
+      return { provider: "anthropic", mode, apiBilled: true, cloud };
+    }
+    throw notAMode(mode, BILLING_MODES);
   }
 
   if (name === "openai-agent") {
-    const mode = (env.CLEAROTRON_AI_BILLING || "subscription").toLowerCase() === "api-key" ? "api-key" : "subscription";
+    const mode = billingMode(env);
+    if (mode === "cloud")
+      throw refuse(
+        `CLEAROTRON_AI_BILLING=cloud bills Claude through a cloud account, and this machine runs the Codex ` +
+        `engine — refusing rather than billing the ChatGPT subscription instead. Use subscription or api-key ` +
+        `with Codex, or CLEAROTRON_AI=anthropic-agent for a cloud account.`);
+    if (mode !== "subscription" && mode !== "api-key") throw notAMode(mode, ["subscription", "api-key"]);
     if (mode === "api-key" && !env.CODEX_API_KEY)
-      throw new Error(
+      throw refuse(
         `CLEAROTRON_AI_BILLING=api-key but CODEX_API_KEY is not set — refusing to silently bill the ChatGPT ` +
         `subscription instead. Set the key, or use CLEAROTRON_AI_BILLING=subscription.`);
     return { provider: "openai", mode, apiBilled: mode === "api-key" };

package/driver/engine/jx-turn.mjs

@@ -68,7 +68,7 @@ export function turnText(tuple) {
  * Read one normalized tuple into the shape the jx lanes consume. PURE, so every branch is assertable
  * from a literal rather than from a spawned CLI.
  */
-export function readJxTuple(tuple, { vendor, authMode, engine }) {
+export function readJxTuple(tuple, { vendor, authMode, cloud = null, engine }) {
   // CANONICAL Usage, whole (engine/CONTRACT.md §2: {input, output, cacheRead, cacheWrite, total}). The old
   // Messages-API rows carried input/output only because that is all the API returned; keeping only those
   // two now would drop cache and total tokens from the rollup on the very lanes this change puts on the
@@ -82,7 +82,7 @@ export function readJxTuple(tuple, { vendor, authMode, engine }) {
   // the receipt names who did the native-language work, and an alias does not name anyone. Both adapters
   // populate it (anthropic-agent from the assistant/init events, openai-agent from `ev.model`).
   const model = tuple?.modelWire ?? null;
-  const base = { model, vendor, authMode, usage, engine };
+  const base = { model, vendor, authMode, cloud, usage, engine };
   // WHETHER TRUNCATION IS OBSERVABLE IS A FACT ABOUT THE ADAPTER, NOT ABOUT THIS TURN. It is keyed on the
   // engine deliberately: `anthropic-agent` writes `stopReason: r?.stop_reason` unconditionally, so the
   // KEY is present on every one of its turns whether or not the wire said anything — testing for the key
@@ -108,7 +108,7 @@ export function readJxTuple(tuple, { vendor, authMode, engine }) {
 /**
  * A `turn` runner for the jx lanes, bound to the run's engine and billing mode.
  *
- * Returns `{ turn, vendor, authMode, engine }`, or `{ error }` when the configuration refuses — the
+ * Returns `{ turn, vendor, authMode, cloud, engine }`, or `{ error }` when the configuration refuses — the
  * caller degrades the lane with that cause rather than this throwing into a pipeline stage.
  */
 export async function makeJxTurnRunner({
@@ -149,16 +149,17 @@ export async function makeJxTurnRunner({
 
   const vendor = auth.provider;
   const authMode = auth.mode;
+  const cloud = auth.cloud ?? null;   // which cloud account bills, under the cloud mode; null otherwise
   return {
-    vendor, authMode, engine: id,
+    vendor, authMode, cloud, engine: id,
     async turn({ prompt }) {
       let tuple;
       try { tuple = await runTurn({ message: prompt, model, thinking, timeoutSec, stallSec }); }
       catch (e) {
         return { ok: false, cause: `the engine turn threw: ${String(e?.message ?? e).slice(0, 200)}`,
-          model: null, vendor, authMode, engine: id, usage: { input: 0, output: 0 }, truncationObservable: false };
+          model: null, vendor, authMode, cloud, engine: id, usage: { input: 0, output: 0 }, truncationObservable: false };
       }
-      return readJxTuple(tuple, { vendor, authMode, engine: id });
+      return readJxTuple(tuple, { vendor, authMode, cloud, engine: id });
     },
   };
 }

package/driver/engine/mcp/README.md

@@ -14,7 +14,7 @@ The active register provider is mounted under the single, neutral server key `re
 named `register_*` — so the namespaced ids the prompts and allowlists carry (`mcp__register__register_enumerate`)
 stay stable across a provider swap. What is PINNED is the vendor's TOOL tokens, not its name:
 `../../test/provider-neutral-prose.test.mjs` walks `driver/` (skipping `fixtures/`) and fails any `<vendor>_<tool>`
-outside the six `<provider>-server.mjs` files and `../../skills/prelim-register/providers/`, exempting a core's own
+outside the six `<provider>-server.mjs` files and `../../skills/clearance-register/providers/`, exempting a core's own
 `ERROR: … HTTP` diagnostics. The plain vendor NAME is unrestricted: `REGISTER_SERVERS` is keyed by it, and 134 other
 files under `driver/` carry `corsearch`.
 

package/driver/engine/mcp/dispositions-server.mjs

@@ -12,7 +12,7 @@
 // held by FOUR stages — `common-law`, `common-law-half`, `narrative-refutation`, `synthesis`. Because
 // `allowedToolsFor` enumerates every tool on every entry a group resolves to, all four carried
 // `mcp__perplexity__record_dispositions`, while every doctrinal mention of the tool is common-law's:
-// `driver/skills/prelim-common-law/SKILL.md`, and the two common-law stage dictations in `stages.mjs`.
+// `driver/skills/clearance-common-law/SKILL.md`, and the two common-law stage dictations in `stages.mjs`.
 // Zero occurrences in synthesis's dictation block, zero in narrative-refutation's doctrine.
 //
 // That is GRANTED-BUT-NEVER-ORDERED, the defect class, in its mirror form: not a stage ordered to
@@ -75,8 +75,8 @@ async function record_dispositions(params) {
   let spec;
   try { spec = validateGridSpec(JSON.parse(readFileSync(grid_spec_path, "utf8"))); }
   catch (err) { return { isError: true, text: `ERROR: grid_spec_path unreadable/invalid (${err.message}). The driver writes this file; do not hand-author it.` }; }
-  if (!/\/studio\/prelim-search\//.test(spec.output_path))
-    return { isError: true, text: `ERROR: grid spec.output_path must be within a studio/prelim-search run dir; got ${spec.output_path}` };
+  if (!/\/studio\/(?:prelim|clearance)-search\//.test(spec.output_path))   // either spelling: an install keeps the studio segment it has
+    return { isError: true, text: `ERROR: grid spec.output_path must be within a studio/clearance-search run dir; got ${spec.output_path}` };
   // NEVER THROWN PAST THIS POINT. An exception surfaces to the seat as a tool error naming no row, which
   // tells it nothing about what to fix — the failure mode this transport exists to end.
   try {

package/driver/engine/mcp/gather-config.mjs

@@ -23,7 +23,7 @@ const BRIDGE = process.env.CLEAROTRON_OAUTH_BRIDGE || join(MCP_DIR, "..", "..",
 // ── The register surface is PROVIDER-NEUTRAL ────────────────────────────────────────────────────
 // The active register provider is mounted under the single server key `register`, and every register
 // tool is named `register_*`. The vendor's name survives ONLY inside its own *-server.mjs file and in
-// skills/prelim-register/providers/<provider>.md (the vocabulary doc the spawns are told to read).
+// skills/clearance-register/providers/<provider>.md (the vocabulary doc the spawns are told to read).
 //
 // Why neutral names rather than interpolating `${PROVIDER}_enumerate` into the prose: the register
 // instructions in stages.mjs / pipeline.mjs / gateway.mjs are then correct BY CONSTRUCTION for every
@@ -275,7 +275,7 @@ const RECORDING = Object.freeze({
       + "DISCOVERY over the run dir (O3c: 21 calls, 1 write / 15 attempts, `ls`/`find`/`cat`), not the "
       + "enumerable pair frame-diff's Read grant covers",
   },
-  // FIFTH — prelim-variants, conversion 3. Classes 3 + 2, and the CLASS 3 half is what makes it
+  // FIFTH — clearance-variants, conversion 3. Classes 3 + 2, and the CLASS 3 half is what makes it
   // different from every conversion before it: O3c measured 9 Bash calls with 4 WRITES across 15
   // attempts, and the shape is `python3 -c` over `variant-manifest.json` — the seat PRE-CHECKING its own
   // JSON before saving it. That is a constraint the transport can check, so under the design's Class 3
@@ -287,12 +287,12 @@ const RECORDING = Object.freeze({
   // enumerable — it derives the manifest from material already on disk that the dictation names — so the
   // seeded `Read` grant carries them. Granting a search tool to a stage whose reads can be listed is
   // what the sanctioned-equivalents design refuses. Same ruling as frame-diff, opposite to matter-frame.
-  "prelim-variants": {
+  "clearance-variants": {
     seatWrites: false,
-    tools: Object.freeze(["record_prelim_variants"]),
+    tools: Object.freeze(["record_clearance_variants"]),
     reason: "hands back the variant manifest — mark, dominant element, elements, variants with their "
       + "romanisations, incumbent classes, watchlist owners and the scope-ledger rows — through "
-      + "record_prelim_variants instead of hand-formatting a JSON skeleton the driver already "
+      + "record_clearance_variants instead of hand-formatting a JSON skeleton the driver already "
       + "strict-parses and a prose twin that restates it; the driver serialises variant-manifest.json, "
       + "renders variant-manifest.md, and derives scope-ledger.json from the same values rather than by "
       + "re-parsing a markdown table the seat typed. Gains NO retrieval server and NO search tool (its "
@@ -320,7 +320,7 @@ const RECORDING = Object.freeze({
   // NO `search_run_artifacts`: the dictation names this stage's ONLY two inputs — the settled narrative
   // and findings.json — and already trimmed its declared reads to exactly those two. A read set that
   // short is enumerable by definition, and the design forbids handing a search tool to a stage whose
-  // reads can be listed. Same ruling as frame-diff and prelim-variants.
+  // reads can be listed. Same ruling as frame-diff and clearance-variants.
   "report-overview": {
     seatWrites: false,
     tools: Object.freeze(["record_report_overview"]),
@@ -671,7 +671,7 @@ const LOCAL = {
   //
   // GRANTED BY EXACTLY ONE LANE'S GROUP LIST — `common-law` and its `common-law-half` variant, through
   // the prefix branch in toolGroupsForStage. Every doctrinal mention of the tool is theirs:
-  // driver/skills/prelim-common-law/SKILL.md and the two common-law stage dictations in stages.mjs.
+  // driver/skills/clearance-common-law/SKILL.md and the two common-law stage dictations in stages.mjs.
   //
   // NOT an allowlist growing by a token this time: it SHRINKS synthesis's and narrative-refutation's
   // argv and RENAMES the token on common-law's (`mcp__perplexity__record_dispositions` →
@@ -1222,8 +1222,8 @@ export const RECORDING_TOOLS = Object.freeze({
   // so deriving it would compare a value with itself. matter-frame carries the search tool for the same
   // reason skeptic does, on its OWN key — a shared key would hand skeptic a writer into the frame.
   // BY HAND, like every row here — O1 compares the resolved grant against it, so a derived row would
-  // compare a value with itself. prelim-variants carries NO search tool: enumerable inputs, Read serves.
-  "prelim-variants": Object.freeze(["Read", "mcp__recording-prelim-variants__record_prelim_variants"]),
+  // compare a value with itself. clearance-variants carries NO search tool: enumerable inputs, Read serves.
+  "clearance-variants": Object.freeze(["Read", "mcp__recording-clearance-variants__record_clearance_variants"]),
   "matter-frame": Object.freeze(["Read", "mcp__recording-matter-frame__record_matter_frame",
     "mcp__recording-matter-frame__search_run_artifacts"]),
   skeptic: Object.freeze(["Read", "mcp__recording-skeptic__record_skeptic",

package/driver/engine/mcp/perplexity-server.mjs

@@ -154,8 +154,8 @@ async function research(params) {
     let spec;
     try { spec = validateGridSpec(JSON.parse(readFileSync(grid_spec_path, "utf8"))); }
     catch (err) { return `ERROR: grid_spec_path unreadable/invalid (${err.message}). The driver writes this file; do not hand-author it.`; }
-    if (!/\/studio\/prelim-search\//.test(spec.output_path))
-      return requiredLedgerRefusal(`ERROR: grid spec.output_path must be within a studio/prelim-search run dir; got ${spec.output_path}`, { spec, gridSpecPath: grid_spec_path });
+    if (!/\/studio\/(?:prelim|clearance)-search\//.test(spec.output_path))   // either spelling: an install keeps the studio segment it has
+      return requiredLedgerRefusal(`ERROR: grid spec.output_path must be within a studio/clearance-search run dir; got ${spec.output_path}`, { spec, gridSpecPath: grid_spec_path });
     // — already recorded and complete? Answer from the ledger; do not buy the grid twice.
     const already = recordedLedgerFor(spec);
     if (already) {

package/driver/engine/mcp/recording-server.mjs

@@ -44,7 +44,7 @@ import { VARIANT_DIRECTIONS, RANKING_BASES } from "../../blind-frame-model.mjs";
 import { recordSkeptic } from "../../skeptic-record.mjs";
 import { recordFrameDiff } from "../../frame-diff-record.mjs";
 import { recordMatterFrame, INTAKE_ASK_OWNERS, SCOPE_BASES } from "../../matter-frame-record.mjs";
-import { recordPrelimVariants, SCOPE_LAYERS, SCOPE_STATUS } from "../../prelim-variants-record.mjs";
+import { recordClearanceVariants, SCOPE_LAYERS, SCOPE_STATUS } from "../../clearance-variants-record.mjs";
 import { recordReportOverview } from "../../report-overview-record.mjs";
 import { recordReportCard } from "../../report-card-record.mjs";      // conversion 5 — the fan-out transport
 import { recordRefutation, REVIEW_VERDICTS } from "../../narrative-refutation-record.mjs";   // conversion 9
@@ -125,12 +125,12 @@ async function record_knockout_review(params) {
   return recordKnockoutReview(runDir, params);
 }
 
-async function record_prelim_variants(params) {
+async function record_clearance_variants(params) {
   const runDir = String(process.env.CLEAROTRON_BAND_RUN_DIR ?? "");
   if (!runDir) {
     return { error: "this server was started without a run — the driver wires it per run; there is no parameter for it and this tool never guesses one" };
   }
-  return recordPrelimVariants(runDir, params);
+  return recordClearanceVariants(runDir, params);
 }
 
 async function record_report_card(params) {
@@ -444,7 +444,7 @@ serve({
     //
     // `scope_ledger` is the one genuinely new field, and it is what deletes a derivation: those rows used
     // to reach the driver only by re-parsing a markdown table out of the prose manifest.
-    name: "record_prelim_variants",
+    name: "record_clearance_variants",
     description:
       "Hand back the variant manifest as VALUES. The driver serialises variant-manifest.json, renders " +
       "variant-manifest.md and writes scope-ledger.json from what you send, so you never format JSON, " +
@@ -516,7 +516,7 @@ serve({
       },
     },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    handler: record_prelim_variants,
+    handler: record_clearance_variants,
   }, {
     // ── CONVERSION 4 — THE REPORT SHELL, AND THE FIRST ARTIFACT A CLIENT READS ────────────────────
     //
@@ -627,6 +627,19 @@ serve({
             },
           },
         },
+        batch: {
+          type: "integer",
+          minimum: 1,
+          description:
+            "The batch of records this call accounts for, when the dispatch splits the band into " +
+            "batches. Send one call per batch, carrying its number. Every record in THAT batch must end " +
+            "in this call — a findings row, an incumbent row, a Negative-results drop, or a " +
+            "Disagreement resolution — and the call is refused naming any that end nowhere; the records " +
+            "in every other batch are not this call's business. A batch call MERGES onto what you have " +
+            "already recorded, so earlier batches are kept without re-sending them, and a record ended " +
+            "under one batch cannot be ended again under another. Omit it only when you are sending the " +
+            "whole band in one call, which the dispatch tells you when it is.",
+        },
         patch: {
           type: "boolean",
           description: