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

package/driver/engine/openai-agent.mjs

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

package/driver/engine/probe.mjs

@@ -54,8 +54,8 @@
 // The one place the real adapter is exercised, it is pointed at `driver/test/mock-claude.mjs` through
 // `CLEAROTRON_CLAUDE_PATH` — the same offline fixture the engine tests already spawn.
 
-import { ENGINE_BINARIES, DEFAULT_ENGINE_ID, engineAdapterSpecifier } from "../driver.config.mjs";
-import { resolveAuthMode } from "./auth.mjs";
+import { ENGINE_BINARIES, DEFAULT_ENGINE_ID, engineAdapterSpecifier, resolveEngineProgram } from "../driver.config.mjs";
+import { resolveAuthMode, CLOUD_SETTINGS, CLOUD_CREDENTIAL_CHECK } from "./auth.mjs";
 
 /** Six words. Short enough to be free in practice, and it still requires a real completed turn. */
 export const PROBE_PROMPT = "Reply with the single word: ok.";
@@ -90,44 +90,97 @@ const tail = (s) => {
   return t.length > DETAIL_CHARS ? `…${t.slice(-DETAIL_CHARS)}` : t;
 };
 
+/**
+ * An engine instruction that names its program (`run \`claude\` once…`, `claude setup-token`), rewritten to
+ * name the copy that will actually run when that copy is the one Clearotron installed. That copy is not on
+ * PATH, so for it the bare word is a command the reader's shell cannot
+ * find, at the one step nobody can do for them. Any other copy is on PATH or named by path already, and
+ * the text is returned unchanged.
+ *
+ * HERE, AND RE-EXPORTED BY SETUP. Setup's own screens used it and the probe's sign-in advice, which doctor
+ * and the run door print, did not, so after setup's install doctor told the reader to run a `claude` their
+ * shell does not have. The probe cannot import the wizard, so the one copy lives on this side.
+ */
+export function namingProgram(text, eng, bin) {
+  if (!text || bin?.source !== "installed" || !bin.path) return text;
+  const program = /\s/.test(bin.path) ? `"${bin.path}"` : bin.path;
+  return String(text).replace(new RegExp(`(^|\`)${eng.fallback}(?=[\\s\`]|$)`, "g"), (_, before) => `${before}${program}`);
+}
+
 // THE HEADLESS ROUTE, WHERE THE ENGINE HAS ONE. The interactive sign-in is the one thing a server with no
 // browser cannot do, and it was the only remedy this offered — including to a box that had configured the
 // route built for servers. The engine table already carries that route; this reads it rather than a copy.
-const signInLine = (engine) => {
+//
+// `program` is the copy that ran ({ source, path }, or null), and every command run ON THIS MACHINE is named
+// through `namingProgram`. The token route's command can run on any machine, so it keeps the bare word,
+// with this machine's copy named beside it, as setup names it.
+const signInLine = (engine, program = null) => {
   const spec = ENGINE_BINARIES[engine];
-  const base = spec?.signIn ?? "sign the CLI in";
+  const base = spec?.signIn ? namingProgram(spec.signIn, spec, program) : "sign the CLI in";
   const h = spec?.headless;
   // Both forms the wizard already offers, read off the same table: a TOKEN route is run elsewhere and
-  // carried here by variable; a DEVICE route is run on this box and signs it in directly.
+  // carried here by variable; a DEVICE route is run on this machine and signs it in directly. The route is
+  // named by where a sign-in can be completed, as INSTALL.md's sign-in table names it.
   if (!h?.cmd) return base;
+  const here = namingProgram(h.cmd, spec, program);
   return h.tokenEnv
-    ? `${base} — or, on a box with no browser, run \`${h.cmd}\` on any machine you can sign in on and set the token it prints as ${h.tokenEnv} in this install's environment file`
-    : `${base} — or, on a box with no browser, run \`${h.cmd}\` here`;
+    ? `${base} — or, on a machine you cannot complete a sign-in on, run \`${h.cmd}\` on any machine you can sign in on${here !== h.cmd ? ` (on this one, \`${here}\`)` : ""} and set the token it prints as ${h.tokenEnv} in this install's environment file`
+    : `${base} — or, on a machine you cannot complete a sign-in on, run \`${here}\` here`;
 };
 
+/**
+ * Who refused the credentials and what to check, for a turn paid through an API key or a cloud account:
+ * `{ who, what, check }`, or null on a subscription, whose remedy is the sign-in above. `auth` is the
+ * resolver's answer for the turn ({ mode, cloud }). Names only, never a value.
+ *
+ * THE SIGN-IN IS A SUBSCRIPTION'S REMEDY AND NO OTHER'S. A cloud that refuses the credentials, or a key the
+ * vendor refuses, answers 401 or 403 like a signed-out program, and the advice was to run the program once
+ * and sign in: nothing to sign in to on a cloud, and a sign-in the adapter would not use under a key.
+ */
+export function credentialCheck(engine, auth) {
+  if (auth?.mode === "cloud") {
+    const c = CLOUD_CREDENTIAL_CHECK[auth.cloud];
+    return c ? { who: c.who, what: "the credentials", check: c.check } : null;
+  }
+  const spec = ENGINE_BINARIES[engine];
+  if (auth?.mode === "api-key" && spec?.apiKeyEnv) return { who: spec.vendor, what: "the API key", check: spec.apiKeyEnv };
+  return null;
+}
+const capitalised = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+
 /**
  * One verdict from one turn. PURE — no clock, no filesystem, no process.
  *
  * `tuple` is the engine's normalized return (engine/CONTRACT.md §1); `error` is a THROW, which is a
  * distinct class and not a returned failure: `openai-agent.runTurn` throws for both of its auth shapes
  * (resolveAuthMode on api-key-without-key, and the auth.json refusal) rather than settling a tuple.
+ *
+ * `auth` is how the turn was paid for (resolveAuthMode's `{ mode, cloud }`) and `program` the copy that ran
+ * (`{ source, path }`); both only shape the advice, never the mode, so the run door refuses exactly what it
+ * refused before. Absent, the advice is the subscription's, naming the bare program word.
  */
-export function classifyProbe({ engine, tuple = null, error = null, timeoutSec = PROBE_TIMEOUT_SEC } = {}) {
+export function classifyProbe({ engine, tuple = null, error = null, timeoutSec = PROBE_TIMEOUT_SEC, auth = null, program = null } = {}) {
   const id = String(engine ?? "").trim().toLowerCase();
   const v = (mode, basis, headline, fix, extra = {}) =>
     ({ ok: false, engine: id, mode, basis, headline, fix, detail: null, ...extra });
 
   // ── a THROW ────────────────────────────────────────────────────────────────────────────────────────
-  // The thrown text is relayed VERBATIM as the fix wherever the thrower already says what to do. Those
-  // messages were written by the module that owns the decision (auth.mjs owns the billing refusal, the
-  // codex adapter owns `codex login`); paraphrasing them here creates a second wording that drifts.
+  // The thrown text is relayed as the fix wherever the thrower already says what to do. Those messages
+  // were written by the module that owns the decision (auth.mjs owns the billing refusal, the codex
+  // adapter owns `codex login`); paraphrasing them here creates a second wording that drifts.
+  //
+  // ONE CHANGE ONLY, AND ONLY TO A SIGN-IN: the program's name. The codex adapter refuses a subscription
+  // with no sign-in by throwing "run `codex login`" before it starts anything, which is the commonest way a
+  // signed-out Codex reaches this line. Relayed as thrown, that told a reader whose only copy is the one
+  // setup installed, which is not on PATH, to run a command their shell does not have. `namingProgram`
+  // rewrites the bare word for that copy and leaves every other copy's text as it was thrown.
   if (error) {
     const msg = String(error?.message ?? error);
-    if (/=api-key but/i.test(msg))
+    if (error?.billingRefusal === true || /=api-key but/i.test(msg))   // auth.mjs marks every billing refusal
       return v("auth-misconfigured", "config",
-        `${id} cannot start: the billing mode this box declares has no key`, msg, { detail: null });
+        `${id} cannot start: ${/=api-key but/i.test(msg) ? "the billing mode this box declares has no key" : "the billing setting this box declares is refused"}`, msg, { detail: null });
     if (SIGNED_OUT_RE.test(msg))
-      return v("signed-out", "config", `${id} is not signed in`, msg);
+      return v("signed-out", "config", `${id} is not signed in`, ENGINE_BINARIES[id] ? namingProgram(msg, ENGINE_BINARIES[id], program) : msg);
     if (TIER_RE.test(msg))
       return v("tier-unavailable", "config", `${id} cannot reach the model it was asked for`, tierFix(id, msg));
     return v("failed", "throw", `${id} could not run a turn`, msg);
@@ -144,7 +197,11 @@ export function classifyProbe({ engine, tuple = null, error = null, timeoutSec =
   // which pipe this happened to look at.
   const detail = tail(tuple.stderr) ?? tail(tuple.stdout);
 
-  if (tuple.code === 0) return { ok: true, engine: id, mode: "ok", basis: "completed-turn", headline: `${id} completed a turn`, fix: null, detail: null };
+  // A completed turn names what served it, the model and the provider as the program reported them, and
+  // null where it named neither, so a proof says which model and whose account it proved.
+  if (tuple.code === 0) return { ok: true, engine: id, mode: "ok", basis: "completed-turn", headline: `${id} completed a turn`, fix: null, detail: null,
+    served: typeof tuple.modelWire === "string" && tuple.modelWire ? tuple.modelWire : null,
+    provider: typeof tuple.providerWire === "string" && tuple.providerWire ? tuple.providerWire : null };
 
   // spawn itself failed. The filesystem preflight normally catches this first; when it does not, say so
   // in the binary's own vocabulary rather than as a mysterious engine fault.
@@ -163,9 +220,15 @@ export function classifyProbe({ engine, tuple = null, error = null, timeoutSec =
       { resetsAt: s.resetsAt ?? null, detail });
   }
 
+  // THE MODE STAYS `signed-out` UNDER EVERY WAY OF PAYING, because the run door refuses on the mode and a
+  // refused credential is as much this machine's to fix as a signed-out program. Only the words follow how
+  // the turn is paid for.
+  const refused = credentialCheck(id, auth);
   if (SIGNED_OUT_RE.test(text))
-    return v("signed-out", "text-match", `${id} is not signed in`,
-      `Sign in: ${signInLine(id)}, then run this again. Setup does not do it for you — the CLI owns its own login.`, { detail });
+    return refused
+      ? v("signed-out", "text-match", `${capitalised(refused.who)} refused ${refused.what}`, `check ${refused.check}, then run this again.`, { detail })
+      : v("signed-out", "text-match", `${id} is not signed in`,
+        `Sign in: ${signInLine(id, program)}, then run this again. Setup does not do it for you — the CLI owns its own login.`, { detail });
 
   if (TIER_RE.test(text))
     return v("tier-unavailable", "text-match", `${id} cannot reach the model it was asked for`, tierFix(id, text), { detail });
@@ -179,7 +242,9 @@ export function classifyProbe({ engine, tuple = null, error = null, timeoutSec =
   // from the shape rather than read from a message.
   if (s.noStreamEvents)
     return v("signed-out", "startup-class", `${id} exited before it produced anything`,
-      `That is the signed-out shape, so start there: ${signInLine(id)}, then run this again. The engine's stderr below is the diagnosis if it is something else.`, { detail });
+      refused
+        ? `That is what refused credentials look like, so start there: check ${refused.check}, then run this again. The engine's stderr below is the diagnosis if it is something else.`
+        : `That is the signed-out shape, so start there: ${signInLine(id, program)}, then run this again. The engine's stderr below is the diagnosis if it is something else.`, { detail });
 
   return v("failed", "nonzero-exit", `${id} ran but the turn failed (exit ${tuple.code})`,
     "The engine's stderr below is the whole story; a turn that starts and fails is not a configuration this check can name.", { detail });
@@ -292,11 +357,15 @@ export function probeWeatherWarning(verdict) {
  * and a caller building the environment it hands this module fills from it. `doctor` kept a second copy
  * that had dropped both credentials, so it filled a probe environment without the very token it then
  * reported missing. Exported so there is nothing left to copy.
+ *
+ * The cloud a Claude turn is sent to and paid through is on it too (`CLOUD_SETTINGS`, from auth.mjs).
+ * Without those names a cloud answered in setup would pass the resolver, which reads the caller's
+ * environment, and never reach the turn, which reads this process's: a proof of an account no run bills.
  */
 export function engineEnvKeys() {
   return [...new Set(["CLEAROTRON_AI", ...Object.values(ENGINE_BINARIES)
     .flatMap((s) => [s.env, s.authEnv, s.apiKeyEnv, s.headless?.tokenEnv])
-    .filter(Boolean)])];
+    .filter(Boolean), ...CLOUD_SETTINGS])];
 }
 
 function applyEngineEnv(env) {
@@ -346,6 +415,12 @@ async function defaultLoadAdapter(engine) {
 /**
  * Run the probe and return a verdict. Never throws for a configuration fault — a caller that wants a
  * refusal calls `preflightEngineTurn`, and a caller that wants to report calls this.
+ *
+ * `program` is the copy the caller has already found and is running (`{ source, path }`), for a caller
+ * that knows more about it than its setting says. Setup pins the program setting to the absolute path of
+ * the copy it proves, so the turn runs exactly that copy; resolved from that setting alone, the copy setup
+ * installed reads as a path the reader set, and the advice then named the bare word that copy does not
+ * answer to. Without it, the probe resolves the copy itself.
  */
 export async function probeEngineTurn({
   env = process.env,
@@ -354,6 +429,7 @@ export async function probeEngineTurn({
   loadAdapter = defaultLoadAdapter,
   timeoutSec = PROBE_TIMEOUT_SEC,
   stallSec = PROBE_STALL_SEC,
+  program: knownProgram = null,
 } = {}) {
   const id = String(env.CLEAROTRON_AI || DEFAULT_ENGINE_ID).trim().toLowerCase();
   if (!ENGINE_BINARIES[id]) {
@@ -366,8 +442,10 @@ export async function probeEngineTurn({
     };
   }
 
-  // The billing-mode door, before anything spawns — a fail-loud config error must not cost a turn.
-  try { resolveAuthMode({ engineName: id, env }); }
+  // The billing-mode door, before anything spawns — a fail-loud config error must not cost a turn. Its
+  // answer is kept: a refusal from a cloud or of a key is advised on differently from a signed-out program.
+  let auth;
+  try { auth = resolveAuthMode({ engineName: id, env }); }
   catch (e) { return classifyProbe({ engine: id, error: e, timeoutSec }); }
 
   let turn = injectedRunTurn;
@@ -377,11 +455,20 @@ export async function probeEngineTurn({
   }
 
   const restore = applyEngineEnv(env);
+  let program = null;
   try {
+    // THE COPY THAT RUNS, resolved the way the adapter resolves it: by the one resolver, inside the
+    // environment the turn runs in. The sign-in advice names it when it is the copy Clearotron installed,
+    // which is not on PATH. AFTER applyEngineEnv, NEVER BEFORE: the resolver reads this process's
+    // environment, and the caller's program setting is only there from that line until `restore()`, so above
+    // it this would name whatever copy the shell happened to point at. Inside the try, so the `finally` puts
+    // the environment back whatever it does. A resolver that cannot answer leaves the bare word.
+    if (knownProgram?.path) program = { source: knownProgram.source ?? null, path: knownProgram.path };
+    else try { const r = resolveEngineProgram(id); program = r.resolved ? { source: r.source, path: r.resolved } : null; } catch { /* the bare word */ }
     const tuple = await turn({ message: PROBE_PROMPT, model: PROBE_MODEL, thinking: PROBE_THINKING, timeoutSec, stallSec });
-    return classifyProbe({ engine: id, tuple, timeoutSec });
+    return classifyProbe({ engine: id, tuple, timeoutSec, auth, program });
   } catch (e) {
-    return classifyProbe({ engine: id, error: e, timeoutSec });
+    return classifyProbe({ engine: id, error: e, timeoutSec, auth, program });
   } finally {
     restore();
   }

package/driver/enqueue-schema.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
-// Job-file shape for studio/prelim-search/queue/<id>.json (written by email-loop on a prelim-search request).
+// Job-file shape for studio/clearance-search/queue/<id>.json (written by email-loop on a clearance-search request).
 // The job id = sanitized email message-id so a re-delivered webhook overwrites the same file (no duplicate run).
 //
 // Blocking semantics follow change-spec v3 §B2: the ONLY content reason a search may not start is the
@@ -10,7 +10,7 @@
 // with a `noref<hash>` slug (see phase0.mjs deriveSlug). The intake confirmation brief (email-loop §6)
 // resolves ambiguity BEFORE enqueue; this validator is the runner-side mechanical backstop.
 
-import { loadProfiles, loadProjects, resolveProfile, applicantMatchesProfile, recipeProseGuard, platformEntryErrors } from "./profiles.mjs";
+import { loadProfiles, loadProjects, resolveProfile, applicantMatchesProfile, recipeProseGuard, platformEntryErrors , unreadableProfiles } from "./profiles.mjs";
 import { demoRunShape } from "./demo-run-agreement.mjs";
 import { ORDERABLE_PRODUCTS, policyFor, checkMarkBudget, checkScopeAgainstPolicy, loadRecipes, kebabCollisions, resolveSearchPolicy } from "./search-policy.mjs";
 // — the §B2 gate resolves the subject through the SAME ladder the run uses. See the gate itself.
@@ -776,6 +776,10 @@ export function validateJob(job, { atClaim = false } = {}) {
         profiles = loadProfiles({ force: true });
         known = profiles.has(key);
       }
+      // A company whose own file would not load is a known company that could not be READ — the same
+      // failure to look as a store that cannot be read, and handled the same way below, never "no such
+      // customer". The file's reason travels with the run's own refusal (resolveProfile).
+      if (!known) known = new Set(unreadableProfiles(profiles).map((u) => u.key)).has(key);
       roster = [...profiles.keys()].sort();
     } catch { known = true; }
     // NAME THE ROSTER THIS PROCESS CAN SEE, always.

package/driver/findings-model.mjs

@@ -590,8 +590,11 @@ export function riskStatement({ tier, verdict, reasons, basis, clauses } = {}) {
   const basisNote = registerOnly ? " Register findings only — no common-law or marketplace search was run." : "";
   if (v === "BLOCKING") return `On hold — the reviewing lawyer's open questions must be resolved before any recommendation.${basisNote}`;
   if (v === "CONDITIONAL") {
-    const conds = (Array.isArray(reasons) ? reasons : []).map((r) => String(r ?? "").trim()).filter(Boolean);
-    const cls = (Array.isArray(clauses) ? clauses : []).map((c) => String(c ?? "").trim()).filter(Boolean);
+    // A clause stored as explicit null is a condition ruled to the run record alone: it is not the lede,
+    // it is not counted, and its reason is never the fallback text. `undefined` (legacy/short) is not null.
+    const cs = Array.isArray(clauses) ? clauses : [];
+    const conds = (Array.isArray(reasons) ? reasons : []).filter((r, i) => cs[i] !== null).map((r) => String(r ?? "").trim()).filter(Boolean);
+    const cls = cs.map((c) => String(c ?? "").trim()).filter(Boolean);
     const lede = cls[0] ?? conds[0] ?? "the open conditions carried in the report";
     const first = clipClause(sentenceCaseLead(lede), STATEMENT_CLAUSE_MAX);
     const n = conds.length || cls.length;
@@ -1732,7 +1735,7 @@ function validateNet(f, ord, mode) {
 // This file's header says `findings_` = a top-level shape defect, `finding_` = a specific finding/field,
 // and by that rule this token would be `finding_net_chained` alongside finding_net_missing /
 // finding_net_invalid / finding_net_prescriptive. It is `findings_net_chained` instead, because the
-// convention is about ROUTING and routing disagrees. pipeline.mjs:3161 reads:
+// convention is about ROUTING and routing disagrees. pipeline.mjs reads:
 //
 //     const eligible = /^invalid_file:/.test(fail) && /:finding_[a-z]/.test(fail) && !/:findings_/.test(fail);
 //

package/driver/flag-snapshot.mjs

@@ -41,7 +41,7 @@
 // than being unable to ask. Failing closed here would mean a file-read error takes the whole portal
 // down — trading a rare wrong-greyed-out option for a total outage.
 
-import { writeFileSync, readFileSync, mkdirSync } from "node:fs";
+import { writeFileSync, readFileSync, mkdirSync, existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { BUILT } from "./search-policy.mjs";
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";   // — one entry-point test, all spellings
@@ -129,7 +129,7 @@ const truthy = (v) => ["1", "true", "yes", "on"].includes(String(v ?? "").trim()
  * `capturedAt` is supplied rather than read from the clock so this stays testable and so a caller can
  * stamp it from the same instant it stamps everything else.
  */
-export function buildFlagSnapshot(env, { capturedAt, registerProvider = null, registerCanCount = null, registerTerritories = undefined, engine = undefined, providers = undefined }) {
+export function buildFlagSnapshot(env, { capturedAt, registerProvider = null, registerLabel = null, registerCanCount = null, registerTerritories = undefined, engine = undefined, providers = undefined }) {
   const flags = {};
   // Written unconditionally, true or false to a count: a reader must be able to tell "this snapshot
   // tracks no flags" from "this snapshot lost its flags", and `flags: {}` alone cannot say which.
@@ -181,6 +181,12 @@ export function buildFlagSnapshot(env, { capturedAt, registerProvider = null, re
     register: registerProvider
       ? {
         provider: registerProvider,
+        // The register's own DISPLAY label ("Signa"), beside the key the engine switches on ("signa").
+        // A door that names the register to a client must not print the key, and capabilities — where
+        // the label lives — is a provider module this process may not be able to import. Same split as
+        // `territories` directly below: the writer runs in the engine environment and resolves it once.
+        // Omitted rather than guessed when the writer had none, and every reader falls back to the key.
+        ...(registerLabel ? { label: registerLabel } : {}),
         canCount: registerCanCount,
         ...(registerTerritories === undefined ? {} : { territories: registerTerritories }),
       }
@@ -335,9 +341,9 @@ export function postureDisagreement(snapshot, live) {
   // the better answer for a reader: "found" against "not found" says it without a legend.
   const found = (v) => (v === true ? "found" : v === false ? "not found" : null);
   differ("engine program", found(snapshot.engine?.binaryPresent), found(live.engine?.binaryPresent),
-    "whether a NEW search can start — the engine that last ran and this deployment do not agree that the "
-    + "engine program can be found, so one screen offers a search the other refuses. Restart the engine "
-    + "service so it re-reads its PATH, or install the CLI where the service can see it");
+    "whether a NEW search can start — the services, when they last started, and this deployment do not agree "
+    + "that the engine program can be found, so one screen offers a search the other refuses. Restart the "
+    + "services so they look again; if they still disagree, `clearotron doctor` says which side to fix and how");
 
   // Flags: compare only names BOTH sides declare, for the same reason `differ` skips absent values —
   // a build that adds a flag must not read as every older capture disagreeing with it.
@@ -363,7 +369,7 @@ export function postureDisagreement(snapshot, live) {
 
 /** Where the snapshot lives. Beside the pool, so it shares the pool's lifecycle and backup. */
 export function snapshotPath(poolRoot) {
-  return join(poolRoot, "_state", "prelim-flag-snapshot.json");
+  return join(poolRoot, "_state", "clearance-flag-snapshot.json");
 }
 
 /**
@@ -377,7 +383,10 @@ export function readFlagSnapshot(poolRoot) {
   // reads as intentional.
   if (!poolRoot) return null;
   try {
-    const raw = JSON.parse(readFileSync(snapshotPath(poolRoot), "utf8"));
+    // The file's pre-rename name is read when the new one is not there yet, so an upgraded install does
+    // not read as "no snapshot" until its first write under the new name.
+    const legacy = join(poolRoot, "_state", "prelim-flag-snapshot.json");
+    const raw = JSON.parse(readFileSync(existsSync(snapshotPath(poolRoot)) || !existsSync(legacy) ? snapshotPath(poolRoot) : legacy, "utf8"));
     if (!raw || typeof raw !== "object" || typeof raw.flags !== "object") return null;
     return raw;
   } catch {
@@ -425,6 +434,22 @@ export function registerTerritoriesFor(snapshot) {
   return Array.isArray(v) ? v.filter((n) => typeof n === "string") : undefined;
 }
 
+/**
+ * The wired register's DISPLAY label, for a sentence a client reads — `null` when the snapshot does not
+ * carry one, which every snapshot written before this shipped does not.
+ *
+ * FALLS BACK TO THE PROVIDER KEY rather than to nothing: a door that names the register is better off
+ * saying "signa" than saying nothing at all, and the caller decides whether a key is good enough to
+ * print. It is deliberately NOT title-cased on the way out — "uspto-local" title-cased is worse prose
+ * than the key, and inventing a display name is the provider module's job, not this reader's.
+ */
+export function registerLabelFor(snapshot) {
+  const l = snapshot?.register?.label;
+  if (typeof l === "string" && l.trim()) return l.trim();
+  const p = snapshot?.register?.provider;
+  return typeof p === "string" && p.trim() ? p.trim() : null;
+}
+
 /**
  * What this instance searches. THREE answers, exactly as `registerTerritoriesFor` above:
  *
@@ -535,11 +560,12 @@ export async function livePosture({ env = process.env } = {}) {
   const { REGISTER_PROVIDER } = await import("./driver.config.mjs");
   const { capabilitiesFor } = await import("./register-capabilities.mjs");
   const canCount = (() => { try { return capabilitiesFor(REGISTER_PROVIDER).countProbe !== "none"; } catch { return null; } })();
+  const label = (() => { try { return capabilitiesFor(REGISTER_PROVIDER).label ?? null; } catch { return null; } })();
   const { coveredTerritoryNames } = await import("./register-coverage.mjs");
   const territories = await (async () => { try { return await coveredTerritoryNames(capabilitiesFor(REGISTER_PROVIDER)); } catch { return undefined; } })();
   const { engineInventory, providerInventory } = await import("./config-inventory.mjs");
   return buildFlagSnapshot(env, {
-    capturedAt: new Date().toISOString(), registerProvider: REGISTER_PROVIDER, registerCanCount: canCount,
+    capturedAt: new Date().toISOString(), registerProvider: REGISTER_PROVIDER, registerLabel: label, registerCanCount: canCount,
     registerTerritories: territories,
     engine: engineInventory(env), providers: providerInventory(env),
   });

package/driver/form-neighbourhood.mjs

@@ -84,6 +84,36 @@ export function editNeighbourhood(element) {
   return [...out].sort();
 }
 
+// ── A one-letter neighbour that is an ordinary word with a DIFFERENT SOUND is not searched ────────────
+//
+// THE REVIEWING LAWYER'S TEST IS CONFUSING SIMILARITY, and edit-1 over a short ordinary word is mostly other
+// ordinary words: CARE, CODE, CORD, BORE, MORE beside CORE, each a common mark with its own crowd. Measured
+// on a delivered four-letter run, 2026-09-18: 1,037 of 2,098 records (49%) were reached only by the one-letter
+// lists; on the dense production matter of 2026-09-16, 1,154 of 2,146 (54%). Conceptually different words are
+// not confused by consumers, so fetching them is cost and not coverage. A respelling that sounds the same —
+// KORE for CORE — is exactly what a search must find, and so is every neighbour of a made-up word, because two
+// unknown words that sound alike have nothing conceptual to keep them apart (MALENA beside VALENA).
+//
+// So a neighbour is dropped only when BOTH hold: it is in the ordinary-word list, AND no Double-Metaphone key
+// of it matches any key of the element. Everything else is dispatched exactly as before. There is no judgment
+// of the MARK here — coined or ordinary — only of each neighbour, so a coined element keeps its whole list
+// except where a neighbour is a different-sounding real word. The list only ever removes queries, and a word
+// missing from it is searched: over-search is the safe direction.
+//
+// DOUBLE METAPHONE KEEPS VOWELS ONLY AT THE START, so a vowel change inside the word does not change the key:
+// CARE, CURE and GORE all key KR, as CORE does, and are KEPT. That is the rule as specified erring towards the
+// search, and it is recorded here so nobody reads those three as a defect of the list.
+//
+// `ordinaryWords` is a Set of lowercase words, or null. Null drops nothing — the behaviour before this rule —
+// so a caller that does not load the list (every test that predates it) is unchanged. PURE.
+export function ordinaryWordDifferentSound(element, ordinaryWords) {
+  const el = normalizeElement(element);
+  if (!el || !(ordinaryWords instanceof Set) || !ordinaryWords.size) return [];
+  const own = new Set(doubleMetaphone(el).filter(Boolean));
+  return editNeighbourhood(el).filter((t) => ordinaryWords.has(t)
+    && !doubleMetaphone(t).filter(Boolean).some((k) => own.has(k)));
+}
+
 // ── Consonant skeleton + wildcard patterns — retrieve the phonetic VOWEL family in one bounded vendor query ──
 // VALENA → consonants V,L,N → skeleton "VLN"; vowel-slot wildcard "V?L?N?"-style patterns the vendor's Lucene
 // `?`/`*` supports (live-confirmed). This is the tractable, complete way to reach VYLONA/VILINA/VILENA without
@@ -229,13 +259,18 @@ export function transliterations(element, { scripts = SUPPORTED_SCRIPTS } = {})
 // droppedVariantFamilies). The floor stays exhaustive WITHIN the families judgment kept — this is the funnel
 // honouring a scope decision that was already written and, until 2026-07-18, ignored. edit-1 is never
 // droppable: it is the doctrine floor (radiusFor), not a family.
-export function formNeighbourhood(element, { markets = [], scripts = SUPPORTED_SCRIPTS, droppedAxes = [] } = {}) {
+export function formNeighbourhood(element, { markets = [], scripts = SUPPORTED_SCRIPTS, droppedAxes = [], ordinaryWords = null } = {}) {
   const radius = radiusFor(element);
   const el = radius.element;
-  if (!el) return { element: "", radius, exactQueries: [], wildcardPatterns: [], phoneticKeys: [], confusables: [], transliterations: [], ledger: { disclosed: radius.note, axes: [] } };
+  if (!el) return { element: "", radius, exactQueries: [], wildcardPatterns: [], phoneticKeys: [], confusables: [], transliterations: [], ordinaryWordDifferentSound: [], ledger: { disclosed: radius.note, axes: [] } };
 
   const drop = new Set(droppedAxes ?? []);
-  const edits = editNeighbourhood(el);
+  const generatedEdits = editNeighbourhood(el);
+  // Only edit-1 is filtered. A term another generator also produces (a confusable, a transliteration) is
+  // still dispatched as that generator's — those families are unchanged by this rule.
+  const notSearched = ordinaryWordDifferentSound(el, ordinaryWords);
+  const skip = new Set(notSearched);
+  const edits = generatedEdits.filter((t) => !skip.has(t));
   const confs = drop.has("visual-confusable") ? [] : visualConfusables(el);
   const trans = drop.has("transliteration") ? [] : transliterations(el, { scripts });
   const wildcards = drop.has("phonetic-family") ? [] : skeletonPatterns(el);
@@ -261,11 +296,15 @@ export function formNeighbourhood(element, { markets = [], scripts = SUPPORTED_S
     phoneticKeys: keys,
     confusables: confs,
     transliterations: trans,
+    ordinaryWordDifferentSound: notSearched,
     ledger: {
       disclosed: radius.note,
       dropped_axes: [...drop].sort(),
       axes: [
-        { axis: "edit-1", count: edits.length, mechanism: "Damerau-Levenshtein edit-1, exhaustive" },
+        { axis: "edit-1", count: edits.length, generated: generatedEdits.length, not_searched: notSearched.length,
+          mechanism: notSearched.length
+            ? "Damerau-Levenshtein edit-1, exhaustive, less the neighbours that are ordinary words with a different sound"
+            : "Damerau-Levenshtein edit-1, exhaustive" },
         // NO PATTERN is a THIRD state, and it is disclosed in the same voice as a judgment drop. An
         // element with too few consonants to anchor a skeleton wildcard (X, and anything normalizing to
         // one character) yields no retrieval pattern at all — see skeletonPatterns. Silence here would
@@ -349,7 +388,7 @@ export function coverageGaps(band, { dispatched = [], explained = [] } = {}) {
 // exhaustive edit-1 neighbourhood: 1,736 junk exact queries on AquaPlus 2026-07-17, 4,524 on the 07-16 run.
 // Measured 2026-07-18: 10 of 20 recent runs carried one of these. The JSON field is a validated scalar and
 // cannot swallow a sentence.
-export function renderFormNeighbourhoodJson(manifestMd, { markets = [], scripts = SUPPORTED_SCRIPTS, droppedAxes = [], model = null, mark = "" } = {}) {
+export function renderFormNeighbourhoodJson(manifestMd, { markets = [], scripts = SUPPORTED_SCRIPTS, droppedAxes = [], model = null, mark = "", ordinaryWords = null } = {}) {
   const { seeds, seededFrom, rejected } = floorSeeds(manifestMd, { model, mark });
   // The reason travels WITH the throw. It used to say only "the job states no mark", which is one
   // of two causes and not the one that actually fires: a non-Latin mark states a mark perfectly well and
@@ -361,7 +400,7 @@ export function renderFormNeighbourhoodJson(manifestMd, { markets = [], scripts
       || "manifest names no Dominant element / Formative root, and the job states no mark";
     throw new Error(`form_neighbourhood_no_element: ${why} — nothing to seed the mechanical form band`);
   }
-  const elements = seeds.map(({ element, role }) => ({ element, role, band: formNeighbourhood(element, { markets, scripts, droppedAxes }) }));
+  const elements = seeds.map(({ element, role }) => ({ element, role, band: formNeighbourhood(element, { markets, scripts, droppedAxes, ordinaryWords }) }));
   const families = variantFloorFamilies(elements, { mark, droppedAxes });
   return JSON.stringify({
     schema_version: 2,
@@ -596,10 +635,11 @@ export function spacingPunctuationForms(mark) {
 export function variantFloorFamilies(elements, { mark = "", droppedAxes = [] } = {}) {
   const drop = new Set(droppedAxes ?? []);
   const edit = new Set(), visual = new Set(), translit = new Set(), other = new Set();
-  const wildcards = new Set(), keys = new Set();
+  const wildcards = new Set(), keys = new Set(), notSearched = new Set();
   for (const el of elements ?? []) {
     const band = el?.band;
     if (!band) continue;
+    for (const t of band.ordinaryWordDifferentSound ?? []) notSearched.add(t);
     const edits = new Set(editNeighbourhood(el.element));
     const confs = new Set(band.confusables ?? []);
     const trans = new Set(band.transliterations ?? []);
@@ -639,6 +679,12 @@ export function variantFloorFamilies(elements, { mark = "", droppedAxes = [] } =
       dropped: drop.has("phonetic-family"), terms: sorted(wildcards), phonetic_keys: sorted(keys) },
     ...(other.size ? [{ family: "other", category: "other", generator: "formNeighbourhood (dedupeOnFold residue)",
       enumeration: "a dispatched term no single generator claims — recorded rather than hidden", dropped: false, terms: sorted(other) }] : []),
+    // NOT SEARCHED, and listed in full so the plan says what it left out and why. Not a crowd and not a
+    // gap: a deliberate rule (ordinaryWordDifferentSound). `searched: false` keeps it out of the floor the
+    // merge below counts, so a model that proposes one of these words is recorded as its own addition.
+    ...(notSearched.size ? [{ family: "ordinary-word-different-sound", category: "phonetic", generator: "editNeighbourhood",
+      enumeration: "edit-1 neighbours that are ordinary English words and share no Double-Metaphone key with the element",
+      dispatch: "not searched — ordinary word, different sound", searched: false, dropped: true, terms: sorted(notSearched) }] : []),
   ];
 }
 
@@ -674,6 +720,7 @@ export function mergeVariantFloor(floorFamilies, modelVariants, { rejectedSeeds
   const families = Array.isArray(floorFamilies) ? floorFamilies : [];
   const floorByKey = new Map();
   for (const f of families) {
+    if (f?.searched === false) continue;   // listed for disclosure, never searched — not floor
     for (const t of f?.terms ?? []) {
       const k = formKey(t);
       if (!k || floorByKey.has(k)) continue;

package/driver/framework.mjs

@@ -2,7 +2,7 @@
 // Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
 // framework.mjs — the risk-framework MANIFEST layer (doc 50: the framework in force rates the matter).
 //
-// The framework itself is a PROSE deck (skills/prelim-search/risk-framework*.md) — the customer's own legal
+// The framework itself is a PROSE deck (skills/clearance-search/risk-framework*.md) — the customer's own legal
 // judgment written down, which synthesis reads and reasons WITH. This module carries the small
 // machine-readable sidecar (<framework>.manifest.json) that lets validators, the renderer, the archive index
 // and the profile UI consume the framework's VOCABULARY — band words, severity order, entity label, source —
@@ -18,12 +18,12 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
 // ── selection (the ?? fallback IS the "Generic default rates the matter" rule) ────────────────────────────
-export const DEFAULT_FRAMEWORK = "skills/prelim-search/risk-framework.md";
-export const DEFAULT_WORKED_EXAMPLES = "skills/prelim-search/worked-examples.md";
+export const DEFAULT_FRAMEWORK = "skills/clearance-search/risk-framework.md";
+export const DEFAULT_WORKED_EXAMPLES = "skills/clearance-search/worked-examples.md";
 export const frameworkFor = (profile) => profile?.frameworkPath ?? DEFAULT_FRAMEWORK;
 export const workedExamplesFor = (profile) => profile?.workedExamplesPath ?? DEFAULT_WORKED_EXAMPLES;
 
-/** skills/prelim-search/risk-framework-x.md → skills/prelim-search/risk-framework-x.manifest.json.
+/** skills/clearance-search/risk-framework-x.md → skills/clearance-search/risk-framework-x.manifest.json.
  *  The manifest path is DERIVED, never a profile knob — the profile names only the .md. */
 export const manifestPathFor = (fwPath) => String(fwPath).replace(/\.md$/, ".manifest.json");