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

package/bin/start.mjs

@@ -84,8 +84,10 @@ import { writeSecretFile } from "../shared/secret-file.mjs";   // one atomic wri
 // below: to COMPOSE the units' environment and to GUARD it before this command reports success. The
 // tables are handed in rather than imported by it, because the register table lives in a CLI entry and
 // the driver must not point at `bin/`.
-import { runRequiredNames, missingRequirements } from "../driver/run-requirements.mjs";
-import { ENGINE_BINARIES, DEFAULT_ENGINE_ID as RUN_DEFAULT_ENGINE } from "../driver/driver.config.mjs";
+import { runRequiredNames, missingRequirements, CLOUD_ROUTES } from "../driver/run-requirements.mjs";
+import { CLOUD_SWITCH, cloudsSwitchedOn } from "../driver/engine/auth.mjs";   // a switch compared the way the program reads it: on or off
+import { ENGINE_BINARIES, DEFAULT_ENGINE_ID as RUN_DEFAULT_ENGINE, resolveEngineProgram } from "../driver/driver.config.mjs";
+import { unitEnvironment, unitValue } from "../driver/unit-environment.mjs";   // the PATH the worker unit will run with, read the way doctor reads it
 
 /**
  * The tables the requirements authority needs — resolved at CALL time, never at module scope.
@@ -104,9 +106,9 @@ import { ENGINE_BINARIES, DEFAULT_ENGINE_ID as RUN_DEFAULT_ENGINE } from "../dri
  * driver/test/a-backgrounded-install-can-actually-run-a-clearance.test.mjs refuses a static import of
  * onboard from this file, so the cycle cannot come back quietly.
  */
-async function runTables() {
+export async function runTables() {
   const { PROVIDERS } = await import("./onboard.mjs");
-  return { registers: PROVIDERS, engines: ENGINE_BINARIES, defaultEngine: RUN_DEFAULT_ENGINE };
+  return { registers: PROVIDERS, engines: ENGINE_BINARIES, defaultEngine: RUN_DEFAULT_ENGINE, resolveEngine: resolveEngineProgram };
 }
 import { spawn, spawnSync, execFileSync } from "node:child_process";
 import { storeInRepo, storeOutsideRepoMessage, storeCommitRefusal } from "../shared/store-in-repo.mjs";   //
@@ -188,6 +190,89 @@ export function homeEnvUpdate(homeText, union) {
   return mergeEnvFile(homeText, union, { refresh: LAUNCHER_MINTED });
 }
 
+/**
+ * The services' settings file as this start will leave it, and the run's settings in it that differ from
+ * the configuration this command holds. PURE, and the one reading `--background` uses for both its guard
+ * and its write, so a test drives start's own answer rather than a copy of it.
+ *
+ * THE GUARD CHECKED A MERGE THE FILE DOES NOT PERFORM. It read `{ ...file, ...union }`, where this
+ * command's value wins, while the add-only merge keeps the file's line, an empty one included. So a file
+ * holding `CLAUDE_CODE_USE_FOUNDRY=` passed the guard on this command's `=1`, kept its empty line, and
+ * every search was refused at the order wall. `reads` is the merged text, parsed: what the units read.
+ *
+ * AND WHAT THE FILE KEEPS IS SAID, never replaced. The merge adds only what the file lacks, and that is
+ * deliberate: the file is the running product's configuration, an operator edits it to change what the
+ * services do, and a start that rewrote it from this command's configuration would undo that edit. What
+ * was wrong was the silence. A machine moved from one cloud to another, or holding a rotated key, started
+ * again and reported the file complete while the services kept the old account.
+ * `differ` names the run settings on which the two disagree, so start can say which. Names only, never a
+ * value.
+ *
+ * WHICH DISAGREEMENTS, BY THE KIND OF SETTING, and never by which side holds the value. A healthy install
+ * can keep its register key, its engine's path and its research key in the units' file alone, because
+ * that file is where start tells an operator to change what the services use; this command's shell then
+ * holds none of them, and naming them on every start would warn about a working install. So a setting
+ * counts only when this command holds a value the file contradicts: a rotated key, or a line kept empty.
+ * The billing word and the settings that pick a cloud are the exception, and count in either direction,
+ * because the file holding one this command does not is exactly the machine billing an account nobody
+ * chose any more. They are compared as the program reads them: an unset billing word is the subscription,
+ * and a switch is on or off, so `1` beside `true` is not a difference.
+ *
+ * BUT ONLY WHERE THIS COMMAND HOLDS AN OPINION. A configuration that sets no billing word says nothing
+ * about how the services pay: an api-key, Codex api-key or cloud install whose billing lives in the units'
+ * file alone, where start's own remedy offers to put it, was warned about its billing word and its switch
+ * on every start. So with no billing word here, neither the word nor the cloud settings are compared. Under
+ * `cloud` with no cloud named here, which cloud is not compared either. And under `subscription` or
+ * `api-key` a cloud setting this command holds counts as unset, because the run door refuses a switch
+ * beside either word and start never carries one: naming it sent the operator to put into the file a
+ * switch every search would then be refused over. A cloud the FILE holds under those words still counts.
+ */
+export function unitsFileAfterStart(homeText, union, { config = {}, tables = {} } = {}) {
+  const merged = homeEnvUpdate(homeText, union);
+  const reads = parseEnvFile(merged.text);
+  const ours = (k) => String(union[k] ?? config[k] ?? "").trim();
+  const theirs = (k) => String(reads[k] ?? "").trim();
+  const words = new Set(Object.values(tables.engines ?? {}).map((e) => e?.authEnv).filter(Boolean));
+  const switches = Object.values(CLOUD_SWITCH);
+  const as = (k, v) => words.has(k) ? (v.toLowerCase() || "subscription")
+    : switches.includes(k) ? cloudsSwitchedOn({ [k]: v }).length > 0 : v;
+  const ourWord = ([...words].map(ours).find(Boolean) ?? "").toLowerCase();
+  const ourRoutes = Object.fromEntries(CLOUD_ROUTES.map((k) => [k, ours(k)]));
+  const ourCloud = cloudsSwitchedOn(ourRoutes).length > 0 || ourRoutes.ANTHROPIC_BASE_URL !== "";
+  const route = (k) => CLOUD_ROUTES.includes(k);
+  const opinion = (k) => ourWord !== "" && (!route(k) || ourWord !== "cloud" || ourCloud);
+  const oursAs = (k) => as(k, route(k) && ourWord !== "cloud" ? "" : ours(k));
+  const eitherWay = (k) => words.has(k) || route(k);
+  const names = new Set([...runRequiredNames(config, tables), ...runRequiredNames(reads, tables), ...CLOUD_ROUTES]);
+  const differ = [...names].filter((k) => !LAUNCHER_MINTED.includes(k)
+    && (eitherWay(k) ? opinion(k) && oursAs(k) !== as(k, theirs(k)) : ours(k) !== "" && ours(k) !== theirs(k)));
+  return { merged, reads, differ };
+}
+
+/**
+ * What start says about `differ`, the settings on which the units' file and this command's configuration
+ * disagree. PURE, so the words are driven rather than read from source. Names only, never a value.
+ *
+ * BOTH PLACES, because the add-only merge makes one of them a trap. This said to edit the units' file and
+ * restart. An operator who moved the services from one cloud to another that way, with this command's
+ * configuration still naming the first, had the first cloud's switch added back on the next start, since
+ * the file no longer held its line: two clouds on, and every search refused. Deleting that line, as the
+ * notice said, only repeated it. So it names the file the units read and the configuration start adds from,
+ * `cliEnv` (envFileRead(), or null when this command read no file and its shell is the configuration).
+ */
+export function keptSettingsNotice(differ, { homeEnv, cliEnv = null } = {}) {
+  if (!differ?.length) return [];
+  const one = differ.length === 1;
+  return [
+    `  ⚠ ${homeEnv} and this command's configuration differ on ${one ? "this setting" : "these settings"}, and the units use what the file says:`,
+    `      ${differ.join(", ")}`,
+    `    This command only adds a setting the file has no line for; it never replaces one. To change what the units`,
+    `    use, change ${one ? "it" : "them"} in both places, then restart them:`,
+    `      ${homeEnv}\n          the file the units read`,
+    `      ${cliEnv ?? "this command's environment"}\n          what this command adds from: a line the file above lacks is added back from here on the next start`,
+  ];
+}
+
 /**
  * What a `--background` run has ALREADY DONE when systemd refuses to enable a unit.
  *
@@ -1709,22 +1794,19 @@ if (isMain) {
     // said everything was fine, and a lawyer's search that died at its first stage with a stack trace,
     // delivering "nothing was delivered. Clearotron has been notified" on a box that notified nobody.
     //
-    // CHECKED AGAINST `union`, WHICH IS WHAT THE FILE WILL SAY — plus what the file ALREADY says, since
-    // `mergeEnvFile` is add-only and an operator's existing line wins. Checking `process.env` here would
+    // CHECKED AGAINST WHAT THE FILE WILL SAY: the file's own lines, with `union` added where the file has
+    // no line, because `mergeEnvFile` is add-only and an existing line wins, an empty one included. That
+    // is `unitsFileAfterStart`, the same reading the write below uses. Checking `process.env` here would
     // measure this shell rather than the units, and pass on exactly the box that fails.
+    let homeText = "";
+    try { homeText = readFileSync(HOME_ENV, "utf8"); } catch (e) { if (e.code !== "ENOENT") fatal(`${HOME_ENV} exists but could not be read (${e.code}).`); }
+    const unitsFile = unitsFileAfterStart(homeText, union, { config: process.env, tables: RUN_TABLES });
     //
     // BLOCKING REFUSES; NARROWING IS SAID OUT LOUD AND STARTS ANYWAY. A research key this box does not
     // hold means the three clearance searches refuse at preflight and a Knockout search still runs and
     // discloses what it skipped — so refusing to start over it would take a box that can serve a real
     // product and make it serve none. The operator is told which products this install can fill.
     {
-      const already = {};
-      try {
-        for (const line of readFileSync(HOME_ENV, "utf8").split("\n")) {
-          const m = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/.exec(line);
-          if (m) already[m[1]] = m[2];
-        }
-      } catch { /* no file yet — the union is the whole of it */ }
       // ONE COMPOSER for "where do I set these", used by the start-time refusal and by the order-time
       // announcement below it. Two copies of this sentence is how one of them comes to name a file the
       // reader cannot use.
@@ -1739,7 +1821,29 @@ if (isMain) {
           : `Set them in ${homeEnv} — the file the units read. This command read no environment file of `
             + `its own, so that is the address. \`${invoke("install")}\` writes them for you IN A TERMINAL.`;
       };
-      const willRead = { ...already, ...union };
+      const willRead = { ...unitsFile.reads };
+      // ── AND THE PATH THE WORKER WILL SEARCH FOR THE ENGINE'S PROGRAM ─────────────────────────────
+      //
+      // The check asks the engine resolver, and a resolver handed no PATH finds only a path setting or
+      // the copy setup installed. So a `claude` on the units' PATH was announced as "every run is
+      // refused", and the run found it and ran. The PATH is the worker unit's own, read from the file
+      // placed below: the worker runs the clearance, and every shipped unit sets
+      // `Environment=PATH=%h/…`, which the unit reader expands to this home. Never this shell's PATH,
+      // which the units do not inherit.
+      //
+      // THE SETTINGS FILE IS READ WITH IT, because on systemd a PATH in that file wins over the unit's own
+      // `Environment=PATH=` line, wherever the two lines sit (systemd.exec(5)), and the unit reader
+      // applies that rule. Nothing Clearotron writes puts a PATH there, but a hand-edited file can, and
+      // then the worker searches that PATH and not the unit's. A file that is not there yet reads as
+      // empty: this command is about to write it, and the unit's PATH is then the one in force.
+      {
+        let text = null;
+        try { text = readFileSync(join(REPO, "driver", "systemd", "clearotron-worker.service"), "utf8"); } catch { /* the install loop below names a missing unit */ }
+        const settingsFile = (p) => { if (p !== HOME_ENV) return ""; try { return readFileSync(p, "utf8"); } catch { return ""; } };
+        const workerPath = unitValue(unitEnvironment({ units: [{ name: "clearotron-worker.service", text }],
+          readEnvFile: settingsFile, home: homedir() }), "PATH").value;
+        if (workerPath) willRead.PATH = workerPath;
+      }
       const miss = missingRequirements(willRead, RUN_TABLES);
       // ── — WHICH HALF OF `blocking` MAY REFUSE A START ─────────────────────────
       //
@@ -1769,9 +1873,9 @@ if (isMain) {
         //
         // BOTH FILES, and that is the difference from the port refusals, which say `~/.env` "is NOT read
         // here". They are right: nothing in that file reaches a port decision. Here both are true. The
-        // block above reads HOME_ENV into `already` and merges it into `willRead`, so a value set there
-        // satisfies this check on the next run; and the CLI's own file reaches it too, through the
-        // `runRequiredNames(process.env, …)` loop that copies its values into `union`. Driven rather than
+        // block above reads HOME_ENV into `willRead`, with its lines winning as they do in the file, so a
+        // value set there satisfies this check on the next run; and the CLI's own file reaches it too,
+        // through the `runRequiredNames(process.env, …)` loop that copies its values into `union`. Driven rather than
         // read: three blocking names cleared from the CLI's file alone, and the refusal came back naming
         // a fourth that the first three had newly required.
         //
@@ -1817,26 +1921,32 @@ if (isMain) {
         // it"), not about which gate happened to print it, and the arms in
         // `a-refusal-names-the-file-when-the-command-it-offers-cannot-be-run.test.mjs` measure it here now.
         //
-        // BOTH FILES, because both genuinely reach the check: `~/.env` is merged into `already` above,
-        // and this command's own file reaches it through the carry loop. `envFileRead()` for the second,
-        // never a path composed here — null means this process read no file of its own (a systemd start,
+        // BOTH FILES, because both genuinely reach the check: `~/.env` is read into `willRead` above,
+        // and this command's own file reaches it through the carry loop where `~/.env` has no line.
+        // `envFileRead()` for the second, never a path composed here — null means this process read no file of its own (a systemd start,
         // or CLEAROTRON_NO_ENV_FILE=1) and then HOME_ENV is the only honest address there is.
         say(`    Nothing has been installed that cannot run, and nothing has been spent.`);
         say(`    ${orderRemedy(HOME_ENV)}`);
       }
       for (const r of miss.narrowing)
         say(`  ⚠ ${r.name} is not set — ${r.why}`);
+      // ── WHAT THE FILE KEEPS, SAID BY NAME ──────────────────────────────────────────────────────────
+      //
+      // The merge never replaces a line (see `unitsFileAfterStart`), so a setting changed in this
+      // command's configuration after the first start does not reach the units. A machine moved from one
+      // cloud to another went on billing the first, and a rotated key stayed at its first value, while this
+      // command reported the file complete. Said here, by name and never by value, naming both places the
+      // setting lives (see `keptSettingsNotice` for why one is not enough).
+      for (const line of keptSettingsNotice(unitsFile.differ, { homeEnv: HOME_ENV, cliEnv: envFileRead() })) say(line);
     }
 
-    let homeText = "";
-    try { homeText = readFileSync(HOME_ENV, "utf8"); } catch (e) { if (e.code !== "ENOENT") fatal(`${HOME_ENV} exists but could not be read (${e.code}).`); }
     // THE TRIGGER KEY IS MINTED HERE, SO IT IS REWRITTEN HERE. Everything else in this union is
     // collected — the operator's credentials, their paths — and add-only is what stops a launcher from
     // losing them. The trigger key is the opposite: this process mints it, thirty days at a time, and a
     // value written once and never again runs down to expiry on a server nobody has touched. When it
     // lapses every Start stops, and the failure arrives as an upstream refusal that reads like an engine
     // fault rather than an expired key card.
-    const merged = homeEnvUpdate(homeText, union);
+    const { merged } = unitsFile;
     if (merged.added.length || merged.refreshed.length) {
       writeSecretFile(HOME_ENV, merged.text);
       const parts = [];

package/bin/update.mjs

@@ -51,7 +51,7 @@ import { existsSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { config } from "../driver/driver.config.mjs";
+import { config, ENGINE_BINARIES, enginesFolder, engineInstallArgs } from "../driver/driver.config.mjs";
 import { isInsideCheckout } from "../shared/inside-checkout.mjs";   // — one copy of the rule
 import { overlayReport, renderOverlayReport, treeFiles } from "../shared/doctrine-overlay.mjs";
 import { liveRunHolds } from "../driver/deploy-live-run-guard.mjs";   // — one live-run test, shared with deploy-preflight
@@ -180,6 +180,34 @@ export function isGitCheckout(repo = REPO, exists = existsSync) {
   return exists(join(repo, ".git"));
 }
 
+/**
+ * The engine programs setup installed for this user, which `clearotron update` refreshes: every engine
+ * whose package is in the engines folder. Setup installs only the one the reader chose, so this is usually
+ * one, and none where the machine's own copy was found first or the reader declined the install.
+ */
+export function enginesToRefresh({ dir = enginesFolder(), exists = existsSync } = {}) {
+  return Object.values(ENGINE_BINARIES)
+    .filter((e) => e.package && exists(join(dir, "node_modules", ...e.package.split("/"), "package.json")));
+}
+
+/**
+ * Run setup's install again for each of them, in the same folder. The same command, because re-running an
+ * install with a `>=` range moves the program to the newest its vendor publishes (driver.config.mjs, above
+ * engineInstallArgs). Returns 0, or the first failing exit code.
+ */
+function refreshEngines(engines, dir = enginesFolder()) {
+  if (!engines.length) return 0;
+  say(`\n  Refreshing the engine program Clearotron installed in ${dir}.`);
+  for (const e of engines) {
+    const rc = runInCheckout("npm", engineInstallArgs(e, dir));
+    if (rc !== 0) {
+      console.error(`\n  npm could not refresh ${e.package}. \`clearotron doctor\` says which copy a run would use now.`);
+      return rc;
+    }
+  }
+  return 0;
+}
+
 function runInCheckout(cmd, args) {
   say(`\n  $ ${cmd} ${args.join(" ")}`);
   const r = spawnSync(cmd, args, { cwd: REPO, stdio: "inherit" });
@@ -301,22 +329,38 @@ export async function update(argv = process.argv.slice(2)) {
   }
 
   if (packaged) {
+    // ONE NPM RUN, WITH THE LAUNCHER PUT BACK AFTER IT, and both branches below install through it, so
+    // neither can run npm and forget the second half. npm puts its own link back at
+    // `<prefix>/bin/clearotron` on every install, over the launcher the install wrote, and that link runs
+    // whichever `node` is first on PATH. Put the launcher back, but only over npm's link or our own:
+    // anything else there was not ours before this update either.
+    const reinstall = () => {
+      const rc = runInCheckout("npm", packaged.npmArgs);
+      if (rc !== 0) return rc;
+      const kind = inspectShim(shimPath()).kind;
+      if (kind === "npm-link" || kind === "ours" || kind === "ours-other-install") {
+        const shim = installShim();
+        if (!shim.ok) console.error(`\n  The update worked, but the launcher at ${shim.path ?? "~/.local/bin/clearotron"} could not be written back: ${shim.detail}.`);
+      }
+      return 0;
+    };
     if (packaged.current) {
-      say(`\n  This install is ${packaged.installed}, and nothing newer is published (${packaged.tag}: ${packaged.version}). Nothing was touched.\n`);
+      say(`\n  This install is ${packaged.installed}, and nothing newer is published (${packaged.tag}: ${packaged.version}).`);
+      // CURRENT STILL REFRESHES THE ENGINE PROGRAM setup installed: it moves on its vendor's schedule, not
+      // this package's. A machine's own copy on PATH updates itself and is used first.
+      const engines = enginesToRefresh();
+      if (!engines.length) { say("  Nothing was touched.\n"); return 0; }
+      const rc = refreshEngines(engines);
+      if (rc !== 0) return rc;
+      say("\n  Clearotron itself was already current; restart the services so they use the refreshed program.\n");
       return 0;
     }
     if (packaged.unread) say(`\n  npm did not say which versions are published, so this follows the ${packaged.tag} channel.`);
     say(`\n  Updating this install at ${packaged.prefix} from ${packaged.installed ?? "an unreadable version"} to clearotron@${packaged.spec}.`);
-    const rc = runInCheckout("npm", packaged.npmArgs);
+    const rc = reinstall();
     if (rc !== 0) return rc;
-    // npm puts its own link back at `<prefix>/bin/clearotron` on every install, over the launcher the
-    // install wrote, and that link runs whichever `node` is first on PATH. Put the launcher back, but only
-    // over npm's link or our own: anything else there was not ours before this update either.
-    const kind = inspectShim(shimPath()).kind;
-    if (kind === "npm-link" || kind === "ours" || kind === "ours-other-install") {
-      const shim = installShim();
-      if (!shim.ok) console.error(`\n  The update worked, but the launcher at ${shim.path ?? "~/.local/bin/clearotron"} could not be written back: ${shim.detail}.`);
-    }
+    const refreshed = refreshEngines(enginesToRefresh());
+    if (refreshed !== 0) return refreshed;
     say("\n  Updated. An assistant starts the new version the next time it launches Clearotron; restart the services for the portal.\n");
     return 0;
   }
@@ -346,6 +390,30 @@ export async function update(argv = process.argv.slice(2)) {
     return installed;
   }
 
+  // ── AND THE STAMP THE PULL CANNOT MOVE ─────────────────────────────────────────────────────────────
+  //
+  // `build-info.json` names the commit an archive was packed from. It is written by `prepack`, which this
+  // route never runs, and it is untracked, so the pull above cannot bring it forward either. A checkout
+  // that was ever packed by hand keeps whatever that pack wrote, and the file then ages while the tree
+  // moves: measured on the test box 2026-09-16, it named a commit five days and two minor versions behind
+  // the tree it was sitting in.
+  //
+  // NOTHING THE PRODUCT READS IS FOOLED BY IT, which is why this stamps rather than refuses. `engineCommit`
+  // takes git first and never lets a packed stamp override a live checkout, so no run has been
+  // misattributed and no client has seen a wrong version. The reader it misleads is a person — checking on
+  // the box which build is deployed, answered confidently and wrongly, with nothing on the file to say it
+  // is stale. This verb is what moves the commit on this route, so it is the cheapest place to keep the
+  // answer true.
+  //
+  // A failure here does not fail the update. The code and its dependencies are already correct, and
+  // reporting a half-done deploy because a note could not be rewritten would be the louder lie.
+  const stamped = runInCheckout("node", ["scripts/write-build-info.mjs"]);
+  if (stamped !== 0) {
+    console.error("\n  The update succeeded, but build-info.json could not be re-stamped. A reader of that");
+    console.error("  file on this box would be told the commit of an earlier pack rather than this one.");
+    console.error("  What this install RUNS is unaffected — that is named from the checkout itself.\n");
+  }
+
   // ── THE BUNDLE THE PULL COULD NOT UPDATE ─────────────────────────────────────────────────────────
   //
   // `portal-ui/dist` is untracked on the public tree, so `git pull` above can never bring it forward.
@@ -369,6 +437,9 @@ export async function update(argv = process.argv.slice(2)) {
     console.error(`  the custom instructions could not be read — ${e.message}`);
   }
 
+  const refreshed = refreshEngines(enginesToRefresh());
+  if (refreshed !== 0) return refreshed;
+
   say("\n  Up to date.\n");
   return 0;
 }

package/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "91905bd9b7ffd04985537f799d2ef49359e3d0e6",
-  "version": "0.3.2-beta.6"
+  "commit": "7596846c65b0bd1a4dcc291732803da5fa8e9ccb",
+  "version": "0.3.2-beta.8"
 }

package/docs/architecture/04-configuration-reference.md

@@ -29,7 +29,7 @@ time, so all of them honour a mid-process env flip — the file's own NOTE besid
 `./driver.config.mjs` resolves to ONE cached module instance across the offline test fleet, so
 import-time captures silently pinned every test to the first test's env. What IS frozen at first import
 is the module-level declarations beside it — the consts `REGISTER_PROVIDER` and
-`UNREACHABLE_SENIOR_POLICY`, and `MODELS.azure`, a plain property reading `CLEAROTRON_AZURE_MODEL`.
+`UNREACHABLE_SENIOR_POLICY`.
 Because the driver runs as a systemd **oneshot** (a fresh process per activation), editing the
 deployment's `.env` takes effect on the next queue-triggered run with no deploy and no restart — that is the
 supported way to change caps and A/B toggles. One trap: `synthesis.model` reads
@@ -130,17 +130,22 @@ through anything containing `/`):
 | gemini | `google/gemini-3.1-pro-preview` |
 | gemini-flash | `google/gemini-3-flash-preview` |
 | deepseek-v4-pro | `together/deepseek-ai/DeepSeek-V4-Pro` |
-| azure | `CLEAROTRON_AZURE_MODEL` (default `azure-openai/gpt-5.4`) |
+| azure | `azure-openai/gpt-5.4` |
 
 The bottom four are **legacy names that no stage declares and no engine can run** — they resolve at
 level 1 and then throw at level 2 (below). They are catalogue entries, not available tiers.
 
 **Level 2 — the active engine** maps aliases to the CLI's own model names. On `anthropic-agent`
-(`CLAUDE_MODEL` in `engine/anthropic-agent.mjs`): **opus and sonnet are pinned** to `claude-opus-5`
-and `claude-sonnet-5` so neither drifts with what the CLI currently calls "opus"/"sonnet"; `haiku`
-and `fable` pass through as aliases. A bare or dated Anthropic id (`claude-haiku-4-5-20251001`)
-still resolves to its family — that is a naming form of a model the CLI can run, not a substitution
-of a different one.
+(`CLAUDE_MODEL` in `engine/anthropic-agent.mjs`): `opus`, `sonnet`, `haiku` and `fable` pass through
+as aliases, so each tier follows the vendor's newest model; to hold one still, set
+`ANTHROPIC_DEFAULT_OPUS_MODEL` (or `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`,
+`ANTHROPIC_DEFAULT_FABLE_MODEL`).
+The catalog ids `anthropic/claude-opus-5` and `anthropic/claude-sonnet-5` are passed as those
+concrete models; `anthropic/claude-haiku-4-5` goes over as the `haiku` alias, so it follows the
+vendor the same way. A bare or dated Anthropic id (`claude-haiku-4-5-20251001`) still resolves to
+its family — that is a naming form of a model the CLI can run, not a substitution of a different
+one. Telemetry keeps the level-1 catalog id as the model asked for, and the attempt row records the
+id the program reports it served.
 
 **Anything else throws.** There is no regex fall-through to sonnet and no cross-provider
 substitution: the `gemini`/`gemini-flash`/`deepseek-v4-pro`/`azure` mappings are gone with the
@@ -170,8 +175,8 @@ timeout shot, warm patch, backoff), the lane-wedge re-dispatch, and the rate-lim
 | Setting | Values | Effect |
 |---|---|---|
 | `CLEAROTRON_AI` | `anthropic-agent` (default) \| `openai-agent` | Compute engine (a registered provider adapter). `anthropic-agent` = `claude -p`; `openai-agent` = `codex exec` (both off-gateway, same normalized contract). An **unregistered** value — a typo, or the gateway-runtime adapter removed in the extraction — **fails loud**: no silent wrong-provider run. Production default is unchanged. |
-| `CLEAROTRON_AI_BILLING` | `subscription` (default) \| `api-key` | Billing mode for the selected engine. ONE variable for both, and only the LIVE engine's setting is read — it fills each engine's billing knob, and the engine that is not selected is never consulted. **`anthropic-agent`:** subscription **deletes `ANTHROPIC_API_KEY` from the child env** so `claude -p` uses OAuth subscription credentials (a present key would override them); `api-key` keeps the key — the scale setting and standing fallback. **`openai-agent`:** subscription seeds `auth.json` into the per-run `CODEX_HOME` from `CLEAROTRON_OPENAI_AUTH_FILE` (default `~/.codex/auth.json`) and strips API keys; `api-key` keeps `CODEX_API_KEY`. **Fail-loud either way:** `api-key` with no `ANTHROPIC_API_KEY` / `CODEX_API_KEY` throws, and never silently bills the subscription. The resolved mode is stamped on every stage telemetry row (`engine`, `authMode`, `apiBilled`). |
-| `CLEAROTRON_CLAUDE_PATH` · `CLEAROTRON_CODEX_PATH` | `claude` / `codex` on `PATH` | The engine binary to spawn, ONE PER ENGINE: `CLEAROTRON_CLAUDE_PATH` under `anthropic-agent`, `CLEAROTRON_CODEX_PATH` under `openai-agent`. Only the live engine's is read, and a box that runs both sets both — they were one variable until it met a box needing two different paths. Give it an **absolute** path if the binary is not on `PATH` — stage subprocesses run with cwd set to the run directory, so a relative path does not resolve there, and `npx clearotron doctor` refuses one. |
+| `CLEAROTRON_AI_BILLING` | `subscription` (default) \| `api-key` \| `cloud` | Billing mode for the selected engine. ONE variable for both, and only the LIVE engine's setting is read — it fills each engine's billing knob, and the engine that is not selected is never consulted. **`anthropic-agent`:** subscription **deletes `ANTHROPIC_API_KEY` from the child env** so `claude -p` uses OAuth subscription credentials (a present key would override them); `api-key` keeps the key — the scale setting and standing fallback; **`cloud`** bills Claude per use through the reader's own cloud account, named by the Claude program's own switch — `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY` or `CLAUDE_CODE_USE_BEDROCK`, or `ANTHROPIC_BASE_URL` alone for a gateway (see the credentials table below) — and deletes `ANTHROPIC_API_KEY` as subscription does. **`openai-agent`:** subscription seeds `auth.json` into the per-run `CODEX_HOME` from `CLEAROTRON_OPENAI_AUTH_FILE` (default `~/.codex/auth.json`) and strips API keys; `api-key` keeps `CODEX_API_KEY`; `cloud` is refused. **Fail-loud, never a guess, never the subscription in its place:** `api-key` with no `ANTHROPIC_API_KEY` / `CODEX_API_KEY` throws; on `anthropic-agent`, `cloud` with two switches on, or with none and no `ANTHROPIC_BASE_URL`, throws, and so does a switch left on under `subscription` or `api-key`, because the program bills that cloud whatever this says; a value that is none of the three throws on both engines. `clearotron start` and `clearotron doctor` report each refusal against the settings the services read, naming a value that is not a billing mode by its setting and never quoting it, and the runner refuses the search when it is ordered, before anything is spent. The resolved mode is stamped on every stage telemetry row (`engine`, `authMode`, `apiBilled`, and `cloud`, null when no cloud bills), and the attempt row also carries `providerReported`, the program's own word for who served the turn. |
+| `CLEAROTRON_CLAUDE_PATH` · `CLEAROTRON_CODEX_PATH` | `claude` / `codex` on `PATH`, then the copy Clearotron installed | The engine binary to spawn, ONE PER ENGINE: `CLEAROTRON_CLAUDE_PATH` under `anthropic-agent`, `CLEAROTRON_CODEX_PATH` under `openai-agent`. Only the live engine's is read, and a machine that runs both sets both — they were one variable until it met a machine needing two different paths. A path set here must be **absolute**: stage subprocesses run with cwd set to the run directory, so a relative path does not resolve there, and `npx clearotron doctor` refuses one. **Unset**, or set to the bare word `claude` / `codex` (which means the same), the engine uses the program on `PATH` when the machine has one, and otherwise the copy Clearotron installed in `~/.local/share/clearotron/engines`: `clearotron install` offers to put the chosen engine's program there (`@anthropic-ai/claude-code` or `@openai/codex`, this platform's build only), and `clearotron update` refreshes it. Nothing is bundled into the package. A value naming anything else is used as given and never falls back. `clearotron doctor` says which copy it found, and its version when npm installed that copy. |
 | `CLEAROTRON_OPENAI_AUTH_FILE` | `~/.codex/auth.json` | The credentials file seeded into the per-run `CODEX_HOME` under subscription billing. Was exempted from the August 2026 rename as an `openai-agent` internal rather than an install-surface name; the owner's 2026-09-04 ruling **reversed that exemption** and renamed the whole namespace, so it carries the house prefix like everything else. One spelling, no exceptions. |
 | `CLEAROTRON_OPENAI_MODEL_JUDGMENT` / `CLEAROTRON_OPENAI_MODEL_SWEEP` / `CLEAROTRON_OPENAI_MODEL_CHEAP` | `gpt-5.6-sol` / `gpt-5.6-terra` / `gpt-5.6-luna`. | Maps the driver's abstract `opus`/`sonnet`/`haiku` tiers onto the codex ladder, the way the anthropic engine maps onto its own (ruling 2026-09-02, superseding the single-model mapping). A tier that cannot hold its stage contract announces itself at that stage — `missing:negative-results`, `no_coverage_status_row`, `named_band_missing` in `_driver/<stage>.jsonl` — not at delivery. |
 | ↳ why they are three, and what the old measurement still says | superseded 2026-09-02, not erased | The three defaulted to `sol` alone on a MEASUREMENT, never a placeholder: on 2026-08-11/12, with `SWEEP=gpt-5.6-terra` / `CHEAP=gpt-5.6-luna`, every codex clearance died on structural-output gates — `missing:negative-results`, `no_coverage_status_row`, `named_band_missing` — over 2 scenarios × 3 stage families, **byte-identically on retry**, so no retry budget rescued it. That measurement stands for the code and the codex CLI **of that date**, and it is why the judgment tier keeps `sol`. Three weeks of stage-contract work and several codex minor versions sit between it and the 2026-09-02 ruling that split the three. **The symptom to match against this cause is unchanged**: those same three gates, as a fail row in`_driver/<stage>.jsonl`, inside the first few dispatches of a clearance and identical on every retry — a model incapable of a contract is not flaky at it. It reads as an engine bug when the only fault is this configuration. A cheap-tier experiment still belongs in the three constants in `driver/engine/openai-agent.mjs` where a reviewer sees it, not in an untraceable env line. |
@@ -207,6 +212,7 @@ deployment may override (verify live values per deployment).
 | `USPTO_LOCAL_DB` | **none — set it to use `uspto-local`** | The local USPTO index (`node:sqlite` + FTS5) that `bin/uspto-sync.mjs` builds and the free US register reads. Named in `.env.example`; this is the reference row. |
 | `CLEAROTRON_JX_SUBCLASS_DB` | unset ⇒ the lane refuses by name | Path to the built similar-group database the JX subclass lane reads, produced by `providers/jx-subclass/load-public.mjs` from the committed public tables. It names WHERE the table lives; what the table says is the build's. Absence is a refusal rather than an empty answer — a clearance that silently found no similar groups is indistinguishable from one where the file was missing. |
 | `CLEAROTRON_SUITE_TELEMETRY_DIR` | unset ⇒ the box's ledger | Redirects the provider telemetry ledger into a suite run's own temp root, so a suite never writes the box's ledger and never inherits it. Sits BELOW an explicitly-named ledger file: a test naming its own path is being deliberate, and this exists for the runs that name nothing. |
+| `CLEAROTRON_ENGINES_DIR` | unset ⇒ `~/.local/share/clearotron/engines` | The folder `clearotron install` installs the chosen engine's program into, `clearotron update` refreshes, and the engine resolver reads as its last step after the explicit setting and `PATH`: an npm project holding `node_modules/@anthropic-ai/claude-code` or `node_modules/@openai/codex`, where an empty directory means there is none. The test suite points it at an empty directory, so a test never reaches a program the developer's own setup installed. |
 | `FEEDBACK_GH_TOKEN` | unset ⇒ `gh`'s own auth | GitHub token for the unattended feedback minter (`scripts/feedback-mint.mjs`), for a service account with no `gh auth` login. Present ⇒ exported to `gh` as `GH_TOKEN` for that call only. A credential: it is not a placeholder value and must not be committed. |
 | `USPTO_API_KEY` | unset ⇒ the download path refuses | API key for the USPTO bulk download path in `bin/uspto-sync.mjs`. The INGEST path needs no key and says so; only the download half reads this. A credential. |
 
@@ -317,7 +323,13 @@ cannot be read as one list.
 
 | Var | Consumer |
 |---|---|
-| `ANTHROPIC_API_KEY` | Engine child env in `api-key` mode only (deleted in subscription mode). |
+| `ANTHROPIC_API_KEY` | Engine child env in `api-key` mode only (deleted in subscription and cloud modes). |
+| `CLAUDE_CODE_USE_VERTEX` / `CLAUDE_CODE_USE_FOUNDRY` / `CLAUDE_CODE_USE_BEDROCK` | **Read by the Claude program**, which sends every turn to that cloud; `1`, `true`, `yes` or `on` switches one on. Clearotron reads them to name the cloud under `CLEAROTRON_AI_BILLING=cloud` and to refuse a switch left on under `subscription` or `api-key`. Under `CLEAROTRON_AI_BILLING=cloud`, `clearotron start --background` carries the switch that is on, and every setting in the five rows below that is set, the model pins included, into `~/.env` (a switch that is set and not on stays behind); under `subscription` or `api-key` it carries none. It adds only a line `~/.env` lacks, and names any of these on which that file and its own configuration differ. A missing switch is reported by `clearotron start` and `clearotron doctor`, and refuses a search when it is ordered. Doctor and setup's proof turn carry these and the five rows below from the settings file a search reads, which is the one at the old location while an install is still configured there (`CLOUD_SETTINGS` in `driver/engine/auth.mjs`). A value in the shell wins over the file's: setup's proof turn keeps a blank one, as a run does, where doctor passes over it and takes the file's. In setup, an answer given wins over both. A run takes the whole file. |
+| `ANTHROPIC_VERTEX_PROJECT_ID` / `CLOUD_ML_REGION` / `GOOGLE_APPLICATION_CREDENTIALS` | Vertex AI's project, region and service-account key, read by the Claude program. Without the key file it uses gcloud's sign-in. |
+| `ANTHROPIC_FOUNDRY_RESOURCE` / `ANTHROPIC_FOUNDRY_API_KEY` | The Foundry resource and its key, read by the Claude program. Without the key it uses the machine's Azure sign-in. |
+| `AWS_REGION` / `AWS_PROFILE` / `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN` | Bedrock's region, optionally the AWS profile, and the standard AWS key variables (the session token only for temporary credentials), read by the Claude program. Without the keys it uses the machine's other AWS credentials, such as an instance role. |
+| `ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN` | A gateway in front of a cloud, and its token, read by the Claude program. With no cloud switch, `ANTHROPIC_BASE_URL` is the gateway form of `CLEAROTRON_AI_BILLING=cloud`; the gateway's credential must then be the token, because `ANTHROPIC_API_KEY` is deleted. |
+| `ANTHROPIC_DEFAULT_OPUS_MODEL` / `ANTHROPIC_DEFAULT_SONNET_MODEL` / `ANTHROPIC_DEFAULT_HAIKU_MODEL` / `ANTHROPIC_DEFAULT_FABLE_MODEL` | The model each tier's alias resolves to, read by the Claude program: on Foundry, the deployment names; anywhere, a way to hold a tier still. Set the fable one to your Fable deployment's name if you set `CLEAROTRON_SYNTHESIS_MODEL=fable`; setup does not ask for it. |
 | `OPENAI_API_KEY` | **Read only to be DELETED.** The `openai-agent` adapter strips it from the `codex exec` environment under subscription billing, so an unrelated key exported on the box cannot spoil a clean subscription bill. It is never the api-key credential for this product — that is `CODEX_API_KEY`. Listed because a reader who has one set needs to know it is removed. |
 | `CORSEARCH_SESSION_KEY` | Register provider auth (session cookie). **Preflighted at run start — a missing credential fails fast before any model spend.** |
 | `CLARIVATE_API_KEY` / `CLARIVATE_API_BASE` | Clarivate adapter — on the engine path: `clarivate-server.mjs` in `gather-config.mjs`'s stage-grant table, plus driver-side `recordFetch` / `countHits` / `listRecords` / `executePlan`. `CLARIVATE_API_BASE` overrides the core's `DEFAULT_BASE`. |
@@ -341,7 +353,6 @@ cannot be read as one list.
 | `CLEAROTRON_SYNTHESIS_MODEL` | unset (⇒ opus) | Stage-specific synthesis model override — the live A/B toggle (e.g. `fable`). Alias must be registered in the engine map or the dispatch REFUSES by name (; it used to run sonnet silently and log the alias asked for). Read at module load; effective per fresh oneshot process. |
 | `CLEAROTRON_MEANING_SEAT_MODEL` | unset (⇒ `haiku`) | The common-law MEANING seat's model (`COMMON_LAW_SEAT_TIER[MEANING_SEAT]`, `stages.mjs`). The default moved sonnet → haiku on measured evidence: 2 attempts / 423 s against 1 attempt / 1674 s for the same outcome. **Margin:** sufficient at every load the test suite exercises, but at its densest scenario haiku used the last rung of the retry ladder — suspect this variable first if a dense matter's meaning seat goes terminal. Set`sonnet` to roll back with no code change. The thinking budget is NOT overridable (one variable, by design). |
 | `CLEAROTRON_STAGE_THINKING` | unset (⇒ each stage's declared tier) | Per-stage thinking-tier override, `<stage>=<tier>[,…]` (e.g. `register-digest=high`) — the A/B instrument, so a suite arm needs no code fork or redeploy between runs. Thinking only: models are deliberately not overridable here, so one arm can never move two variables. **The env override is a dev/test instrument**; a permanent change edits the tier in `stages.mjs` and ships. Unknown stage or tier **throws** — `effortFor()` falls back to `medium`, so a typo would otherwise run a stage at a tier nobody chose and every number measured against it would be wrong. Read per call, so an arm can flip mid-process. |
-| `CLEAROTRON_AZURE_MODEL` | `azure-openai/gpt-5.4` | Target of the `azure` alias — a legacy catalogue entry no engine can run (see model tiers above). |
 | `CLEAROTRON_DUMP_JSON` | unset | Dump each attempt's raw engine envelope to `_driver/<stage>.attempt<N>.rawjson.json`. Opt-in: any value except `0`/`off`/`false`/`no`/empty arms it. |
 | `CLEAROTRON_DISPATCH_RECORD` | **on** | Write the verbatim message of every stage dispatch to `_driver/<stage>.attempt<N>[.repair<M>].dispatch.txt`, with `{file, sha, bytes, chars, kind}` on the attempt row. **Default ON** — `0`/`off`/`false`/`no` disarms it. Unlike `CLEAROTRON_DUMP_JSON` beside it, this is opt-OUT: the question it answers ("was the model given this?") is asked *after* the run that raised it, so a flag someone had to remember would be off on exactly the run that needed it. The files carry the company's identity verbatim and are deliberately not in the artifact table. |
 | `CLEAROTRON_GATHER_SESSION_KEY` / `CLEAROTRON_GATHER_AGENT` / `CLEAROTRON_GATHER_SESSION_ID` | set per stage | Telemetry attribution into the provider-call ledger (set by the gather config; not operator-set). |
@@ -356,8 +367,12 @@ The settings below were deleted. Nothing in any environment set them, so each be
 had always resolved to. **They are listed because an operator whose `.env` still carries one needs to
 know it is inert** — an unread setting is indistinguishable from a setting that works.
 
+`CLEAROTRON_AZURE_MODEL` left for a different reason, on 2026-09-15: it retargeted the `azure` alias,
+which no stage names and no engine runs, so no run ever used its value.
+
 | Was | Now fixed at |
 |---|---|
+| `CLEAROTRON_AZURE_MODEL` | `azure-openai/gpt-5.4`, the target of the `azure` alias (see model tiers above) |
 | `CLEAROTRON_BAND_SHAPE_PART_CHARS` | 70000 characters per shape part |
 | `CLEAROTRON_DEDUP_WINDOW_HOURS` | 24 hours, and the window can no longer be disabled |
 | `CLEAROTRON_FETCH_MAX_CHARS` | 200000 characters per fetched page |

package/docs/architecture/05-config-governance.md

@@ -159,13 +159,19 @@ structural, or dev seam); [dev] = dev/test seam, never set in prod.
 ### 5.2 Engine & models — T3
 
 `CLEAROTRON_AI` (anthropic-agent | openai-agent; default anthropic-agent), `CLEAROTRON_AI_BILLING`
-(subscription|api-key), `CLEAROTRON_AI_BILLING` (subscription|api-key), `CLEAROTRON_CODEX_PATH`,
+(subscription|api-key|cloud; cloud is Claude only), `CLEAROTRON_CODEX_PATH`,
 `CLEAROTRON_OPENAI_AUTH_FILE`, `CLEAROTRON_OPENAI_MODEL_JUDGMENT` / `CLEAROTRON_OPENAI_MODEL_SWEEP` /
 `CLEAROTRON_OPENAI_MODEL_CHEAP` (all gpt-5.6-sol),
-`CLEAROTRON_CLAUDE_PATH` (claude), `CLEAROTRON_AZURE_MODEL`,
+`CLEAROTRON_CLAUDE_PATH` (claude on PATH, then the copy Clearotron installed),
 `CLEAROTRON_SYNTHESIS_MODEL` (opus), `CLEAROTRON_KNOCKOUT_MODEL` (opus),
 `CLEAROTRON_KNOCKOUT_PRESET` (pro-search), `CLEAROTRON_MAX_BUDGET_USD` (unset).
 
+The Claude program's own cloud settings — `CLAUDE_CODE_USE_FOUNDRY`, `CLAUDE_CODE_USE_VERTEX` and
+`CLAUDE_CODE_USE_BEDROCK`, each cloud's own settings, the gateway pair and the model pins — are the
+vendor's names, not this tier's; the configuration reference's credentials table lists them. Written out
+rather than as one wildcard: a guard reads these documents for the names they govern, and a trailing `*`
+matches nothing it can check, so a name hidden behind one reads as governed while being invisible.
+
 ### 5.3 Concurrency, admission, retries, walls — T3 (walls are load-bearing; change deliberately)
 
 `CLEAROTRON_MAX_CONCURRENT_RUNS` (2), `CLEAROTRON_GATHER_CONCURRENCY` (7), `CLEAROTRON_CARD_CONCURRENCY` (8),
@@ -472,6 +478,12 @@ It must be **asked for**: a real deployment behind its upstream still reports be
 blank value is not a declaration, and the doctor names this variable in its output when it obeys it. Set
 it in CI and nowhere else — on a deployed box it silences the one check that notices the box is stale.
 
+Engines folder: `CLEAROTRON_ENGINES_DIR` — where setup installs the chosen engine's program, where
+`clearotron update` refreshes it, and where the engine resolver in `driver/driver.config.mjs` looks for it
+after the explicit setting and `PATH`. Unset on a deployment, where it is
+`~/.local/share/clearotron/engines`. The suite runner points it at an empty directory, so a test never
+reaches a program the developer's own setup installed.
+
 > **Write every name out. No `*`, no `{A,B}`, no `/_SUFFIX`.** The enforcement test matches a name on
 > a word boundary, so shorthand documents a variable to a human and hides it from the guard. This row
 > is where that was found: `*_AUTH_DISABLED`, `*_DEV` and `CLEAROTRON_REPLAY_SNAPSHOT`/`_ROOTS` left five
@@ -483,11 +495,9 @@ it in CI and nowhere else — on a deployed box it silences the one check that n
 > see `providers/oauth-mcp-bridge/README.md`) were listed there for years and read by nothing, which
 > made a reader configure a variable and get no behaviour.
 >
-> `COURTLISTENER_TOKEN` is gone. The four`AZURE_OPENAI_*` names are **still there and stay**:
-> they are a reconstructed external contract, the file says so in place and tells a reader to verify
-> the spellings against the platform that consumes them. Naming a foreign contract is not the same
-> defect as inviting someone to set a variable this product reads — the rule above is about the
-> second.
+> Both are gone. The four `AZURE_OPENAI_*` names left `.env.example` on 2026-09-15: on a page that
+> explains paying for Claude through an Azure account, four Azure variables nothing in Clearotron reads
+> looked like that setup's settings, and they are not.
 
 `portal-ui/` has **zero** env config (no `VITE_*`, no `import.meta.env`) — the SPA talks to its
 origin; all portal config lives server-side in portal-service.