clearotron 0.2.1 → 0.2.3

package/driver/engine/cli-version.mjs

@@ -0,0 +1,103 @@
+// 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
+//
+// THE VERSION OF THE BINARY THAT SERVED A RUN, captured at dispatch.
+//
+// The record already says whether the model id the provider reported names a pinned build or an alias it
+// may repoint. That answers "did the model move". It cannot answer "did the TOOL move", and the two are
+// different questions with the same symptom: a run whose judgment differs from last week's.
+//
+// Nothing recorded it. Three archived runs were walked for every spelling of a version field and carried
+// none — so what served them is not recoverable, and the box could have answered at any time.
+//
+// ── UNREADABLE IS A VALUE, NOT AN OMISSION ──────────────────────────────────────────────────────────
+//
+// The whole point of the field is telling three states apart, and only one of them is "we know":
+//
+//   { version: "2.1.241", probe: "ok" }          the binary answered
+//   { version: null, probe: "unreadable", why }  it was asked and could not say
+//   (no field at all)                            this record predates the gauge
+//
+// An omission on failure collapses the middle into the third, and a reader comparing two runs cannot
+// tell a tool that would not answer from a record written before anybody asked. That distinction is the
+// reason for the field, so failing to write it is failing at the thing rather than at the edge of it.
+//
+// ── ONE SPAWN PER BUILD, NOT PER PROCESS ────────────────────────────────────────────────────────────
+//
+// A dispatch is many stages and every stage would otherwise pay. But the cache lives as long as the
+// process, and the process is NOT one run: the drainer's watch loop calls the pipeline for job after job
+// without exiting. A first version cached there would be reported as fact for every later run in that
+// process — including runs served by a binary somebody upgraded in place underneath it.
+//
+// That is the exact silence this field exists to end, reintroduced by the cache meant to make it cheap,
+// and it would have been invisible: the record would carry a version, confidently, and be wrong.
+//
+// So the key is the path AND what the filesystem says about the file — an in-place upgrade changes the
+// modification time and the size, so it misses the cache and is probed again. The path alone is not
+// enough (two engines can point at one binary, an engine can be repointed) and the engine id is not
+// enough for the same reason.
+//
+// A file the filesystem cannot describe is NOT CACHED at all. Caching an unreadable probe under a key
+// derived from a failed stat would pin the failure for the life of the process, so a binary that
+// appeared a moment later would keep reading as absent.
+// ── WHAT THIS DEPENDS ON, WHICH IS NOT ENFORCEABLE FROM HERE ────────────────────────────────────────
+//
+// A probe that can change what it probes is not a probe. This one spawns the engine binary, so it rests
+// on `--version` being side-effect-free — true of every real CLI and not something this module can make
+// true. It bit immediately: the suite's engine stand-ins fell through to their stage path, and one of
+// them counts invocations to decide when to fail, so the probe consumed the failure a retry test was
+// measuring and the retry never happened. The symptom was an attempt count off by one, three files away
+// from the cause.
+//
+// The stand-ins now answer `--version` and exit, which is what the binaries they stand in for do. A new
+// one that forgets will produce the same off-by-one, so `driver/test/a-run-records-the-tool-that-served-it`
+// asserts every engine stand-in answers — the cheap ratchet under a condition that cannot be checked at
+// the call site.
+import { execFileSync } from "node:child_process";
+import { statSync } from "node:fs";
+
+/** Live for the process, keyed by resolved path. A run is one process; a probe is one spawn. */
+const CACHE = new Map();
+
+/** The first version-shaped token in the output, or the whole first line when nothing matches. */
+export function parseVersion(out) {
+  const line = String(out ?? "").split("\n").map((l) => l.trim()).filter(Boolean)[0] ?? "";
+  if (!line) return null;
+  // These CLIs answer `2.1.241`, `codex-cli 0.5.0`, `claude 2.1.241 (Claude Code)`. Take the first
+  // dotted number and keep it; a build that answers in prose is recorded verbatim rather than dropped,
+  // because a string somebody can compare beats a null.
+  return (line.match(/\b\d+\.\d+(?:\.\d+)?(?:[-+][0-9A-Za-z.-]+)?\b/) ?? [line])[0];
+}
+
+/**
+ * Probe one binary. PURE apart from the spawn, which is injected so an arm can drive both branches
+ * without a binary on the box — the unreadable branch is the one that matters and it cannot be produced
+ * on demand from a real install.
+ *
+ * Never throws. A probe that could take down a dispatch would be a worse defect than the gap it closes.
+ */
+export function probeCliVersion(bin, { run = null, timeoutMs = 5000, cache = CACHE, stat = statSync } = {}) {
+  if (!bin) return { version: null, probe: "unreadable", why: "no engine binary was resolved" };
+  let key = null;
+  try { const st = stat(bin); key = `${bin}\u0000${st.mtimeMs}:${st.size}`; } catch { /* not cacheable */ }
+  if (key && cache.has(key)) return cache.get(key);
+  const spawn = run ?? ((b) => execFileSync(b, ["--version"], {
+    encoding: "utf8", timeout: timeoutMs, stdio: ["ignore", "pipe", "ignore"],
+  }));
+  let result;
+  try {
+    const version = parseVersion(spawn(bin));
+    result = version
+      ? { version, probe: "ok" }
+      // It ran and said nothing a version could be read from. That is not the same as failing to run,
+      // and a reader chasing a tool change needs to know which happened.
+      : { version: null, probe: "unreadable", why: "the binary answered with no version-shaped token" };
+  } catch (e) {
+    result = { version: null, probe: "unreadable", why: String(e?.message ?? e).slice(0, 160) };
+  }
+  if (key) cache.set(key, result);
+  return result;
+}
+
+/** Drop the cache. For arms, and for a caller that has just repointed an engine deliberately. */
+export function forgetCliVersions(cache = CACHE) { cache.clear(); }

package/driver/engine/common.mjs

@@ -157,7 +157,7 @@ export function runStreamingChild({
   // timeout; NaN/≤0 clamps to 660s so the wall never silently disables. A non-positive or unparseable
   // PIN falls through to that derivation for the same reason — a pin is an instrument, never an off
   // switch. Without it the floor here is 61 SECONDS at the shortest, which is why this clock had no arm
-  // and why 's grace never reached the line below: no test could drive it without sitting for a
+  // and why the grace never reached the line below: no test could drive it without sitting for a
   // minute.
   const pinnedHard = Number(process.env.CLEAROTRON_HARD_MS);
   const hardMs = pinnedHard > 0 ? pinnedHard : (Number(timeoutSec) > 0 ? Number(timeoutSec) + 60 : 660) * 1000;

package/driver/engine/deny-authority-write.mjs

@@ -10,7 +10,7 @@
 //
 // ── WHY A HOOK, AND NOT THE THING YOU WOULD TRY FIRST ────────────────────────────────────────────────
 //
-// 's incident was a live clearance writing two files into the skills tree. The obvious reading is
+// That incident was a live clearance writing two files into the skills tree. The obvious reading is
 // "a seat did something it should not". Reading the grant layer first says otherwise: `buildClaudeArgs`
 // grants that tree with `--add-dir`, WHICH HAS NO READ-ONLY FORM, under `--permission-mode acceptEdits`
 // which auto-approves Write/Edit so each stage can save its output without prompting. The tree was

package/driver/engine/jx-turn.mjs

@@ -78,7 +78,7 @@ export function readJxTuple(tuple, { vendor, authMode, engine }) {
   const usage = u ? { input: u.input ?? 0, output: u.output ?? 0, cacheRead: u.cacheRead ?? 0,
                       cacheWrite: u.cacheWrite ?? 0, total: u.total ?? 0 }
                   : null;
-  // The model that actually served the turn, never the alias we asked for — 's criterion 4 is that
+  // The model that actually served the turn, never the alias we asked for — the criterion 4 is that
   // 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;

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

@@ -38,7 +38,7 @@ const API_KEY = process.env.CLARIVATE_API_KEY || "";
 const BASE = process.env.CLARIVATE_API_BASE || DEFAULT_BASE;
 const tctx = (kind) => ({
   kind,
-  agentId: process.env.CLEAROTRON_GATHER_AGENT || "clawdi",
+  agentId: process.env.CLEAROTRON_GATHER_AGENT || "localagent",
   sessionKey: process.env.CLEAROTRON_GATHER_SESSION_KEY || "",   // run session key — telemetry attribution
   sessionId: process.env.CLEAROTRON_GATHER_SESSION_ID || "",
 });

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

@@ -13,7 +13,7 @@ import { proposeSupplemental } from "./supplemental.mjs";
 const COOKIE = process.env.CORSEARCH_SESSION_KEY || "";
 const tctx = (kind) => ({
   kind,
-  agentId: process.env.CLEAROTRON_GATHER_AGENT || "clawdi",
+  agentId: process.env.CLEAROTRON_GATHER_AGENT || "localagent",
   sessionKey: process.env.CLEAROTRON_GATHER_SESSION_KEY || "",   // run session key — telemetry attribution
   sessionId: process.env.CLEAROTRON_GATHER_SESSION_ID || "",
 });

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

@@ -65,7 +65,7 @@ function loadDeclinationSpec(runDir) {
 
 async function record_declination(params) {
   // `CLEAROTRON_BAND_RUN_DIR` at CALL TIME, and there is no `run_dir` parameter — the run is not the seat's
-  // to name. 's lesson, where an invented fallback sat two lines under a promise never to guess.
+  // to name. That lesson, where an invented fallback sat two lines under a promise never to guess.
   const runDir = String(process.env.CLEAROTRON_BAND_RUN_DIR ?? "");
   if (!runDir) {
     return { error: "this server was started without a run — the driver wires it per run; there is no parameter for it and this tool never guesses one" };

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

@@ -66,7 +66,7 @@ import { MAX_ROWS_PER_CALL } from "../../disposition-call.mjs";
 // can have. Here the serialization is ours, so the class is gone rather than caught.
 //
 // THE SPEC PATH IS THE SEAT'S ONLY PATH ARGUMENT, and it is the same driver-written file the grid tool
-// was given. 's rule: the path is the DRIVER'S, taken from the spec it wrote. Two derivations of one
+// was given. That rule: the path is the DRIVER'S, taken from the spec it wrote. Two derivations of one
 // filename is the drift that cost weeks.
 async function record_dispositions(params) {
   const { grid_spec_path, rows } = params ?? {};

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

@@ -46,7 +46,7 @@ const AUTH = {
 };
 const tctx = (kind) => ({
   kind,
-  agentId: process.env.CLEAROTRON_GATHER_AGENT || "clawdi",
+  agentId: process.env.CLEAROTRON_GATHER_AGENT || "localagent",
   sessionKey: process.env.CLEAROTRON_GATHER_SESSION_KEY || "",
   sessionId: process.env.CLEAROTRON_GATHER_SESSION_ID || "",
 });

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

@@ -30,7 +30,7 @@ serve({
       const ctrl = new AbortController();
       const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
       try {
-        const res = await fetch(url, { redirect: "follow", signal: ctrl.signal, headers: { "user-agent": "cordillera-prelim-fetch/0.1" } });
+        const res = await fetch(url, { redirect: "follow", signal: ctrl.signal, headers: { "user-agent": "cordillera-clearotron-fetch/0.1" } });
         const body = await res.text();
         const text = body.length > MAX_CHARS ? body.slice(0, MAX_CHARS) + `\n…[truncated at ${MAX_CHARS} chars]` : body;
         return { isError: res.ok ? undefined : true, text: `HTTP ${res.status} ${res.statusText} — ${url}\n\n${text}` };

package/driver/engine/mcp/free-tier-server.mjs

@@ -42,7 +42,7 @@ const AUTH = null;
 
 const tctx = (kind) => ({
   kind,
-  agentId: process.env.CLEAROTRON_GATHER_AGENT || "clawdi",
+  agentId: process.env.CLEAROTRON_GATHER_AGENT || "localagent",
   sessionKey: process.env.CLEAROTRON_GATHER_SESSION_KEY || "",
   sessionId: process.env.CLEAROTRON_GATHER_SESSION_ID || "",
 });
@@ -56,7 +56,7 @@ const CAPABILITY_OFFICES = CAPABILITIES.offices.covered.join("+");
 // it a third. It did. This is that third site, and it went on requiring USPTO_LOCAL_DB after the other
 // two stopped.
 //
-// The cost was total. On an EU-only box 's whole path worked — preflight passed, the plan compiled
+// The cost was total. On an EU-only box the whole path worked — preflight passed, the plan compiled
 // with the US split off as a disclosed deferral, the EU entry was executable — and then EVERY register_*
 // tool the seat called was refused here, so the EU half never ran. Everything upstream was right and
 // nothing downstream happened, which is the least legible way for a fix to fail.

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

@@ -79,7 +79,7 @@ export const REGISTER_SERVERS = {
   //   register_search / register_record_fetch — served since the thin days.
   //   register_enumerate     — SERVED and now granted.  built the page loop on the shared kernel;
   //     capabilities.js records the bounds it runs against as live-probed 2026-08-17 (pageSize 100 is the
-  //     API's hard refusal, verified at 200/250/500). This is the tool 's owner-window ceiling is
+  //     API's hard refusal, verified at 200/250/500). This is the tool the owner-window ceiling is
   //     passed into (OWNER_SCOPED_WINDOW → ceilingFor → makeEnumerate), so withholding it put that
   //     criterion out of reach of any round.
   //   register_execute_plan  — SERVED and now granted. Two corrective-ladder hints name it unconditionally
@@ -188,7 +188,7 @@ export const REGISTER_SERVERS = {
 // (server-tools-granted-or-stated.test.mjs: every record tool has exactly one granting stage).
 const RECORDING_SERVER = "recording-server.mjs";
 const RECORDING = Object.freeze({
-  // FIRST OCCUPANT — blind-frame ('s transport, wired by, dictation deleted by).
+  // FIRST OCCUPANT — blind-frame (the transport, wired by, dictation deleted by).
   //
   // `seatWrites: false` is the half, and it is the only thing that closes the regression door BY
   // CONSTRUCTION rather than by prose. Once the driver writes blind-frame-model.json, nothing this stage is
@@ -686,7 +686,7 @@ const LOCAL = {
   "unit-note": { script: "unit-note-server.mjs", tools: ["record_unit_note"] },
   // ── RECORDING — DERIVED from the registry above, one entry per stage, in registry order ──────────
   //
-  // These rows were hand-written here until 's collapse. They are LAST in this object on purpose:
+  // These rows were hand-written here until the collapse. They are LAST in this object on purpose:
   // LOCAL_SERVER_SCRIPTS below is `Object.values(LOCAL).map(...)`, so insertion order is part of its
   // value, and `recording-server.mjs` appearing TWICE is the evidence both keys resolve to the one
   // module. recording-grant-preservation.test.mjs pins that array verbatim, duplicates included.
@@ -695,7 +695,7 @@ const LOCAL = {
 };
 
 // The scripts LOCAL grants, DERIVED. Exported because the server census would otherwise recite them, and
-// a recited list is one more population to keep in sync by hand — 's census derived the register
+// a recited list is one more population to keep in sync by hand — the census derived the register
 // half from REGISTER_SERVERS and hardcoded this half, so wiring a new local server left it reading as
 // ungranted. Derive both halves or neither.
 export const LOCAL_SERVER_SCRIPTS = Object.freeze(Object.values(LOCAL).map((e) => e.script));
@@ -873,7 +873,7 @@ export function buildGatherMcpConfig(groups = [], { sessionKey, agent, runDir, r
   // There is no production caller to break: `driver/gateway.mjs` is the only non-test call site in the
   // tree and it always passes the run it is dispatching for. A caller that reaches this without one has
   // a defect a refusal names immediately, instead of a record body somewhere its run will never look.
-  // ORDER MATTERS: resolve the register provider FIRST. 's "CLEAROTRON_DATABASE is not set"
+  // ORDER MATTERS: resolve the register provider FIRST. That "CLEAROTRON_DATABASE is not set"
   // is the more fundamental refusal and the one an operator acts on, so it must still come out ahead of
   // this one — a box with neither a provider nor a run should be told about the provider.
   if (localKeys.has("register")) {
@@ -964,7 +964,7 @@ export function toolGroupsForStage(name = "") {
   // the issue predicts, on the one matter where the confirmation step was most clearly indicated (four
   // `loaded` meaning rulings, see).
   //
-  // This changes engine behaviour and ships `status:merged-awaiting-e2e`, which 's out-of-scope block
+  // This changes engine behaviour and ships `status:merged-awaiting-e2e`, which the out-of-scope block
   // anticipates in as many words. The scoping is doctrine's, not the grant's: SKILL.md already caps it at
   // one probe per review and requires the query and its result recorded verbatim.
   // ── THE ONE BRANCH THAT RETURNS RETRIEVAL *AND* RECORDING, and it has to be here ────────────────
@@ -1027,7 +1027,7 @@ export function toolGroupsForStage(name = "") {
   //
   // NOT a prefix test, for either form. A prefix would hand the grant to any future stage whose name
   // merely began with a recording stage's. The base row must SAY it fans out — declaration, not
-  // inference, the same principle as 's declared phase.
+  // inference, the same principle as the declared phase.
   for (const [sep, flag] of SUFFIX_FORMS) {
     const at = name.lastIndexOf(sep);
     if (at <= 0) continue;
@@ -1153,7 +1153,7 @@ export function recordAxisFor(name = "") {
 // gains `--mcp-config`, `--strict-mcp-config` AND `--allowedTools` where it previously had none. That is
 // a change in KIND and the right one — these stages become constrained for the first time — but it must
 // be asserted at the argv level, not inferred from this map.
-// FIRST OCCUPANT — blind-frame ('s transport, wired here). SECOND — skeptic.
+// FIRST OCCUPANT — blind-frame (the transport, wired here). SECOND — skeptic.
 //
 // The safety basis is a SAMPLE and is stated as one: O3c measured blind-frame at 0 Bash calls across 15
 // attempts, alone among the eleven tool-free stages. That is why it converted first. On attempt 16 a
@@ -1189,7 +1189,7 @@ export const RECORDING_STAGES = Object.freeze(Object.fromEntries(
 //
 // ── DELIBERATELY NOT DERIVED FROM THE REGISTRY, unlike the four declarations above it ──────────────
 //
-// 's collapse made the LOCAL entries, the group resolution, the stage→group map and RECORDING_STAGES
+// That collapse made the LOCAL entries, the group resolution, the stage→group map and RECORDING_STAGES
 // derive from one registry. This table did NOT move, and the reason is the whole value of it: O1 asserts
 // the resolved grant EQUALS this row. Derive it from the same registry the grant derives from and O1
 // compares a value with itself — a guard turned tautology inside the PR that was meant to strengthen it.
@@ -1211,7 +1211,7 @@ export const RECORDING_TOOLS = Object.freeze({
     "mcp__recording-matter-frame__search_run_artifacts"]),
   skeptic: Object.freeze(["Read", "mcp__recording-skeptic__record_skeptic",
     "mcp__recording-skeptic__search_run_artifacts"]),
-  // 's third conversion. `Read` and its one record tool: the stage's reads are its two named input
+  // That third conversion. `Read` and its one record tool: the stage's reads are its two named input
   // files, which the seeded grant serves, and it gets no search tool because a stage with an enumerable
   // read set does not need one. BY HAND, like every row here — deriving it from the registry would make
   // O1 compare a value with itself.
@@ -1370,7 +1370,7 @@ export function seatWritesForGroups(groups = []) {
 }
 
 /**
- * THE ENUMERATION, derived and not hand-listed ('s third proof requirement).
+ * THE ENUMERATION, derived and not hand-listed (the third proof requirement).
  *
  * A naive grep for `seatWrites: false` returns TEN hits and the population is EIGHT: two of the hits are
  * comment text — one in the blind-frame FIRST OCCUPANT note, one in `allowedToolsFor`'s own

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

@@ -135,7 +135,7 @@ function tellObligations(spec, ledgerJson) {
     }, null, 2) + "\n",
   );
   // B — NO SEAT-FACING FORM IS WRITTEN, ANY MORE, BY ANYONE. The -era write-back that lived here
-  // (a union of the seat's file bytes into a rebuilt seat-facing form, plus 's whose-bytes referee)
+  // (a union of the seat's file bytes into a rebuilt seat-facing form, plus the whose-bytes referee)
   // died with the form path: the seat records rulings only through `record_dispositions`, the
   // accumulator in `_driver/` is the one copy and the tool is its writer mid-turn. What the seat needs
   // at this moment — the obligations, the candidates, the positions and the recording route — is all in

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

@@ -24,12 +24,12 @@
 //
 // `CLEAROTRON_BAND_RUN_DIR`, read at CALL TIME. `serverEnv()` (gather-config.mjs:162) sets it for every local
 // server, not only band. There is no `run_dir` parameter and there must not be one — the lesson is
-// 's, where an invented `CLEAROTRON_RUN_DIR` fallback sat two lines under a sentence promising the tool
+// the earlier one, where an invented `CLEAROTRON_RUN_DIR` fallback sat two lines under a sentence promising the tool
 // never guesses a run. Call time rather than module load: stdio-server.mjs:29-33 states why for this
 // exact variable.
 // ── THE SECOND CAPABILITY CLASS: A SCOPED READ, and why it does not break the sentence above ────────
 //
-// `search_run_artifacts` is the skeptic's sanctioned read surface ('s ratification hold, unlock
+// `search_run_artifacts` is the skeptic's sanctioned read surface (the ratification hold, unlock
 // path 1): a literal substring search over the calling run's OWN artifact tree, replacing the Bash
 // reads O3c measured the stage using. It still dials nothing and writes nothing — the category's
 // promise is about RETRIEVAL and writes, and a read bounded to CLEAROTRON_BAND_RUN_DIR widens neither.
@@ -464,7 +464,7 @@ serve({
               value: { type: "string", description: "The search term itself — never a label, never an enumeration." },
               // THE CANONICAL ENUM, imported — never a second copy. `parseVariantManifestModel` refuses
               // anything outside it, so a hand-typed list here could drift into promising a category the
-              // parser rejects. 's brief reads the same constant.
+              // parser rejects. That brief reads the same constant.
               category: { type: "string", enum: [...VARIANT_CATEGORIES] },
               rationale: { type: "string" },
               romanization: { type: "string", description: "Latin-script form. NON-LATIN VALUES ONLY — a romanisation on a Latin value is refused as an orphan." },
@@ -848,7 +848,7 @@ serve({
     // The reviewer is the report's only check, and it wrote its own review as prose. Everything
     // downstream then parsed that prose back: the verdict token, the flag list, the `[kind:]`/`[on:]`
     // channels, and the count that decides whether a BLOCKING is degenerate. The seat chose the
-    // enumeration style, so the parse could miss it — 's lettered flags were invisible
+    // enumeration style, so the parse could miss it — the lettered flags were invisible
     // for exactly that reason. Handing values makes the style the driver's, so a flag the parse cannot
     // see stops being possible rather than being detected afterwards.
     //
@@ -1120,6 +1120,10 @@ serve({
                   properties: {
                     recordId: { type: "string", description: "Copied VERBATIM from the filings you were given." },
                     read: { type: "string", description: "What you concluded about THIS filing." },
+                    // Declared here for the reason the comment above gives: `additionalProperties: false`
+                    // means an undeclared key is a contradiction between the prose and the schema, and the
+                    // seat resolves it whichever way it happens to trust.
+                    band: { type: "string", description: "OPTIONAL — how you rate THIS filing, in the framework's own band words. Send it when you formed a view on the filing itself; the card prints it as that filing's rating. Omit it and your read still prints, with no rating claimed." },
                   },
                 },
               },

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

@@ -17,7 +17,7 @@ const API_KEY = process.env.SIGNA_API_KEY || "";
 const BASE = process.env.SIGNA_BASE_URL || DEFAULT_BASE;
 const tctx = (kind) => ({
   kind,
-  agentId: process.env.CLEAROTRON_GATHER_AGENT || "clawdi",
+  agentId: process.env.CLEAROTRON_GATHER_AGENT || "localagent",
   sessionKey: process.env.CLEAROTRON_GATHER_SESSION_KEY || "",   // run session key — telemetry attribution
   sessionId: process.env.CLEAROTRON_GATHER_SESSION_ID || "",
 });

package/driver/engine/mcp/uspto-local-server.mjs

@@ -43,7 +43,7 @@ const DB_PATH = process.env[DEFAULT_DB_ENV] || "";
 const AUTH = { dbPath: DB_PATH };
 const tctx = (kind) => ({
   kind,
-  agentId: process.env.CLEAROTRON_GATHER_AGENT || "clawdi",
+  agentId: process.env.CLEAROTRON_GATHER_AGENT || "localagent",
   sessionKey: process.env.CLEAROTRON_GATHER_SESSION_KEY || "",   // run session key — telemetry attribution
   sessionId: process.env.CLEAROTRON_GATHER_SESSION_ID || "",
 });

package/driver/engine/openai-agent.mjs

@@ -446,7 +446,7 @@ function settleTuple({ r, ev, resumeRef }) {
     killed, wall: r.wall,
     stdout: text, stderr: stderrOut, laneWaitMs: 0,
     json, usage,
-    // MODEL GAUGE (,): the id codex recorded for this turn — from its session rollout under
+    // MODEL GAUGE (): the id codex recorded for this turn — from its session rollout under
     // this run's own CODEX_HOME, since the event stream states none. Still two states and never one:
     // null = "this engine did not report", never the requested tier wearing the word "actual".
     // gateway.mjs records the absence as modelBasis:"unknown".
@@ -478,7 +478,7 @@ function settleTuple({ r, ev, resumeRef }) {
       mcpRefused: mcpToolGauge(ev).mcpToolCallsRefused > 0 || undefined,
       rateLimited: rateLimited || undefined,
       rateLimitBasis: rateLimited ? "text-match" : undefined,
-      // resetsAtBasis (, 2026-08-20): same honesty as rateLimitBasis one line up, for the reset
+      // resetsAtBasis (2026-08-20): same honesty as rateLimitBasis one line up, for the reset
       // CLOCK rather than the classification. codex states its reset as human prose with NO timezone
       // ("try again at Aug 22nd, 2026 9:06 AM"), so the ISO we derive is a reading of that prose in the
       // box's own zone — never a provider fact. Absent when no hint was found, exactly as `resetsAt` is.

package/driver/engine-build.mjs

@@ -87,11 +87,11 @@ export function resetEngineCommit() { cached = undefined; source = undefined; re
 // So attribution has been a reflog reconstruction: join a checkout's reflog against each run's
 // `startedAt`. That reconstruction expires with the reflog, cannot survive a re-clone, is wrong for
 // every run made while the checkout sat detached, and mixes a local-time reflog against UTC stamps.
-// It decided three certifications in one morning (,) and produced two near-miss
+// It decided three certifications in one morning () and produced two near-miss
 // wrong rulings in two days.
 //
 // A SIBLING, NOT A WIDER RETURN TYPE. `engineCommit()` keeps its bare-string contract exactly:
-// 's guard pins its import line by regex AND pins the literal `engineCommit: engineCommit` in
+// That guard pins its import line by regex AND pins the literal `engineCommit: engineCommit` in
 // the publisher, four consumers read the string, and `scripts/freeze-example-run.mjs` asserts in prose
 // that it "is cached to one value and cannot differ between the two". Widening it would break all of
 // that to add a field only one new caller wants.

package/driver/enqueue-schema.mjs

@@ -237,7 +237,7 @@ function niceClassErrors(list, label) {
 //   and reaches the report body, where it REVERSES THE DISPLAY of everything after it. The report is a
 //   legal deliverable that goes to a client.
 //
-//   A zero-width joiner makes "AUR\u200DORA" render as AURORA and compare unequal to it, so
+//   A zero-width joiner makes "IRON\u200DWHISK" render as IRONWHISK and compare unequal to it, so
 //   `selfExclusionOwners` and dedup both miss a mark a human reads as the account's own.
 //
 //   NFD "SIRÈNE" !== NFC "SIRÈNE", so one mark submitted two ways is two matters, two searches, two bills.
@@ -285,7 +285,7 @@ const markNameSites = (job) => {
   for (const f of ["markName", "name"]) if (job?.[f] != null) sites.push([f, () => job[f], (v) => { job[f] = v; }]);
   if (Array.isArray(job?.marks)) job.marks.forEach((m, i) => {
     // A BARE STRING IS A MARK NAME, and this shape reaches validateJob unconverted. `assembleFromFlags`
-    // turns `marks: ["AURORA"]` into `[{ name: "AURORA" }]`, so every door that assembles is already
+    // turns `marks: ["IRONWHISK"]` into `[{ name: "IRONWHISK" }]`, so every door that assembles is already
     // covered — but the runner's wall calls validateJob({ atClaim: true }) on the MANIFEST AS IT SITS ON
     // DISK, which nothing re-assembles. The kebab-collision check below reads the same shape for exactly
     // that reason. Walking only `m.name` would leave this guard covering every door except the one it
@@ -663,7 +663,7 @@ export function validateJob(job, { atClaim = false } = {}) {
   // Every other check in this build lives at one or two of them: `checkClearanceScopeRules` runs at the
   // runner, the portal and plan_run but at neither start_run nor the CLI; the mark budget and the
   // availability gate run at the runner alone. A rule placed at a door is a rule the other doors do not
-  // have, and 's acceptance test is that all three refuse the same request in the same words.
+  // have, and the acceptance test is that all three refuse the same request in the same words.
   //
   // WHAT IS JUDGED HERE: everything the REQUEST states. Each of the offering's illegal shapes is visible
   // without resolving anything — a narrowed Global preliminary, a two-country Full country search, a
@@ -778,16 +778,16 @@ export function validateJob(job, { atClaim = false } = {}) {
   // that would drop the customer's platforms, self-exclusion seed and the framework that RATES the matter".
   // A MISSING key returns generic in silence. Both produce the same wrong deliverable, and only one says so.
   //
-  // It has already happened: a paid Zephyr Beverages clearance was rated on the Generic default scale because the
-  // request named the customer in prose and left the account field empty. Nothing objected. A person
-  // noticed hours later and re-ran it.
+  // It has already happened: a paid clearance for a test account was rated on the Generic default scale
+  // because the request named the customer in prose and left the account field empty. Nothing objected.
+  // A person noticed hours later and re-ran it.
   //
   // WHY THIS IS NOT SIMPLY "customer present, key absent". That shape is byte-identical to a LEGITIMATE
   // third-party search — a firm asking us to clear a mark for their own client, who is not our account —
   // and the applicant deliberately never selects a profile, because a third-party search must never inherit
   // a customer's exclusions. Clarifying on that shape alone would bounce real work every day.
   //
-  // The discriminator is the ROSTER. The Zephyr Beverages request differed in one way that matters: we hold an
+  // The discriminator is the ROSTER. That request differed in one way that matters: we hold an
   // account by that name. A named applicant we have no account for is a third-party search and runs
   // untouched; a named applicant who IS one of our customers, with no key, is ambiguous in a way only a
   // person can settle — did intake forget to tag it, or is this genuinely a search against a name that
@@ -965,7 +965,7 @@ export const EXAMPLE_JOB = {
   rawRequest: "<the verbatim forwarded email text, untouched — archived as inbound-request.txt (§A5)>",
   brief: "<the confirmation brief exactly as sent to the requester — archived as confirmation-brief.md>",
   deadline: "2026-06-20T17:00:00Z",     // optional; drives the §A3 deadline-envelope arithmetic
-  profileKey: "aurora",              // D4.1: the customer ACCOUNT the intake AI resolved → selects the
+  profileKey: "demo-brand-owner",    // D4.1: the customer ACCOUNT the intake AI resolved → selects the
                                         // profile (marketplaces/classes/delivery/appetite); omit ⇒ generic
   product: "multi-country-focus-search",// WHICH OF THE FOUR (OPTIONAL): one of products.mjs PRODUCT_IDS.
                                         // Omit ⇒ the project/customer defaultProduct, else the product
@@ -983,11 +983,11 @@ export const EXAMPLE_JOB = {
   // deliveryRoute: "portal",           // OPTIONAL: "email" (default) or "portal" — a portal-route packet
                                         // is mark_sent by the courier WITHOUT an email send.
   // parentRunId: "novapulse-cedar",    // OPTIONAL escalation lineage: the run this one escalates from
-                                        // (e.g. a knockout HIGH mark → this prelim). Recorded, not yet resolved.
+                                        // (e.g. a knockout HIGH mark → this clearotron). Recorded, not yet resolved.
   projectKey: "console-ecosystem",      // spec 62 (OPTIONAL): the PROJECT/engagement under the customer whose
                                         // overlay (its own marketplaces/classes/sector/posture) rates this
                                         // matter; omit ⇒ runs on the customer profile. Unknown key ⇒ clarify.
-  customer: "Aurora Interactive",                // applicant/owner → affiliate self-exclusion set (§B3.2)
+  customer: "Demo Brand Owner",                  // applicant/owner → affiliate self-exclusion set (§B3.2)
   customerUnknown: false,               // B5: true when the applicant is neither stated nor forwarder-implied —
                                         // arms candidate-self classification + the late-bind watch (NEVER inferred from the mark)
   // caseLaw — NOT A FIELD. The case-law and opposition reading is what a Full country search IS

package/driver/enqueue.mjs

@@ -245,7 +245,7 @@ async function main(argv) {
   try { job = assembleFromFlags(flags); } catch (e) { fail(`could not assemble the job: ${e.message}`); }
   if (!job.forwarder) fail("missing --forwarder — the requester/reply-routing key; the delivery packet needs it to route the report (there is deliberately no default)", 2);
   // THE EARLY --product CHECK IS GONE, and its deletion is the fix. It fired before validateJob and said
-  // the same thing in different words — `--product "prelim"` rather than `product "prelim"`, and without
+  // the same thing in different words — `--product "clearotron"` rather than `product "clearotron"`, and without
   // the `(or omit it for the account's default)` clause, which is the one clause that tells a requester
   // the field is optional. So the CLI's real answer to a typo was not the shared one, and a test that
   // started at assembleFromFlags could never see it. validateJob refuses it now, in the sentence every

package/driver/envelope-settle.mjs

@@ -196,7 +196,7 @@ export async function settleReceipt({ P, plan, receipt, dispatch = null, rejoin
 
 /**
  * The settled facts a digest dispatch needs, as a message section — mechanical only, quoting the executor's
- * own reason. Every digest pass gets this, not just the first: 's dispatch hint reaches FRESH dispatches
+ * own reason. Every digest pass gets this, not just the first: the dispatch hint reaches FRESH dispatches
  * by construction (stageOnce ignores `extra` when opts.followup is set), and the flush passes it misses are
  * exactly where the evidence run burned 2,908 seconds failing the same validator twice more.
  *

package/driver/evidence-claim-invariant.mjs

@@ -26,11 +26,11 @@
 // reading only the claim misses it: the increase is in the evidence stamp.
 //
 // THE LADDER ALREADY EXISTS, so this introduces no vocabulary. `basis` is the run's own certainty
-// ordering and 's demotion is its enforcement; `basis-derivation.json` records every demotion with
+// ordering and the demotion is its enforcement; `basis-derivation.json` records every demotion with
 // its reason and its uri. Arm B is a comparison against an artifact the driver already writes, which is
 // why it needs no fetch ledger and no new plumbing.
 //
-// REPORTS, NEVER THROWS. The caller decides what a violation costs — 's lesson is that a guard
+// REPORTS, NEVER THROWS. The caller decides what a violation costs — the lesson is that a guard
 // which can kill a run is a guard that eventually kills a run over its own false positive.
 
 /** The run's own certainty ordering for a meter's basis. Higher is more certain. */

package/driver/feedback-store.mjs

@@ -19,7 +19,7 @@
 // come from report-data.json; the disposition comes from findings.json beside it in the same run dir,
 // because report-data.json is the CLIENT cut and stopped serving the engine's placement key. A
 // reader who finds the ordinal now points at `KURENA / Manageable / rebuttable` when the flag says
-// `PETCARY / Medium / conceded` knows the run was republished, which is exactly the thing a bare id
+// `BURROWELL / Medium / conceded` knows the run was republished, which is exactly the thing a bare id
 // would have hidden.
 
 import { randomUUID } from "node:crypto";