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

package/driver/surface-exit-verdict.mjs

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026 Cordillera Sarl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
+//
+// WHICH ANSWER THE DEPLOYMENT CHECK GIVES, as a number a caller can act on.
+//
+// Extracted from scripts/live-surface-check.mjs for the reason roster-verdict.mjs and
+// unit-state-verdict.mjs were: that file is a program, and importing it to reach one decision runs its
+// preflight and exits. A decision nobody can drive without a deployment to point at is a decision nobody
+// drives.
+//
+// ── THE DEFECT THIS SETTLES ──────────────────────────────────────────────────────────────────────────
+//
+// The check reported "I could not look" and "this has drifted" through the same FAIL. Two arms said in
+// their own message "This is a failure to look, never a pass" and then returned the verdict a genuine
+// drift returns, so a reader could not tell them apart without reading to the end of the message.
+//
+// They want different things done. A drift is fixed by redeploying. A could-not-look is fixed by pointing
+// the check at something it can read, and until somebody does, nothing is known about that surface in
+// either direction — redeploying would change nothing, because nothing was compared.
+//
+// The cost of leaving it is the familiar one: a FAIL that turns out to be "could not look" teaches
+// whoever runs the check to read FAIL as noise, and the run where it means drift is the one nobody acts
+// on. A deployment check is exactly where that is expensive.
+
+/**
+ * The exit code for a finished run.
+ *
+ *   0  every surface was read and none disagreed
+ *   1  a surface DRIFTED — redeploy; the report names which
+ *   3  nothing drifted, and a surface COULD NOT BE READ
+ *
+ * 2 belongs to the preflight refusals, which fire before any surface is examined: the instance did not
+ * say where its pool or its doors are, so the run has nothing to report rather than something to report
+ * badly.
+ *
+ * A DRIFT OUTRANKS A COULD-NOT-LOOK when both are present. The drift is actionable now and the unreadable
+ * surface is a second errand; both are on the report, and only the code is ordered.
+ *
+ * ORDINARY SKIPS MUST NOT REACH HERE, which is why the caller passes a separate count rather than every
+ * skip. Several surfaces are deliberately not probed — a client door behind an access proxy, a door this
+ * instance does not name — and those are the resting state of a healthy box. A code that moved on them
+ * would fire on every good run and be ignored inside a week, which is this same defect one level up.
+ *
+ * @param {{failed?: number, couldNotLook?: number}} counts
+ */
+export function exitFor({ failed = 0, couldNotLook = 0 } = {}) {
+  if (failed) return 1;
+  if (couldNotLook) return 3;
+  return 0;
+}
+
+/** What each code means, for a caller printing it or a reader wondering. Keyed by the code itself. */
+export const EXIT_MEANING = Object.freeze({
+  0: "every surface was read and none disagreed",
+  1: "a surface drifted — redeploy; the report names which",
+  2: "the instance did not say where its pool or its doors are, so nothing was examined",
+  3: "nothing drifted, and a surface could not be read — nothing is known about it either way",
+});

package/driver/systemd/README.md

@@ -137,7 +137,7 @@ on a **literal glob** -- a `.path` unit cannot read an environment variable, so
 your configuration:
 
 ```
-PathExistsGlob=%h/.openclaw/workspace-clawdi/studio/prelim-search/queue/*.json
+PathExistsGlob=%h/.openclaw/workspace-clawdi/studio/clearance-search/queue/*.json
 ```
 
 **That prefix is one deployment's layout, not yours.** Enable this unit without editing that line to
@@ -153,10 +153,13 @@ checkout by a debugging session cannot quietly reconfigure the queue drain.
 
 **If the service fails to start**, `systemctl --user status prelim-driver.service` names the reason.
 The two that have actually happened: `CLEAROTRON_CHECKOUT_DIR` unset — so `ExecStart` resolves to
-`/driver/runner.mjs`, which does not exist — and `claude` not on the unit's `PATH`, which is not a
-start failure at all but shows later as every stage burning its retry ladder for zero tokens. For the
-second, set `CLEAROTRON_CLAUDE_PATH` in `~/.env` to the binary's absolute path; the unit's `PATH`
-already covers `~/.local/bin` and `~/.npm-global/bin`, the two layouts the documents permit.
+`/driver/runner.mjs`, which does not exist — and no `claude` the unit can find, which is not a start
+failure at all but shows later as every stage burning its retry ladder for zero tokens. `clearotron
+install` offers to install the chosen engine's program into `~/.local/share/clearotron/engines`, and the
+unit uses that copy when its `PATH` has none, so the second happens only when that offer was declined.
+Accept it by running `clearotron install` again, or set `CLEAROTRON_CLAUDE_PATH`
+in `~/.env` to the binary's absolute path; the unit's `PATH` already covers `~/.local/bin` and
+`~/.npm-global/bin`, the two layouts the documents permit.
 
 ### `profile-service.service` needs its checkout path edited by hand
 
@@ -191,7 +194,7 @@ degrades and the degradation should be findable.
 
 | Part | Needs | What happens without it |
 |---|---|---|
-| **Outbox delivery trigger** — `driver/deliver-trigger.sh`, driven by the `prelim-outbox` systemd `.path`/`.service`/`.timer` units | systemd; bash >= 4 for `declare -A`; `timeout(1)` (GNU coreutils, or `gtimeout` from Homebrew) as the enforced wall on every courier wake | The script refuses at startup and names the missing piece. It will not wake a courier it cannot put a wall around — an unkillable wake wedged a lane for 19h once. No event is touched: everything stays pending and delivers as soon as the host is fixed. |
+| **Outbox delivery trigger** — `driver/deliver-trigger.sh`, driven by the `clearance-outbox` systemd `.path`/`.service`/`.timer` units | systemd; bash >= 4 for `declare -A`; `timeout(1)` (GNU coreutils, or `gtimeout` from Homebrew) as the enforced wall on every courier wake | The script refuses at startup and names the missing piece. It will not wake a courier it cannot put a wall around — an unkillable wake wedged a lane for 19h once. No event is touched: everything stays pending and delivers as soon as the host is fixed. |
 | **PID-reuse claim defence** — the queue runner telling a live claimer from a recycled pid | A birth stamp for a process:`/proc/<pid>/stat` on Linux, `ps -o lstart` on macOS and anywhere else POSIX. Absent only where neither answers — WSL1, some sandboxes | Degrades **fail-safe**, and the runner says so once at startup. Claims record a bare pid, so a claim whose liveness cannot be proved counts as alive: no run is ever double-claimed and no lawyer double-delivered to. What is lost is the escape hatch — a `.processing` marker held by a recycled pid waits for the max-claim-age ceiling instead of being freed on the next tick. |
 
 CI runs the suite on macOS as well as Linux, and an assertion covering a capability the box lacks skips

package/driver/systemd/clearotron-worker.service

@@ -49,7 +49,7 @@ Environment=PATH=%h/.local/bin:%h/.npm-global/bin:/usr/local/bin:/usr/bin:/bin
 Environment=CLEAROTRON_NO_ENV_FILE=1
 ExecStart=/usr/bin/node ${CLEAROTRON_CHECKOUT_DIR}/driver/runner.mjs --watch
 # ── REFRESH THE CAPABILITY PAGE'S CAPTURE AT EVERY START ─────────────────────────────────────────────
-# The capability page renders `pool/_state/prelim-flag-snapshot.json`, and until this line its only
+# The capability page renders `pool/_state/clearance-flag-snapshot.json`, and until this line its only
 # writers were a RUN and the `clearotron start` launcher. A hosted box runs neither: these units are the
 # entrypoint, and a deployment being CONFIGURED runs nothing by definition. So the page reported the old
 # configuration as current fact for exactly as long as somebody was working on the configuration, which

package/driver/terminal-clamp.mjs

@@ -87,6 +87,37 @@ export function recordNamesDefect(record) {
   return typeof record?.defect === "string" && record.defect.trim().length > 0 && record?.delivered === true;
 }
 
+
+/**
+ * The conditions `clientConditions` could NOT render, so the surface does not carry them. PURE.
+ *
+ * A REFUSAL NOBODY RECORDS IS THE DEFECT ONE LAYER ALONG. The fallback drops a token-bearing reason it
+ * cannot compose a sentence for, which is the right answer for the client and a silent loss for
+ * everyone else: the condition was in the run record, it applies, and the delivered page no longer says
+ * so. Before this, the operator's signal was the voice lint flagging the token on the page. Take the
+ * token off the page and that flag goes quiet — the gap would be closed and the disclosure would go
+ * with it, with nothing in between to say which. So the drop reports itself here, the lint reads it,
+ * and the run record keeps the reason either way.
+ *
+ * @param {{reasons?: string[], clauses?: string[]}} sidecar  the parsed `_driver/verdict.json`
+ * @returns {string[]} the run-record reasons that reach no client surface
+ */
+// IT DECIDES THE SAME THREE THINGS `clientConditions` DECIDES, and they have to keep agreeing: what
+// counts as a stored clause, what counts as an empty reason, and which reasons the authority can
+// render. The third cannot drift — both call `clauseFromReason` — and the first two are the two lines
+// below. A change to either belongs in both, and arm 9 drives them together against one sidecar.
+export function unrenderableConditions({ reasons, clauses } = {}) {
+  const rs = Array.isArray(reasons) ? reasons : [];
+  const cs = Array.isArray(clauses) ? clauses : [];
+  return rs.filter((r, i) => {
+    if (cs[i] === null) return false;   // run record only BY RULING, not a clause that failed to compose
+    if (typeof cs[i] === "string" && cs[i].trim()) return false;
+    const text = String(r ?? "").trim();
+    if (!text) return false;
+    return !clauseFromReason(text) && ENGINE_TOKEN_RE.test(text);
+  }).map((r) => String(r).trim());
+}
+
 /**
  * THE LEDE IS THE OPINION'S, BY DECISION AND NOT BY PUSH ORDER. The terminal guards run
  * earlier in the delivery block than the coverage floor, so their clauses landed at index 0 and the
@@ -107,6 +138,70 @@ export function orderClausesForLede(clauses, reasons, guardSet) {
   return { clauses: ordered.map((x) => x.c), reasons: ordered.map((x) => x.r) };
 }
 
+/**
+ * THE CLAUSE AUTHORITY — one composer for the reader's sentence, called both where the numbers are
+ * known and where only the run-record reason survives. PURE.
+ *
+ * A run recorded before clauses were persisted carries `reasons` and no `clauses`, so every condition
+ * fell back to the run-record sentence and a republished archived report opened its Conditions list
+ * with `floor_duty_undischarged:4 of 430 floor row(s)…` — on the page and in the exported PDF. Dropping
+ * the condition instead loses a point the reader must weigh, and re-generating every archived run is
+ * not on offer. The third way is this: for both defects that can reach that list the reader's sentence
+ * is fully determined by the two numbers the reason already carries in its own prefix. An archived run
+ * therefore holds everything needed to compose the client's sentence; what it lacks is only the store.
+ *
+ * ONE DEFINITION, TWO ENTRY POINTS. The clamp site calls `clauseForDefect` with the counts it already
+ * holds; the republish path calls `clauseFromReason`, which reads the same two numbers off the reason's
+ * prefix and hands them to the same composer. A second spelling of either sentence would drift, and the
+ * drift would be invisible: both surfaces render, and only a reader comparing a fresh run against a
+ * republished one would ever see it.
+ *
+ * AN UNRECOGNISED SHAPE IS REFUSED, AND REFUSED HERE MEANS `null` — NEVER A THROW. This runs on the
+ * republish path. A throw there is the failure at the top of this file: a live run died at delivery
+ * after 5.55 hours and the client received nothing instead of a report naming one gap. The caller
+ * decides what the absence means.
+ */
+const CLAUSE_AUTHORITY = Object.freeze({
+  synthesis_unaccounted_delivered: (n, m) =>
+    `${n} of the ${m} register records this search surfaced are neither addressed as findings nor expressly set aside in this report — they remain open points a reader must weigh`,
+  floor_duty_undischarged: (n, m) =>
+    `${n} of the ${m} live registrations identical or near-identical to the mark are not individually addressed in this report — each remains an open point a reader must weigh`,
+});
+
+/**
+ * The reader's sentence for a defect, from its counts. PURE.
+ *
+ * @param {string} defect  the machine token, with or without its `:N` tail
+ * @param {number} n       the count the defect names
+ * @param {number} m       the population it is out of
+ * @returns {string|null}  the client's sentence, or null for a shape this module cannot render
+ */
+export function clauseForDefect(defect, n, m) {
+  const compose = CLAUSE_AUTHORITY[String(defect ?? "").split(":")[0].trim()];
+  if (!compose) return null;
+  const a = Number(n), b = Number(m);
+  if (!Number.isFinite(a) || !Number.isFinite(b)) return null;
+  return compose(a, b);
+}
+
+// The run-record reason's own opening: `<token>:<n> of <m> <noun>`. The NOUN is deliberately not part
+// of the match — `record(s)` and `floor row(s)` are the two spellings today, and a third would make
+// this stop recognising a shape it can render perfectly well. The token is what selects the sentence.
+const REASON_PREFIX_RE = /^([a-z][a-z0-9_]*):(\d[\d,]*)\s+of\s+(\d[\d,]*)\s/i;
+
+/**
+ * The reader's sentence for a condition that has only its run-record reason. PURE.
+ *
+ * @param {string} reason  the run-record sentence
+ * @returns {string|null}  the client's sentence, or null when the reason is not one this can render
+ */
+export function clauseFromReason(reason) {
+  const m = String(reason ?? "").match(REASON_PREFIX_RE);
+  if (!m) return null;
+  const num = (t) => Number(String(t).replace(/,/g, ""));
+  return clauseForDefect(m[1], num(m[2]), num(m[3]));
+}
+
 /**
  * THE CLIENT'S CONDITION LIST, from a verdict sidecar. PURE.
  *
@@ -135,6 +230,15 @@ export function orderClausesForLede(clauses, reasons, guardSet) {
  *   · a clean reason with no clause survives       → break: return "" for a missing clause, arm 2 red
  *   · a legacy sidecar still yields its conditions  → break: require the clauses key, arm 3 red
  *   · clauses shorter than reasons loses nothing    → break: map over clauses, arm 4 red
+ *   · a pre-split reason renders as the lawyer's    → break: return the reason, arm 5 red
+ *   · an unrenderable token-bearing reason is gone  → break: return it, arm 6 red
+ *
+ * THE FALLBACK NO LONGER PRINTS THE RUN RECORD. Where no clause was stored, the clause authority above
+ * composes one from the reason's own counts; where it cannot, the condition is DROPPED rather than
+ * rendered in engine voice. Dropping is a loss and it is the smaller one: a client who reads
+ * `floor_duty_undischarged:4` has been handed the engine's private vocabulary as their own advice. A
+ * reason carrying no engine identifier is a factual open-state already — the three machinery sites push
+ * the reason AS the clause — and it still survives untouched, which is arm 2.
  *
  * @param {{reasons?: string[], clauses?: string[]}} sidecar  the parsed `_driver/verdict.json`
  * @returns {string[]} one condition per reason, in the sidecar's own order
@@ -143,7 +247,11 @@ export function clientConditions({ reasons, clauses } = {}) {
   const rs = Array.isArray(reasons) ? reasons : [];
   const cs = Array.isArray(clauses) ? clauses : [];
   return rs.map((r, i) => {
+    if (cs[i] === null) return "";   // a stored null is a condition ruled for the run record alone
     const clause = typeof cs[i] === "string" ? cs[i].trim() : "";
-    return clause || String(r ?? "").trim();
+    if (clause) return clause;
+    const text = String(r ?? "").trim();
+    if (!text) return "";
+    return clauseFromReason(text) ?? (ENGINE_TOKEN_RE.test(text) ? "" : text);
   }).filter(Boolean);
 }

package/driver/tokens.mjs

@@ -46,10 +46,10 @@
 import { readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { driverDir } from "../shared/driver-dir.mjs";   //
-import { resolveModel } from "./driver.config.mjs";
+import { resolveModel, modelFamily } from "./driver.config.mjs";
 import { runLog, note } from "./log.mjs";
 import { writeRunStatus } from "./progress.mjs";
-import { stampRunEconomics, isCodeSide } from "./run-economics.mjs";
+import { stampRunEconomics, isCodeSide, vendorOf } from "./run-economics.mjs";
 
 function emptyAcc() {
   return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, attempts: 0, thoughtTurns: 0 };
@@ -84,9 +84,27 @@ function modelKey(rec) {
   // them would break byModel summing to total, and an invisible gap is the failure this file already
   // fixed once for byEngine), and the key says what is missing rather than asserting an Anthropic
   // model produced them.
+  //
+  // A TURN THAT NAMED NO MODEL, a native-language row recording `modelActual: null` (see isAttemptRow),
+  // has no id at all. Its tokens still account, under a key that says the model is missing rather than
+  // one built from the absent field. Such a row always carries its vendor's stamp, so it reaches here.
+  if (typeof rec.model !== "string") return `${engine || "unknown"}/no-model-reported`;
   return `${engine}/unstamped:${rec.model}`;
 }
 
+/**
+ * WHETHER A ROW IS A PROVIDER ATTEMPT, the one test rollupTokens and servedModels both apply. A row that
+ * names a model is one: every stage attempt row carries the tier it asked for, and a native-language row
+ * the id its turn reported. So is a native-language row whose turn ran and named no model, which records
+ * `modelActual: null` instead (jxModelFields in jx-lanes.mjs). Without that second half, such a turn's
+ * attempt and the tokens it reported were dropped from every total, and a run made only of such turns
+ * read as one where nothing was looked at. A row with neither field is not a turn: the run log's events,
+ * a tool call, a native-language call no provider served.
+ */
+export function isAttemptRow(rec) {
+  return Boolean(rec) && (typeof rec.model === "string" || rec.modelActual === null);
+}
+
 // usage shape (gateway.mjs): {input,output,cacheRead,cacheWrite}. There is deliberately NO reasoning-token
 // field: the old `reasoning`/`reasoningTokens` pair was an unfillable slot — no reasoning count exists
 // anywhere in the claude payload (not result.usage, not usage.iterations), so no shipped adapter ever
@@ -128,7 +146,7 @@ export function rollupTokens(runDir) {
       if (!ln.trim()) continue;
       let rec;
       try { rec = JSON.parse(ln); } catch { continue; }
-      if (!rec || typeof rec.model !== "string") continue; // only stage-attempt records carry a model
+      if (!isAttemptRow(rec)) continue; // only provider attempts carry tokens (see isAttemptRow)
       const t = tokensOf(rec.usage);
       const accs = [total, (byStage[stage] ??= emptyAcc()), (byModel[modelKey(rec)] ??= emptyAcc())];
       // Engine and billing mode are split out because a token is not a portable unit of cost: a turn on a
@@ -168,6 +186,154 @@ export function rollupTokens(runDir) {
   return { total, byStage, byModel, byEngine, byAuthMode };
 }
 
+/**
+ * THE MODELS THAT SERVED THIS RUN, as the engine reported them: distinct ids, in the order each first
+ * served a turn. Read from every attempt row's `modelActual`, the id the wire named: the stage rows
+ * gateway.mjs writes and the native-language rows jx.mjs and jx-units.mjs write, one list across both. Never
+ * the tier a stage asked for in place of a model the wire named: a tier goes to the CLI as the vendor's
+ * alias, so the request says nothing about which model ran, and this is the record that does. The tier
+ * stands in only for a name no client may read (below).
+ *
+ * THREE-VALUED. `null` when there is no attempt row to read (no telemetry directory, or no row in it is
+ * a provider turn), so nothing was looked at. `[]` when attempt rows exist and none names a served model
+ * a client may read (an engine that does not report one, a turn killed before it said, a turn the Claude
+ * program answered itself), on a stage turn and a native-language turn alike. One more case reads `[]`:
+ * a Claude turn served under a deployment name whose requested tier the tier reader cannot place (a request
+ * outside opus, sonnet, haiku and fable) is left off, because the name must not be printed and there is no
+ * tier word to print instead. In a run that mixes such turns with others, the list names only the others.
+ * So does a turn stamped by an engine whose vendor the closed table in run-economics.mjs does not name:
+ * nobody can say whose model served it. An empty list is never a guess.
+ *
+ * WHAT IS LISTED IS WHAT A CLIENT MAY READ, mapped here and nowhere else (servedName below), so meta.json,
+ * report-data.json and the report's closing line carry one list and cannot disagree. Through a cloud, a
+ * turn reports either that cloud's spelling of a Claude model or a name the company gave its own
+ * deployment. The first is listed as the Claude id it names; the second is listed as the tier the turn
+ * asked for ("Opus"), never as the name. The attempt row itself keeps what the program reported.
+ */
+export function servedModels(runDir) {
+  const dDir = driverDir(runDir);
+  let files;
+  try { files = readdirSync(dDir).filter((f) => f.endsWith(".jsonl") && f !== "run.jsonl"); }
+  catch { return null; }
+  const firstSeen = new Map();   // id → the earliest row timestamp that named it
+  let attempts = 0;
+  for (const file of files) {
+    let raw;
+    try { raw = readFileSync(join(dDir, file), "utf8"); } catch { continue; }
+    for (const ln of raw.split("\n")) {
+      if (!ln.trim()) continue;
+      let rec;
+      try { rec = JSON.parse(ln); } catch { continue; }
+      // The same test rollupTokens applies for an attempt row, less the driver's own code-side rows:
+      // no provider served those, so they cannot stand for "a turn ran and named no model".
+      if (!isAttemptRow(rec) || isCodeSide(rec)) continue;
+      attempts += 1;
+      const id = typeof rec.modelActual === "string" ? rec.modelActual.trim() : "";
+      // `<synthetic>` is the Claude CLI's name for a message it wrote itself, measured in testing on a
+      // turn a cloud refused for a missing deployment (2026-09-14). No model served that turn, so a
+      // bracketed marker is never listed as one.
+      if (!id || /^<.*>$/.test(id)) continue;
+      // Keyed on the name a client reads, so two deployments serving one tier, or one model reached
+      // through two clouds, are listed once.
+      const name = servedName(rec, id);
+      if (!name) continue;
+      const ts = String(rec.ts ?? "");
+      if (!firstSeen.has(name) || ts < firstSeen.get(name)) firstSeen.set(name, ts);
+    }
+  }
+  if (!attempts) return null;
+  return [...firstSeen].sort((a, b) => (a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0)).map(([id]) => id);
+}
+
+// Imported here, beside its one reader: the tier every native-language step asks for (see servedName).
+import { JX_TIER } from "./engine/jx-turn.mjs";
+
+// AMAZON'S SPELLING OF A CLAUDE ID: an optional cross-region prefix (`us.`, `eu.`, `apac.`, `global.`), the
+// vendor prefix `anthropic.`, and a version suffix (`-v1:0`), optionally at the end of an inference
+// profile's full address (`arn:aws:bedrock:<region>:<account>:inference-profile/…`), whose account number
+// is the company's and is dropped with the rest. `us.anthropic.claude-opus-4-1-20250805-v1:0` is
+// `claude-opus-4-1-20250805`. Anchored on `anthropic.claude-`, so no other vendor's id is rewritten.
+const AMAZON_CLAUDE_ID_RE = /^(?:arn:aws[\w-]*:bedrock:[^/]*\/)?(?:[a-z]{2,6}(?:-[a-z]+)?\.)?anthropic\.(claude-[a-z0-9.-]+?)(?:-v\d+(?::\d+)?)?$/i;
+// GOOGLE'S SPELLING, `claude-opus-4-1@20250805`. It already names the model; it is listed as the dated id
+// `claude-opus-4-1-20250805` because that is the same model's name on Anthropic's own API and on Amazon's,
+// so a model reached through two routes is one entry rather than two spellings of one model. An older
+// model's Google name carries a version mark before the date (`claude-3-5-sonnet-v2@20241022`), the same
+// mark Amazon writes as `-v2:0`; it is not in the model's own name, so it goes too.
+const GOOGLE_CLAUDE_ID_RE = /^(claude-[a-z0-9.-]+?)(?:-v\d+)?@(\d{8})$/i;
+// THE SHAPE OF A CLAUDE MODEL ID, which is what lets an id be printed as itself. A family and one or two
+// version numbers (`claude-opus-4-1`), or the older order of version before family
+// (`claude-3-5-sonnet`); then an optional date; then an optional context-window mark (`[1m]`), which
+// the program may report beside the model and is kept as reported. Tested lower-cased, after the cloud
+// spellings above are rewritten. A prefix test is not enough: a company may name its own deployment
+// `claude-acme-prod`, or wrap its own name in Amazon's form, and neither is a Claude model. A family with
+// no version, `claude-opus`, names no model either: it is the name an operator types for a deployment of
+// that tier, and printed as itself it would put that name on the report, and a Sonnet deployment's name
+// on a turn that asked for Haiku. A `latest` alias, `-latest` or Google's `@latest`, is a pointer the
+// provider moves, never the name of the model a turn reports, so it reads as the tier too.
+const CLAUDE_MODEL_ID_RE = /^claude-(?:(?:opus|sonnet|haiku|fable)(?:-\d{1,2}){1,2}|\d(?:-\d)?-(?:opus|sonnet|haiku))(?:-\d{8})?(?:\[\d+[km]\])?$/;
+const CLAUDE_TIERS = new Set(["opus", "sonnet", "haiku", "fable"]);   // fable is reached through the synthesis override
+// A FABLE REQUEST IS READ HERE, NOT BY modelFamily. modelFamily is also the gateway's family comparison on every
+// turn, and it places opus, sonnet and haiku only: an id naming fable stays unknown there, so it can never
+// refuse a turn (driver.config.mjs says why). The report still needs the tier word of a fable turn served under
+// a company's deployment name, so it is read for the report alone, placed where the family reader places the
+// other three: the whole request, or first in it or after a `/`, with or without `claude-`. So `fable` and a
+// request in a pinned id's spelling (`claude-fable-5-1`) both read fable, and `acme-fable` does not. A turn
+// served as a fable id never reaches this: that id is a Claude model's name and prints as itself. modelFamily is
+// asked first, so a request it places reads as that tier even when it also names fable (`fable-x/sonnet` is
+// Sonnet), and one it cannot place falls through to this reader (`sonnet/fable-x` is Fable).
+const FABLE_REQUEST_RE = /(?:^|\/)(?:claude-)?fable(?:[-.]|$)/i;
+const requestedTier = (asked) =>
+  modelFamily(asked) ?? (FABLE_REQUEST_RE.test(String(resolveModel(asked) ?? "")) ? "fable" : null);
+
+/** A Claude model id in any cloud's spelling, as its own lower-case name, or null when it is not one. */
+function claudeModelId(id) {
+  const raw = String(id ?? "").trim();
+  const amazon = AMAZON_CLAUDE_ID_RE.exec(raw);
+  const google = amazon ? null : GOOGLE_CLAUDE_ID_RE.exec(raw);
+  const named = (amazon ? amazon[1] : google ? `${google[1]}-${google[2]}` : raw).toLowerCase();
+  return CLAUDE_MODEL_ID_RE.test(named) ? named : null;
+}
+
+/**
+ * The name a client reads for one served id, or null when it must not be listed.
+ *
+ * A CLAUDE ID, in any cloud's spelling, is the model it names. ANY OTHER ID ON A CLAUDE TURN names no
+ * Claude model, and on Azure Foundry that is the name a company gave its deployment (`acme-prod-opus`): a
+ * company's internal name, and never one to print on its client's report. The turn is listed as the tier
+ * it asked for instead, which is what the company deployed under that name.
+ *
+ * WHOSE TURN IT WAS IS THE VENDOR'S QUESTION, answered by the one closed table of engines (vendorOf in
+ * run-economics.mjs), not by a list kept here. An OpenAI turn's id is listed as reported: a Codex id is the
+ * model's own name. An Anthropic turn under any engine name is mapped as above; a second list of Claude
+ * engines here printed a deployment name, as reported, for every engine it left out. An engine the table
+ * does not name is left off: printing its id would make a vendor claim nobody can check.
+ *
+ * A ROW WITH NO ENGINE STAMP reads as Claude's, as modelKey above reads it, EXCEPT when the id is plainly
+ * another vendor's (a `gpt-` or o-series id, by modelFamily's OpenAI reader): printing that as a Claude
+ * tier would put a false vendor on a client's report, where a wrong guess in modelKey costs only a key.
+ */
+function servedName(rec, id) {
+  const claude = claudeModelId(id);
+  if (claude) return claude;
+  const engine = typeof rec.engine === "string" ? rec.engine : "";
+  const family = engine ? null : modelFamily(id);
+  const vendor = engine ? vendorOf(engine) : family && !CLAUDE_TIERS.has(family) ? "openai" : "anthropic";
+  if (vendor === "openai") return id;
+  if (vendor !== "anthropic") return null;
+  // THE TIER THE TURN ASKED FOR, told apart by the kind of row, which its engine stamp names. A stage row
+  // (engine "anthropic-agent", another Anthropic engine, or no stamp) records that request as `model`
+  // ("opus"), and that holds even when the served id is spelled the same as the request, as it is for a
+  // deployment named after its tier. A native-language row (engine "anthropic") records its SERVED id as `model`, beside
+  // `modelActual` (jxModelFields), so reading it as the request would hand back the deployment name;
+  // every one of those steps asks for JX_TIER. A request in a cloud's spelling is read as the Claude id it
+  // names first. modelFamily reads opus, sonnet and haiku, and requestedTier adds fable, for the report
+  // alone. A tier neither can place returns null and the id is left off: listing nothing is honest, and
+  // listing the name is the leak this prevents.
+  const asked = engine === "anthropic" ? JX_TIER : rec.model;
+  const tier = requestedTier(claudeModelId(asked) ?? asked);
+  return CLAUDE_TIERS.has(tier) ? tier[0].toUpperCase() + tier.slice(1) : null;
+}
+
 /**
  * Stamp the rollup onto the run: the `token-rollup` event in _driver/run.jsonl plus `status.json.tokens`.
  *

package/driver/unit-environment.mjs

@@ -51,36 +51,63 @@ const OPTIONAL = "-";
  * @returns {{path: string}|{unresolved: string}}
  */
 function expandSpecifiers(raw, home) {
-  const path = String(raw).replace(/%h/g, home ?? "");
-  if (!home && /%h/.test(raw)) return { unresolved: raw };
-  // %% is an escaped percent and is legal; anything else left over is a specifier we do not implement.
-  const leftover = path.replace(/%%/g, "").match(/%[A-Za-z]/);
-  return leftover ? { unresolved: raw } : { path };
+  // ONE PASS, LEFT TO RIGHT, as systemd reads them. `%%` is an escaped percent and becomes one `%`, so
+  // `%%h` is a literal `%h`, never the home. Replacing `%h` first and unescaping after read `%%h` as a
+  // `%` followed by the home, and left `50%%` doubled, so a value reached doctor and connect in a form
+  // the service was never given. Any other letter after a `%` is a specifier this reader does not
+  // implement.
+  let unresolved = false;
+  const path = String(raw).replace(/%([%A-Za-z])/g, (whole, c) => {
+    if (c === "%") return "%";
+    if (c === "h" && home) return home;
+    unresolved = true;
+    return whole;
+  });
+  return unresolved ? { unresolved: raw } : { path };
 }
 
 /**
- * Merge one unit file's environment directives IN FILE ORDER.
+ * Merge one unit file's environment directives THE WAY SYSTEMD MERGES THEM: every `Environment=`
+ * assignment first, then every `EnvironmentFile=`'s contents over them, the files in the order listed.
  *
- * systemd applies `EnvironmentFile=` and `Environment=` as it encounters them, and a later assignment
- * overrides an earlier one. Reading the whole file and applying the two kinds in separate passes would
- * be a different resolution order from the one the running service got — which is exactly the class of
- * bug this module exists to close, so the order is preserved rather than approximated.
+ * WHERE A LINE SITS DOES NOT DECIDE IT. systemd.exec(5) on `EnvironmentFile=`: "Settings from these files
+ * override settings made with Environment=." This reader used to apply the two kinds in file order, so a
+ * name set by both came back with the unit's value whenever its `Environment=` line followed the file,
+ * which is how every shipped unit is written, while the service ran with the file's. A PATH in the
+ * settings file was the case that showed: doctor looked for the engine's program on the unit's PATH,
+ * found it, and passed a machine whose services would not find it. The renderer's header
+ * (driver/systemd/render-units.mjs) states the same rule, and one unit loads no settings file because of it.
+ *
+ * Within each kind a later assignment still overrides an earlier one.
  *
  * @param {string} unitText            the unit file's contents
  * @param {(path: string) => string|null} readEnvFile  returns the file's text, or null if unreadable
- * @returns {{env: Object, missing: string[]}}  `missing` names REQUIRED files that could not be read
+ * @returns {{env: Object, missing: string[]}}  `missing` names REQUIRED files that could not be read, and
+ *   assignments whose value carries a specifier that could not be expanded
  */
 function applyUnit(unitText, readEnvFile, home) {
   const env = {};
+  const fromFiles = {};
   const missing = [];
   for (const raw of String(unitText ?? "").split("\n")) {
     const line = raw.trim();
     // `Environment=` may carry several assignments on one line; systemd splits on whitespace.
+    //
+    // ITS VALUES ARE EXPANDED TOO, by the same rule as a file path. Every shipped unit writes
+    // `Environment=PATH=%h/.local/bin:%h/.npm-global/bin:…`, and systemd hands the service that PATH with
+    // the home filled in. Passed through as written, it named a folder called `%h/.local/bin` that exists
+    // nowhere, so a check that looked for the engine's program on the units' PATH found nothing on a
+    // machine whose searches found it and ran. A value that cannot be expanded is a hole in the picture,
+    // for the reason the file branch below gives: a literal `%h` answers "absent" for a reader that
+    // failed.
     const direct = /^Environment=(.*)$/.exec(line);
     if (direct) {
       for (const pair of direct[1].trim().split(/\s+/)) {
         const m = /^"?([A-Za-z_][A-Za-z0-9_]*)=(.*?)"?$/.exec(pair);
-        if (m) env[m[1]] = m[2];
+        if (!m) continue;
+        const value = expandSpecifiers(m[2], home);
+        if (value.unresolved !== undefined) missing.push(`${m[1]}=${value.unresolved} (unresolved systemd specifier)`);
+        else env[m[1]] = value.path;
       }
       continue;
     }
@@ -106,10 +133,10 @@ function applyUnit(unitText, readEnvFile, home) {
         if (!optional) missing.push(path);
         continue;
       }
-      Object.assign(env, parseEnvFile(text));
+      Object.assign(fromFiles, parseEnvFile(text));
     }
   }
-  return { env, missing };
+  return { env: { ...env, ...fromFiles }, missing };
 }
 
 /**
@@ -143,7 +170,7 @@ export function unitEnvironment({ units = [], readEnvFile = () => null, home = n
     // name we did not find might live in it — and reporting those as absent would be the original bug
     // with a smaller blast radius. The whole picture is refused instead.
     return { known: false, env, read,
-      why: `the units require environment file(s) this command could not read: ${[...new Set(holes)].join(", ")}` };
+      why: `the units require environment file(s) or values this command could not read: ${[...new Set(holes)].join(", ")}` };
   }
   return { known: true, env, read, why: null };
 }

package/driver/unit-inventory.mjs

@@ -73,7 +73,24 @@
 // it for current state.)
 
 /** Where a unit is expected to be installed. "none" is a claim, not an absence — see ORPHANED below. */
-export const BOXES = Object.freeze(["prod", "test", "dev"]);
+export const BOXES = Object.freeze(["prod", "preprod", "test", "dev"]);
+
+/**
+ * Whose DECLARED units a box is expected to carry, where that is not its own name.
+ *
+ * `runsOn` is a MEASURED claim — this file says so in as many words: an entry gains a box the day an
+ * enumeration of that box shows the unit, never the day somebody intends it. So pre-prod cannot be
+ * written into `runsOn` from a machine that has not enumerated pre-prod, and it must not be: that would
+ * turn a measurement into a plan, which is the one thing these entries are not.
+ *
+ * What CAN be stated from here is the expectation. Pre-prod is a packaged install of the same product on
+ * its own account, with the same doors and the same worker, so what it is expected to carry is what
+ * production is expected to carry. The expectation derives; the measurement stays measured; and a unit
+ * genuinely absent on pre-prod is reported rather than skipped, which is the whole point of the box
+ * being able to name itself.
+ */
+const EXPECTS_LIKE = Object.freeze({ preprod: "prod" });
+const expectationBox = (box) => EXPECTS_LIKE[box] ?? box;
 
 // ── RESOLVED UNITS (ruling 2026-08-25 — option B) ──────────────────────
 //
@@ -773,7 +790,7 @@ export function unitInventoryVerdict({
   // unit that is gone from a box is the ruling taking effect, not drift; reporting it as a fault trains
   // a reader to skim the arm that would have caught a real one. Both are still REPORTED — the
   // distinction is which of them is a fault.
-  const declaredHere = (u) => box && u.runsOn.includes(box) && !liveBases.includes(u.unit);
+  const declaredHere = (u) => box && u.runsOn.includes(expectationBox(box)) && !liveBases.includes(u.unit);
   const absent = box
     ? inventory.filter((u) => declaredHere(u) && !u.retired).map((u) => u.unit).sort()
     : [];

package/driver/usage-ledger.mjs

@@ -11,7 +11,7 @@
 // portal-service re-exports both names, so every existing caller is untouched.
 //
 // THIS FILE OWNS THE LEDGER PATH. It used to reconstruct a workspace-relative one —
-// `<workspaceRoot>/workspace-*/studio/prelim-search/.matter-ledger.jsonl` — under a comment claiming it
+// `<workspaceRoot>/workspace-*/studio/clearance-search/.matter-ledger.jsonl` — under a comment claiming it
 // was what runner.mjs computed. The comment was right and the code was not: once the product moved the
 // queue to a standalone directory, that path resolved to nothing, and because a missing ledger is a low
 // count rather than an error, every account read as ZERO on every request. Two copies of one calculation

package/driver/variant-manifest-model.mjs

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
-// variant-manifest-model.mjs — strict parser for the prelim-variants stage's machine output
+// variant-manifest-model.mjs — strict parser for the clearance-variants stage's machine output
 // (variant-manifest.json, the structured SIBLING of variant-manifest.md).
 //
 // WS2 (F2 — reproducible search): the model reasons ONCE about what to search (elements,
@@ -34,7 +34,7 @@ export const ELEMENT_KINDS = ["distinctive", "common", "saturated-common"];
 // transliteration-numeric axis); composite = the element inside a larger mark.
 //
 // — THE DOCTRINE'S FOUR UNIVERSAL TAGS ARE WRITABLE. The variants doctrine
-// (prelim-variants SKILL.md, "Universal categories") tells the seat to tag rows `exact-phrase`,
+// (clearance-variants SKILL.md, "Universal categories") tells the seat to tag rows `exact-phrase`,
 // `exact-element`, `plural-root` and `formative-family`, and this enum refused every one — a manifest
 // that obeyed the doctrine literally failed the stage, so seats substituted (`other` on one run,
 // `composite` in the fixture corpus) and the family lane's contains-not-exact mandate had nothing to
@@ -171,7 +171,7 @@ export function parseVariantManifestModel(raw) {
   // compromise: it is the granularity at which BOTH sides are typed, and the only one where the join
   // cannot go quietly wrong.
   //
-  // WHY IT IS DESIGNATED HERE AND JUDGED ELSEWHERE. prelim-variants designates; prelim-register writes the
+  // WHY IT IS DESIGNATED HERE AND JUDGED ELSEWHERE. clearance-variants designates; clearance-register writes the
   // coverage row that either honours it or does not. Different stage, earlier turn, before any outcome is
   // known — which is the whole mechanism. A floor field on the coverage row itself would let the seat that
   // missed the work also decide the work was never obliged: the self-grading loophole rebuilt inside its
@@ -266,7 +266,7 @@ export function variantRomanizationGaps(model) {
  * deferred row both stop the nil search, and neither one tells the stage that AUTHORED the string.
  * A `**`-wrapped variant silently becomes a deferred row and the manifest still says the family was
  * covered — the search shrinks and nothing asks for it back. This arm hands the reason to the
- * corrective ladder in-turn, so prelim-variants restates the term while the run is still cheap: the
+ * corrective ladder in-turn, so clearance-variants restates the term while the run is still cheap: the
  * half of the issue's first acceptance criterion the plan-side screen cannot reach.
  *
  * MARKUP ARM ONLY, deliberately. The prose/long-form arm is legitimately shielded for a slogan mark