clearotron 0.2.3 → 0.2.4

package/bin/onboard.mjs

@@ -671,24 +671,114 @@ export async function askSignIn(io, { localAccount = "user", staffLabel = "Staff
  * Was `resolveClaudeBin`. The body never had anything claude-specific in it; the NAME was the last place
  * this file still assumed one engine, and a name that lies is how the second adapter stayed invisible.
  */
-export function resolveEngineBin(bin) {
+export function resolveEngineBin(bin, { env = process.env, wsl = null, onWindowsDrive = null } = {}) {
+  // The predicate, not just the pattern, because /mnt/c cannot be created on a Linux runner without
+  // root — so an arm that could only supply a PATH could never drive the skip, and the branch would
+  // ship asserted by nobody. `ON_A_WINDOWS_DRIVE` is held to real paths by its own arm.
+  const onDrive = onWindowsDrive ?? ((x) => ON_A_WINDOWS_DRIVE.test(x));
   // driver/engine/anthropic-agent.mjs — `CLEAROTRON_CLAUDE_PATH || "claude"`; openai-agent.mjs — the same
   // shape on `CLEAROTRON_CODEX_PATH || "codex"`. A RELATIVE path is the trap for BOTH: stage subprocesses are
   // spawned with cwd set to the RUN DIRECTORY (driver/engine/common.mjs resolveSpawnCwd, shared by the
   // two adapters), so a relative binary resolves against a directory that did not exist at setup time.
+  const underWsl = wsl ?? isWsl({ env });
   if (bin.includes("/")) {
     const abs = resolve(bin);
-    if (!isAbsolute(bin)) return { path: abs, executable: isExec(abs), relative: true };
-    return { path: abs, executable: isExec(abs), relative: false };
+    // A PATH SOMEBODY TYPED IS NOT OVERRULED, only reported. The reader stated this one, and silently
+    // resolving somewhere else would be the launcher moving a door off a port that was asked for.
+    return { path: abs, executable: isExec(abs), relative: !isAbsolute(bin), windowsShim: underWsl && onDrive(abs), skipped: [] };
   }
-  for (const dir of (process.env.PATH || "").split(delimiter).filter(Boolean)) {
+  // ── UNDER WSL, THE WINDOWS PATH IS APPENDED TO THIS ONE ────────────────────────────────────────
+  //
+  // So `claude` on a fresh WSL2 Ubuntu resolves to /mnt/c/…/claude — the WINDOWS shim — before any
+  // Linux install is reached, and it is executable by every test this makes. It then fails the proof
+  // turn as "not signed in", because the credential it is looking for is the Linux one, and a reader
+  // is sent to fix a sign-in that was never the problem. Reported from a real WSL2 attempt.
+  //
+  // SKIPPED, AND NAMED. Passing over a candidate silently would leave the reader with "no binary
+  // found" on a machine where `which claude` prints one, so the skips travel back for the caller to
+  // say out loud. A missing Linux install then reports as missing, which is the true answer.
+  const skipped = [];
+  for (const dir of (env.PATH || "").split(delimiter).filter(Boolean)) {
     const p = join(dir, bin);
-    if (isExec(p)) return { path: p, executable: true, relative: false };
+    if (!isExec(p)) continue;
+    if (underWsl && onDrive(p)) { skipped.push(p); continue; }
+    return { path: p, executable: true, relative: false, windowsShim: false, skipped };
   }
-  return { path: null, executable: false, relative: false };
+  return { path: null, executable: false, relative: false, windowsShim: false, skipped };
+}
+
+/** A path on a Windows drive as WSL mounts it. */
+export const ON_A_WINDOWS_DRIVE = /^\/mnt\/[a-z]\//i;
+
+/**
+ * Whether this is a Linux running under Windows.
+ *
+ * BOTH SIGNALS INJECTABLE, for the reason `platformEngineRefusal` gives: the readers this protects
+ * are the ones who cannot run this suite to find out, so a Linux runner has to be able to drive both
+ * answers rather than read the source and agree with it.
+ *
+ * A READ THAT FAILS ANSWERS "NOT WSL", and that is the direction that changes nothing: it leaves the
+ * resolution exactly as it was before this existed. Claiming WSL on a could-not-read would start
+ * refusing candidates under /mnt on an ordinary Linux box with an ordinary mount.
+ */
+export function isWsl({ env = process.env, procVersion = null } = {}) {
+  if (String(env.WSL_DISTRO_NAME ?? "").trim()) return true;
+  if (String(env.WSL_INTEROP ?? "").trim()) return true;
+  const v = procVersion ?? (() => { try { return readFileSync("/proc/version", "utf8"); } catch { return ""; } })();
+  return /microsoft|wsl/i.test(v);
+}
+
+/**
+ * What to say about candidates passed over because they sit on a Windows drive — or `null` when none
+ * were. Plural because a reader can have both a shim and a wrapper on PATH.
+ */
+export function windowsShimNote(skipped, bin) {
+  if (!skipped?.length) return null;
+  return `ignored ${skipped.length === 1 ? "a `" + bin + "` on a Windows drive" : skipped.length + " `" + bin + "` binaries on Windows drives"} `
+    + `(${skipped.join(", ")}): WSL appends the Windows PATH to this one, and a Windows build cannot run a `
+    + `stage here — it fails the proof turn as "not signed in" while holding a credential this side never `
+    + `wrote. Install it inside the Linux distribution instead.`;
 }
 const isExec = (p) => { try { accessSync(p, constants.X_OK); return statSync(p).isFile(); } catch { return false; } };
 
+/**
+ * What doctor says about the engine on a platform the run door refuses outright, or `null` where the
+ * ordinary binary checks apply.
+ *
+ * `platform` IS INJECTABLE, and for the reason `preflightEngineBinary` gives at its own refusal: the
+ * population this protects is the one that cannot run this suite to find out. An arm on a Linux runner
+ * has to be able to ask what a Windows reader is shown, or the Windows text is asserted by nobody —
+ * and reading `process.platform` inside the caller would make that arm read source instead of driving
+ * the answer.
+ */
+export function platformEngineRefusal({ platform = process.platform } = {}) {
+  if (platform !== "win32") return null;
+  return "this engine does not run on native Windows — stage subprocesses are spawned with POSIX path "
+    + "and process semantics, so the run door refuses before it reads PATH. Run it under WSL2, or in "
+    + "the devcontainer. The demo works here as it is: it replays finished reports and needs no engine.";
+}
+
+/**
+ * How to leave demo mode, which is not the same instruction everywhere.
+ *
+ * On the platform the run door refuses, the standard advice is a loop: install a CLI the reader may
+ * already have, then restart a service — neither of which can change the answer, because the refusal
+ * is about the platform rather than the program. Naming WSL2 is the only instruction that ends it.
+ */
+export function leaveDemoAdvice(engSpec, { platform = process.platform } = {}) {
+  if (platform === "win32") {
+    return [`To leave demo on Windows: run the product under WSL2, or in the devcontainer. Installing `
+      + `${engSpec.vendor}'s CLI natively will not change this — the run door refuses on the platform, `
+      + "not on the program."];
+  }
+  return [
+    `To leave demo: install ${engSpec.vendor}'s CLI (\`${engSpec.fallback}\`)`
+      + `${engSpec.install ? ` with \`${engSpec.install}\`` : ""}, then ${engSpec.signIn}.`,
+    "Restart any running engine service afterwards so it re-reads its PATH: the portal reports what the "
+      + "engine saw when it last started, and it will not notice a new install until then.",
+  ];
+}
+
 /**
  * The engine menu, built from the driver's registry so the wizard cannot offer an adapter that does not
  * exist — or hide one that does. Same guarantee the register-provider list has.
@@ -1201,7 +1291,28 @@ export async function runCheck() {
     const binSet = !!binEff;
     const binSetting = binEff?.v || engSpec.fallback;
     const bin = resolveEngineBin(binSetting);
-    if (bin.executable && !bin.relative) ok(`${bin.path}`);
+    // ── NATIVE WINDOWS IS ANSWERED HERE, BEFORE ANY PATH IS RESOLVED OR REPORTED ──────────────────
+    //
+    // `resolveEngineBin` tests a candidate with `accessSync(X_OK)` and `isFile()`. Windows has no
+    // execute bit, so X_OK is satisfied by any file that exists — and an npm global install writes
+    // BOTH `claude`, an extensionless shell script for Git Bash, and `claude.cmd`. The POSIX test
+    // passes on the shell script, so this line reported the engine FOUND at a path CreateProcess
+    // cannot start, and the probe then failed with `spawn claude ENOENT`. Reported from a real
+    // Windows run, 2026-09-09.
+    //
+    // RESOLVING `claude.cmd` INSTEAD WOULD MOVE THE CONTRADICTION, NOT REMOVE IT.
+    // `preflightEngineBinary` refuses native Windows by name, and the run door calls it
+    // unconditionally — so a clearance cannot run here whatever this line finds. Making the probe
+    // succeed would produce a doctor that says ready, a probe that passes, and a run that refuses
+    // anyway: the same disagreement one step later, and more convincing for having spawned something.
+    //
+    // So doctor says what the run door says. That is the property — the two agree — and the reader
+    // gets one refusal they can act on instead of a found-then-failed sequence that sends them
+    // looking for a PATH problem they do not have. The demo is unaffected: it replays finished runs
+    // and needs no engine, which is why four reports published on that same Windows box.
+    const platformRefusal = platformEngineRefusal();
+    if (platformRefusal) problem(platformRefusal);
+    else if (bin.executable && !bin.relative) ok(`${bin.path}`);
     // The FACT only. It used to carry "install it for a real run (`npm run example` needs no engine)",
     // which is the absence framing was filed about — and it now says half of what the MODE line
     // below says, in worse words. One statement of a state, in the place that states states.
@@ -1212,6 +1323,15 @@ export async function runCheck() {
     else if (bin.relative) problem(`${engSpec.env}="${binSetting}" is RELATIVE — stage subprocesses run with cwd set to the run directory, so it will not resolve there. Use an absolute path (${bin.path} from here)`);
     else if (!bin.path) problem(`${engSpec.env}="${binSetting}" resolves to nothing on PATH`);
     else problem(`${engSpec.env}="${binSetting}" → ${bin.path} is not an executable file`);
+    // SAID AFTER THE CHAIN ABOVE, AND OUTSIDE IT. This block is one if/else-if ladder, so a statement
+    // placed between two of its clauses re-parents every clause below onto the new `if` — measured:
+    // it made doctor report an executable mock binary as "not an executable file", because the ladder's
+    // tail became the else of THIS condition. Said whether or not a binary was found: under WSL a
+    // Windows build on the appended PATH is passed over, and if a Linux one was found the reader still
+    // needs to know which of the two they have, while if none was, "no binary" over a machine whose own
+    // `which` prints one is a refusal nobody can act on.
+    const shimNote = windowsShimNote(bin.skipped, engSpec.fallback);
+    if (shimNote) info(shimNote);
 
     // ── — WHICH MODE THIS INSTALL IS IN, said as a mode rather than as a list of absences ──────
     //
@@ -1242,7 +1362,15 @@ export async function runCheck() {
     if (installMode === ENGINE_MODES.DEMO) {
       info("MODE: demo — everything works except starting a NEW search. The example report, its audit trail "
         + "and the MCP connection are live right now; `npm run example` needs no engine.");
-      info(`To leave demo: install ${engSpec.vendor}'s CLI (\`${engSpec.fallback}\`), then ${engSpec.signIn}.`);
+      // NAMES THE COMMAND, AND THE RESTART. The settings page says both now, and a doctor that named
+      // the program but not how to install it — or that left out the restart, which is what actually
+      // unsticks a reader who has just installed it — would be the third opinion this issue exists to
+      // remove. Same words on all three surfaces, taken from the same table.
+      // THE WAY OUT IS NOT THE SAME ON EVERY PLATFORM, and on the one where it differs the standard
+      // advice is a loop: a Windows reader is told to install a CLI they may already have, and then to
+      // restart a service — neither of which can change the answer, because the refusal is about the
+      // platform rather than the binary. Naming WSL2 is the only instruction that ends this state.
+      for (const line of leaveDemoAdvice(engSpec)) info(line);
     } else {
       info("The engine program is installed. Whether it is signed in cannot be read from disk: run "
         + "clearotron doctor --probe-engine to find out.");
@@ -2257,7 +2385,7 @@ export async function runCheck() {
     //
     // `describeDoorState` was written for exactly this block and then never called from it: the split
     // it encodes sat in `shared/client-door.mjs` with no caller in `bin/` or `driver/`, while doctor
-    // went on printing the three sentences the split replaces. The defect role-e2e measured is one of
+    // went on printing the three sentences the split replaces. The defect testing measured is one of
     // them — a `connect` that died at `daemon-reload` had already written the fence and placed both
     // units, and doctor said "the client door is on" over a unit that was inactive with nothing on its
     // port. Every angle read as configured, because configured is all anything asked.
@@ -2730,7 +2858,32 @@ try {
     if (!pick.id) { sayNoEngine(); break; }
     const eng = ENGINE_BINARIES[pick.id];
 
+    // ── NATIVE WINDOWS IS ANSWERED HERE TOO, AND THE ESCAPE IS OFFERED RATHER THAN LEFT ON A MENU ──
+    //
+    // Doctor learned this and the wizard did not, and the gap is worse than it sounds: the two "no
+    // engine" escapes below both sit behind "no usable binary", and on Windows that is FALSE. X_OK is
+    // satisfied by any file that exists, so the wizard says "found C:\...\claude", walks past both
+    // escapes, asks which lane pays, spends a proof turn, and meets `spawn claude ENOENT`. The only
+    // prompt left then defaults to No and returns to the engine menu — with nothing changed between
+    // iterations, on either lane. Reported from a real Windows run: the menu's last row was the one
+    // way out and nothing on screen said so.
+    //
+    // So the refusal is stated before a candidate is resolved, and finishing with no engine is OFFERED
+    // rather than being a row the reader has to notice. Declining leaves them on the menu exactly as
+    // before, which is the branch that was already there.
+    const wizardRefusal = platformEngineRefusal();
+    if (wizardRefusal) {
+      problem(wizardRefusal);
+      if (await confirm("Finish setup with no engine configured?", true)) { sayNoEngine(); break engine; }
+      continue;
+    }
+
     let bin = resolveEngineBin(process.env[eng.env] || eng.fallback);
+    // Under WSL the Windows build on the appended PATH has been passed over. Said before the install
+    // offer below, because otherwise a reader whose Linux install is genuinely missing is asked to
+    // install a binary their own `which` already prints — and would decline for the wrong reason.
+    const shimNote = windowsShimNote(bin.skipped, eng.fallback);
+    if (shimNote) info(shimNote);
     if (!(bin.executable && !bin.relative) && eng.install) {
       // ── — INSTALLING IT IS ONE COMMAND, AND WE USED TO STOP AT A SENTENCE ───────────────────
       //
@@ -2929,7 +3082,20 @@ try {
         break engine;
       }
       problem(probeFailureText(v));
+      // ── THE ENGINE'S OWN LAST LINES, UNDER EVERY VERDICT, ON BOTH LANES ──────────────────────────
+      //
+      // This used to be `if (v.detail)`, so a verdict carrying no detail printed a headline and nothing
+      // else — and the reader had a classification with no evidence to check it against. That is the
+      // worst shape for a heuristic: the signed-out test is a text match over the engine's output, it
+      // matches broadly on purpose, and a reader shown only its conclusion cannot tell a genuinely
+      // signed-out CLI from an unrelated failure whose words happened to match.
+      //
+      // SAY WHICH IT IS, INCLUDING WHEN THERE IS NOTHING. "The engine printed nothing" is itself the
+      // diagnosis on a binary that died before it opened its mouth, and printing no line at all leaves
+      // a reader unable to tell that from a wizard that decided not to show them.
       if (v.detail) info(`engine said: ${v.detail}`);
+      else info("engine said: nothing — it produced no output on either stream before it stopped.");
+      if (v.basis) info(`(that reading is ${v.basis === "text-match" ? "matched out of the text above, not a signal from the provider" : v.basis})`);
       // — THE HAND-OFF. Signing in is the one step of this sequence nobody here can perform for
       // someone, so the wizard names the command, waits, and re-probes rather than ending at a
       // description of what is wrong. The text comes from ENGINE_BINARIES so the two adapters cannot

package/bin/start.mjs

@@ -116,7 +116,7 @@ import { SERVER_INSTALL_SET, unitsToRestartOnRefresh, unitHealthVerdict } from "
 // tolerate and never manage"; settled point 2 superseded that.)
 import { defaultDenylistPath, denylistPathFor, denylistFor, ensureDenylistFile, CLIENT_DOOR_UNIT, enablePlan, clientDoorPort } from "../shared/client-door.mjs";   // — one owner for the revocation list's path
 import { createServer } from "node:net";
-import { listenErrorMessage } from "../shared/listen.mjs";
+import { listenErrorMessage, nextFreePort } from "../shared/listen.mjs";
 import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { invocationPrefix, invoke } from "../shared/invocation.mjs";   // — the banner names the verb
@@ -133,6 +133,8 @@ import { rebuildIfStale } from "../shared/bundle-rebuild.mjs";   // never serve
 // ONE CLASSIFIER FOR WHAT A STAFF RULE ADMITS, shared with the setup wizard. Two copies of this
 // judgement would be a wizard that asks about one rule and a launcher that writes another.
 import { classifyStaffDomain, staffDomainRefusal, staffGrantSentence } from "../shared/staff-domain.mjs";
+import { backgroundManager } from "../shared/os-advice.mjs";
+import { frontingVariablesSet } from "../shared/install-auth.mjs";   // — one owner for what counts as a proxy in front of a door
 
 const REPO = join(dirname(fileURLToPath(import.meta.url)), "..");
 const ENV_PATH = envLocalPath({ repoRoot: REPO });   // resolved, never composed: one resolver, so moving this file later is one line
@@ -962,7 +964,24 @@ if (isMain) {
   // loop because both paths below have to act on it: the background path must RESTART the door it
   // adopted, and the foreground path must not spawn a second one beside it.
   let adoptedClientDoor = false;
-  for (const [what, port, portVar, doorUnit = null] of [["portal", ports.portal, "PORTAL_SERVICE_PORT"], ["engine door", ports.mcp, "TRADEMARK_MCP_HTTP_PORT"], ["client door", ports.client, "CLIENT_MCP_HTTP_PORT", CLIENT_DOOR_UNIT]]) {
+  // ── WHETHER ANYTHING OUTSIDE THIS PROCESS IS ADDRESSED TO THESE NUMBERS ────────────────────────
+  //
+  // A door may only be moved off a port nobody chose when nothing fronts it. A proxy, an Access team
+  // or an OIDC issuer means something external resolves to these numbers, and a door that quietly
+  // moved would be up and unreachable — which looks like success and is the worst of the three
+  // outcomes. The auth-mode half of this is already closed further up: a foreground start refuses
+  // outright when PORTAL_AUTH_MODE names a hosted door, and again when the units are installed and
+  // serving. What is left to check is the settings that can be present with the mode unset.
+  //
+  // PORTAL_AUTH_MODE IS ABSENT FROM THAT LIST ON PURPOSE, and only a rule in another file makes that
+  // safe: `driver/portal-service.mjs` refuses to start in auth-proxy without CF_ACCESS_TEAM or
+  // PORTAL_OIDC_ISSUER, so a portal fronted by the mode alone cannot come up at all. Relaxing that
+  // refusal without adding the mode here would let this under-report — which is why the list has one
+  // owner in `shared/install-auth.mjs` with an arm holding it to the doors themselves.
+  const fronted = frontingVariablesSet(process.env);
+  const claimedPorts = new Set([ports.portal, ports.mcp, ports.client]);
+  const movedDoors = [];
+  for (const [what, port, portVar, doorUnit = null, key = null] of [["portal", ports.portal, "PORTAL_SERVICE_PORT", null, "portal"], ["engine door", ports.mcp, "TRADEMARK_MCP_HTTP_PORT", null, "mcp"], ["client door", ports.client, "CLIENT_MCP_HTTP_PORT", CLIENT_DOOR_UNIT, "client"]]) {
     // A --background REFRESH runs over its own healthy units, which hold these ports on purpose;
     // systemd's restart is the handover. Probing would refuse the flag exactly once it has worked.
     // The narrow carve above already proved every installed unit is ours.
@@ -987,8 +1006,38 @@ if (isMain) {
     // on a privileged port and from an address this host does not have, and names the way out of each;
     // the launcher having its own shorter sentence for one of the three would mean a user meets two
     // different answers to the same question depending on which door refused first.
+    // ── A PORT NOBODY CHOSE IS MOVED RATHER THAN REFUSED (owner ruling, 2026-09-09) ─────────────
+    //
+    // Three conditions, and each is a different reason:
+    //   · the address is genuinely taken — anything else is not this case;
+    //   · the reader did not state this port, so no one is addressed to it. An explicitly set port is
+    //     a stated address and is refused exactly as before;
+    //   · nothing fronts these doors, so nothing outside resolves to the old number.
+    // With any of those false the refusal below fires unchanged, which is the whole of the previous
+    // behaviour kept intact underneath this.
+    if (code === "EADDRINUSE" && key && !fronted.length && !String(process.env[portVar] ?? "").trim()) {
+      const next = await nextFreePort(port, async (p) => (await probe(p)) === null, { claimed: claimedPorts });
+      // NULL IS NOT A FALLBACK. Nothing free in range means the reader is told the truth about the
+      // port they asked for, rather than sent to one this could not prove was free either.
+      if (next) {
+        claimedPorts.delete(port);
+        claimedPorts.add(next);
+        ports[key] = next;
+        movedDoors.push({ what, portVar, from: port, to: next });
+        continue;
+      }
+    }
     if (code) fatal(listenErrorMessage({ code }, { what, host: HOST, port, portVar, portFile }));
   }
+  // SAID OUT LOUD, EVERY TIME. A door that moved is at an address the reader did not ask for and will
+  // not find by memory — and the portal's own URL is printed from `ports.portal` further down, so a
+  // silent move would leave the two disagreeing with nothing explaining it.
+  if (movedDoors.length) {
+    say("");
+    say(`  ${movedDoors.length === 1 ? "One door was" : `${movedDoors.length} doors were`} already in use, so ${movedDoors.length === 1 ? "it" : "they"} moved:`);
+    for (const d of movedDoors) say(`    the ${d.what}: ${d.from} → ${d.to}   (set ${d.portVar} to pin it)`);
+    say("  Nothing outside this machine is addressed to these, so nothing else needed changing.");
+  }
 
   // ── 2. the two secrets, generated once and kept ────────────────────────────────────────────────────
 
@@ -1981,8 +2030,21 @@ if (isMain) {
   // run". Saying it here, before the commands go by, is the whole fix.
   say("  This terminal is now the product: it runs only while this command does, and Ctrl-C — or closing");
   say("  the window — stops everything it started. So the commands above need a SECOND terminal.");
-  say(`  To get your prompt back instead, stop this and run  ${invoke("start")} --background`);
-  say("  — same product, managed by systemd, and it survives logout.");
+  // ── THE BACKGROUND ROUTE IS NOT OFFERED WHERE IT CANNOT WORK ────────────────────────────────────
+  //
+  // `--background` installs and enables service units. There are none on Windows, so both the offer
+  // and the sentence naming what manages them were wrong there — a reader was told to run a flag that
+  // cannot succeed and given a service manager that is not on the machine and cannot be put there.
+  // Reported from a real run. Same rule as the engine refusal above: do not name a route this platform
+  // does not have.
+  const manager = backgroundManager();
+  if (manager) {
+    say(`  To get your prompt back instead, stop this and run  ${invoke("start")} --background`);
+    say(`  — same product, managed by ${manager}, and it survives logout.`);
+  } else {
+    say("  There is no background form on this platform: the product runs as long as this window does.");
+    say("  Leave it open and use a second terminal for the commands above.");
+  }
   say("");
 }
 

package/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "5c8eca66a5f226dde9e1d01affd63da4eda61bbd",
-  "version": "0.2.3"
+  "commit": "3c2277f7fab7452490c86d19802dd60a886a2b06",
+  "version": "0.2.4"
 }

package/demo/README.md

@@ -37,7 +37,7 @@ they are machine output with a fixed shape, described here instead:
   the search policy, the receipts, the pre-delivery lint. These are what the report is assembled from
   and what the audit surfaces read.
 - `<product-id>/run/_records/` — the register records the run actually retrieved, one file per record,
-  named by register and number. Real EUIPO records for a fictional mark.
+  named by register and number. Real Clarivate Compumark records for a fictional mark.
 
 `<product-id>/PROVENANCE.md` says how each run was frozen, what was dropped, and how to regenerate it.
 

package/docs/GLOSSARY.md

@@ -0,0 +1,85 @@
+# Glossary
+
+Words this codebase uses in a particular way. They are here because they are already in the tree —
+in file names, comments and test titles — and a contributor meeting one should not have to reverse
+it out of the code. Product vocabulary a client would meet is in [`../README.md`](../README.md); the
+tenant, account and project model is in [`../INSTALL.md`](../INSTALL.md) under "The four things, and
+what contains what".
+
+Nothing here is a rule. Each line says what the word points at, and names the file that owns it.
+
+## The run
+
+**Seat** — one model turn with one job, inside a stage that has several. The common-law grid runs
+halves `a` and `b` and a meaning seat `m`; each has its own model tier and its own ledger, and one
+seat failing is not the stage failing.
+
+**Dispatch** — handing a seat its prompt and waiting for the turn. Recorded per attempt in
+`_driver/<stage>.jsonl`, so a stage that ran three times has three dispatches and one result.
+
+**Matter frame** — what the run understands the request to be: the mark, the goods, the sector, the
+territories. Everything downstream derives from it, and it is told not to widen past the territories
+the job named.
+
+**Blind frame** — a second reading of the raw request that never sees the matter frame. It runs
+beside the investigation as a non-fatal sibling, so a framing mistake shows up as a disagreement
+rather than propagating quietly.
+
+**Feedforward** — the reviewer's flags reaching the corrective pass as data rather than as prose.
+`corrections-feedforward.mjs` decides which flags count as still open.
+
+**Carry-through** — of every subject the run's findings surface, which ones reach none of the
+delivered documents. A finding that is recorded and never carried is the thing this measures.
+
+**Declination** — a record the run enumerated and then decided not to pursue, with the position of
+its reason in `_driver/declination-spec.json`. A declination is a decision, not a gap.
+
+**Refusal** — the product declining rather than failing. `terminalKind: "designed-refusal"`. Nothing
+about a refusal is retried, parked or recovered; the remedy is always the operator's.
+
+## What a run leaves behind
+
+**Ledger** — an append-only record of what was covered, kept so that "unsearched" can never be
+reported as "clean". The coverage ledger appears in the report as prose and as JSON, from one source.
+
+**Receipt** — a record that something happened, kept for observability and deliberately not used as a
+gate. A receipt read as a gate is a Goodhart problem, and the reasoning-integrity receipt says so on
+its own face.
+
+**Register-digest** — the condensed register result a downstream stage reads instead of the raw
+records: the same evidence, at the size a model turn can hold.
+
+**Hit list** — one line per enumerated record and the fate it was given. It is not a read: a record
+can be on the hit list and never opened, and the sign-off condition is about documents actually read.
+
+**Predelivery** — the checks that run after the documents exist and before anyone receives them
+(`predelivery-lint.mjs`, `_driver/predelivery-lint.json`). A failing predelivery withholds the
+artifact; it never annotates it.
+
+**Courier** — delivery as a self-contained packet handed to the integrator. The engine does not send;
+what it produces is carried.
+
+**Drift** — a value that is mirrored in two places by design, and the two disagreeing. The catalogue
+of what is mirrored, and which copy owns it, is in the architecture docs.
+
+## Guards and tests
+
+**Arm** — one `test(...)` block. A file has many; each is named for the property it holds, and a red
+arm is read by its output rather than by its name.
+
+**Plant** — deliberately breaking something to prove a check would catch it. A guard that has never
+been shown failing has not been shown to work, so the hard version plants a NEW instance of the class
+rather than the one the check was written against.
+
+**Contract dictation** — the rule that a contract is stated once and everything else derives from it.
+`contract-dictation.mjs` computes over a corpus; `scripts/contract-dictation-scan.mjs` builds that
+corpus from the tracked tree, so a new authoring layer is caught structurally rather than because
+somebody remembered to list it.
+
+**Assert census** — counting the assertions that never executed. An assertion inside a branch nothing
+reaches is a test that passes and guards nothing (`scripts/unexecuted-asserts.mjs`).
+
+**Authority probe** — asking the live CLI whether it honours a boundary the driver sets, and whether
+the turn survives being refused. CI has no CLI and no subscription, so it can only prove the decision
+is made correctly; whether it is obeyed is a property of the real binary
+(`scripts/authority-boundary-probe.mjs`).

package/docs/README.md

@@ -38,6 +38,7 @@ the vendor flags approximate is UNKNOWN, never a number.
 | [`PORTAL.md`](PORTAL.md) | The portal: what it serves, and who sees what |
 | [`CLIENT-MCP.md`](CLIENT-MCP.md) | Publishing a connector your customers sign in to, and how their access is scoped. To connect *your own* app to *your own* runs, use [`../mcp-server/CONNECT.md`](../mcp-server/CONNECT.md) instead |
 | [`E2E.md`](E2E.md) | Proving a deployment works end to end |
+| [`GLOSSARY.md`](GLOSSARY.md) | The words this codebase uses in a particular way — one line each, for a contributor meeting them for the first time |
 | [`SECURITY.md`](SECURITY.md) | The security envelope — what protects what, and where it is enforced in code. To report a vulnerability, use [`../SECURITY.md`](../SECURITY.md) |
 
 Access control is stated once, in [`SECURITY.md`](SECURITY.md): who may see which runs, what an unset

package/docs/architecture/01-product-overview.md

@@ -3,18 +3,30 @@
 > Part of the architecture pack (`docs/architecture/`). The driver's module tree and the headless
 > integrator contract are in [`driver/README.md`](../../driver/README.md).
 
-The clearotron driver turns a plain-language clearance request into a delivered, lawyer-vetted
-preliminary trademark clearance report. One matter in, one decision out — with the investigation,
-the reasoning, the challenge, and the paper trail in between run by deterministic code that treats
-the model as a reasoning step, never as the orchestrator.
+The clearotron driver turns a clearance request into a delivered preliminary trademark clearance
+report. One matter in, one decision out — with the investigation, the reasoning, the challenge, and
+the paper trail in between run by deterministic code that treats the model as a reasoning step,
+never as the orchestrator.
 
 ## What it does
 
-A lawyer forwards a clearance request by email. The system resolves the matter (mark, client,
-scope, deadline), investigates worldwide — trademark registers and the live marketplace, in the
-variations a lawyer would try — reasons the risk in the client's own framework, challenges its own
-draft twice, and delivers a client-formatted report with every factual claim traceable to a fetched
-source record. A lawyer vets the result, then it moves.
+**Who this is for.** Anyone who needs to know whether a name is free to use and is willing to run the
+search themselves: a lawyer, a brand team, or an individual clearing their own mark. You need three
+self-serve accounts: a reasoning CLI, a register, and web research.
+
+**What you get.** Four searches at different depths. A knockout screens up to eight names in minutes.
+A global preliminary, a multi-country focus, or a full country search takes one name deeper, and the
+full country search adds case law. Each delivers a written report with the records behind every
+finding. What you do with it is your call.
+
+The four searches are declared in `driver/products.mjs`, and that declaration is what the rest of the
+system reads: a knockout screens up to eight names and skips case law, and only the full country
+search turns case law on. A knockout takes 5 to 10 minutes; the other three take 1.5 to 2.5 hours.
+
+Under any of them the system resolves the matter (mark, scope, deadline), investigates the trademark
+registers and the live marketplace in the variations a searcher would try, reasons the risk in the
+matter's own framework, challenges its own draft twice, and delivers a report with every factual
+claim traceable to a fetched source record.
 
 The driver is the machine that runs that whole distance. It is **not an agent**: it is a plain
 Node.js process, launched by systemd, that executes a fixed pipeline of stages. Each stage that

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

@@ -136,6 +136,11 @@ boxes rebuild.
 
 ## 5. Env-var register (by domain → tier)
 
+**[`04-configuration-reference.md`](04-configuration-reference.md) is the variable table**, and it is
+the one two instruments read — `driver/doc-constants.mjs` and `scripts/env-audit.mjs`. What follows
+here is the governance view: which tier a name sits in and who may change it. When the two disagree
+about what a variable *does*, 04 is right and this page is stale.
+
 Tiers: T3 = operator-tunable (candidate for read-only display); T4 = backend-only (secret,
 structural, or dev seam); [dev] = dev/test seam, never set in prod.
 

package/docs/decisions/0006-what-the-public-repository-carries.md

@@ -29,11 +29,36 @@ cut, not before: `cut/rules.mjs` treats a rule matching nothing as a refusal, so
 does not yet exist cannot be pre-added, and `driver/test/release-pipeline.test.mjs` reds the moment the
 file exists undecided.
 
-**The drop list is `shared/withheld-paths.mjs`, and it is the only place a cut decision is recorded.** Two
-tests read it: `driver/test/publication-scrub.test.mjs` fails a shipped file that cites a withheld path
-without a declared reason, and `driver/test/no-caveat-repair.test.mjs` treats an absent-and-declared file
-as a stated consequence rather than damage. A decision recorded anywhere else — an issue, a chat, a comment
-— is not recorded.
+**The drop list is `shared/withheld-paths.mjs`, and it is the only place a cut decision is recorded.** A
+decision recorded anywhere else — an issue, a chat, a comment — is not recorded.
+
+**Amended 2026-09-09.** This paragraph named two tests as the enforcement: `publication-scrub` and
+`no-caveat-repair`. Neither exists. Measured across both repositories that day: neither file is tracked,
+neither is on disk, and neither was ever added or deleted in either repository's history. A decision
+record that names enforcement which was never written is worse than one that names none, because a
+reader stops looking. What follows is what actually holds the line.
+
+**The drop list itself does not ship.** It stays with the archive by owner ruling, 2026-08-31, so the
+published tree carries no copy — and neither, today, does any other tree. `CUT_RECORD_PRESENT` is false
+everywhere the code runs.
+
+**What enforces the cut today is `shared/withheld-paths-access.mjs` and its three readers.** The accessor
+is the only thing that reads the drop list, and it is written to work where the list is absent:
+
+| Reader | With the list | Without it, which is every tree today |
+|---|---|---|
+| `scripts/citation-line-check.mjs` | a withheld file's citations need not resolve | every file crosses the cut, so every citation must resolve |
+| `scripts/mint-suite-census.mjs` | a withheld test file is a stated absence | a removed test file is a LOSS |
+| `shared/reference-guard-classes.mjs` | withheld paths are skipped | nothing is skipped, so the whole tree is counted |
+
+Every one degrades **stricter**, never weaker, which is the property that makes the absence safe. A
+separate record of what was cut is kept with the archive rather than published, so this repository can be
+checked without it.
+
+**The gap, stated rather than left to be found.** Because no tree carries the list, the with-the-list
+column above has never run. What is enforced today is the strict fallback, not the record — and a check
+that has never executed its other branch is a check whose other branch is unproven. The accessor
+announces which mode it is in, once, so a reader of any run can tell which column applies.
 
 **What survives a withheld document is the fact itself, moved to where the code enforces it:**
 

package/driver/CHANGELOG.md

@@ -1,5 +1,39 @@
 # clearotron-driver
 
+## 0.2.4
+
+### Patch Changes
+
+- d35dd9b: Fixed: A search that was planned and never run is disclosed on the report again, even when another search mentions the same word.
+  
+  One row on the coverage section says a planned search never reached the register. That row was removed whenever another row's heading carried the same words. A row for a search that had run and found nothing could remove it.
+  
+  So a report could mention a term in its coverage section and say nothing was left undone. The only disclosure of the gap had been dropped. A completed search no longer stands in for an uncompleted one.
+  
+  Re-rendering an archived report restores the row where this had removed it.
+- b47be41: Fixed: Seven fixed sentences on the clearance report are now written for the person reading it.
+  
+  These lines print on every report and none of them was written for a client. The footer explained the risk-band vocabulary to a developer. A paragraph defined a label most readers never saw on their page. An internal coverage note ran to about a thousand characters of the engine's own search names and ended mid-word.
+  
+  Registration numbers no longer carry "(placeholder)" where the register has no per-record link — the number stands on its own. A gap that was disclosed twice, once in the model's words and once in the engine's, is disclosed once. Three section captions say what the section is rather than how it was produced. And a use check that found nothing no longer prints an evidence tag beside it, which read as a contradiction.
+  
+  The page also no longer calls itself a working draft for legal review. That sentence printed on every report and went with the footer rewrite; it is a deliberate removal, not a casualty of one.
+  
+  Nothing here changes what was searched, counted, rated or judged. Every fact about where a record came from is still there: the registration numbers, the dates they were read, the year each was registered.
+- a4c9045: Fixed: The demo now names the register its example run was captured against.
+  
+  `clearotron demo` said the run came from a production EU register. It did not. All four frozen runs were captured against Clarivate Compumark, which is what their own records and the reports say. The label also carried a capture date that matches none of the four runs, so it has gone.
+  
+  The line now says what it is: a real run against Clarivate Compumark, and replaying it needs no account, no key and no network. That last part was always true and is worth saying where a reader meets it.
+- f3bab16: Fixed: The lines a client reads first are now checked for the profession's vocabulary and for sentences carrying more than one idea. The reviewing pass rewrites them before delivery. Nothing about the check is shown to the client, and no run fails over it. A report clearing a name like PREVAIL is unaffected, because the mark being cleared is never read as a legal term.
+- 862f76a: Fixed: The screen that will not start a search now gives advice that fits your machine.
+  
+  An install with the engine program present, but invisible to the engine service, was told to install a program it already had. That advice cannot work. Following it changes nothing, because the engine reads its PATH when it starts. Until it is restarted, every screen reports what it saw at startup. Nothing said so.
+  
+  The New clearance notice now tells those two states apart. Where the program is absent it gives the install advice as before. It adds that the service has to be restarted afterwards before it will notice. Where the program is present and the engine cannot see it, the notice says that instead, and names the restart as the remedy. Staff also get a link from that notice to the configuration page.
+  
+  The configuration page's engine row now names the program it could not find. It names the command that installs it too, and `clearotron doctor` says the same, in the same words.
+
 ## 0.2.3
 
 ### Patch Changes