clearotron 0.2.0 → 0.2.1

package/.env.example

@@ -403,3 +403,55 @@ CLEAROTRON_DEMO=
 # Read by driver/whatif-worker.mjs. Refs tracker issue 1953.
 # effect: tuning
 CLEAROTRON_WHATIF_MAX_CONCURRENT=1
+
+# The checkout every shipped systemd unit interpolates — and the one name in this file you are most
+# likely to meet before you meet this file. Ten units name it in their `ExecStart`
+# (clearotron-portal, -worker, -deploy, -client-mcp, -mcp-face, prelim-driver, prelim-outbox, the two
+# mcp-server/remote units and the courtlistener bridge), and production's units all depend on it.
+#
+# YOU ALMOST CERTAINLY DO NOT SET THIS. `clearotron connect` writes it into the install's env file, set
+# to the checkout it just installed (bin/connect.mjs, shared/checkout-move.mjs), and it rewrites it when
+# the checkout moves. So this is not a decision waiting for you at install time, and the row does not
+# exist because a deployment cannot be configured without it.
+#
+# IT EXISTS BECAUSE OF WHO READS IT AT 2AM. Somebody whose unit will not start reads
+# `${CLEAROTRON_CHECKOUT_DIR}` in an ExecStart, comes to the file INSTALL.md §8 calls the catalogue, and
+# finds nothing. `shared/names-in-force.mjs` already knew the name; neither governance document did.
+# A row that says "the installer writes this" is the answer to their question — the absence was not.
+#
+# Surfaced by the cut-over overlay control once the withheld `ops/` bucket was laid back over the public
+# tree: the ratchets that would have caught it had had no subject since the cut, so this is a gap of
+# long standing rather than a regression. Refs tracker issue 213.
+#
+# Left EMPTY here on purpose. A path in this file would read as a default; there is none, and the
+# installer supplies the real value.
+# effect: deployment
+CLEAROTRON_CHECKOUT_DIR=
+
+# ── The release pipeline's own two names ─────────────────────────────────────────────────────────
+# Both are set by `.github/workflows/release.yml` and read by the release scripts. NEITHER is an
+# operator's decision, and on an install both are unset and the defaults are the right answer. They are
+# catalogued for the same reason CLEAROTRON_CHECKOUT_DIR above is: they are OUR names, read by code that
+# ships, and a reader who meets one in a workflow log needs somewhere to look it up.
+#
+# They are NOT in the system-owned list beside GITHUB_OUTPUT, and the line between them is worth stating:
+# GitHub sets GITHUB_*, so a row would document somebody else's decision. We set these, so a row
+# documents ours.
+#
+# Found by the audit while closing tracker issue 213, not by that issue's diagnosis — they arrived with
+# tonight's release-pipeline work and the catalogue ratchet caught them on the next run, which is the
+# ratchet doing its job. Raised with the release lane rather than silently absorbed.
+
+# The commit the cut decision is ABOUT. The workflow sets it to `github.sha` — the push — because the
+# checkout may have moved on since, and a decision made about "whatever HEAD is now" tried to republish
+# an already-released version. Unset falls back to HEAD, which is correct for the cron and for a hand
+# run, where nothing has moved. Read by scripts/release-cut-decision.mjs.
+# effect: deployment
+CLEAROTRON_CUT_REF=
+
+# How long publishing waits for a parked version run, in whole milliseconds. Unset uses the built-in
+# budget; the workflow sets it to 0 on a `workflow_dispatch` rehearsal so a dry run does not sit out the
+# full wait. A malformed value REFUSES rather than defaulting — taken as 0 it would skip the wait
+# entirely, which is that script not running at all. Read by scripts/release-await-cut.mjs.
+# effect: tuning
+CLEAROTRON_RELEASE_WAIT_MS=

package/INSTALL.md

@@ -115,12 +115,13 @@ Nothing here requires an agent platform or a database — reports are written to
 
 ```
 npm install -g clearotron          # stable — the tested one
-npm install -g clearotron@beta     # newest — every merge, minutes after it lands
+npm install -g clearotron@beta     # newest — cut when there is something worth testing
 ```
 
 A **stable** has run a real clearance end to end and had a from-scratch install driven by somebody who has
-never seen the product, before it was published. A **beta** is published automatically on every merge to
-`main`; it built and the suite passed, and nothing has driven a live register through it.
+never seen the product, before it was published. A **beta** is published when a change lands that is worth
+testing, or while a stable is being prepared — days apart, not on every merge; it built and the suite
+passed, and nothing has driven a live register through it.
 
 **Upgrade production to stables only.** What each channel promises and how often one is cut:
 **[docs/RELEASES.md](docs/RELEASES.md)**.

package/README.md

@@ -39,7 +39,8 @@ Node 22 or newer, on macOS, Linux, or Windows via WSL2. That puts `clearotron` o
 command below works in that short form.
 
 That command gives you the **stable** release — the one that has run a real clearance end to end before it
-was published. If you want the newest code instead, every merge publishes a beta within minutes:
+was published. If you want the newest code instead, a beta is published whenever there is something worth
+testing — deliberately, days apart, not on every merge:
 
 ```bash
 npm install -g clearotron@beta

package/bin/example.mjs

@@ -40,7 +40,7 @@ import "../shared/env-local.mjs";   // step 4 / — FIRST: this program read a
 import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { invoke } from "../shared/invocation.mjs";   // — the printed command is resolved once, for the reader who is actually standing there
-import { join, resolve, dirname, sep } from "node:path";
+import { basename, dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 import { BRAND } from "../shared/brand.mjs";   // — the installer's own name, from the tenant seam
@@ -100,11 +100,26 @@ const DEMO_ROOT = join(REPO, "demo");
 // name is PRINTED below rather than assumed, because "the demo" is about to mean one of several.
 const wanted = flag("--product");
 const children = demoChildren(DEMO_ROOT);
-const sampleDir = resolve(
-  flag("--run-dir")
-  ?? (wanted ? join(DEMO_ROOT, wanted) : (children[0] ? join(DEMO_ROOT, children[0]) : DEMO_ROOT)),
-);
-if (!isFrozen(sampleDir)) {
+
+// ── ALL OF THEM, UNLESS THE CALLER NARROWED IT (tracker issue 277) ──────────────────────────────────
+//
+// This used to replay `children[0]` and stop. The package ships one finished report per product, and a
+// first-time reader met one of them with nothing on screen saying the other three existed — so three
+// quarters of what was shipped was reachable only by someone who already knew to ask for it. The owner's
+// ruling is that they auto-load: "it should auto-load since it is NOT obvious these runs are there unless
+// you know about it."
+//
+// `--product` and `--run-dir` still narrow to one, because "show me just this one" is a real thing to
+// want. Neither given now means every product this tree ships, in the container's own order.
+const sampleDirs = flag("--run-dir")
+  ? [resolve(flag("--run-dir"))]
+  : wanted
+    ? [resolve(join(DEMO_ROOT, wanted))]
+    : children.map((c) => resolve(join(DEMO_ROOT, c)));
+// The refusal below is about ONE directory, and with nothing shipped there is no directory to name — so
+// the container itself is what it looks at, which is what it always did when `demo/` was empty.
+const sampleDir = sampleDirs[0] ?? resolve(DEMO_ROOT);
+if (!sampleDirs.length || !isFrozen(sampleDir)) {
   // AN ABSENCE IS A FINDING, AND IT NAMES WHAT IT LOOKED AT. This exits 1 and always has; tracker issue
   // 2193 reported it exiting 0, which did not reproduce at v0.1.0 or at main's tip. An arm pins it.
   die(
@@ -128,10 +143,17 @@ if (!isFrozen(sampleDir)) {
 // PUBLISHING WRITES A RECEIPT INTO THE RUN DIRECTORY, and `demo/` is tracked — so a reader who only READ
 // the demo came back to a dirty checkout. `publishSource` is the one definition of that rule, shared with
 // the launcher, which seeds the pool from the same container on every `--demo` start.
-const publishFrom = publishSource(sampleDir, { repoRoot: REPO });
-
-const meta = JSON.parse(readFileSync(join(sampleDir, "meta.json"), "utf8"));
-if (!meta?.runId) die(`example: ${join(sampleDir, "meta.json")} names no runId — it is not a frozen example manifest.`);
+// EVERY ONE THAT WAS ASKED FOR IS READ BEFORE ANY IS PUBLISHED, so a manifest missing a runId is a
+// refusal about that demo by name rather than a partial pool nobody can account for.
+const samples = sampleDirs.map((dir) => {
+  const manifest = join(dir, "meta.json");
+  if (!isFrozen(dir)) die(`demo: ${dir} is not a frozen demo — it holds no meta.json and lane entry file.`);
+  const m = JSON.parse(readFileSync(manifest, "utf8"));
+  if (!m?.runId) die(`example: ${manifest} names no runId — it is not a frozen example manifest.`);
+  return { dir, meta: m, publishFrom: publishSource(dir, { repoRoot: REPO }), name: basename(dir) };
+});
+const publishFrom = samples[0].publishFrom;
+const meta = samples[0].meta;
 
 // ── 2. the pool guard ────────────────────────────────────────────────────────────────────────────────
 // Resolve through symlinks. A $HOME that resolves inside the archive is exactly the shape a `===` test
@@ -192,19 +214,38 @@ if (existsSync(poolRoot) && !statSync(poolRoot).isDirectory()) die(`demo: ${pool
 
 // ── 3. replay ────────────────────────────────────────────────────────────────────────────────────────
 console.log(`\n  ${BRAND.name} ${BRAND.product.toLowerCase()} — demo\n`);
-console.log(`  sample:  ${sampleDir}`);
+console.log(samples.length === 1
+  ? `  sample:  ${samples[0].dir}`
+  : `  samples: ${samples.length} — ${samples.map((x) => x.name).join(", ")}`);
 console.log(`  pool:    ${poolRoot}\n`);
 
 mkdirSync(poolRoot, { recursive: true });
 const { republishRun } = await import(join(REPO, "driver", "publish", "report-registry.mjs"));
-let published;
-try {
-  // poolUrl "" on purpose: the report's own link block is for a deployment that serves the pool at a
-  // public URL. This one is served from this process, at a port picked below.
-  published = await republishRun({ runId: meta.runId, meta, pool: poolRoot, poolUrl: "", runDir: join(publishFrom, "run") });
-} catch (e) {
-  die(`demo: replaying the sample failed: ${String(e?.message ?? e)}`);
+
+// ── ONE FAILURE MUST NOT COST THE OTHERS, AND MUST NOT BE A QUIET COUNT (tracker issue 277) ─────────
+//
+// Publishing stopped at the first error, which was right when there was one demo and is wrong now: a
+// reader whose knockout capture is unreadable should still get the other three, and should be TOLD which
+// one is missing. "3 published" with no other line is the shape this repository calls a silent count —
+// the number is true and the reader cannot tell it is short.
+//
+// The failures are collected and reported together at the end, and the process exits non-zero, because a
+// demo that came up missing a quarter of itself is not a success however good the three look.
+const results = [];
+const failures = [];
+for (const s0 of samples) {
+  try {
+    // poolUrl "" on purpose: the report's own link block is for a deployment that serves the pool at a
+    // public URL. This one is served from this process, at a port picked below.
+    results.push({ ...s0, published: await republishRun({ runId: s0.meta.runId, meta: s0.meta, pool: poolRoot, poolUrl: "", runDir: join(s0.publishFrom, "run") }) });
+  } catch (e) {
+    failures.push({ name: s0.name, why: String(e?.message ?? e) });
+  }
+}
+if (!results.length) {
+  die(`demo: no demo could be replayed.`, "", ...failures.map((f) => `  ${f.name}: ${f.why}`));
 }
+const published = results[0].published;
 
 // THE LABEL. The reader is about to look at a document that reads like advice about a real mark. It is
 // not, and the demo says so before the browser opens rather than in a footnote nobody reaches.
@@ -227,18 +268,34 @@ console.log("  re-rendered from its artifacts. It is an example, not advice.\n")
 //
 // The third branch is the point: a lane whose publisher reports no count says so. This line printed a
 // bare "?" to the knockout — a could-not-look wearing the costume of a number.
-const spine =
-  Number.isFinite(published.counts?.findings)
-    ? `${published.counts.findings} finding(s) recorded in the run's audit spine; the report shows
+// PER LANE, FOR EVERY DEMO — not for the first one with the rest reduced to a product name. The three
+// branches below are the whole point of this sentence: two lanes count different populations and a third
+// counts none, and printing one lane's number beside four reports would state the wrong population three
+// times.
+const spineOf = (pub) =>
+  Number.isFinite(pub.counts?.findings)
+    ? `${pub.counts.findings} finding(s) recorded in the run's audit spine; the report shows
              the ones it retains`
-    : Number.isFinite(published.receipts?.findings)
-      ? `${published.receipts.findings} finding(s) with citations traced to this run's own held
-             evidence, on ${published.receipts.citing}/${published.receipts.marks} mark(s)`
+    : Number.isFinite(pub.receipts?.findings)
+      ? `${pub.receipts.findings} finding(s) with citations traced to this run's own held
+             evidence, on ${pub.receipts.citing}/${pub.receipts.marks} mark(s)`
       : `this lane's publisher reported no finding count — the report itself is the record`;
-console.log(`  published: ${published.runId}  (${spine})`);
+for (const r of results) console.log(`  published: ${r.published.runId}\n             ${r.name} — ${spineOf(r.published)}`);
+if (results.length > 1) console.log(`\n  ${results.length} demo reports are published and listed — one per product.`);
+// LOUD, AND ON STDERR, AND NON-ZERO. Said after the successes so a reader sees what they DID get first,
+// and cannot mistake the run for a clean one.
+if (failures.length) {
+  console.error(`\n  ${failures.length} of ${samples.length} demo(s) could NOT be replayed:`);
+  for (const f of failures) console.error(`    ${f.name}: ${f.why}`);
+  console.error(`  The portal below lists the ${results.length} that published. This exits non-zero.`);
+  process.exitCode = 1;
+}
 
 if (has("--once")) {
-  console.log(`\n  report: ${join(poolRoot, meta.runId, "report.html")}`);
+  // EVERY REPORT THAT WAS PUBLISHED, not the first one. Naming one of four here is the same defect as
+  // publishing one of four: the reader is handed a path and has no way to learn the others exist.
+  console.log("");
+  for (const r of results) console.log(`  report: ${join(poolRoot, r.published.runId, "report.html")}`);
   //, criterion 5 — SAY WHAT WAS CREATED, ON EVERY PATH THAT CREATES SOMETHING.
   //
   // The portal path below prints this and `--once` did not, so the one invocation a reader is most
@@ -251,7 +308,11 @@ if (has("--once")) {
   // does — worse than silence, because it reads as an answer.
   const created = flag("--pool") ? poolRoot : demoBase;
   console.log(`  Removing it later is one directory:  rm -rf ${created}\n`);
-  process.exit(0);
+  // NOT A BARE ZERO. A demo that failed to replay one of its four sets `exitCode` above, and exiting 0
+  // here would discard it — printing the failure and then reporting success, which is the shape this
+  // change exists to remove. `--once` is also the invocation a script is most likely to use, so it is
+  // the one where a swallowed code does the most damage.
+  process.exit(process.exitCode ?? 0);
 }
 
 /**

package/bin/onboard.mjs

@@ -2311,7 +2311,12 @@ export async function runCheck() {
     // rather than beside the unit, because the unit running and the address being reachable are
     // different facts and the second is the one a client depends on.
     const { clientDoorReachability } = await import(join(REPO, "shared", "client-door.mjs"));
-    const published = process.env.CLEAROTRON_CLIENT_MCP_URL ?? null;
+    // FROM THE FILE THE UNITS LOAD, NOT THE SHELL THIS COMMAND WAS TYPED IN (the tracker issue 226
+    // family, met again here). On a hosted box the published address lives in the units' environment,
+    // and reading `process.env` reported "no client connector address is published — that is correct
+    // for a local install" about a deployment that publishes one. Every verdict below rests on this
+    // value, including the audience comparison, so a wrong reading here is not one wrong line.
+    const published = effectiveForService("CLEAROTRON_CLIENT_MCP_URL")?.v ?? null;
     // A SHORT, CHEAP ASK, and a failure to reach IS the finding rather than a failure to look — the
     // property under test is reachability itself. What would be dishonest is calling an address green
     // because nothing asked, which is why `probe` stays null when there is nothing to ask about.
@@ -2327,8 +2332,13 @@ export async function runCheck() {
         // returns null when the header is absent — a looked-and-none answer, not a did-not-look — and
         // the readers separate those, so a probe that omits the field reads as never-looked rather
         // than silently as "no challenge".
+        // THE REDIRECT TARGET TRAVELS WITH IT (tracker issue 241). This request is already made with
+        // `redirect: "manual"`, so the Location an unauthenticated caller is handed is right here —
+        // and it is where Cloudflare Access puts the audience. Reading it from THIS response rather
+        // than asking a second time keeps `doctor` to one request per address, and keeps both answers
+        // about the same moment.
         probe = { ok: res.status < 500, status: res.status, error: null,
-          challenge: res.headers.get("www-authenticate") };
+          challenge: res.headers.get("www-authenticate"), location: res.headers.get("location") };
       } catch (e) { probe = { ok: false, status: null, error: String(e?.cause?.code ?? e?.name ?? e?.message ?? e) }; }
     }
     const reach = clientDoorReachability({ url: published, probe });
@@ -2336,6 +2346,34 @@ export async function runCheck() {
     else if (reach.state === "fail") problem(reach.message);
     else info(reach.message);
 
+    // ── AND IS IT THE AUDIENCE THIS INSTALL CHECKS AGAINST? (tracker issue 241) ───────────────────
+    //
+    // The other half of the recreation trap, and the half with no symptom of its own. Deleting and
+    // recreating an Access application changes the audience; the existing warning fires on the
+    // CHALLENGE being wrong, so on a box where somebody recreated the application and then fixed the
+    // sign-in, everything above reads healthy and the stale audience stays invisible until a real
+    // request is rejected.
+    //
+    // No new credential and no provider API: the audience is in the redirect handed to a caller with
+    // no session at all, which is the request just made.
+    {
+      const { readAudience, audienceVerdict } = await import(join(REPO, "shared", "access-audience.mjs"));
+      const configuredAud = effectiveForService("CLEAROTRON_OIDC_AUDIENCE")?.v ?? "";
+      const read = readAudience(probe ?? { error: "the published address was never asked" });
+      // NOTHING IS CLAIMED ABOUT A BOX THAT USES NO EDGE. With no audience configured AND no Access
+      // challenge in front of the address, there is no question here — a local install is not a
+      // misconfigured hosted one, and saying so every time is how a reader learns to skim this.
+      if (configuredAud || read.kind !== "not-fronted") {
+        const v = audienceVerdict({ configured: configuredAud, read });
+        if (v.ok) ok(v.message);
+        // A COULD-NOT-LOOK IS SAID, NOT RAISED. The line above has already reported the address as
+        // unreachable; repeating it as a second failure teaches the reader that this section
+        // double-counts. It still states what was NOT established, which is the whole job.
+        else if (v.kind === "could-not-look") info(v.message);
+        else problem(v.message);
+      }
+    }
+
     // ── CAN AN ASSISTANT ACTUALLY SIGN IN? (tracker issue 149, opt-in) ────────────────────────────
     //
     // The check above reads the CHALLENGE FORM, which is the first of two provider settings that decide

package/bin/start.mjs

@@ -1057,6 +1057,12 @@ if (isMain) {
     // — `clearotron demo` hands over to this — so fixing the player alone left the defect where it was.
     const { publishSource } = await import("../driver/demo-container.mjs");
     const seed = await seedPool({ pool: paths.pool, examplesDir: publishSource(join(REPO, "demo"), { repoRoot: REPO }), republish: republishRun });
+    // WHAT WAS ALREADY THERE IS SAID TOO (tracker issue 277). This branch used to run only when the pool
+    // was empty; it now tops a stale pool up to the package's set, so "seeded 1" on an upgrade is a fact
+    // about what was MISSING and says nothing on its own about how many are now listed.
+    if (seed.already?.length) {
+      say(`  archive        ${seed.already.length} example report(s) already published here`);
+    }
     if (seed.seeded.length) {
       say(`  seeded         ${seed.seeded.length} example report(s) into ${paths.pool}`);
       // THE LABEL. is delivered: the report now carries the owner's own sample sentence on its
@@ -1070,6 +1076,7 @@ if (isMain) {
     }
     // Never a silent nothing. "The archive is empty" and "the archive is empty and nobody noticed why"
     // look identical in the browser, so both other outcomes are said out loud.
+    if (seed.skipped) say(`  archive        ${seed.skipped}`);
     for (const p of seed.problems) err(`  WARNING: sample seeding — ${p}`);
   } catch (e) {
     err(`  WARNING: the example report could not be seeded (${String(e?.message ?? e)}) — the archive will come up empty. Everything else works; \`npm run example\` shows a sample without touching this install.`);

package/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "1054d6ef379db87612033acbaa73bdb737b5128c",
-  "version": "0.2.0"
+  "commit": "df42f25966148479a5a6d34aba3f82c110a1ba43",
+  "version": "0.2.1"
 }

package/docs/RELEASES.md

@@ -8,7 +8,7 @@ nothing else.
 
 ```bash
 npm install -g clearotron          # stable — the tested one
-npm install -g clearotron@beta     # newest — every merge, minutes after it lands
+npm install -g clearotron@beta     # newest — cut when there is something worth testing
 ```
 
 ## What each channel promises
@@ -16,7 +16,7 @@ npm install -g clearotron@beta     # newest — every merge, minutes after it la
 | | `latest` (stable) | `beta` |
 |---|---|---|
 | **Version looks like** | `0.2.0` | `0.2.1-beta.4` |
-| **Cut when** | a beta has passed a full clearance run and a from-scratch install by somebody who has never seen the product, and the owner says go | every merge to `main`, automatically |
+| **Cut when** | a beta has passed a full clearance run and a from-scratch install by somebody who has never seen the product, and the owner says go | when a change lands that is worth testing, or while a stable is being prepared |
 | **Promises** | it installed and ran a real clearance end to end before it was published | it built, and the automated suite passed |
 | **Use it if** | you are running this for real work | you want a fix that landed today, or you are helping test |
 
@@ -35,8 +35,10 @@ suggest for yours.
 
 ## How often
 
-A stable is cut when a beta earns it, which we aim at roughly weekly. Betas arrive whenever something
-merges — several a day when a round is running, none for a day when nothing lands.
+A stable is cut when a beta earns it, which we aim at roughly weekly. **Betas are cut deliberately, days
+apart** — when a change lands that somebody should test, or while a stable is being prepared. They are not
+published on every merge, so `beta` is a version somebody chose to publish rather than whatever merged
+last. Some stables have several betas before them and some have none.
 
 Numbering follows the change, not the calendar: `0.2.x` for fixes, `0.3.0` when a feature lands, `1.0`
 when the hit-list redesign ships.

package/docs/architecture/04-configuration-reference.md

@@ -200,7 +200,7 @@ deployment may override (verify live values per deployment).
 | `CLEAROTRON_OAUTH_BRIDGE` | module-relative `providers/oauth-mcp-bridge/bridge.mjs` | Case-law MCP bridge script. (Portable since the module-relative default; set explicitly only for a bridge outside the repo tree.) |
 | `CLEAROTRON_REGISTER_CALL_LOG` | `~/trademark/telemetry/register-calls.jsonl`, or the existing file wherever it already is | Billing-grade provider-call ledger, shared by whichever ONE register provider is wired — not a vendor artifact. Every read site derives the default from`homedir()` at call time (2026-07-19: two sites had hardcoded a literal account home, splitting the ledger under any other service account — guarded by `test/deployment-hostnames.test.mjs`). |
 | `CLEAROTRON_REGISTER_RECORD_LOG` | **runtime-injected per run**: `<runDir>/_driver/register-record-bodies.jsonl` | Citation-fidelity log: the BODY of every fetched official record. ** moved it INTO the run** — created with the run, unioned into the run's`_records/`, archived and purged with it. There is no retention setting and no cleanup job, because it no longer grows on the box: held globally it reached 432 MB in 61 days on production and needed a rotation timer on every install. **Do not set this by hand** — a fixed value pins every run's bodies to one file and restores the problem. A box upgraded across still holds its old global file; nothing writes or reads it, the driver names it once per process on stderr, and archiving it is one`mv`. An empty log cannot read as verified: the run's successful `record_fetch` rows in the (still global) call ledger are compared against the assembled record set, and a gap is reported as a failure. |
-| `CORSEARCH_CALL_LOG` / `CORSEARCH_RECORD_LOG` | — | **Deprecated, honoured for one release.** The pre- names. Unset on every deployed box (all three ran the homedir default), so what actually protects an upgrade is the filename fallback: a`corsearch-calls.jsonl` / `corsearch-records.jsonl` already on disk keeps being read where it sits. Resolution order is in `providers/_shared/ledger-path.mjs`. |
+| `CORSEARCH_CALL_LOG` / `CORSEARCH_RECORD_LOG` | — | **Deprecated, honoured for one release.** These are the names these two variables carried before the rename. Unset on every deployed box (all three ran the homedir default), so what actually protects an upgrade is the filename fallback: a`corsearch-calls.jsonl` / `corsearch-records.jsonl` already on disk keeps being read where it sits. Resolution order is in `providers/_shared/ledger-path.mjs`. |
 | `CLEAROTRON_BAND_RUN_DIR` | set per dispatch | The run dir the band MCP server writes into, injected per stage — unset means the server has no run to write to and says so rather than guessing one. |
 | `CLEAROTRON_FEEDBACK_DIR` | `<poolRoot>/_feedback` | Where report feedback flags are stored. Beside the pool by default so a deployment that moves the pool moves the flags with it. |
 | `USPTO_LOCAL_DB` | **none — set it to use `uspto-local`** | The local USPTO index (`node:sqlite` + FTS5) that `bin/uspto-sync.mjs` builds and the free US register reads. Named in `.env.example`; this is the reference row. |

package/driver/CHANGELOG.md

@@ -1,5 +1,35 @@
 # prelim-driver
 
+## 0.2.1
+
+### Patch Changes
+
+- 3cc154a: Fixed: A report now keeps a mark the search confirmed, instead of dropping it because it was already noted on an internal working sheet. Where a mark is still missing, the run records it by name rather than closing the question.
+- 3cc154a: Fixed: Asking a what-if question about a delivered report now returns a memo, instead of failing to find the run it was asked about.
+- 0f7b44a: New: `clearotron demo` now publishes all four example reports — one per product — instead of only the first.
+- 2138a3c: For operators: The `beta` channel now gets a release when there is something worth testing, days apart, instead of one on every merge.
+- 8b5ab91: Fixed: `doctor` no longer reports a working Cloudflare Access door as unprotected. An API-style door and a failing origin are now told apart, each with its own message. Neither is reported as a pass.
+- 77cf56d: For operators: The configuration reference now explains the two deprecated search-log variables in full, instead of stopping mid-sentence.
+- 0dcd05a: Fixed: the settings catalogue now lists `CLEAROTRON_CHECKOUT_DIR`, the path every service file points at. The installer still fills it in for you. It is written down so that anyone whose service will not start can look it up.
+
+## 0.2.1-beta.2
+
+### Patch Changes
+
+- 8b5ab91: Fixed: `doctor` no longer reports a working Cloudflare Access door as unprotected. An API-style door and a failing origin are now told apart, each with its own message. Neither is reported as a pass.
+
+## 0.2.1-beta.1
+
+### Patch Changes
+
+- 0dcd05a: Fixed: the settings catalogue now lists `CLEAROTRON_CHECKOUT_DIR`, the path every service file points at. The installer still fills it in for you. It is written down so that anyone whose service will not start can look it up.
+
+## 0.2.1-beta.0
+
+### Patch Changes
+
+- 77cf56d: For operators: The configuration reference now explains the two deprecated search-log variables in full, instead of stopping mid-sentence.
+
 ## 0.2.0
 
 ### Minor Changes

package/driver/ask-ledger.mjs

@@ -574,6 +574,64 @@ export function parseAskClosureLines(text) {
   return out;
 }
 
+/**
+ * The marks the CLIENT was actually shown — `findings[].mark` from findings.json, normalized.
+ *
+ * Returns null when the file is absent or unparseable, and null is NOT an empty set: an absence is a
+ * could-not-look, and the caller below fails toward leaving the ask OPEN rather than closing it on a
+ * file it could not read.
+ *
+ * ✕ NEVER a substring search of the serialized document. `"DELFIN" in JSON.stringify(findings)` is true
+ * when the findings name DELFIN TECHNOLOGIES OY and nothing else — a membership test that matches every
+ * longer name inflates whatever it is counting and reads as a clean result. The field, or nothing.
+ * PURE.
+ */
+export function deliveredMarks(findingsJsonText) {
+  let doc;
+  try { doc = JSON.parse(String(findingsJsonText ?? "")); } catch { return null; }
+  const rows = Array.isArray(doc?.findings) ? doc.findings : null;
+  if (!rows) return null;
+  return new Set(rows.map((f) => normMark(f?.mark)).filter(Boolean));
+}
+
+const normMark = (s) => String(s ?? "").toLowerCase().replace(/[^a-z0-9]/g, "");
+
+/**
+ * Owner ruling 2026-09-07 (tracker issue 246), Option A, worded ABOUT THE MARK: a recall ask may close
+ * as immaterial only when the mark it went looking for is in the client's findings. Otherwise the mark
+ * is owed a finding and the ask stays open.
+ *
+ * The defect this answers: a recall probe found OSLER DELPHI, the closure stage pointed at
+ * `register-findings.md` — the run's own working sheet, where the mark genuinely IS reasoned — and the
+ * ask closed. The sheet is a citable file and the citation was true. It is simply not the document the
+ * client reads, and nothing checked that.
+ *
+ * ✕ SCOPED TO `ask:recall:` ASKS CARRYING A `mark_text`, deliberately, and this is the whole difference
+ * between the two readings of the ruling. `ask:recall-overflow:` rows carry a `term` — an owner name, a
+ * law firm, a probe never dispatched (Lewis Silkin LLP, NORDWEST Handel AG). Measured across three runs
+ * they are 28-29 per run and constant whether the run was healthy or not; reopening them would put
+ * names no lawyer asked for into the findings. A `mark_text` is the test because a mark is what a
+ * finding is about.
+ *
+ * Returns the owed row, or null when the ask is out of scope or the mark was delivered. PURE.
+ */
+export function recallMarkOwed(ask, delivered) {
+  if (!String(ask?.ask_id ?? "").startsWith("ask:recall:")) return null;
+  const st = ask?.ask?.structured ?? {};
+  const mark = String(st.mark_text ?? "").trim();
+  if (!mark) return null;                                       // an owner/term probe is not a mark ask
+  if (delivered instanceof Set && delivered.has(normMark(mark))) return null;
+  return {
+    ask_id: ask.ask_id,
+    mark,
+    owner: String(st.owner ?? "").trim() || null,
+    uri: String(st.uri ?? "").trim() || null,
+    // null delivered = findings.json unreadable. Recorded so a reader can tell "the client was not shown
+    // this mark" from "nobody could tell what the client was shown" — they need different repairs.
+    basis: delivered instanceof Set ? "absent-from-findings" : "findings-unreadable",
+  };
+}
+
 /**
  * The anti-confabulation guard, ask side (doubt-ledger applyClosure reused shape-for-shape): an
  * IMMATERIAL line ends its ask IFF the ask is still open AND the quote appears VERBATIM
@@ -586,7 +644,9 @@ export function applyAskClosure(asks, closureLines, fileTexts = {}, { ts = null
   const byId = new Map();
   for (const l of closureLines ?? []) if (l?.id && !byId.has(l.id)) byId.set(l.id, l);
   const unverified = [];
+  const carryIntoFindings = [];
   let immaterialByStage = 0;
+  const delivered = deliveredMarks(fileTexts?.["findings.json"]);
   const out = (asks ?? []).map((a) => {
     if (a?.ending) return a;                                    // the stage may never touch an ended ask
     const l = byId.get(a.ask_id);
@@ -595,13 +655,21 @@ export function applyAskClosure(asks, closureLines, fileTexts = {}, { ts = null
     const hay = squash(fileTexts?.[l.file]);
     const q = squash(l.quote);
     if (q && hay && hay.includes(q)) {
+      // THE CITATION IS VERIFIED AND THAT IS NO LONGER ENOUGH FOR A RECALL ASK ABOUT A MARK.
+      const owed = recallMarkOwed(a, delivered);
+      if (owed) {
+        carryIntoFindings.push(owed);
+        return { ...a, handoff: clip(`the recall probe found ${owed.mark} and the delivered findings do not name it — `
+          + `the closure cited ${l.file}, which is the run's own working sheet, not what the client was shown. `
+          + `This mark is owed a finding.`, 300) };
+      }
       immaterialByStage++;
       return { ...a, ending: mkEnding("judged-immaterial", "doubt-closure-stage", { evidence: `${l.file}: "${clip(l.quote)}"`, reasons: [l.reason], ts }) };
     }
     unverified.push({ ask_id: a.ask_id, file: l.file, quote: l.quote });
     return a;
   });
-  return { asks: out, immaterialByStage, unverified };
+  return { asks: out, immaterialByStage, unverified, carryIntoFindings };
 }
 
 /** Stamp the default handoff on every still-open ask (after closure) — an OPEN ask always names

package/driver/package.json

@@ -2,7 +2,7 @@
   "name": "prelim-driver",
   "private": true,
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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/pipeline.mjs

@@ -114,7 +114,7 @@ import { escalatedAxes } from "./skeptic-record.mjs";   // THE escalation parse
 import { PLACEMENT_CARRY_SCHEMA_VERSION, reconcilePlacementCarry, placementCarryEvent, mintPlacementCarryDoubts, entryUris } from "./placement-carry.mjs";
 import { FLOOR_DUTY_SCHEMA_VERSION, reconcileFloorDuty, floorDutyEvent, armFloorDuty, floorDutyArmed, floorDutyBlock, floorDutyBlocksSkip } from "./floor-duty.mjs";   // — the era stamp that turns disclosure into a delivery floor
 import { synthesisDutyForRun } from "./synthesis-record.mjs";   // — the duty checked against the DELIVERED document
-import { RECORD_CARRY_SCHEMA_VERSION, traceRecordCarry, parseStageOutcomes, recordCarryEvent, mintRecordCarryDoubts, bandRecordUri, placementIndex, findingUris , silentlyLostFindings } from "./record-carry.mjs";
+import { RECORD_CARRY_SCHEMA_VERSION, traceRecordCarry, parseStageOutcomes, recordCarryEvent, mintRecordCarryDoubts, bandRecordUri, placementIndex, findingUris , silentlyLostFindings, statedDivergenceFindings } from "./record-carry.mjs";
 import { reconcileSurfaceDuty, surfaceDutyNote } from "./surface-duty.mjs";   // item 3 — silence at the findings surface, read off the rows above
 import { DISCARD_LEDGER_NAME, seamRows, appendDiscardRows, foldDiscardLedger } from "./record-discard.mjs";
 import { readDeclinations } from "./declination-tool.mjs";   // — synthesis's own stated declines
@@ -4651,7 +4651,7 @@ export function buildFailurePacket({ runId, agent, job = {}, failedStage, shortR
   // was healthy and answering, re-triggering now hits the same cap, and "overloaded" points the reader
   // at an availability problem they cannot act on.
   //
-  // The owner pre-committed the wording watching indigo-falcon: a cap death is reported as a
+  // The owner pre-committed the wording watching a capped run: a cap death is reported as a
   // SUBSCRIPTION OUTCOME, NEVER AS AN ENGINE FINDING. So this names the cap, states how long the run
   // actually held out before giving up, and says plainly that nothing about the run or the mark
   // produced it.
@@ -13215,6 +13215,30 @@ async function pipelineInner(job, opts = {}) {
           note(`recall: ${silent.lost.length} position(s) the digest ended as FINDINGS reached no client `
             + `surface and no step said why — ${silent.lost.map((l) => `${l.mark ?? l.uri} (${l.reason})`).join("; ")}`);
         }
+        // ── AND THE STATED CASE, WHICH IS THE ONE THAT REACHED A CLIENT (tracker issue 248) ────────
+        //
+        // Same inputs, same seam, same best-effort contract — a second call rather than a widened first
+        // one, because the sibling's population boundary is deliberate and correct. It covers a
+        // finding-ending followed by SILENCE; this covers one followed by a SENTENCE.
+        //
+        // On R2 `russet-kestrel` the sibling logged `checked:5 matched:5 lost:0` — correctly — on a
+        // delivery missing two marks from the lawyer's final list, one rated HIGH. They were dropped with
+        // a reason, so they were outside its population by design. A drop with a reason nobody verifies
+        // is not accounted for; it is unexamined with a paper trail, and that delivery carried 66 of them.
+        const stated = statedDivergenceFindings({
+          reconciliation: safeReadJson(P.recallReconciliation),
+          carryRows: safeReadJson(P.recordCarry)?.rows ?? null,
+          digestFindingUris: recordedFindingUris(P.runDir),
+        });
+        runLog(P.runDir, { event: "stated-divergence-findings", computable: stated.computable,
+          reason: stated.reason, population_empty: stated.population_empty === true,
+          checked: stated.checked, matched: stated.matched, diverged: stated.diverged.length,
+          marks: stated.diverged.map((d) => d.mark).filter(Boolean).slice(0, 10) });
+        if (stated.diverged.length) {
+          note(`recall: ${stated.diverged.length} position(s) the digest ended as FINDINGS are absent from `
+            + "the findings and were dropped with a STATED reason pointing at another artifact — "
+            + stated.diverged.map((d) => `${d.mark ?? d.uri} (${d.reason}${d.cites_artifact ? ` → ${d.cites_artifact.join(", ")}` : ""})`).join("; "));
+        }
       } catch (e) { /* never mask a delivery */ }
       // — the common-law path, and the jx zh slice on the same tracer. `consumed` used to read
       // CLEAROTRON_JX_CONSUME, which decided whether a zh candidate could reach a finding at all: with it
@@ -13486,6 +13510,21 @@ async function pipelineInner(job, opts = {}) {
                 const askApplied = applyAskClosure(runAsks, acc.ask, fileTexts, { ts: askTs });
                 runAsks = askApplied.asks;
                 for (const u of askApplied.unverified) runLog(run.runDir, { event: "ask-closure-unverified", ...u });
+                // Option A (tracker issue 246): a recall ask whose mark is not in the delivered findings
+                // did NOT close. Each one is a mark the run found and the client was not shown, so it is
+                // recorded by name rather than left to be inferred from an ask that merely stayed open.
+                // ✕ NOT written into findings.json here. See the sidecar's own note: a row appended after
+                // the drafting stage would carry no band and no reasoning.
+                for (const c of askApplied.carryIntoFindings ?? [])
+                  runLog(run.runDir, { event: "ask-closure-mark-owed", ...c });
+                if (askApplied.carryIntoFindings?.length)
+                  writeFileSync(driverDir(run.runDir, "marks-owed-a-finding.json"),
+                    JSON.stringify({
+                      _provenance: "recall asks that could not close because the mark they found is absent from findings.json — owner ruling 2026-09-07, tracker issue 246 Option A, worded about the MARK",
+                      _notWritten: "these are NOT appended to findings.json: a finding carries a band, a net line and a legal position, and a row minted here would carry none of them. The repair belongs where the findings are authored.",
+                      count: askApplied.carryIntoFindings.length,
+                      marks: askApplied.carryIntoFindings,
+                    }, null, 2) + "\n");
               }
             } else {
               note(`doubt-closure failed (non-fatal — the open doubts/asks ship OPEN, as without the stage): ${dc.fail}`);

package/driver/predelivery-lint.mjs

@@ -701,7 +701,7 @@ export function competitorClaimChecks({ text, ownerScreen, recordsByUri, markVoc
 // ── COVERAGE CLAIMS IN PROSE vs WHAT THE RUN ACTUALLY SEARCHED (tracker issue 134) ──────────────────
 //
 // THE DEFECT. `coverage_line:` is code-stamped from scope-facts.json; the narrative is model-written
-// prose. Nothing bound them to one searched-territory set. On `amber-summit` the masthead read
+// prose. Nothing bound them to one searched-territory set. On one recorded run the masthead read
 // `registers: JP, WO` while the narrative said "Register searches covered Japan and Korea" — one of
 // them was wrong and nothing detected it until a human compared the two surfaces by eye. They agree
 // on today's runs because a prompt fix stopped the input contradicting itself, which is evidence the