clearotron 0.3.2-beta.6 → 0.3.2-beta.8

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/recording-server.mjs

@@ -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:

package/driver/engine/openai-agent.mjs

@@ -29,9 +29,11 @@ import { join } from "node:path";
 import { runStreamingChild, absolutizeSkillRefs, WRITE_DISCIPLINE, buildEnvelope, resolveSpawnCwd } from "./common.mjs";
 import { renderCodexConfigToml } from "./mcp/codex-config.mjs";
 import { resolveAuthMode } from "./auth.mjs";
-import { envFrom } from "../../shared/env-aliases.mjs";   // — advice names the name in force
+import { resolveEngineProgram } from "../driver.config.mjs";   // — the one place that finds the program; it reads every spelling of the setting
 
-const codexBin = () => envFrom(process.env, "CLEAROTRON_CODEX_PATH") || "codex";
+// The same one resolver as the claude adapter (driver.config.mjs resolveEngineProgram), for the same reason:
+// the absolute path it found, or what was asked for when it found nothing.
+const codexBin = () => { const r = resolveEngineProgram("openai-agent"); return r.resolved ?? r.bin; };
 
 // tier/alias → codex `-m` model id. opus/sonnet/haiku are the driver's abstract tiers (CONTRACT §3). The
 // GPT ids are ENV-OVERRIDABLE and default to three DISTINCT rungs of the codex ladder — `gpt-5.6-sol`,