clearotron 0.3.0-beta.1 → 0.3.0-beta.2

package/driver/demo-posture.mjs

@@ -26,6 +26,7 @@
 // demo out of one. Anything but the literal `1` is not a demo.
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
+import { loadProfiles, loadProjects } from "./profiles.mjs";
 
 /** Literal `1`, and nothing else. A truthy-looking value is not a demo. */
 export function isDemo(env = process.env) {
@@ -58,15 +59,58 @@ export function demoReportCount(env = process.env) {
   } catch { return null; }
 }
 
+/**
+ * The companies the roster in force actually holds, Generic excepted.
+ *
+ * ── A READ OF THE ROSTER, NEVER A CONSTANT ────────────────────────────────────────────────────────
+ *
+ * The line below used to name Demo Brand Owner, "rating under the generic default framework, with its
+ * demo project", as a literal, and on 0.3.0-beta.1 it was wrong twice. The demo account rates under a
+ * framework of its own, and a demo that had taken a real install's settings served a roster without it
+ * while still printing its name. So each fact is read off the loader this process serves from: the
+ * name, whether the profile names a framework of its own, how many projects sit under it, and whether it
+ * is marked demo data. When the roster changes, the sentence changes with it.
+ *
+ * `roster` and `projects` are the loader's own Maps, passed by a caller that already holds them and read
+ * here otherwise. `null` when the roster cannot be read, which is a different fact from an empty one.
+ */
+export function demoCompanies({ roster, projects } = {}) {
+  try {
+    const profiles = roster ?? loadProfiles({ force: true });
+    let byProject = projects;
+    // Projects that cannot be read are not counted, and a count of zero is never said: the clause is
+    // left out rather than stating a number nobody looked at.
+    if (!byProject) { try { byProject = loadProjects({ profiles }); } catch { byProject = new Map(); } }
+    return [...profiles.values()]
+      .filter((p) => p && p.key !== "generic")
+      .map((p) => ({
+        key: p.key,
+        name: String(p.name ?? "").trim() || p.key,
+        ownFramework: Boolean(String(p.frameworkPath ?? "").trim()),
+        projects: [...byProject.keys()].filter((k) => k.startsWith(`${p.key}/`)).length,
+        demoData: p.demoData === true,
+      }))
+      .sort((a, b) => a.name.localeCompare(b.name));
+  } catch { return null; }
+}
+
+const describeCompany = (c) =>
+  `${c.name}, rating under ${c.ownFramework ? "its own framework" : "the generic default framework"}`
+  + (c.projects ? `, with ${c.projects} project${c.projects === 1 ? "" : "s"}` : "");
+
 /**
  * What to say instead of an operator's warning, when this process is part of a demo.
  *
  * ── THE SAME FACTS, AS WHAT THE DEMO *IS* RATHER THAN WHAT THE INSTALL *LACKS* ──────────────────────
  *
- * The ruled shape, from the owner's own description of the demo: Demo Brand Owner, rating under the
- * generic default framework, with its project and its reports. Naming two environment variables and a
- * "config store" tells a first-time visitor that the thing they just started is misconfigured — and
- * this is the output that gets captured for the website.
+ * The shape the owner described: the demo's company, the framework it rates under, its project and its
+ * reports. Every one of those is read (`demoCompanies`, `demoReportCount`), never stated. Naming two
+ * environment variables and a "config store" tells a first-time visitor that the thing they just
+ * started is misconfigured — and this is the output that gets captured for the website.
+ *
+ * THE CLOSING SENTENCE IS EARNED. "Nothing here is configured against a real customer" is said only
+ * when every company on the roster is marked demo data; a company a visitor created in the demo is not,
+ * and neither is anything a misconfigured store brought in.
  *
  * NEITHER WARNING IS SILENCED OUTSIDE A DEMO. Both are load-bearing on a real deployment, and the second
  * warns that a page may show synthetic data as though it were a customer's own, which is precisely the
@@ -74,7 +118,7 @@ export function demoReportCount(env = process.env) {
  *
  * `null` outside a demo, so a caller that forgets to branch prints its warning rather than nothing.
  */
-export function demoPostureLine(env = process.env) {
+export function demoPostureLine(env = process.env, { roster, projects } = {}) {
   if (!isDemo(env)) return null;
   const n = demoReportCount(env);
   const reports = n === null
@@ -82,7 +126,14 @@ export function demoPostureLine(env = process.env) {
     // not look at — an absence is a finding, and a number invented here is one nobody can check.
     ? "its finished clearance reports"
     : `${n} finished clearance report${n === 1 ? "" : "s"}`;
-  return `This is ${"`clearotron demo`"}: it carries Demo Brand Owner, rating under the generic default `
-    + `framework, with its demo project and ${reports} ready to open. Nothing here is configured against `
-    + `a real customer, and nothing needs to be.`;
+  const head = `This is ${"`clearotron demo`"}`;
+  const companies = demoCompanies({ roster, projects });
+  if (companies === null) return `${head}: its roster could not be read, so what it carries is not said here. It has ${reports} ready to open.`;
+  if (!companies.length) return `${head}, and its roster holds no company but the generic default. It has ${reports} ready to open.`;
+  const carries = companies.length === 1
+    ? describeCompany(companies[0])
+    : `${companies.slice(0, -1).map(describeCompany).join("; ")}; and ${describeCompany(companies.at(-1))}`;
+  const unreal = companies.every((c) => c.demoData)
+    ? " Nothing here is configured against a real customer, and nothing needs to be." : "";
+  return `${head}: it carries ${carries}, and ${reports} ready to open.${unreal}`;
 }

package/driver/driver.config.mjs

@@ -219,7 +219,7 @@ export const config = {
       // 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 is set but the process cannot see it — customer-specific skills would silently fall back to the repo defaults)`);
+        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;
     }
@@ -255,7 +255,7 @@ export const config = {
     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 is set but the process cannot see it — customer-specific skills would silently fall back to the repo defaults)`);
+      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);
     if (existsSync(overlayPath)) return { path: overlayPath, rel, layer: "overlay", overlayPath, basePath };
     return { path: basePath, rel, layer: existsSync(basePath) ? "base" : "missing", overlayPath, basePath };
@@ -1193,21 +1193,50 @@ export const PROVIDERS = {
           approximate: p.total_approximate === true, 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
+    // Signa search that failed reached the workbook as "the search did not run", its cause dropped.
     async listRecords({ name, matchMode, classes, regions, limit }, { agentId, sessionKey, recordLog = null }) {
-      if (!process.env.SIGNA_API_KEY) return { ok: false, cause: "SIGNA_API_KEY absent from driver env" };
+      if (!process.env.SIGNA_API_KEY) return { ok: false, records: null, reason: "SIGNA_API_KEY absent from driver env" };
       let core;
       try { core = await import("../providers/signa/src/core.js"); }
-      catch (e) { return { ok: false, cause: `plugin core unavailable: ${e.message}` }; }
+      catch (e) { return { ok: false, records: null, reason: `plugin core unavailable: ${e.message}` }; }
       const base = process.env.SIGNA_BASE_URL || core.DEFAULT_BASE;
       try {
         const r = await core.doSearch(process.env.SIGNA_API_KEY, base,
           { ...core.toSignaParams({ name, match_mode: matchMode || "exact", nice_classes: classes, regions }), limit },
           { kind: "search", agentId, sessionKey, sessionId: null, recordLog });
         const text = typeof r?.text === "string" ? r.text : "";
-        if (text.startsWith("ERROR")) return { ok: false, cause: text.slice(0, 200) };
+        if (text.startsWith("ERROR")) return { ok: false, records: null, reason: text.slice(0, 200) };
         const p = JSON.parse(text);
-        return { ok: true, records: Array.isArray(p.results) ? p.results : [] };
-      } catch (e) { return { ok: false, cause: `listRecords threw: ${e.message}` }; }
+        // THE SEARCH ROW IS NOT THE LISTING'S RECORD. The row names the owner `owner`, the classes
+        // `nice_classes` and the filing date `filing_date`; the listing reads `owner_name`, `classes` and
+        // `application_date`. Handed over unmapped, every Signa filing reached the knockout with no owner,
+        // no classes and no filing date. Mapped here, as clarivate's adapter above maps its screen row.
+        //
+        // The office's own numbers come off the full record Signa returns on search, through the
+        // provider's own normaliser, so publish can address the office's page for each filing
+        // (publish/office-record-links.mjs) instead of showing the handle.
+        return { ok: true, records: (Array.isArray(p.results) ? p.results : []).map((row) => {
+          const rec = row?.raw && typeof row.raw === "object" ? core.normalizeRecord(row.raw, row.office || null) : null;
+          return {
+            record_id: row?.record_id ?? null,
+            mark_text: row?.mark_text ?? null,
+            owner_name: rec?.owner ?? row?.owner ?? null,
+            owner_country: rec?.ownerCountry ?? null,
+            status: row?.status ?? null,
+            classes: Array.isArray(row?.nice_classes) ? row.nice_classes : null,
+            office: row?.office || null,
+            application_date: row?.filing_date ?? null,
+            registration_date: row?.registration_date ?? null,
+            application_number: rec?.applicationNumber ?? null,
+            registration_number: rec?.registrationNumber ?? null,
+            ir_number: rec?.irNumber ?? null,
+            filing_route: rec?.filingRoute ?? null,
+            // No page per record at Signa (hasPublicRecordUrl: false above), and none is made up here.
+            record_url: null,
+          };
+        }) };
+      } catch (e) { return { ok: false, records: null, reason: `listRecords threw: ${e.message}` }; }
     },
     async executePlan({ planPath, axis, outputPath, qids }, { agentId, sessionKey, recordLog = null }) {
       if (!process.env.SIGNA_API_KEY) return { ok: false, cause: "SIGNA_API_KEY absent from driver env" };

package/driver/engine/child-record.mjs

@@ -43,6 +43,7 @@
 // reads. A second spelling of "which process is this" is a second thing to keep in step.
 
 import { writeFileSync, readFileSync, rmSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 import { driverDir } from "../../shared/driver-dir.mjs";
 import { procStarttime, parseClaimSidecar } from "../claim-liveness.mjs";
 
@@ -110,3 +111,95 @@ export function engineChildIsLive(rec, { starttimeOf = procStarttime } = {}) {
   if (!rec.starttime) return false;
   return starttimeOf(rec.pid) === rec.starttime;
 }
+
+/**
+ * The process group `pid` is in, or null when that cannot be read.
+ *
+ * Linux reads it from /proc; everywhere else asks `ps`, as `procStarttime` does for a start time, and an
+ * injected reader outranks the platform for the reason `procStarttime` gives.
+ */
+export function procPgid(pid, readStat = undefined, { platform = process.platform, readPsPgid = defaultReadPsPgid } = {}) {
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+  let v = NaN;
+  try {
+    if (readStat || platform === "linux") {
+      const stat = (readStat ?? ((p) => readFileSync(`/proc/${p}/stat`, "utf8")))(pid);
+      // After the last ')', because comm may hold spaces and parens: state is index 0, ppid 1, pgrp 2.
+      v = Number(stat.slice(stat.lastIndexOf(")") + 2).trim().split(/\s+/)[2]);
+    } else {
+      v = Number(String(readPsPgid(pid)).trim());
+    }
+  } catch { return null; }
+  return Number.isInteger(v) && v > 0 ? v : null;
+}
+
+function defaultReadPsPgid(pid) {
+  const r = spawnSync("ps", ["-o", "pgid=", "-p", String(pid)], { encoding: "utf8" });
+  return r.status === 0 ? r.stdout : "";
+}
+
+/**
+ * End the recorded turn, and report whether it ENDED from what was seen afterwards, never from the
+ * signal having been sent.
+ *
+ * SIGNALLED IS NOT ENDED. `process.kill` returning means the OS accepted the signal for delivery, and a
+ * process that handles or ignores SIGTERM leaves that line looking the same. On the owner's WSL install
+ * of 0.3.0-beta.1 a stop that was reported as having ended the step ran on to the next step boundary. So
+ * this watches the turn after the signal, sends SIGKILL to whatever is left when the grace runs out, and
+ * answers `ended: true` only once it has seen nothing left.
+ *
+ * THE GROUP, WHEN THE TURN LEADS ONE. Both engines spawn the turn `detached: true`, so it leads its own
+ * process group and the MCP servers it starts are members of it. Measured 2026-09-10 on the coding CLI
+ * the engine spawns: a SIGTERM to the turn's pid alone ends the turn and its servers, but a SIGKILL to
+ * the pid alone leaves a server running under pid 1, and a SIGKILL to the group does not. So the
+ * escalation addresses the group, and "ended" means the group is empty as well as the turn gone.
+ *
+ * ONLY A GROUP THIS RECORD LEADS. The watchdogs signal `-child.pid` without asking, because they spawned
+ * the child detached themselves. This reads a pid off disk. If that pid does not lead its own group,
+ * `-pid` names no group of this run's, so the signals go to the pid alone. Nothing at or below pid 1 is
+ * ever signalled: `-1` reaches every process this user may signal.
+ */
+export async function endEngineChild(rec, {
+  graceMs = 5000, settleMs = 2000, pollMs = 50,
+  kill = (target, sig) => process.kill(target, sig),
+  isLive = (r) => engineChildIsLive(r),
+  pgidOf = (pid) => procPgid(pid),
+  sleep = (ms) => new Promise((res) => setTimeout(res, ms)),
+  now = () => Date.now(),
+} = {}) {
+  if (!rec || !Number.isInteger(rec.pid) || rec.pid <= 1)
+    return { signalled: null, escalated: null, group: false, ended: false, error: "no process to signal" };
+  const group = pgidOf(rec.pid) === rec.pid;
+  const target = group ? -rec.pid : rec.pid;
+  const send = (sig) => { try { kill(target, sig); return null; } catch (e) { return e?.code ?? String(e?.message ?? e); } };
+  // Signal 0 asks only whether the group still has a member. EPERM is a member this user may not
+  // signal, and a member all the same. Once the leader has exited, the start-time check no longer covers
+  // this number: `-pid` names the run's group because a group's number is not reused while any member of
+  // it lives. What is left uncovered is a reuse, by a new process that then leads a group of its own,
+  // inside one poll after the run's group has emptied.
+  const groupHasMembers = () => {
+    if (!group) return false;
+    try { kill(-rec.pid, 0); return true; } catch (e) { return e?.code === "EPERM"; }
+  };
+  const gone = () => !isLive(rec) && !groupHasMembers();
+  const seenGone = async (ms) => {
+    const until = now() + ms;
+    for (;;) {
+      if (gone()) return true;
+      if (now() >= until) return false;
+      await sleep(pollMs);
+    }
+  };
+
+  // ESRCH: it exited between the caller's liveness read and this signal, a race lost harmlessly. EPERM:
+  // it is not ours to signal, which must not read as success. Either way nothing was sent.
+  const refused = send("SIGTERM");
+  if (refused) return { signalled: null, escalated: null, group, ended: false, error: refused };
+  if (await seenGone(graceMs)) return { signalled: "SIGTERM", escalated: null, group, ended: true };
+
+  // Still there when the grace ran out. SIGKILL cannot be handled or ignored.
+  const killRefused = send("SIGKILL");
+  if (killRefused && killRefused !== "ESRCH")
+    return { signalled: "SIGTERM", escalated: null, group, ended: gone(), error: killRefused };
+  return { signalled: "SIGTERM", escalated: killRefused ? null : "SIGKILL", group, ended: await seenGone(settleMs) };
+}

package/driver/findings-model.mjs

@@ -2219,7 +2219,12 @@ export const KNOCKOUT_FINDING_TYPES = [
   "Famous Brand", "Active Business", "Cultural Reference", "Domain", "Descriptive Use",
   "Negative Association", "Competitor Intelligence",
 ];
-const KNOCKOUT_FINDING_KEYS = ["ordinal", "name", "owner", "band", "net", "type", "evidence", "basis"];
+// THE ONE LIST of a knockout finding's keys. The recording transport's allowlist takes it from here
+// (knockout-assess-record.mjs), so the call and the validator cannot come to disagree. They did: the
+// transport allowed `weighedFilings` and this list refused it, so a seat that sent what its doctrine
+// teaches had the whole stage refused, and the retry dropped the key the report's source chip is derived
+// from. `weighedFilings` is optional; verify-knockout.mjs joins every id against the run's own records.
+export const KNOCKOUT_FINDING_KEYS = Object.freeze(["ordinal", "name", "owner", "band", "net", "type", "evidence", "basis", "weighedFilings"]);
 // The throw family is `knockout_`, NOT `findings_`, and that is deliberate: gateway.mjs's
 // repairSiblingName routes every `/findings?_/` token to **findings.json**, which is the clearance
 // artifact and does not exist on a knockout run. A knockout token borrowing that family would aim its

package/driver/knockout-assess-record.mjs

@@ -67,6 +67,8 @@ import { refuseUndeclared as refuseUndeclaredShared, keepIfAbsent, lastAccepted,
 // THE VALIDATOR'S OWN PREDICATE, imported rather than restated. Two spellings of one closed set is how
 // the call and the stage come to disagree about what is legal, which is the defect this check closes.
 import { normalizeKnockoutQualifier, KNOCKOUT_RATING_QUALIFIERS } from "./verify-knockout.mjs";
+// A FINDING'S KEYS, likewise: the validator's one list, so a key the call records is a key the stage accepts.
+import { KNOCKOUT_FINDING_KEYS } from "./findings-model.mjs";
 
 const SCHEMA_VERSION = 1;
 
@@ -146,14 +148,15 @@ const DECLARED = Object.freeze({
     // store, so it is a fact and not an echo.
     "registerReads",
   ],
-  // "closed keys, all eight, no others" — the doctrine's own words, and the one place it is stricter
-  // than the template around it.
+  // A finding's closed keys are the VALIDATOR'S OWN LIST, imported rather than restated. This allowlist
+  // and that list were two spellings of one closed set, and they disagreed: this one allowed
+  // `weighedFilings` and the validator refused it, so the call recorded and the stage failed.
   // — `weighedFilings` is the register record ids this finding's reasoning rests on.
   // It exists so the SOURCE of a finding is a driver fact rather than a label: stages.mjs already
   // classifies source_type as `mechanical:code-extracted` for the clearance lane, on the ground that
   // "the lane that produced the record is a driver fact". The chip is derived from this joined list and
   // from the finding's own receipted evidence — never from a word the seat typed about itself.
-  "marks.findings": ["ordinal", "name", "owner", "band", "net", "type", "evidence", "basis", "weighedFilings"],
+  "marks.findings": KNOCKOUT_FINDING_KEYS,
   // `band` is the rater's rating OF THAT FILING, optional, in the framework's own ladder words. It is
   // declared here as well as in the tool schema because this allowlist — not the schema — is what the
   // driver validates against: a key the seat sends and this list omits is refused, so the read would

package/driver/package.json

@@ -2,7 +2,7 @@
   "name": "clearotron-driver",
   "private": true,
   "type": "module",
-  "version": "0.3.0-beta.1",
+  "version": "0.3.0-beta.2",
   "license": "AGPL-3.0-only",
   "description": "Deterministic driver for the trademark clearance workflow: orchestration in code (fan-out, fan-in barrier, gating, retries); the model does judgment leaves only, through a reasoning CLI spawned per stage.",
   "engines": {

package/driver/portal-local-auth.mjs

@@ -44,8 +44,8 @@
 // running portal; prefixing it would invalidate every in-flight confirmation on deploy, and it does not
 // need the prefix — one side of a pair is enough to separate the pair.
 import { randomBytes, scryptSync, timingSafeEqual, createHmac } from "node:crypto";
-import { readFileSync, writeFileSync, mkdirSync, chmodSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { readFileSync, writeFileSync, mkdirSync, chmodSync, existsSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { envPrefix } from "../shared/os-advice.mjs";
 
@@ -165,10 +165,105 @@ export function passphraseResetCommand({ prefix = "", credentialPath = null, env
   const base = `${prefix}clearotron passphrase --reset`;
   const path = credentialPath ?? env.PORTAL_LOCAL_CREDENTIAL ?? null;
   if (!path || path === credentialPathFor({}, home)) return base;
+  // AN INSTALL'S OWN FILE IS NAMED BY ITS INSTALL, the way `clearotron start` names it: `--base`, which the
+  // verb resolves through installCredential exactly as start does, and nothing at all for the default
+  // install, where the verb looks first. Every new install keeps its credential in its own directory now,
+  // so this is the ordinary line, and it has no environment variable in it to bind to the wrong command.
+  if (basename(path) === INSTALL_CREDENTIAL_FILE) {
+    const dir = dirname(path);
+    if (dir === defaultInstallBase({ home })) return base;
+    return `${base} --base ${/\s/.test(dir) ? `"${dir}"` : dir}`;
+  }
   // `VAR=value cmd` IS POSIX-ONLY. PowerShell has no such juxtaposition — the assignment is its own
   // statement there — so this line told a Windows reader their variable name was not a cmdlet, naming
   // the wrong half of the command as the fault. Reported from a real run.
-  return `${envPrefix("PORTAL_LOCAL_CREDENTIAL", path)}${base}`;
+  //
+  // AND IT BINDS TO THE COMMAND BESIDE IT, which after a `cd … && ` prefix is `cd`. Printed from a
+  // checkout, the line set the variable for the directory change and ran the verb without it, so the
+  // reset went to the shared file. Measured by running the printed line, 2026-09-10. So the assignment
+  // goes after the prefix's directory change, next to the verb it is for.
+  const posix = prefix.lastIndexOf("&& "), ps = prefix.lastIndexOf("; ");
+  const at = Math.max(posix < 0 ? 0 : posix + 3, ps < 0 ? 0 : ps + 2);
+  return `${prefix.slice(0, at)}${envPrefix("PORTAL_LOCAL_CREDENTIAL", path)}${prefix.slice(at)}clearotron passphrase --reset`;
+}
+
+/**
+ * The name an install's own credential has inside the install's directory: the shared default's name,
+ * so the two are one kind of file in two places.
+ */
+export const INSTALL_CREDENTIAL_FILE = "portal-local-credential.json";
+
+/** The directory `clearotron start` and setup use when none is given: `~/trademark`, or the demo's own. */
+export function defaultInstallBase({ demo = false, home = null } = {}) {
+  return join(home ?? homedir(), demo ? "trademark-demo" : "trademark");
+}
+
+/**
+ * WHICH CREDENTIAL AN INSTALL SIGNS IN WITH, decided here once, so the file `clearotron passphrase` resets
+ * is the file the portal reads.
+ *
+ * A NEW INSTALL GETS ITS OWN, as the demo already does. Every install used to sign in with the one shared
+ * file under the operator's home, so an install made on a machine that had held another adopted that
+ * install's digest. Its first start said the passphrase "was minted on an earlier start and is NOT
+ * reprinted", and the person who had just installed had no passphrase and no way to learn one. Reported
+ * from a real install, 2026-09-10.
+ *
+ * AN INSTALL THAT HAS BEEN USING THE SHARED FILE KEEPS IT. Moving it would stop the passphrase its operator
+ * holds from working, and under a service unit the new one would reach only the journal.
+ *
+ * In order: the operator's own setting; the install's own file when it exists; the install's own file on
+ * the install's first start, or when there is no shared file to keep; otherwise the shared file. `source`
+ * says which of "configured", "install" and "shared" answered.
+ */
+export function installCredential({ base, env = process.env, home = null, firstStart = false, exists = existsSync } = {}) {
+  const configured = String(env.PORTAL_LOCAL_CREDENTIAL ?? "").trim();
+  if (configured) return { path: configured, source: "configured" };
+  const own = join(base, INSTALL_CREDENTIAL_FILE);
+  if (exists(own) || firstStart) return { path: own, source: "install" };
+  const shared = credentialPathFor({}, home);
+  return exists(shared) ? { path: shared, source: "shared" } : { path: own, source: "install" };
+}
+
+/**
+ * What a start that minted nothing says about signing in, composed so a test can read the TEXT.
+ *
+ * THE WAY BACK IN COMES FIRST. The reader holds, at best, a passphrase from a start they may not remember,
+ * and at worst none: an install signing in with a file another install wrote. The recovery command used
+ * to be the last words of the paragraph. It is the first line now.
+ *
+ * AND IT SAYS WHICH FILE, WHEN IT WAS WRITTEN AND FOR WHOM, which is all that can be known about a reused
+ * credential. Nothing records which install wrote a shared file, so a shared file is called shared rather
+ * than attributed to anyone.
+ */
+export function laterStartLines({ user, reset, credentialPath, source = "install", record = null }) {
+  const made = record?.createdAt ? `created ${String(record.createdAt).slice(0, 10)}` : "no creation date recorded";
+  const lines = [`  Sign in as ${user}. No passphrase for it? Run  ${reset}  to mint a new one; it is printed once.`];
+  if (source === "shared") {
+    lines.push(`  This install signs in with the shared credential ${credentialPath} (${made}${record?.email ? `, for ${record.email}` : ""}).`);
+    lines.push("  It is not inside this install's directory, so an earlier install on this machine may have written it.");
+  } else {
+    lines.push(`  Its credential is ${credentialPath} (${made}).`);
+  }
+  lines.push("  The passphrase was minted on an earlier start and is NOT reprinted: the file holds only a digest of it.");
+  return lines;
+}
+
+/**
+ * The demo credential a demo start should replace, or null.
+ *
+ * A DEMO ALWAYS HAS A WAY IN. A demo run on a machine where an earlier demo had left its credential reused
+ * it, minted nothing, and told the visitor the passphrase "was minted on an earlier start": a sign-in they
+ * could not pass, reported from a real machine, 2026-09-10. A demo's credential guards invented data in a
+ * directory that is removed as one, so every demo start replaces it and prints the new passphrase.
+ *
+ * ONLY ITS OWN FILE, AND ONLY FOR THE DEMO'S ADDRESS. A credential anywhere else, for another address, or
+ * one that cannot be read is left exactly where it is, and the portal's own boot says what is wrong with it.
+ */
+export function demoCredentialToReplace({ path, ownPath, user, read = readLocalCredential }) {
+  if (!path || path !== ownPath) return null;
+  let rec;
+  try { rec = read(path); } catch { return null; }
+  return rec && rec.email === String(user ?? "").trim().toLowerCase() ? path : null;
 }
 
 /**

package/driver/portal-service.mjs

@@ -1998,7 +1998,12 @@ export function makePortalService({
         // immediate mode carries `immediate.pid` — a process id on the box — and this response goes to
         // a browser. Nothing in the client has ever read `upstream`; what a reader needs is which stop
         // is happening and the sentence the driver already composed for them.
-        const mode = r?.immediate?.attempted && r?.immediate?.signalled ? "immediate" : "boundary";
+        //
+        // AND "IMMEDIATE" MEANS THE STEP WAS SEEN TO END. `signalled` says only that a signal was accepted
+        // for delivery; `ended` is what the driver saw afterwards. An answer without it, an older driver's
+        // `ended: null` included, is the boundary stop: that is the honest reading of an answer that does
+        // not say.
+        const mode = r?.immediate?.attempted && r?.immediate?.ended === true ? "immediate" : "boundary";
         audit({ event: "stop", by: principal.email, account, runId, ok: Boolean(r?.ok), action: r?.action ?? null,
           // ASKED and TAKEN, both, because they differ exactly when something went wrong — a reader
           // pressed "stop now" and got the boundary stop, which is the row somebody will come looking
@@ -3282,6 +3287,45 @@ export function opsTokenPosture(token, { now = Date.now() } = {}) {
 // Best-effort, always. A health probe that 500s because git is slow has turned a diagnostic into an
 // outage — the whole point is that it answers from any account, at any time, without a grant.
 const STORE_TTL_MS = 30_000;
+/**
+ * The skills overlay this portal resolves frameworks through, decided once at boot, and the one line
+ * that says what was decided.
+ *
+ * DERIVED MEANS "IF THERE IS ONE". When the operator set nothing, PROFILE_REPO_ROOT names the config
+ * store and the store's layout puts instruction overrides in its `skills` folder. A folder that is
+ * absent or empty overrides nothing, which is the state setup leaves on purpose: it keeps
+ * CLEAROTRON_INSTRUCTIONS_DIR unset so the product's own instructions are used. Pinning the folder anyway
+ * made every framework read throw `skills_overlay_unreadable`, so the company profile answered 500 on
+ * a store with no `skills` folder, and the boot told a fresh install its frameworks might be synthetic.
+ * Pinned to an EMPTY folder inside the store's repository, the doctrine-store verdict read "blocked",
+ * because the checkout tracks no file under it. Unset reads "pass". Both measured, 2026-09-10.
+ *
+ * A folder that EXISTS AND CANNOT BE READ is still pinned, so every read of it keeps refusing by name
+ * rather than falling back, and a WARNING says why. An overlay the OPERATOR set is theirs: nothing here
+ * changes it, and the warning for one this process cannot see is unchanged.
+ *
+ * `posture` is the demo's own sentence. In a demo it stands wherever this would otherwise say more.
+ */
+export function skillsOverlayAtBoot({ explicit = null, profileRepoRoot = null, readdir = readdirSync, exists = existsSync, posture = null } = {}) {
+  const synthetic = "customer risk frameworks will resolve to this repo's demo fixtures and the Brand profile page will "
+    + "show either \"could not be read\" or a SYNTHETIC framework as though it were the customer's own. "
+    + "Set CLEAROTRON_INSTRUCTIONS_DIR (or PROFILE_REPO_ROOT) to the config store.";
+  if (explicit) return { pin: null, line: exists(explicit) ? null : (posture || `WARNING: skills overlay unreadable (${explicit}) — ${synthetic}`) };
+  if (!profileRepoRoot) return { pin: null, line: posture || `WARNING: skills overlay unset — ${synthetic}` };
+  const dir = join(profileRepoRoot, "skills");
+  const nothing = (how) => posture || (`skills overlay: ${dir} ${how}, so this install overrides nothing and the product's own `
+    + "instruction files are used. To override one, put the file there, commit it, set CLEAROTRON_INSTRUCTIONS_DIR to that folder, and restart.");
+  let entries;
+  try { entries = readdir(dir); }
+  catch (e) {
+    if (e?.code === "ENOENT") return { pin: null, line: nothing("does not exist") };
+    return { pin: dir, line: posture || (`WARNING: skills overlay ${dir} exists and cannot be read (${e?.code ?? String(e?.message ?? e)}) — `
+      + "every instruction read will refuse by name rather than fall back. Make the folder readable by this process, or remove it if this install overrides nothing.") };
+  }
+  if (!entries.length) return { pin: null, line: nothing("is empty") };
+  return { pin: dir, line: `skills overlay derived from PROFILE_REPO_ROOT: ${dir}` };
+}
+
 let storeCache = { at: 0, value: null };
 function doctrineStore(now = Date.now) {
   const t = now();
@@ -4467,34 +4511,26 @@ const PORT = PORT_CHOICE.port;
       // profile-service's own unit sets the instructions dir correctly — neither should learn a fallback
       // from the portal's mistake. Setting the env var (rather than threading a value) is what the
       // getter reads, and this process never runs the engine.
-      if (!envFrom(process.env, "CLEAROTRON_INSTRUCTIONS_DIR") && process.env.PROFILE_REPO_ROOT) {
-        // `pinEnv`, not a bare assignment. This write lands at RUNTIME, long after `applyEnvAliases`
-        // back-filled the spellings at load, so assigning one name reaches only the readers already
-        // converted. `pinEnv` writes every spelling, which is what keeps a half-converted tree honest.
-        pinEnv(process.env, "CLEAROTRON_INSTRUCTIONS_DIR", join(repoRoot, "skills"));
-        log(`skills overlay derived from PROFILE_REPO_ROOT: ${envFrom(process.env, "CLEAROTRON_INSTRUCTIONS_DIR")}`);
-      }
-      // FAIL LOUD, NEVER FALL BACK. A missing overlay does not error — it resolves every framework to the
-      // repo's demo fixtures, which is exactly the silence this guard exists to break. Mirrors the
-      // roster-vs-ops-token boot check below: one directory read, once, at boot.
-      const overlay = envFrom(process.env, "CLEAROTRON_INSTRUCTIONS_DIR");
-      if (!overlay || !existsSync(overlay)) {
-        // — SAME FACT, DIFFERENT READER. In a demo there is no customer whose
-        // framework could be shown wrongly: Demo Brand Owner rates under the generic default, which is
-        // the real house rubric rather than a fixture. Naming two environment variables and a config
-        // store at a first-time visitor tells them the thing they just started is broken — and this
-        // output is what gets captured for the website.
-        //
-        // OUTSIDE A DEMO IT IS UNCHANGED AND STILL A WARNING. It is load-bearing on a real deployment:
-        // it says a page may show synthetic data as though it were a customer's own, which is exactly
-        // the class of thing that must stay loud. The defect was the audience, not the content.
-        const posture = demoPostureLine(process.env);
-        if (posture) log(posture);
-        else log(`WARNING: skills overlay ${overlay ? `unreadable (${overlay})` : "unset"} — customer risk `
-          + `frameworks will resolve to this repo's demo fixtures and the Brand profile page will show `
-          + `either "could not be read" or a SYNTHETIC framework as though it were the customer's own. `
-          + `Set CLEAROTRON_INSTRUCTIONS_DIR (or PROFILE_REPO_ROOT) to the config store.`);
-      }
+      //
+      // DERIVED ONLY WHEN THE STORE HOLDS AN OVERRIDE, and said in one line either way: the rule and its
+      // measurements are at `skillsOverlayAtBoot`. One directory read, once, at boot, mirroring the
+      // roster-vs-ops-token boot check below.
+      //
+      // — SAME FACT, DIFFERENT READER. In a demo there is no customer whose framework could be shown
+      // wrongly: the demo's company is marked demo data and rates under the framework shipped for it.
+      // Naming two environment variables and a config store at a first-time visitor tells them the thing
+      // they just started is broken, and this output is what gets captured for the website.
+      // So the demo's posture line stands wherever a warning would.
+      const overlayAtBoot = skillsOverlayAtBoot({
+        explicit: envFrom(process.env, "CLEAROTRON_INSTRUCTIONS_DIR"),
+        profileRepoRoot: process.env.PROFILE_REPO_ROOT || null,
+        posture: demoPostureLine(process.env),
+      });
+      // `pinEnv`, not a bare assignment. This write lands at RUNTIME, long after `applyEnvAliases`
+      // back-filled the spellings at load, so assigning one name reaches only the readers already
+      // converted. `pinEnv` writes every spelling, which is what keeps a half-converted tree honest.
+      if (overlayAtBoot.pin) pinEnv(process.env, "CLEAROTRON_INSTRUCTIONS_DIR", overlayAtBoot.pin);
+      if (overlayAtBoot.line) log(overlayAtBoot.line);
       // — SAY IT WHEN IT HAPPENS. The core catches this and reports `commitError` on the response and
       // in the audit row, both read by whoever made the save and nobody else. A failed commit leaves a
       // permanent sync blocker, so the service journal needs it too: the boot check above removes the

package/driver/publish/knockout.mjs

@@ -201,7 +201,7 @@ export async function buildKnockoutWorkbook(findings, receipts, outPath, registe
           'Trademark': r.mark ?? '—', 'Owner': r.owner ?? '—', 'Status': r.status ?? '—',
           'Classes': (r.classes ?? []).join(', ') || '—', 'Territory': r.territory ?? '—',
           'Filed': r.applicationDate ?? '—', 'Registered': r.registrationDate ?? '—',
-          'Record': r.url ?? r.recordId ?? '—', 'Note': '',
+          'Record': r.officeLink?.href ?? r.officeLink?.label ?? r.url ?? r.recordId ?? '—', 'Note': r.officeLink && !r.officeLink.href ? reasonCellFor(r.officeLink) : '',
         });
       }
       // Every search that did NOT answer gets its own row. Without them a mark with two dead searches
@@ -398,6 +398,12 @@ export async function publishKnockout({ runId, codename, runDir, findings, plan,
       + `cannot produce reduced to the record number — ${recordLinksDropped.slice(0, 3).map((d) => d.was).join(', ')}`
       + `${recordLinksDropped.length > 3 ? ` and ${recordLinksDropped.length - 3} more` : ''}`);
   }
+  // THE OFFICE'S OWN PAGE FOR EACH LISTED FILING, where the run's register publishes none of its own:
+  // the addressing the clearance gives its register findings (office-record-links.mjs), set on the
+  // sidecar here for the same reason the normalisation above is. Keyed on the run's own provider, and
+  // the tally goes to meta.json, so numbers that never fit show as a count rather than as silence.
+  const officeLinks = addressListedFilings(registerRecords);
+  if (officeLinks) note(`[record-links] ${officeLinks.summary}`);
 
   // ── Predelivery lint — the APPLICABLE subset, FLAGS not FAILS (2026-07-31) ─────────────────────────
   // This lane wrote no lint receipt at all until now (docs/DELIVERY.md decision memo, updated in the
@@ -641,6 +647,7 @@ export async function publishKnockout({ runId, codename, runDir, findings, plan,
     registerCounts: registerCounts
       ? { provider: registerCounts.provider, takenAt: registerCounts.takenAt, marks: registerCounts.marks?.length ?? 0, counted: countedMarks(registerCounts) }
       : undefined,
+    recordLinks: officeLinks?.tally ?? undefined,   // per office: linked, or cited by number and why; only where the register has no record pages
     recipe: searchPolicy?.recipe ?? undefined,
     enqueuedVia: searchPolicy?.enqueuedVia ?? undefined,
     parentRunId: searchPolicy?.parentRunId ?? undefined,
@@ -742,3 +749,7 @@ export function knockoutDocumentRoutes(reports, { auditFile = null } = {}) {
     ...(auditFile ? [`The receipts are in the audit workbook: \`${auditFile}\`.`] : []),
   ];
 }
+
+// The office's own page for each listed filing (office-record-links.mjs). Kept down here, below every
+// line the rest of the tree cites by number.
+import { addressListedFilings, reasonCellFor } from './office-record-links.mjs';