clearotron 0.2.1 → 0.2.3

package/driver/profiles.mjs

@@ -4,7 +4,7 @@
 //
 // One git-owned JSON file per customer under profiles/ — hand-authored, PR-reviewed, onboarded one
 // customer at a time. generic.json is the universal fallback and MUST exist;
-// aurora.json reproduces today's behavior exactly (the regression anchor). Every field shipped
+// one test-suite profile reproduces today's behavior exactly (the regression anchor). Every field shipped
 // here has working machinery behind it — parked knobs live in profiles/README.md, not in the files.
 //
 // Resolution is FORWARDER-DOMAIN ONLY: the profile describes WHO ASKS US (the
@@ -143,10 +143,10 @@ export const SAFE_GRID_CELLS = 98;
 // A DENSE marketplace profile (long retail URLs + many listings per cell — e.g. beverages/supplements on
 // Amazon/GNC/iHerb) makes each grid cell ~5-10x heavier in OUTPUT BYTES than a sparse gaming-store cell, so
 // the cell-count budget above (calibrated on sparse stores) overflows the worker's output channel and the
-// verbatim stdout transcription truncates mid-JSON (Zephyr KINETIC, 2026-06-14: ~21 dense cells ≈ 20KB cut
+// verbatim stdout transcription truncates mid-JSON (measured on a dense beverages profile, 2026-06-14: ~21 dense cells ≈ 20KB cut
 // the ledger unparseable). A dense profile gets a much smaller cell budget so each grid call's stdout stays
 // well under that ceiling (a 7-platform dense profile ⇒ floor 8 ⇒ batchSize 2 ⇒ ≤16 cells/call). The
-// gaming/Aurora budget is unchanged (default density = sparse).
+// gaming budget is unchanged (default density = sparse).
 export const DENSE_GRID_CELLS = 16;
 
 // The two values a profile may hold, as a LIST rather than as a phrase repeated at each site.
@@ -238,6 +238,9 @@ export const KNOWN_PROFILE_KEYS = [
   // queue was a cost bomb the run-slot cap doesn't stop. Visible, git-tracked profile config (never a
   // hidden env var); enforced at the runner's admission chokepoint for BOTH doors (email + portal).
   "runCaps",
+  // AN ACCOUNT THE SUITE USES AND NO INSTALL OFFERS. `testFixture: true` keeps a profile in the tree,
+  // under its own name, and out of every roster this module resolves — see loadProfiles.
+  "testFixture",
   // THIS RECORD IS FICTION. `demoData: true` marks a profile as demo data, and a
   // real clearance refuses to start under it — at the runner's admission wall, so no door can miss it.
   //
@@ -276,6 +279,12 @@ export const CUSTOMER_ONLY_KEYS = [
   // may trigger (allowedRecipes) nor re-declare its jx deepening policy — both are the same
   // rating-authority-adjacent discipline as frameworkPath, one notch out.
   "allowedRecipes", "jxPolicy",
+  // WHETHER AN ACCOUNT IS OFFERED AT ALL is the account's own fact, and a project overlay must not touch
+  // it in either direction. Un-marking would put a test account into a customer's picker through an
+  // overlay nobody reviewed as identity; marking would hide a real account from its own owner. Same
+  // reasoning as `demoData` one notch out — that one decides whether fiction may spend money, this one
+  // decides whether it is visible, and neither is a project's to decide.
+  "testFixture",
   // Admission caps bind the ACCOUNT: a project widening its own caps would hollow the customer's.
   "runCaps",
   // Provenance binds the ACCOUNT and cannot be overlaid in either direction: a project marking a real
@@ -305,6 +314,7 @@ export const FIELD_CONSUMERS = {
   allowedRecipes:       { file: "search-policy.mjs", symbol: "allowedRecipes" },                // entitlement gate on the resolved search selection
   jxPolicy:             { file: "pipeline.mjs",      symbol: "jxPolicy" },                      // frozen into the run sidecar for the Stage-1.5 lanes (resume-safe)
   demoData:             { file: "runner.mjs",        symbol: "demoData" },                      // the admission wall refuses a real clearance on demo data
+  testFixture:          { file: "profiles.mjs",      symbol: "loadProfiles" },                  // never offered by a resolved roster; the suite asks for it by name
   runCaps:              { file: "runner.mjs",        symbol: "runCaps" },                       // admission caps at claimAndPrep (queued + monthly, both doors)
 };
 
@@ -644,7 +654,7 @@ function readProfilesLayer(dir) {
  *
  *  `dir` names the OVERLAY, not the whole store: passing it keeps the bundled set underneath, which is
  *  what makes an empty store a working install. Pass `dir: null` for the bundled set alone. */
-export function loadProfiles({ dir, force = false } = {}) {
+export function loadProfiles({ dir, force = false, includeTestFixtures, includeDemo } = {}) {
   // — LAYERING APPLIES ONLY TO THE ENV-RESOLVED STORE, and that boundary is deliberate.
   //
   // `dir` OMITTED => resolve the deployment's store, overlay over base. `dir` PASSED => that directory
@@ -659,7 +669,10 @@ export function loadProfiles({ dir, force = false } = {}) {
   const explicit = dir !== undefined;
   const overlay = explicit ? null : PROFILES_OVERLAY_DIR;
   const baseDir = explicit ? (dir || PROFILES_BASE_DIR) : PROFILES_BASE_DIR;
-  const cacheKey = `${overlay ?? ""} :: ${baseDir}`;
+  // EVERY DIMENSION THAT CHANGES THE ANSWER IS IN THE KEY. A cache keyed on the directory alone
+  // serves the demo's roster to the next caller that did not ask for it, which is the defect this
+  // gate exists to prevent, arriving from inside.
+  const cacheKey = `${overlay ?? ""} :: ${baseDir} :: ${includeTestFixtures ?? "env"} :: ${process.env.CLEAROTRON_TEST_FIXTURE_PROFILES ?? ""} :: ${includeDemo ?? "env"} :: ${process.env.CLEAROTRON_DEMO_PROFILES ?? ""}`;
   if (cache && !force && cache.key === cacheKey) return cache.profiles;
 
   // FAIL LOUD ON AN UNREADABLE OVERLAY, the same ruling as the doctrine tree's. existsSync() answers
@@ -675,7 +688,7 @@ export function loadProfiles({ dir, force = false } = {}) {
   // chosen. driver/test/pool-admin-reassign.test.mjs asserts "with CLEAROTRON_CUSTOMERS_DIR unset it REFUSES
   // rather than validating against the demo roster", and mcp-server's roster boot check counts the
   // configured roster exactly. Layering the whole bundled set underneath a configured store would put
-  // aurora/petcary/zephyr into every deployment's roster: a typo'd customer key would be checked
+  // the three test accounts into every deployment's roster: a typo'd customer key would be checked
   // against demo fixtures, and a boot check that says "N customers" would count ours among theirs.
   //
   // `generic` is different in kind from the rest of that directory. It is not a demo customer — it is
@@ -683,6 +696,84 @@ export function loadProfiles({ dir, force = false } = {}) {
   // is the one file whose absence makes an empty store a refusal, so that is the only one that falls
   // through. Everything else in a deployment's roster is the deployment's own.
   const profiles = overlay ? readProfilesLayer(overlay) : readProfilesLayer(baseDir);
+
+  // ── A TEST FIXTURE IS PRESENT AND NEVER OFFERED ─────────────────────────────────────────────────
+  //
+  // An outside user installed this product and their brand-owner picker offered three of our test
+  // accounts. The picker was not wrong: it listed the roster, and the roster was the bundled directory.
+  //
+  // `package.json` already excludes those files, and that exclusion works — the published tarball
+  // carries two profiles. It protects ONE route. `INSTALL.md` documents `git clone && npm install` as a
+  // first-class way in, and on that route nothing is excluded, the checkout IS the bundled directory,
+  // and every fixture loads. A packaging rule cannot answer a question the loader is asked.
+  //
+  // So the loader answers it. A profile marked `testFixture` is refused from the roster this returns, on
+  // every route, whether it was excluded from a tarball or not — and the suite asks for it by name.
+  //
+  // TWO FLAGS, TWO QUESTIONS, AND THE SECOND ONE'S ANSWER CHANGED. `testFixture` marks visibility:
+  // a suite fixture is never offered. `demoData` marks provenance: the account is fiction and the
+  // admission wall refuses a real clearance under it. This file argued that `demoData` must leave its
+  // account LISTABLE, because the demo needed to show it — true until the owner ruled otherwise on
+  // 2026-09-08. A fresh install now resolves `generic` alone, and the demo asks for its own account
+  // when it runs, so the demo account is refused here too. The flags stay separate because the
+  // questions are: a fixture is never shown to anybody, a demo account is shown to the demo.
+  //
+  // ONE ROSTER, NOT TWO. The tested set and the resolvable set are now the same files with a flag,
+  // rather than five profiles the suite exercises against two a customer receives. That disjoint pair is
+  // the defect this module's own header narrates from 2026-07-19, and a packaging-only fix recreates it.
+  //
+  // THE SUITE ASKS ONCE, BY ENVIRONMENT, RATHER THAN AT NINETY-FOUR CALL SITES. Most of the checks that
+  // need a fixture do not call this function — they exercise code that calls it, so there is no argument
+  // to pass. `scripts/test-run.mjs` sets the variable for every child, which keeps the ask visible in
+  // one place and OFF everywhere else, including any process that merely imports this module.
+  //
+  // That leaves the tested roster larger than the resolved one, which is the disjoint-roster shape this
+  // module's header narrates and the reason a packaging-only fix was refused. What makes it one roster
+  // rather than two is `a-clean-install-offers-generic-alone`: it names both sides — every file
+  // in the directory, and exactly what a resolved roster returns — so the difference between them is
+  // asserted rather than assumed, and adding a fixture without marking it reds that check.
+  //
+  // AN EXPLICIT ARGUMENT BEATS THE ENVIRONMENT, and the distinction is `undefined` rather than falsiness.
+  // The suite sets the variable for every child, so a check asking for the RESOLVED roster — the one a
+  // customer gets — would otherwise be handed the suite's own. Two of this change's own arms failed that
+  // way before this line: they asked for what an install offers and were told what the suite runs with.
+  const asked = includeTestFixtures !== undefined
+    ? includeTestFixtures
+    : String(process.env.CLEAROTRON_TEST_FIXTURE_PROFILES ?? "").trim() === "1";
+  if (!asked) for (const [k, p] of [...profiles]) if (p?.testFixture === true) profiles.delete(k);
+
+  // THE DEMO ACCOUNT IS NOT PART OF A FRESH INSTALL EITHER — owner ruling, 2026-09-08: a clean install
+  // resolves `generic` and nothing else, and the demo brings its own account when somebody runs it.
+  // Nobody should have to clean demo material out of an environment they just created.
+  //
+  // Same shape as the gate above and for the same reason: the packaging exclusion cannot answer this,
+  // because `git clone && npm install` is a documented route on which the checkout IS the bundled
+  // directory. The loader answers it on every route.
+  const askedDemo = includeDemo !== undefined
+    ? includeDemo
+    : String(process.env.CLEAROTRON_DEMO_PROFILES ?? "").trim() === "1";
+
+  // — AND IT GATES THE LAYER, NOT THE FLAG. The ruling is about the demo account this PRODUCT bundles.
+  // A deployment that put a `demoData` account in its OWN configured store chose to have it: that is an
+  // operator's decision about their own roster, and the admission wall still refuses a real clearance
+  // under it, so nothing is spent. Gating on the flag alone would have reached into a configured store
+  // and deleted an account nobody asked us to hide — the test deployment has one. When an overlay is
+  // configured this loader reads that store and not the bundled directory, so the question is which
+  // directory was actually read — NOT whether an overlay was set. An explicit `dir` pointing at a
+  // configured store leaves `overlay` null while reading somebody's own roster, and `!overlay` would
+  // have called that bundled and gated it.
+  const bundled = (overlay ?? baseDir) === PROFILES_BASE_DIR;
+  //
+  // THE MORE SPECIFIC FLAG DECIDES. Every shipped profile but `generic` carries `demoData`, the three
+  // suite fixtures included, so a demo gate applied to all of them would swallow a roster somebody had
+  // explicitly asked for: `includeTestFixtures: true` would return `generic` alone, silently, and a
+  // check that asks for its own fixtures would pass having exercised nothing. That is the same vacuous
+  // green two of this loader's own checks produced before the argument beat the environment. A fixture's
+  // visibility is answered by its own gate above; this one answers only for accounts that are demo data
+  // and nothing more specific.
+  if (!askedDemo && bundled) {
+    for (const [k, p] of [...profiles]) if (p?.demoData === true && p?.testFixture !== true) profiles.delete(k);
+  }
   if (overlay && !profiles.has("generic")) {
     const base = readProfilesLayer(baseDir);
     if (base.has("generic")) profiles.set("generic", base.get("generic"));
@@ -742,6 +833,32 @@ export function resolveProfile(job, { profiles = loadProfiles() } = {}) {
 const PROJECTS_SUBDIR = "projects";
 let projectCache = null;
 
+
+/**
+ * Is `key` a profile that exists in one of these roots and is marked as a test fixture?
+ *
+ * Read from the FILE rather than from the roster, deliberately: the roster handed to the projects walk
+ * is the resolved one, which has already dropped every fixture — so asking it cannot tell "a fixture
+ * whose projects are beside it" from "a project directory whose customer is gone". Those want different
+ * answers and the file is the only place that still holds the difference.
+ */
+function readProfileFlag(roots, key, flag) {
+  for (const root of roots) {
+    const f = join(root, `${key}.json`);
+    if (!existsSync(f)) continue;
+    try { return JSON.parse(readFileSync(f, "utf8"))?.[flag] === true; } catch { return false; }
+  }
+  return false;
+}
+
+const isTestFixtureKey = (roots, key) => readProfileFlag(roots, key, "testFixture");
+
+/** Is this project directory's customer an account the DEMO brings, rather than one this install has?
+ *  Read from the FILE for the same reason as the fixture check beside it: the roster handed to this walk
+ *  has already dropped the account, so asking the roster cannot tell "the demo's, and hidden" from "the
+ *  customer is gone", and the second is an authoring error that must still hard-fail. */
+const isDemoKey = (roots, key) => readProfileFlag(roots, key, "demoData");
+
 /** Load every profiles/projects/<customer>/<slug>.json → Map("<customer>/<slug>" → overlay). Each overlay is
  *  validated in SPARSE mode (PROJECT_KEYS optional, customer-only keys rejected) and carries its lifted-out
  *  `projectName` (default = slug) + optional sibling `<slug>.context.md`. A project directory under an unknown
@@ -778,8 +895,22 @@ export function loadProjects({ dir, profiles, force = false } = {}) {
   for (const ent of readdirSync(projDir, { withFileTypes: true })) {
     if (!ent.isDirectory()) continue;   // only <customer>/ subdirs participate; a stray file is ignored
     const ck = ent.name;
-    if (!roster.has(ck))
+    // A PROJECT UNDER A TEST FIXTURE IS SKIPPED, NOT A FAULT. The refusal below is right and stays: a
+    // project directory with no customer is a typo or a half-deleted account, and resolving it silently
+    // would attach an overlay to nothing. But a fixture's own projects are in the same checkout as the
+    // fixture, and the roster no longer offers the fixture — so on a clone install this refusal would
+    // fire on the product's own files and stop the process at load. Skipped by reading the fixture
+    // marker from the file, because the roster this walk was handed is the one that already dropped it.
+    if (!roster.has(ck)) {
+      if (isTestFixtureKey(roots, ck)) continue;
+      // AND THE DEMO'S OWN PROJECTS, for the identical reason. `profiles/projects/demo-brand-owner/`
+      // ships, and since a fresh install stopped resolving that account this walk met a project whose
+      // customer it could not see — a HARD startup failure, from the product's own files, on every
+      // clean install. Caught by the arm below, not by review; it is the third time this shape has been
+      // found in this loader.
+      if (isDemoKey(roots, ck)) continue;
       throw new Error(`profiles/projects/${ck}/: no customer profile "${ck}" — a project must live under a known customer (add profiles/${ck}.json first)`);
+    }
     const cdir = join(projDir, ck);
     for (const f of readdirSync(cdir).filter((n) => n.endsWith(".json")).sort()) {
       const slug = f.replace(/\.json$/, "");
@@ -845,7 +976,7 @@ export function resolveEffectiveProfile(job, { profiles = loadProfiles(), projec
       //
       // The customer's platforms are CLIENT-MANDATED — the account asked for those marketplaces to be
       // searched, and a project may add to that instruction but never revoke it. Replace semantics meant a
-      // project that stated its own marketplaces silently DELETED the customer's: the Aurora Interactive account
+      // project that stated its own marketplaces silently DELETED the customer's: one test account
       // names 7 games storefronts, its console-ecosystem project names 9 mostly-retail sites, and every run
       // of that project searched the 9 — dropping store.epicgames.com, itch.io, apps.microsoft.com and
       // mobygames.com. The report still read as clean coverage, because the sweep faithfully covered the
@@ -882,16 +1013,17 @@ export function resolveEffectiveProfile(job, { profiles = loadProfiles(), projec
   //
   // Attached here rather than threaded through four call sites because this is the one place that KNOWS
   // — every caller that resolves a profile now carries its provenance whether or not it thought to ask,
-  // and 's hand-bridge at the §B2 door (`{...profile, origins }`) becomes a no-op rather than the
+  // and the hand-bridge at the §B2 door (`{...profile, origins }`) becomes a no-op rather than the
   // only correct call site. The sibling stays in the return for the callers that read it directly.
   return { profile: { ...profile, origins }, projectKey: overlay.projectKey, projectName: overlay.projectName, origins };
 }
 
 /** The self-exclusion gate: a profile's selfExclusionOwners[]
- *  may only inject when the job's APPLICANT is the profile's customer — an aurora-interactive.example-forwarded
- *  search for a third-party applicant must NOT classify Aurora-owned conflicts as own rights
- *  (that would delete true conflicts from a delivered clearance). Word-boundary containment of the
- *  profile name in the applicant string ("Aurora Interactive" ⊂ "Aurora Interactive Ltd"), never fuzzy. */
+ *  may only inject when the job's APPLICANT is the profile's customer — a search forwarded from a
+ *  customer's own domain, but asking about a THIRD-PARTY applicant, must not classify that
+ *  customer's conflicts as own rights (that would delete true conflicts from a delivered
+ *  clearance). Word-boundary containment of the profile name in the applicant string
+ *  ("Foxglade Interactive" ⊂ "Foxglade Interactive Ltd"), never fuzzy. */
 export function applicantMatchesProfile(profile, customer) {
   const n = (s) => String(s ?? "").toLowerCase().replace(/[^a-z0-9 ]+/g, " ").replace(/\s+/g, " ").trim();
   const c = n(customer);

package/driver/progress.mjs

@@ -8,7 +8,7 @@
 //   1. <runDir>/status.json        — the machine-readable per-run truth (travels into the archive on
 //                                     success, since the run-dir is renamed there).
 //   2. <studioRoot>/STATUS.md       — a human-readable rollup of recent runs, newest-first, the ONE file
-//                                     the prelim-status skill reads to answer "where is it at?".
+//                                     the clearotron-status skill reads to answer "where is it at?".
 //
 // Both writes are atomic (temp + rename) and idempotent — status is DERIVED from the current run, never
 // blindly incremented — so the resumable pipeline can re-drive a run without corrupting either file.
@@ -440,15 +440,15 @@ export function lineFor(s) {
   // 2026-07-04 incident: STATUS.md showed marble-spire as plain "delivered" and VENZY as plain
   // "FAILED" while BOTH still had their email/WhatsApp queued (sendPending) behind a wedged outbox
   // lane — so the heartbeat completion-watch read the rollup, saw nothing pending, and stood down.
-  // The rollup now carries the send state loudly; prelim-deliver flips sendPending:false on send.
-  const pending = s.sendPending === true ? " — 📮 SEND PENDING (email/WhatsApp NOT yet out — run prelim-deliver)" : "";
+  // The rollup now carries the send state loudly; clearotron-deliver flips sendPending:false on send.
+  const pending = s.sendPending === true ? " — 📮 SEND PENDING (email/WhatsApp NOT yet out — run clearotron-deliver)" : "";
   if (s.state === "delivered") {
     const v = s.verdict ? ` (${s.verdict})` : "";
     return `- ${head} — delivered${v}${s.url ? ` — ${s.url}` : ""}${pending}`;
   }
   if (s.state === "failed") {
     const at = s.failedStage ?? s.lastStage ?? stepTxt;
-    return `- ${head} — ⚠️ FAILED at ${at}${s.reason ? ` — ${trunc(s.reason)}` : ""}${pending ? " — 📮 FAILURE NOTICE PENDING (run prelim-deliver)" : ""}`;
+    return `- ${head} — ⚠️ FAILED at ${at}${s.reason ? ` — ${trunc(s.reason)}` : ""}${pending ? " — 📮 FAILURE NOTICE PENDING (run clearotron-deliver)" : ""}`;
   }
   if (s.state === "recovering") {
     // 2026-07-04 production doctrine: a recoverable failure AUTO-RESUMES — the report is still owed.
@@ -513,8 +513,8 @@ export function rollupStatus(studioRoot) {
       .sort((a, b) => String(b.updatedAt ?? "").localeCompare(String(a.updatedAt ?? "")))
       .slice(0, MAX_RUNS);
     const agent = agentFromStudioRoot(studioRoot);
-    const body = runs.length ? runs.map(lineFor).join("\n") : "_No prelim searches running or recently finished._";
-    const md = `# Prelim-search status — ${agent}\n_updated ${nowISO()}_\n\n${body}\n`;
+    const body = runs.length ? runs.map(lineFor).join("\n") : "_No clearotron searches running or recently finished._";
+    const md = `# Clearotron-search status — ${agent}\n_updated ${nowISO()}_\n\n${body}\n`;
     atomicWrite(join(studioRoot, "STATUS.md"), md);
   } catch { /* never throw */ }
 }

package/driver/provider-usage.mjs

@@ -48,7 +48,7 @@ export const KINDS = ["search", "record_fetch", "image", "phoneme", "batch_scree
 // The gateway namespaces the driver's --session-key as `agent:<agentId>:<key>` before it reaches the
 // plugin (confirmed on the first live run: sessionKey = `agent:clawdi:prelim-<slug>-<codename>-…`). Strip
 // that leading `agent:<id>:` namespace so the run prefix anchors at the real start of the caller's key —
-// otherwise a bare startsWith("prelim-…") matches nothing.
+// otherwise a bare startsWith("clearotron-…") matches nothing.
 function stripGatewayNs(s) {
   return typeof s === "string" ? s.replace(/^agent:[^:]+:/, "") : "";
 }

package/driver/publish/demo-marking.mjs

@@ -74,7 +74,7 @@ export function resolveDemoData({
 /**
  * The demonstration note for a MARKDOWN surface.
  *
- * 's acceptance 3 asks for the banner on "the grouped knockout page … the one a
+ * That acceptance 3 asks for the banner on "the grouped knockout page … the one a
  * reader opens first". THAT PAGE DOES NOT EXIST: `knockout.mjs` states in its own header that a
  * multi-mark run "writes no `report.html` AT ALL — the documents are `report-<slug>.html`, one per
  * mark", and that `report.md` "is the ONLY file that names every mark together". It is also written

package/driver/publish/index.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
-// Pure-code publish step for the prelim-driver: takes a finished run's two contract markdown files
+// Pure-code publish step for the clearotron-driver: takes a finished run's two contract markdown files
 // (report.md + audit.md, written by the report-synthesis / audit-emit stages) and renders + writes the
 // delivery artifacts into the pool (`config.poolRoot`, which since has NO default — unset refuses),
 // then regenerates the index.
@@ -463,7 +463,7 @@ export function regenIndex(poolDir) {
   // Do NOT chmod the customer dirs: they inherit the set-gid pool group (an explicit dir chmod here was the
   // 2026-06-02→-06-08 Caddy-403 bug — see the publishReport comment). Only the index FILES get 0o640.
   // The page heading speaks the customer's DISPLAY name (profile .name), never the internal key slug —
-  // "Trademark clearance — aurora" read as an internal id on a client-facing page. Best-effort: profiles
+  // "Trademark clearance — foxglade" read as an internal id on a client-facing page. Best-effort: profiles
   // unreadable ⇒ fall back to the filter label (the runs' client string) ⇒ the key (displayOf, built above).
   for (const [key, crs] of byCustomer) {
     // LEAK-#9 fail-closed: NEVER emit a client-facing customer/generic/index.html. 'generic' is the shared
@@ -702,7 +702,7 @@ export async function publishReport({ runId, codename, reportMd, auditMd, findin
   let findings = [], coverage = [], contextNotes = [], quarantined = [], findingsError = null, coverageJudgment = null, markAssessment = null, actionsRegister = null, askAnswers = null, correctionsDoc = null, fourAnswers = null;
   // — the DECLARED findings contract version, threaded to the renderer so the grouped
   // reasoned-negative section fires only on a v6 record. Stays null on the lenient/error paths: fail
-  // closed, an unknown version renders the pre- section.
+  // closed, an unknown version renders the pre-change section.
   let findingsSchemaVersion = null;
   // — THE STORES THIS PUBLISH DID NOT FIND. Declared in publish/publish-inputs.mjs, read through
   // its three-state helper, and recorded onto meta.clientGate below. Before this list existed an absent
@@ -981,7 +981,7 @@ export async function publishReport({ runId, codename, reportMd, auditMd, findin
   // `gateViolations` — those are LOGGED for observability but never a reason to drop the download. (An earlier
   // version made the gate fatal, so a legitimately-sparse run — e.g. no bound Class — silently lost its Excel.)
   // The run's REPORT IDENTITY, off the same registry row that chose its machinery. The FROZEN policy
-  // sidecar names WHICH level ran; the registry names what that level is called TODAY (, one
+  // sidecar names WHICH level ran; the registry names what that level is called TODAY (one
   // numbering system — reportIdentityFor is registry-first, sidecar label only for a level the registry
   // no longer knows). So a republished pre-renumber run renders under the current scale, deliberately.
   // A run with no sidecar (every run older than the level registry) yields undefined and renders
@@ -1189,7 +1189,10 @@ export async function publishReport({ runId, codename, reportMd, auditMd, findin
 
   const total = skipRegen ? null : regenIndex(poolRoot);
   if (!skipRegen) await regenSurfaces(poolRoot);
-  const url = poolUrl ? `${String(poolUrl).replace(/\/$/, '')}/${runId}/report.html` : null;
+  // THE PORTAL ROUTE, not the pool's directory layout (tracker issue 289). This was
+  // `<origin>/<runId>/report.html` — where the documents sit on disk, which is not an application route.
+  // Composed rather than spelled here so the report link is built the same way the audit link always was.
+  const url = reportRouteFor(poolUrl, runId);
   return { runId, auditFile, counts, total, url, poolRunDir, auditError, findingsError, customerKey: customerKey || 'generic', clientGate };
 }
 
@@ -1241,7 +1244,21 @@ export function accessNoteHtml(font, domain = config.accessDomain) {
  * the edge's own legacy-report regexp character for character, so this function admits exactly the URLs the
  * deployment admits and no others.
  */
-const REPORT_PATH_RE = /^\/([A-Za-z0-9][A-Za-z0-9._-]{0,180})\/report\.html$/;
+// ── TWO SHAPES, AND THE SECOND ONE IS HISTORY (tracker issue 289) ────────────────────────────────────
+//
+// The block quoted above describes an edge rewrite that IS NOT IN FORCE ON PRODUCTION. Settled by the
+// account owner against the live deployment, signed in as a delivered run's own owner: the emailed link
+// returned the portal application's own `{"error":"not_found"}` — the app answered, so nothing rewrote
+// the path ahead of it — while the portal's own link for that same run opened. The prose above, and the
+// notes in portal-service.mjs and publish/knockout.mjs that lean on it, describe a config that does not
+// live in this repository and were transcribed when it was true somewhere. A transcription is a claim
+// about a host at the moment somebody wrote it down, not a fact about the host today.
+//
+// So reports are addressed at the portal route now (reportRouteFor), and this pattern keeps matching the
+// LEGACY shape as well for one reason: `auditUrlFor` derives the workbook link by parsing the report URL,
+// and an archived run re-published from its stored legacy URL must not silently lose its audit link. The
+// two alternatives are read in one place so a future reader cannot fix one and miss the other.
+const REPORT_PATH_RE = /^\/(?:portal\/report\/([A-Za-z0-9][A-Za-z0-9._-]{0,180})\/?|([A-Za-z0-9][A-Za-z0-9._-]{0,180})\/report\.html)$/;
 
 // The run id as the edge and the portal both spell it: one path segment, no separators, no traversal.
 // Same character class as REPORT_PATH_RE's capture and as portal-service's own slug gate, because a
@@ -1261,6 +1278,29 @@ export function auditRouteFor(origin, runId) {
   return `${String(origin).replace(/\/$/, '')}/portal/report/${runId}/audit.xlsx`;
 }
 
+/**
+ * THE REPORT'S ROUTE, from an origin and a run id (tracker issue 289).
+ *
+ * The delivered link used to be the pool's directory layout pasted behind the public origin —
+ * `<origin>/<runId>/report.html` — which is where the documents sit on disk and is not an application
+ * route. It resolved only where an edge rewrite happened to claim it, and on production no such rewrite
+ * is in force: the emailed link returned the portal's own `{"error":"not_found"}` for the run's OWN
+ * owner. Every delivered report on both lanes carried it, on all three surfaces that quote the URL.
+ *
+ * Composed here, beside auditRouteFor and markReportRouteFor, so the three links a delivery carries are
+ * built by three functions with one idea of where the portal lives. That is the property worth having:
+ * the audit link has been correct throughout precisely because it was composed against the route instead
+ * of derived from the file layout, and this makes the report link the same kind of thing.
+ *
+ * A link the portal will refuse is worse than none, so an unconfigured origin or a run id that is not a
+ * single clean path segment yields null — the same posture auditRouteFor takes, and the caller already
+ * treats null as "no link on any surface".
+ */
+export function reportRouteFor(origin, runId) {
+  if (!origin || !runId || !RUN_SEGMENT_RE.test(String(runId))) return null;
+  return `${String(origin).replace(/\/$/, '')}/portal/report/${runId}/`;
+}
+
 /**
  * ONE MARK'S DOCUMENT in a batch, at the address the portal serves it from.
  *
@@ -1292,7 +1332,8 @@ export function auditUrlFor(reportUrl, auditFile) {
   let u;
   try { u = new URL(String(reportUrl)); } catch { return null; }
   const m = REPORT_PATH_RE.exec(u.pathname);
-  return m ? auditRouteFor(u.origin, m[1]) : null;
+  // Group 1 is the portal shape, group 2 the legacy one — exactly one of them matches.
+  return m ? auditRouteFor(u.origin, m[1] ?? m[2]) : null;
 }
 
 /**
@@ -1385,7 +1426,7 @@ export const RISK_TIERS = [
   [/LOW/,            { bg: '#4472C4', fg: '#fff', label: 'LOW',        txt: '#2f55a4' }],
 ];
 // doc 50 — the run's band LADDER (from opts.bands / meta.framework.bands): per-run vocabulary with the
-// same template palette keyed by TONE, so "Moderate" (house) and "Medium" (zephyr) both colour correctly
+// same template palette keyed by TONE, so "Moderate" (house) and "Medium" (a customer ladder) both colour correctly
 // and a 5-band matrix framework (incl. "Low") lands on the same ramp. Set per compose; null = legacy.
 let EMAIL_BANDS = null;
 export const TONE_TIER = {

package/driver/publish/knockout.mjs

@@ -10,7 +10,7 @@
 import { readFileSync, writeFileSync, mkdirSync, chmodSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { driverDir, ensureDriverDir } from '../../shared/driver-dir.mjs';   //
-import { riskTier, TONE_TIER, regenIndex, regenSurfaces, auditRouteFor, markReportRouteFor } from './index.mjs';
+import { riskTier, TONE_TIER, regenIndex, regenSurfaces, auditRouteFor, markReportRouteFor, reportRouteFor } from './index.mjs';
 import { runKnockoutLint, deliveryFlagLines } from '../predelivery-lint.mjs';
 import { note } from '../log.mjs';
 import { addSheet } from './xlsx.mjs';
@@ -68,9 +68,13 @@ export const knockoutStatement = (framework, marks) =>
 // 11pt, no <!DOCTYPE>, no <head>, no <meta charset> — and they rendered a Depth 2 report as a grey
 // spreadsheet with the register hit-counts the customer paid for buried in a table cell. The report now
 // renders through publish/render-knockout.mjs in the product's own design language, off the same shared
-// stylesheet and brand tokens as the clearance report. Internal working material (the purple staff notes,
-// the model's registerEstimate) is not stripped from the report — it is not IN the report; it lives in
-// the audit workbook, which is what an internal artifact is for.
+// stylesheet and brand tokens as the clearance report.
+//
+// THE REVIEWER'S NOTES ARE ON THE REPORT SINCE 2026-09-07 (owner ruling, tracker issue 274). This
+// paragraph used to end "internal working material (the purple staff notes, the model's registerEstimate)
+// is not IN the report; it lives in the audit workbook". That is now true of `registerEstimate` only: the
+// notes render on the page, labelled, and the workbook keeps its copy. See render-knockout.mjs's header
+// for the ruling and reviewerNotesBlock for the shape.
 
 // ── The workbook: the skill's three sheet names + columns, plus the conditional sheets below ────────
 // ── ONE DRILL-THROUGH KEY: `<MARK> #<ordinal>`, per mark ──────────────────────────────────────
@@ -250,9 +254,11 @@ export async function buildKnockoutWorkbook(findings, receipts, outPath, registe
 // ── The email: a COVER NOTE. Headline band, one line per mark, the report link. Nothing else. ────────
 // The report is the deliverable and the email points at it — the same doctrine the clearance lane
 // follows. The old `delivery.email === 'table'` overlay inlined the full review table into the mail
-// body, and it inlined the INTERNAL variant: purple staff notes and the model's register estimate went
-// out over the wire to whoever the mail reached. A second rendering of the findings in a second dialect
-// is also a second thing to keep true. Per-lawyer client formatting is drafted by the assistant from the
+// body, which put the findings in front of whoever the mail reached rather than whoever opened the
+// report, and made a second rendering of them in a second dialect — a second thing to keep true.
+// (That overlay's other charge, that it shipped an INTERNAL variant, no longer describes anything: the
+// 2026-09-07 ruling put the reviewer's notes on the one report. The reason above is the load-bearing one
+// and it is unaffected — the mail stays a cover note.) Per-lawyer client formatting is drafted by the assistant from the
 // run's report-data.json, not by a template knob in here.
 // `reports` is publishKnockout's own list — `[{mark, url}]`, one per published document — and
 // `auditUrl` is composed by the publisher from the pool URL it already holds. Neither is derived here.
@@ -358,6 +364,18 @@ export async function publishKnockout({ runId, codename, runDir, findings, plan,
   let registerRecords = null;
   try { registerRecords = JSON.parse(readFileSync(driverDir(runDir, 'register-records.json'), 'utf8')); }
   catch { registerRecords = null; }
+  // The owner lookups this run made (tracker issue 276), read the same tolerant way as the records above:
+  // an archived run that predates the lane has no file, and its cards then render exactly as they were
+  // delivered. The source line the report prints comes from HERE, not from anything the seat typed.
+  let ownerChecks = [];
+  try { ownerChecks = JSON.parse(readFileSync(driverDir(runDir, 'owner-checks.json'), 'utf8')).checks ?? []; }
+  catch { ownerChecks = []; }
+  // The request the run was given, read the same tolerant way as the sidecars above and for the same
+  // reason (tracker issue 331 A.1). It is what "About this request" states; a run archived before the
+  // sidecar existed has none, and its page renders exactly as it was delivered.
+  let instructedScope = null;
+  try { instructedScope = JSON.parse(readFileSync(driverDir(runDir, 'instructed-scope.json'), 'utf8')); }
+  catch { instructedScope = null; }
 
   // ── — THIS LANE HAD NO RECORD-ORIGIN LOGIC AT ALL ─────────────────────────────────────────────
   //
@@ -473,12 +491,22 @@ export async function publishKnockout({ runId, codename, runDir, findings, plan,
   // "every audit link we have ever emailed died at the front door, silently". It came back here twice:
   // once as string surgery on the report URL, once as this function, and both spelled a pool path.
   //
-  // A SINGLE MARK KEEPS THE LEGACY SHAPE. `<runId>/report.html` is what the rewrite exists for, it is
-  // the address in every knockout email already sent, and it resolves. Changing a link that works to
-  // match one that did not is how the next one of these gets written.
+  // A SINGLE MARK USED TO KEEP THE LEGACY SHAPE, on the reasoning that `<runId>/report.html` is what the
+  // rewrite exists for and that it resolves. THAT IS FALSE ON PRODUCTION (tracker issue 289) and the
+  // paragraph is kept, corrected, because its warning is still the right instinct and only its premise
+  // was wrong.
+  //
+  // Settled by the account owner against the live deployment, signed in as a delivered run's own owner:
+  // the emailed link returned the portal application's own `{"error":"not_found"}` — the app answered, so
+  // no rewrite touched the path — while the portal's own link for that run opened. The edge block this
+  // reasoning rests on is not in this repository, and the transcription of it in the test tree describes
+  // a host at the moment somebody wrote it down, not production today.
+  //
+  // The warning it ends with — changing a link that works to match one that did not — is why this was
+  // checked against the live thing before being changed rather than after.
   const origin = poolUrl ? String(poolUrl).replace(/\/$/, '') : null;
   const reportUrlFor = (slug) => !origin ? null
-    : single ? `${origin}/${runId}/report.html`
+    : single ? reportRouteFor(origin, runId)
     : markReportRouteFor(origin, runId, slug);
   // — resolved once for the whole publish, off the same two sources the clearance
   // publisher uses (frozen sidecar, then roster; either marks, neither un-marks).
@@ -512,7 +540,7 @@ export async function publishKnockout({ runId, codename, runDir, findings, plan,
     };
     const markBand = single ? overall : worstBand(framework, [m]);
     writeRO(file, renderKnockoutHtml(one, framework, {
-      runId, overall: markBand, issued, auditFile, probeRan, registerCounts, registerRecords, identity, matter: runId,
+      runId, overall: markBand, issued, auditFile, probeRan, registerCounts, registerRecords, ownerChecks, instructedScope, identity, matter: runId,
       // — an invented mark says so on its own report. Resolved ONCE above the loop:
       // the answer is a property of the run, and asking per mark would let a multi-mark demo mark some
       // documents and not others if the roster moved mid-publish.
@@ -528,7 +556,7 @@ export async function publishKnockout({ runId, codename, runDir, findings, plan,
     // native-render path has been reading for since before anything wrote it. One per report, so the
     // native render of a per-mark document is that mark's data and not the batch's.
     writeRO(dataFile, JSON.stringify(knockoutReportData(one, framework, {
-      runId, codename, overall: markBand, issued, registerCounts, registerRecords, auditFile, customerKey, matter: runId,
+      runId, codename, overall: markBand, issued, registerCounts, registerRecords, ownerChecks, auditFile, customerKey, matter: runId,
       identity: { ...identity, level: searchPolicy?.level ?? null },
       url: reportUrlFor(slug),
     }), null, 2));
@@ -628,7 +656,7 @@ export async function publishKnockout({ runId, codename, runDir, findings, plan,
     // WHICH DOCUMENTS THIS RUN PUBLISHED, and for which name. Every reader that has to open,
     // serve or link a knockout's reports takes the list from here rather than deriving a filename: the
     // naming rule (one mark ⇒ `report.html`, several ⇒ `report-<slug>.html`) is written ONCE, above, and
-    // nobody re-implements it. Absent on every pre- meta, which is exactly the run that has one
+    // nobody re-implements it. Absent on every pre-change meta, which is exactly the run that has one
     // report at `report.html` — so a reader that falls back to that name on absence is reading the
     // archive correctly, not guessing.
     // — `slug` RIDES. It was destructured away here while being computed twenty lines up, and

package/driver/publish/parse.mjs

@@ -225,11 +225,11 @@ export function stripTelemetry(md) {
     .join('\n');
 }
 
-// ── tracker issue 831 — THE CLIENT CUT OF THE AUDIT BLOCK'S CROSS-REFERENCE LINES ────────────────────────────────
+// ── THE CLIENT CUT OF THE AUDIT BLOCK'S CROSS-REFERENCE LINES ────────────────────────────────
 //
 // `disposition` is a PLACEMENT key. stages.mjs dictates it as the posture that sets only WHERE a card is
 // placed and never the band; findings-model's DISPOSITION_GROUP maps it to the section heading the report
-// already prints. tracker issue 762 D5 took it off the report's risk chip and tracker issue 833 added the `disposition` KEY to
+// already prints. D5 took it off the report's risk chip and a later change added the `disposition` KEY to
 // scrubCards' strip list — and the word still reached client principals, because audit-from-spine.mjs
 // re-encodes it into two OTHER keys that survive an allowlist keyed on names:
 //
@@ -252,7 +252,7 @@ export function stripTelemetry(md) {
 // resolved to, and which fragment of a contradicted pair the record supports. Deleting the key deletes the
 // pointer along with the word.
 //
-// THIS IS NOT THE SUBSTITUTION tracker issue 669 FORBIDS. Nothing here reads arbitrary client prose for a vocabulary.
+// THIS IS NOT THE FORBIDDEN SUBSTITUTION. Nothing here reads arbitrary client prose for a vocabulary.
 // Each rule is ANCHORED to one position in a grammar THIS ENGINE writes: the disposition token at the head
 // of `resolution`, and the disposition token inside the `(finding #N, …)` parenthetical the contradiction
 // line builds. A mark named ADVERSARIAL survives both — it is not at position 0 of a resolution line, and
@@ -290,7 +290,7 @@ export function contradictionResolutionForClient(v) {
   return String(v).replace(CONTRADICTION_DISPOSITION_RE, '$1)');
 }
 
-// ── tracker issue 669 — ENGINE_PLAIN AND plainify ARE DELETED ────────────────────────────────────────────────────
+// ── ENGINE_PLAIN AND plainify ARE DELETED ────────────────────────────────────────────────────
 //
 // doc-52 put nineteen find-and-replace rules on the rendered client surface. tracker issue 656 is what that cost:
 // `axis` -> `group` turned "AXIS Bank filed in class 36" into "group Bank filed in class 36" — a report

package/driver/publish/publish-inputs.mjs

@@ -19,7 +19,7 @@
 //
 // Modelled on mcp-server/lib/coverage.mjs:65-75 (assertValidatorCoverage): a closed partition asserted
 // at LOAD, so a new store cannot be added without consciously choosing its gating. The failure that
-// mechanism exists to prevent is 's — a hand-copied mirror that silently stopped covering an
+// mechanism exists to prevent is the — a hand-copied mirror that silently stopped covering an
 // artifact and still answered "complete: yes" about a file it never checked.
 
 import { existsSync, readFileSync } from "node:fs";
@@ -93,7 +93,7 @@ export const NOT_READ_BY_NAME = {
   "token-ledger": "the per-recipe token rollup, read through tokens.mjs rollupTokens(runDir) which walks the run's own telemetry; absent ⇒ the meta simply omits the tokens field",
 };
 
-// Neither of these is a run-side store, and both have been miscounted as one ('s own issue body
+// Neither of these is a run-side store, and both have been miscounted as one (its own issue body
 // lists audit.md among the stores publishReport reads). They are FUNCTION ARGUMENTS — publishReport is
 // handed the two contract markdown paths by its caller and reads them from wherever it is told, so an
 // absent one is the caller's error and already throws. Declared so the source scan can tell "argument"

package/driver/publish/register-presence.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
 // register-presence.mjs — the audit's queryable store of every live, matter-in-scope enumerated record.
 //
-// THE RULING THIS IMPLEMENTS (, owner 2026-08-31): "YES of course they should be in
+// THE RULING THIS IMPLEMENTS (owner 2026-08-31): "YES of course they should be in
 // the audit. always. … we don't need to report on them but we need to store them." On the run this was
 // measured against, 65 live records inside the matter's scope and carrying the client's own dominant
 // element appeared in NO stored artifact — not the report (correct), and not the audit either (the