clearotron 0.3.2-beta.8 → 0.3.2-beta.9

package/driver/drainer-identity.mjs

@@ -105,14 +105,40 @@ export function drainerVerdict({ stamp, headCommit, isAlive, processes, ppidOf =
   const nameThem = (ps) => ps.map((p) => `pid ${p.pid}`).join(", ");
 
   if (!stamp) {
-    // COULD NOT LOOK, AND THAT IS A FAILURE. The deploy must not report a build live having never
-    // established what the executing process holds — "no stamp" is the exact state the incident's
-    // orphaned drainer was in, so treating it as a skip would pass the very box this arm exists for.
-    const extra = seen === null ? "and the process table could not be read either"
-      : seen.length ? `while ${seen.length} drainer-shaped process(es) ARE running (${nameThem(seen)}) — unstamped, so what build they hold is unknown`
-      : "and no drainer-shaped process is running, so nothing is executing runs on this box";
-    return { state: "fail", message: `no drainer identity stamp at ${STAMP_BASENAME}: the build held by the process that `
-      + `executes runs was NOT established, ${extra}. This is a failure to look, never a pass.${postureNote}` };
+    // THREE SITUATIONS LIVED IN ONE FAIL, AND ONE OF THEM IS NOT A FINDING.
+    //
+    // All three begin the same way — no stamp, so what the executing process holds was never
+    // established. What separates them is the PROCESS TABLE, and the old message ran the answers
+    // together: it asserted "nothing is executing runs on this box", a finding, and closed with "This is
+    // a failure to look, never a pass", which is the opposite claim. A reader could act on either.
+    //
+    // The module's ruling about postures says what each exit's posture IS. It does not license reporting
+    // two different facts through one verdict, and a deployment check is exactly where that is
+    // expensive: redeploying fixes an idle box and does nothing at all for an unreadable process table.
+    //
+    // — NOTHING WAS ESTABLISHED IN EITHER DIRECTION. No stamp and no process table: this arm did not
+    // find an idle box, it failed to look at one. Skipped and marked, never passed — the caller counts
+    // it toward a different exit code, and the box could be perfectly healthy or completely wedged.
+    if (seen === null) {
+      return { state: "skip", blocked: true,
+        message: `no drainer identity stamp at ${STAMP_BASENAME} AND the process table could not be read: what the `
+          + "process that executes runs holds was not established, and neither was whether one is running at all. "
+          + `This is a failure to look — redeploying would change nothing, because nothing was compared.${postureNote}` };
+    }
+    // — THE INCIDENT'S OWN SHAPE. Drainer-shaped processes are running and none of them stamped
+    // anything, so what build they hold is unknown. This is the state the orphaned drainer was in and
+    // the reason this arm exists; it is a finding and stays one.
+    if (seen.length) {
+      return { state: "fail", message: `no drainer identity stamp at ${STAMP_BASENAME} while ${seen.length} `
+        + `drainer-shaped process(es) ARE running (${nameThem(seen)}) — unstamped, so what build they hold is `
+        + `unknown. The process table was read; this is what it said.${postureNote}` };
+    }
+    // — A FINDING, and the plainest one here. The process table WAS read and holds no drainer, so
+    // nothing is executing runs on this box. Saying "failure to look" about a table that answered was
+    // the contradiction at the centre of this.
+    return { state: "fail", message: `no drainer identity stamp at ${STAMP_BASENAME} and no drainer-shaped process `
+      + "is running, so nothing is executing runs on this box. The process table was read, and this is what "
+      + `it said.${postureNote}` };
   }
 
   const pid = Number(stamp.pid) || 0;

package/driver/driver.config.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
-// Central paths + tunables for the prelim-search deterministic driver.
+// Central paths + tunables for the clearance-search deterministic driver.
 //
 // The driver runs as an ordinary UNIX service account (launched by systemd), NOT as an LLM agent.
 // The agent exec-deny is a gateway agent-tool restriction; it does not apply to this OS process.
@@ -15,7 +15,7 @@ import { isWsl } from "../shared/wsl.mjs";   // — the one answer to "is this L
 import { envFrom } from "../shared/env-aliases.mjs";   // — an operator-facing name is the one an operator sets, and it has to work where they set it; — envFrom is the resolver that reads every spelling of it
 import { invoke } from "../shared/invocation.mjs";   // — name a command the reader can actually type
 import { envFileRead } from "../shared/env-local.mjs";   // — WHICH file to set it in, measured; null for a service that read none
-import { numericSetting, resolveNumericSetting } from "./numeric-setting.mjs";   // — a number, or a refusal that names the variable; never NaN
+import { numericSetting, resolveNumericSetting } from "./numeric-setting.mjs"; import { STUDIO_SEGMENTS, STUDIO_SEGMENT_RE, studioSegmentFor } from "../shared/pre-rename-spellings.mjs"; export { STUDIO_SEGMENTS, STUDIO_SEGMENT_RE, studioSegmentFor };   // the studio segment an install keeps its runs under   // — a number, or a refusal that names the variable; never NaN
 
 const { X_OK } = FS;
 
@@ -111,6 +111,23 @@ export const envGateOn = (name) => {
 // so import-time captures silently pinned every test to the FIRST test's env (workspace root, pool,
 // retries) — the root of the intermittent cross-test contamination flake. Getters make "set env, then
 // run" mean what it says, in tests and in prod alike.
+// The four skill folders the identifier rename moved. A store outside the product may still hold them,
+// and a profile may still name them, under the old spelling.
+const RENAMED_SKILL_DIRS = Object.freeze([
+  ["clearance-search", "prelim-search"], ["clearance-register", "prelim-register"],
+  ["clearance-common-law", "prelim-common-law"], ["clearance-variants", "prelim-variants"],
+]);
+/** `[rel, the same path under the folder's other spelling | null]`. PURE. */
+export function skillSpellings(rel) {
+  const m = /^skills\/([a-z-]+)(\/.*)?$/.exec(String(rel ?? ""));
+  if (!m) return [rel, null];
+  for (const [now, before] of RENAMED_SKILL_DIRS) {
+    if (m[1] === now) return [rel, `skills/${before}${m[2] ?? ""}`];
+    if (m[1] === before) return [rel, `skills/${now}${m[2] ?? ""}`];
+  }
+  return [rel, null];
+}
+
 export const config = {
   // / — A BLANK VALUE IS NOT A CONFIGURED VALUE. `process.env.X || default` treats "   " as
   // configured, because a whitespace-only string is TRUTHY in JavaScript — so a variable set to spaces
@@ -212,21 +229,8 @@ export const config = {
    * still fails loudly against the canonical location rather than silently against the overlay.
    */
   resolveSkillPath(relFromSkillsRoot) {
-    const rel = String(relFromSkillsRoot ?? "").replace(/^\/+/, "");
-    const overlay = this.skillsOverlayDir;
-    if (overlay) {
-      // FAIL LOUD ON AN UNREADABLE OVERLAY. existsSync() answers false for a permission error just as it
-      // does for a missing file, so a config store the process cannot read would silently resolve EVERY
-      // file to the repo — swapping a customer's own risk framework for the Generic default with nothing
-      // in the log to say so. A configured-but-unreadable overlay is a deploy defect, not a fallback.
-      if (!existsSync(overlay))
-        throw new Error(`skills_overlay_unreadable:${overlay} (CLEAROTRON_INSTRUCTIONS_DIR names it, set by the operator or derived by the portal from PROFILE_REPO_ROOT, but this process cannot see it — customer-specific skills would silently fall back to the repo defaults)`);
-      const p = join(dirname(overlay), rel);
-      if (existsSync(p)) return p;
-    }
-    return join(dirname(this.skillsBaseDir), rel);
+    return this.resolveSkillPathReport(relFromSkillsRoot).path;
   },
-
   /**
    * WHICH LAYER ANSWERED, as a fact rather than a path — `resolveSkillPath` with its reasoning shown.
    *
@@ -252,13 +256,24 @@ export const config = {
    */
   resolveSkillPathReport(relFromSkillsRoot) {
     const rel = String(relFromSkillsRoot ?? "").replace(/^\/+/, "");
-    const basePath = join(dirname(this.skillsBaseDir), rel);
+    // EITHER SPELLING OF A RENAMED SKILL FOLDER, in either direction. A store that has not moved its
+    // folders still holds `skills/prelim-search/…`, and a profile written before the rename still NAMES
+    // it; the product ships only the new names. Tried in the overlay first — a client's own doctrine must
+    // never be silently replaced by ours because a folder name changed — and the base answers only under
+    // the name it ships.
+    const [asNamed, other] = skillSpellings(rel);
+    const shipped = rel === asNamed && other && /^skills\/prelim-/.test(asNamed) ? other : asNamed;
+    const basePath = join(dirname(this.skillsBaseDir), shipped);
     const overlay = this.skillsOverlayDir;
     if (!overlay) return { path: basePath, rel, layer: existsSync(basePath) ? "base-only" : "missing", overlayPath: null, basePath };
     if (!existsSync(overlay))
       throw new Error(`skills_overlay_unreadable:${overlay} (CLEAROTRON_INSTRUCTIONS_DIR names it, set by the operator or derived by the portal from PROFILE_REPO_ROOT, but this process cannot see it — customer-specific skills would silently fall back to the repo defaults)`);
-    const overlayPath = join(dirname(overlay), rel);
+    const overlayPath = join(dirname(overlay), asNamed);
     if (existsSync(overlayPath)) return { path: overlayPath, rel, layer: "overlay", overlayPath, basePath };
+    if (other) {
+      const otherPath = join(dirname(overlay), other);
+      if (existsSync(otherPath)) return { path: otherPath, rel, layer: "overlay", overlayPath: otherPath, basePath };
+    }
     return { path: basePath, rel, layer: existsSync(basePath) ? "base" : "missing", overlayPath, basePath };
   },
 
@@ -276,7 +291,7 @@ export const config = {
     return roots;
   },
 
-  // The base that a profile's "skills/prelim-search/<file>.md" path is relative to — i.e. the PARENT
+  // The base that a profile's "skills/clearance-search/<file>.md" path is relative to — i.e. the PARENT
   // of skillsDir. Everything the DRIVER reads itself (framework manifests, band-meaning extraction)
   // must join against this, exactly as the agent resolves the same relative paths against the
   // skillsDir it is handed (gateway.mjs engineSkillsDir).
@@ -305,15 +320,17 @@ export const config = {
   },
   // Escaped prefix for the reverse regexes below (a custom prefix may carry regex metachars).
   get workspacePrefixRe() { return this.workspacePrefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); },
-  // `prelim-search` IS NOT A PRODUCT NAME HERE and does not follow the product rename. It is a
-  // directory segment on disk, and every archived run — its slug dirs, its `archive/`, its matter
-  // ledger — was written under it. Renaming the segment does not move those runs; it points the
-  // reader somewhere empty, and an empty directory reads as "no runs" rather than as an error.
-  // The rule the tree already enforces elsewhere: a token that is read back out of an archive keeps
-  // its old spelling, or the code refuses its own archive. Thirteen sites compute this segment and
-  // all thirteen stay.
+  // THE STUDIO SEGMENT IS NOT A PRODUCT NAME and does not follow the product rename. It is a directory
+  // segment on disk, and every archived run — its slug dirs, its `archive/`, its queue, its matter ledger —
+  // was written under it. Renaming it does not move those runs; it points the reader somewhere empty, and
+  // an empty directory reads as "no runs" rather than as an error. The identifier rename rewrote this
+  // comment together with the thirteen sites it protected, and an upgraded install lost sight of its whole
+  // archive. So an install keeps the segment it has: `prelim-search` wherever that directory exists, and
+  // `clearance-search` only for an install that has no other. Every site asks `studioSegmentFor`.
+  studioSegment(workspaceDir) { return studioSegmentFor(workspaceDir); },
   studioRootForAgent(agentId) {
-    return join(this.workspaceRoot, this.workspaceDirName(agentId), "studio", "prelim-search");
+    const ws = join(this.workspaceRoot, this.workspaceDirName(agentId));
+    return join(ws, "studio", studioSegmentFor(ws));
   },
   queueDirForAgent(agentId) {
     return join(this.studioRootForAgent(agentId), "queue");
@@ -321,9 +338,10 @@ export const config = {
   archiveRootForAgent(agentId) {
     return join(this.studioRootForAgent(agentId), "archive");
   },
-  // …/<prefix><id>/studio/prelim-search/queue → "<id>"; null if the path isn't an agent queue dir.
+  // …/<prefix><id>/studio/<segment>/queue → "<id>"; null if the path isn't an agent queue dir. Either
+  // spelling of the segment, because an install keeps the one it has.
   agentIdFromQueueDir(qdir) {
-    const m = new RegExp(`(?:^|/)${this.workspacePrefixRe}([^/]+)/studio/prelim-search/queue/?$`).exec(qdir);
+    const m = new RegExp(`(?:^|/)${this.workspacePrefixRe}([^/]+)/studio/${STUDIO_SEGMENT_RE}/queue/?$`).exec(qdir);
     return m ? m[1] : null;
   },
   // Every agent workspace's clearotron queue. The systemd `.path` watches these and the runner drains ALL of
@@ -343,14 +361,18 @@ export const config = {
     try {
       for (const name of readdirSync(root)) {
         if (this.agentIdFromWorkspaceName(name) == null) continue;
-        const q = join(root, name, "studio", "prelim-search", "queue");
-        if (existsSync(q)) dirs.push(q);
+        // BOTH spellings are drained where both exist: a job queued under either is a job somebody is
+        // waiting on, and an unwatched queue looks exactly like an empty one.
+        for (const seg of STUDIO_SEGMENTS) {
+          const q = join(root, name, "studio", seg, "queue");
+          if (existsSync(q)) dirs.push(q);
+        }
       }
     } catch { /* workspaceRoot may not exist in some test envs — fall through to the canonical queue */ }
     // THE ONE AGENT NAME NO CONFIGURATION REMOVES, and it is deliberate. row 5.
     //
     // `this.queueDir` is `queueDirForAgent("clawdi")` — a LITERAL, not `defaultAgent` — so every
-    // deployment, however configured, watches `<workspacePrefix>clawdi/studio/prelim-search/queue`.
+    // deployment, however configured, watches `<workspacePrefix>clawdi/studio/clearance-search/queue`.
     // Setting CLEAROTRON_DEFAULT_AGENT does not remove it (prod runs `ops`, dev runs `dev`, and both still
     // watch this); nor does CLEAROTRON_WORKSPACE_PREFIX. An installer who copies `.env.example` gets a
     // neutral default agent AND this directory.
@@ -540,7 +562,7 @@ export const config = {
   // directory, so renaming the default moves the install to an empty one and nothing migrates. Here
   // the orphaned files are run-slot locks, so a live run's slot goes unseen and the global cap is
   // silently exceeded rather than enforced. Ruling.
-  get runLockDir() { return this.envValue("CLEAROTRON_RUN_LOCK_DIR") || join(this.workspaceRoot, "prelim-run-locks"); },
+  get runLockDir() { return this.envValue("CLEAROTRON_RUN_LOCK_DIR") || [join(this.workspaceRoot, "prelim-run-locks"), join(this.workspaceRoot, "clearance-run-locks")].find((d, i) => i === 1 || existsSync(d)); },   // the name the install already has wins
 
   // Delivery outbox (Workstream B). On a handoff-mode finish the driver drops <runId>.pending here (naming
   // the forwarder agent); the systemd-user prelim-outbox.path unit fires an INSTANT clearotron-deliver wake off
@@ -552,7 +574,31 @@ export const config = {
   // directory, so renaming the default moves the install to an empty one and nothing migrates. Here
   // the orphaned files are requester-facing events — delivered, run-failed, intake-rejected — so the
   // visible failure is a requester never told their run finished. Ruling.
-  get outboxDir() { return this.envValue("CLEAROTRON_OUTBOX_DIR") || join(this.workspaceRoot, "prelim-outbox"); },
+  get outboxDir() { return this.envValue("CLEAROTRON_OUTBOX_DIR") || join(this.workspaceRoot, "clearance-outbox"); },
+
+  // ── THE DIRECTORY THIS DEFAULT USED TO NAME, AND WHY IT IS STILL READ ──────────────────────────────
+  //
+  // This default was `clearance-outbox` until the identifier was renamed. A deployment that never pinned
+  // `CLEAROTRON_OUTBOX_DIR` has its `<runId>.pending` markers sitting in the old directory, and moving
+  // the default without reading the old one orphans every one of them. That failure is silent and it is
+  // the expensive kind: a marker is a report a client is OWED, an unread outbox is indistinguishable
+  // from nothing to send, and the run that produced it has already recorded itself as delivered-pending.
+  //
+  // NULL WHEN THE VARIABLE IS SET, because then the operator named the directory and there is no old
+  // default in play. Writers use `outboxDir` alone; only readers consult this, which is the same posture
+  // the run records take — new work uses the new name, old work is still understood.
+  //
+  // THE OLD SPELLING IS THE WHOLE POINT OF THIS ACCESSOR, and a sweep took it. The identifier rename
+  // moved the directory from `prelim-outbox` to `clearance-outbox`, and the follow-up that renamed the
+  // directory's 85 occurrences rewrote this literal along with them — leaving the accessor that exists to
+  // name the OLD directory naming the new one. Both getters then answered the same path: the drain read
+  // the new directory twice, never read the old one, and every marker under it was listed TWICE. So a box
+  // that never pinned the variable got exactly the failure the block above describes — orphaned markers,
+  // silently — plus duplicate work on the ones it could see. It is written once, here, and pinned by a
+  // test that asserts the two are different.
+  get legacyOutboxDir() {
+    return this.envValue("CLEAROTRON_OUTBOX_DIR") ? null : join(this.workspaceRoot, "prelim-outbox");
+  },
 
   // ── Delivery/comms (Phase 2, standalone product) ─────────────────────────────────────────────────
   // THERE IS ONE MODE AND IT IS NOT A SETTING. The driver SENDS NOTHING: every requester-facing event
@@ -570,7 +616,7 @@ export const config = {
   // LOCATION (see studioRootForAgent / agentIdFromQueueDir above).
   //
   // THE DEFAULT IS PART OF A PATH, so changing it moves where an install looks for its own runs:
-  // every run dir is `<workspaceRoot>/workspace-<agent>/studio/prelim-search/…`. An install created
+  // every run dir is `<workspaceRoot>/workspace-<agent>/studio/clearance-search/…`. An install created
   // before this default changed keeps its runs under the old id and must pin it — both spellings,
   // because the gather servers read their own variable:
   //
@@ -939,7 +985,7 @@ export const PROVIDERS = {
     id: "corsearch",
     label: "Corsearch",
     credEnv: "CORSEARCH_SESSION_KEY",
-    skillDoc: "skills/prelim-register/providers/corsearch.md",
+    skillDoc: "skills/clearance-register/providers/corsearch.md",
     hasPublicRecordUrl: true,
     // WP-receipts W2: the public per-record origin (publicRecordOrigin + /mark/<jur>/<id> is a working
     // link) — replaces the fragile resolved-link-origin inference at render for receipt-carrying runs.
@@ -1013,7 +1059,7 @@ export const PROVIDERS = {
     id: "clarivate",
     label: "Clarivate Compumark",
     credEnv: "CLARIVATE_API_KEY",
-    skillDoc: "skills/prelim-register/providers/clarivate.md",
+    skillDoc: "skills/clearance-register/providers/clarivate.md",
     hasPublicRecordUrl: false, // Compumark Content has no public record URL — cite the office register
     //, ruling 2026-08-20 — WHAT A CARD SHOWS WHERE A LINK CANNOT GO. A UI exists for this
     // provider and we do not know its per-record URL, so the card says so and says it is unfinished.
@@ -1155,7 +1201,7 @@ export const PROVIDERS = {
     id: "signa",
     label: "Signa",
     credEnv: "SIGNA_API_KEY",
-    skillDoc: "skills/prelim-register/providers/signa.md",
+    skillDoc: "skills/clearance-register/providers/signa.md",
     hasPublicRecordUrl: false, // Signa exposes no per-record public URL — cite the office register
     //, ruling 2026-08-20 — no register UI exists to link to at all, so the card points at
     // the artifact that DOES carry the record: the audit workbook. Naming it is the whole of this
@@ -1210,8 +1256,12 @@ export const PROVIDERS = {
         // on the search response, so this no longer has to answer `present` and nothing else. It is
         // still null whenever the vendor would only approximate it — and null there means UNKNOWN,
         // which is the whole reason the field may never be filled in with a figure from anywhere else.
+        // `floor` rides beside `approximate` because the two are one fact: the register answered, and the
+        // answer is "more than this". Without the number the disclosure is not usable — "approximate"
+        // alone says no more than "unknown" does, which is the state this replaces.
         return { ok: true, total: Number.isFinite(p.total_hits) ? p.total_hits : null,
-          approximate: p.total_approximate === true, present: p.present === true, note: p.note };
+          approximate: p.total_approximate === true, floor: Number.isFinite(p.total_floor) ? p.total_floor : null,
+          present: p.present === true, note: p.note };
       } catch (e) { return { ok: false, cause: `countHits threw: ${e.message}` }; }
     },
     // `reason`, not `cause`, on every refusal: the listing reads `reason` (register-records.mjs), so a
@@ -1301,7 +1351,7 @@ export const PROVIDERS = {
     // list — without this, an instance holding the id and no secret passes preflight and dies on the
     // first token request, after model spend and reported as a provider fault.
     credEnvAlso: ["EUIPO_CLIENT_SECRET"],
-    skillDoc: "skills/prelim-register/providers/euipo.md",
+    skillDoc: "skills/clearance-register/providers/euipo.md",
     hasPublicRecordUrl: true,
     publicRecordOrigin: "https://euipo.europa.eu",
     async recordFetch(uri, { agentId, sessionKey, recordLog = null }) {
@@ -1367,7 +1417,7 @@ export const PROVIDERS = {
     id: "uspto-local",
     label: "USPTO (local index)",
     credEnv: "USPTO_LOCAL_DB",
-    skillDoc: "skills/prelim-register/providers/uspto-local.md",
+    skillDoc: "skills/clearance-register/providers/uspto-local.md",
     hasPublicRecordUrl: true,
     // TSDR publishes a page per serial, so a finding can cite an address the reader can open. The
     // record ref is /mark/us/<serial>, and the core builds the full statusSearch link on the record.
@@ -1471,7 +1521,7 @@ export const PROVIDERS = {
     label: "Free tier (EUIPO + USPTO local index)",
     credEnv: "EUIPO_CLIENT_ID",
     credEnvAlso: ["EUIPO_CLIENT_SECRET"],
-    skillDoc: "skills/prelim-register/providers/free-tier.md",
+    skillDoc: "skills/clearance-register/providers/free-tier.md",
     hasPublicRecordUrl: true,
     // NULL, deliberately: the two members have DIFFERENT public origins (euipo.europa.eu and the USPTO),
     // so a single origin string here would stamp one office's host onto the other's citations. The
@@ -1821,7 +1871,7 @@ export function preflightCredentials(env = process.env) {
 // paid for. This door is that same failure, moved in front of the spend.
 //
 // GATED ON THE COMPONENT, NEVER ON THE PIPELINE. `pipeline === "clearance"` is the wrong predicate and
-// fails in the expensive direction: `prelim-register-only` is a clearance that carries
+// fails in the expensive direction: `clearance-register-only` is a clearance that carries
 // `commonLawGrid: false`, searches no unregistered-use half by design, and would be refused for a
 // credential its lane never reads. The component IS the question — search-policy.mjs calls it "the
 // clearance's unregistered-use half" in as many words.
@@ -2332,7 +2382,7 @@ export function preflightDeploymentUrls(env = process.env) {
 const RUN_FREE_BYTES_FLOOR = 500e6;
 
 /** Nearest ancestor of `p` that exists. statfs needs a real path, and on a first run NONE of
- *  …/workspace-<agent>/studio/prelim-search exists yet — measuring the leaf would throw ENOENT and land
+ *  …/workspace-<agent>/studio/clearance-search exists yet — measuring the leaf would throw ENOENT and land
  *  in the unmeasurable branch, which would disable this check on exactly the fresh installs it is for. */
 function nearestExistingDir(p) {
   let dir = p;
@@ -2374,7 +2424,7 @@ export function freeSpacePlan({ freeBytes, needBytes, path }) {
  * shape of run that can proceed without one, so there is no exemption to write.
  *
  * MEASURES THE FILESYSTEM THAT WILL HOLD THE BYTES, which is the workspace root's, not `/` and not the
- * repo's. Run directories live under config.studioRoot (…/workspace-<agent>/studio/prelim-search); the
+ * repo's. Run directories live under config.studioRoot (…/workspace-<agent>/studio/clearance-search); the
  * published report goes to poolRoot and the packet to outboxDir, which on a laptop are different
  * filesystems again. A check aimed at the wrong mount passes while the right one is full, which is the
  * silent-pass this exists to prevent — so the path is taken from the caller's studioRoot when the runner

package/driver/engine/mcp/README.md

@@ -14,7 +14,7 @@ The active register provider is mounted under the single, neutral server key `re
 named `register_*` — so the namespaced ids the prompts and allowlists carry (`mcp__register__register_enumerate`)
 stay stable across a provider swap. What is PINNED is the vendor's TOOL tokens, not its name:
 `../../test/provider-neutral-prose.test.mjs` walks `driver/` (skipping `fixtures/`) and fails any `<vendor>_<tool>`
-outside the six `<provider>-server.mjs` files and `../../skills/prelim-register/providers/`, exempting a core's own
+outside the six `<provider>-server.mjs` files and `../../skills/clearance-register/providers/`, exempting a core's own
 `ERROR: … HTTP` diagnostics. The plain vendor NAME is unrestricted: `REGISTER_SERVERS` is keyed by it, and 134 other
 files under `driver/` carry `corsearch`.
 

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

@@ -12,7 +12,7 @@
 // held by FOUR stages — `common-law`, `common-law-half`, `narrative-refutation`, `synthesis`. Because
 // `allowedToolsFor` enumerates every tool on every entry a group resolves to, all four carried
 // `mcp__perplexity__record_dispositions`, while every doctrinal mention of the tool is common-law's:
-// `driver/skills/prelim-common-law/SKILL.md`, and the two common-law stage dictations in `stages.mjs`.
+// `driver/skills/clearance-common-law/SKILL.md`, and the two common-law stage dictations in `stages.mjs`.
 // Zero occurrences in synthesis's dictation block, zero in narrative-refutation's doctrine.
 //
 // That is GRANTED-BUT-NEVER-ORDERED, the defect class, in its mirror form: not a stage ordered to
@@ -75,8 +75,8 @@ async function record_dispositions(params) {
   let spec;
   try { spec = validateGridSpec(JSON.parse(readFileSync(grid_spec_path, "utf8"))); }
   catch (err) { return { isError: true, text: `ERROR: grid_spec_path unreadable/invalid (${err.message}). The driver writes this file; do not hand-author it.` }; }
-  if (!/\/studio\/prelim-search\//.test(spec.output_path))
-    return { isError: true, text: `ERROR: grid spec.output_path must be within a studio/prelim-search run dir; got ${spec.output_path}` };
+  if (!/\/studio\/(?:prelim|clearance)-search\//.test(spec.output_path))   // either spelling: an install keeps the studio segment it has
+    return { isError: true, text: `ERROR: grid spec.output_path must be within a studio/clearance-search run dir; got ${spec.output_path}` };
   // NEVER THROWN PAST THIS POINT. An exception surfaces to the seat as a tool error naming no row, which
   // tells it nothing about what to fix — the failure mode this transport exists to end.
   try {

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

@@ -23,7 +23,7 @@ const BRIDGE = process.env.CLEAROTRON_OAUTH_BRIDGE || join(MCP_DIR, "..", "..",
 // ── The register surface is PROVIDER-NEUTRAL ────────────────────────────────────────────────────
 // The active register provider is mounted under the single server key `register`, and every register
 // tool is named `register_*`. The vendor's name survives ONLY inside its own *-server.mjs file and in
-// skills/prelim-register/providers/<provider>.md (the vocabulary doc the spawns are told to read).
+// skills/clearance-register/providers/<provider>.md (the vocabulary doc the spawns are told to read).
 //
 // Why neutral names rather than interpolating `${PROVIDER}_enumerate` into the prose: the register
 // instructions in stages.mjs / pipeline.mjs / gateway.mjs are then correct BY CONSTRUCTION for every
@@ -275,7 +275,7 @@ const RECORDING = Object.freeze({
       + "DISCOVERY over the run dir (O3c: 21 calls, 1 write / 15 attempts, `ls`/`find`/`cat`), not the "
       + "enumerable pair frame-diff's Read grant covers",
   },
-  // FIFTH — prelim-variants, conversion 3. Classes 3 + 2, and the CLASS 3 half is what makes it
+  // FIFTH — clearance-variants, conversion 3. Classes 3 + 2, and the CLASS 3 half is what makes it
   // different from every conversion before it: O3c measured 9 Bash calls with 4 WRITES across 15
   // attempts, and the shape is `python3 -c` over `variant-manifest.json` — the seat PRE-CHECKING its own
   // JSON before saving it. That is a constraint the transport can check, so under the design's Class 3
@@ -287,12 +287,12 @@ const RECORDING = Object.freeze({
   // enumerable — it derives the manifest from material already on disk that the dictation names — so the
   // seeded `Read` grant carries them. Granting a search tool to a stage whose reads can be listed is
   // what the sanctioned-equivalents design refuses. Same ruling as frame-diff, opposite to matter-frame.
-  "prelim-variants": {
+  "clearance-variants": {
     seatWrites: false,
-    tools: Object.freeze(["record_prelim_variants"]),
+    tools: Object.freeze(["record_clearance_variants"]),
     reason: "hands back the variant manifest — mark, dominant element, elements, variants with their "
       + "romanisations, incumbent classes, watchlist owners and the scope-ledger rows — through "
-      + "record_prelim_variants instead of hand-formatting a JSON skeleton the driver already "
+      + "record_clearance_variants instead of hand-formatting a JSON skeleton the driver already "
       + "strict-parses and a prose twin that restates it; the driver serialises variant-manifest.json, "
       + "renders variant-manifest.md, and derives scope-ledger.json from the same values rather than by "
       + "re-parsing a markdown table the seat typed. Gains NO retrieval server and NO search tool (its "
@@ -320,7 +320,7 @@ const RECORDING = Object.freeze({
   // NO `search_run_artifacts`: the dictation names this stage's ONLY two inputs — the settled narrative
   // and findings.json — and already trimmed its declared reads to exactly those two. A read set that
   // short is enumerable by definition, and the design forbids handing a search tool to a stage whose
-  // reads can be listed. Same ruling as frame-diff and prelim-variants.
+  // reads can be listed. Same ruling as frame-diff and clearance-variants.
   "report-overview": {
     seatWrites: false,
     tools: Object.freeze(["record_report_overview"]),
@@ -671,7 +671,7 @@ const LOCAL = {
   //
   // GRANTED BY EXACTLY ONE LANE'S GROUP LIST — `common-law` and its `common-law-half` variant, through
   // the prefix branch in toolGroupsForStage. Every doctrinal mention of the tool is theirs:
-  // driver/skills/prelim-common-law/SKILL.md and the two common-law stage dictations in stages.mjs.
+  // driver/skills/clearance-common-law/SKILL.md and the two common-law stage dictations in stages.mjs.
   //
   // NOT an allowlist growing by a token this time: it SHRINKS synthesis's and narrative-refutation's
   // argv and RENAMES the token on common-law's (`mcp__perplexity__record_dispositions` →
@@ -1222,8 +1222,8 @@ export const RECORDING_TOOLS = Object.freeze({
   // so deriving it would compare a value with itself. matter-frame carries the search tool for the same
   // reason skeptic does, on its OWN key — a shared key would hand skeptic a writer into the frame.
   // BY HAND, like every row here — O1 compares the resolved grant against it, so a derived row would
-  // compare a value with itself. prelim-variants carries NO search tool: enumerable inputs, Read serves.
-  "prelim-variants": Object.freeze(["Read", "mcp__recording-prelim-variants__record_prelim_variants"]),
+  // compare a value with itself. clearance-variants carries NO search tool: enumerable inputs, Read serves.
+  "clearance-variants": Object.freeze(["Read", "mcp__recording-clearance-variants__record_clearance_variants"]),
   "matter-frame": Object.freeze(["Read", "mcp__recording-matter-frame__record_matter_frame",
     "mcp__recording-matter-frame__search_run_artifacts"]),
   skeptic: Object.freeze(["Read", "mcp__recording-skeptic__record_skeptic",

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

@@ -154,8 +154,8 @@ async function research(params) {
     let spec;
     try { spec = validateGridSpec(JSON.parse(readFileSync(grid_spec_path, "utf8"))); }
     catch (err) { return `ERROR: grid_spec_path unreadable/invalid (${err.message}). The driver writes this file; do not hand-author it.`; }
-    if (!/\/studio\/prelim-search\//.test(spec.output_path))
-      return requiredLedgerRefusal(`ERROR: grid spec.output_path must be within a studio/prelim-search run dir; got ${spec.output_path}`, { spec, gridSpecPath: grid_spec_path });
+    if (!/\/studio\/(?:prelim|clearance)-search\//.test(spec.output_path))   // either spelling: an install keeps the studio segment it has
+      return requiredLedgerRefusal(`ERROR: grid spec.output_path must be within a studio/clearance-search run dir; got ${spec.output_path}`, { spec, gridSpecPath: grid_spec_path });
     // — already recorded and complete? Answer from the ledger; do not buy the grid twice.
     const already = recordedLedgerFor(spec);
     if (already) {

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

@@ -44,7 +44,7 @@ import { VARIANT_DIRECTIONS, RANKING_BASES } from "../../blind-frame-model.mjs";
 import { recordSkeptic } from "../../skeptic-record.mjs";
 import { recordFrameDiff } from "../../frame-diff-record.mjs";
 import { recordMatterFrame, INTAKE_ASK_OWNERS, SCOPE_BASES } from "../../matter-frame-record.mjs";
-import { recordPrelimVariants, SCOPE_LAYERS, SCOPE_STATUS } from "../../prelim-variants-record.mjs";
+import { recordClearanceVariants, SCOPE_LAYERS, SCOPE_STATUS } from "../../clearance-variants-record.mjs";
 import { recordReportOverview } from "../../report-overview-record.mjs";
 import { recordReportCard } from "../../report-card-record.mjs";      // conversion 5 — the fan-out transport
 import { recordRefutation, REVIEW_VERDICTS } from "../../narrative-refutation-record.mjs";   // conversion 9
@@ -125,12 +125,12 @@ async function record_knockout_review(params) {
   return recordKnockoutReview(runDir, params);
 }
 
-async function record_prelim_variants(params) {
+async function record_clearance_variants(params) {
   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" };
   }
-  return recordPrelimVariants(runDir, params);
+  return recordClearanceVariants(runDir, params);
 }
 
 async function record_report_card(params) {
@@ -444,7 +444,7 @@ serve({
     //
     // `scope_ledger` is the one genuinely new field, and it is what deletes a derivation: those rows used
     // to reach the driver only by re-parsing a markdown table out of the prose manifest.
-    name: "record_prelim_variants",
+    name: "record_clearance_variants",
     description:
       "Hand back the variant manifest as VALUES. The driver serialises variant-manifest.json, renders " +
       "variant-manifest.md and writes scope-ledger.json from what you send, so you never format JSON, " +
@@ -516,7 +516,7 @@ serve({
       },
     },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    handler: record_prelim_variants,
+    handler: record_clearance_variants,
   }, {
     // ── CONVERSION 4 — THE REPORT SHELL, AND THE FIRST ARTIFACT A CLIENT READS ────────────────────
     //

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;

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
@@ -369,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");
 }
 
 /**
@@ -383,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 {