clearotron 0.2.0 → 0.3.0-beta.0

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

@@ -41,10 +41,11 @@ run is [mcp-server/CONNECT.md](mcp-server/CONNECT.md), and why something is the
 - **Node.js >= 22**, and npm. A hard floor: `package.json` declares it, `.nvmrc` pins it, and the free
   US register runs on `node:sqlite`, which ships with FTS5 from Node 22. Node 20 installs and then fails
   at the first US search. `nvm use` picks the pin up.
-- **macOS, Linux, or Windows via WSL2.** Native Windows is not supported: the engine resolves the
-  reasoning CLI the POSIX way, so a native-Windows run refuses at preflight even with the CLI on `PATH`.
-  On Windows, `wsl --install`, then install Node 22 **inside** the Linux distribution and work through
-  this page from there. `npx clearotron demo` is the exception and runs anywhere Node does. A *hosted*
+- **macOS, Linux, or native Windows for the demo; WSL2 with Node 22 for a clearance.** `npx clearotron
+  demo` runs anywhere Node does, native Windows included. A real clearance does not: the engine resolves
+  the reasoning CLI the POSIX way, so a native-Windows clearance refuses at preflight even with the CLI
+  on `PATH`. On Windows, `wsl --install`, then install Node 22 **inside** the Linux distribution and work
+  through this page from there. A *hosted*
   deployment needs Linux for one further thing, the systemd outbox trigger —
   [driver/systemd/README.md](driver/systemd/README.md).
 - **A reasoning CLI on your `PATH`, signed in.** This is the prerequisite people miss. Every stage runs
@@ -115,12 +116,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,8 +40,8 @@ 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 { fileURLToPath } from "node:url";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { spawn } from "node:child_process";
 import { BRAND } from "../shared/brand.mjs";   // — the installer's own name, from the tenant seam
 import { envFrom } from "../shared/env-aliases.mjs";   // — resolves EITHER spelling; names the retired one because that is the live-writable half
@@ -68,7 +68,11 @@ if (has("--help") || has("-h")) {
   const shipped = demoChildren(join(REPO, "demo"));
   if (shipped.length) {
     console.log(`\n  --product takes one of:`);
-    for (const id of shipped) console.log(`    ${id}${id === shipped[0] ? "   (the default, when --product is not given)" : ""}`);
+    // NO "DEFAULT" MARKER (tracker issue 277). This printed "(the default, when --product is not given)"
+    // beside the first id, and kept printing it after the default became ALL of them — so `--help` taught
+    // a reader the exact belief the change removed, in the command it was reported against.
+    for (const id of shipped) console.log(`    ${id}`);
+    console.log(`\n  With no --product, every one of them is published.`);
     console.log("");
   } else {
     // An absence is a finding: a tree with no demo says so rather than printing an empty list.
@@ -96,15 +100,30 @@ const DEMO_ROOT = join(REPO, "demo");
 // disagreed. That file records what a knockout demo carries instead of a report.md, and why this line
 // once let `demo/knockout-search` ship and stay unopenable..
 
-// --run-dir takes a directory outright. --product names a child. Neither given: the first child, and the
-// name is PRINTED below rather than assumed, because "the demo" is about to mean one of several.
+// --run-dir takes a directory outright. --product names a child. Neither given: EVERY child, and the
+// names are PRINTED below rather than assumed, because "the demo" means 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 +147,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 +218,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)}`);
+const { republishRun } = await import(pathToFileURL(join(REPO, "driver", "publish", "report-registry.mjs")).href);
+
+// ── 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 +272,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 +312,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

@@ -693,8 +693,8 @@ export async function preflightCandidate(candidate) {
 /** Ask EUIPO for a token. This is the check that makes "refuses to persist a bad secret" true. */
 export async function validateEuipo({ clientId, clientSecret, environment }) {
   try {
-    const { resolveConfig } = await import(join(REPO, "providers", "euipo", "src", "core.js"));
-    const { getAccessToken } = await import(join(REPO, "providers", "euipo", "src", "euipo-client.js"));
+    const { resolveConfig } = await import(pathToFileURL(join(REPO, "providers", "euipo", "src", "core.js")).href);
+    const { getAccessToken } = await import(pathToFileURL(join(REPO, "providers", "euipo", "src", "euipo-client.js")).href);
     await getAccessToken(resolveConfig({ clientId, clientSecret, environment }), { force: true });
     return { ok: true };
   } catch (e) {
@@ -705,7 +705,7 @@ export async function validateEuipo({ clientId, clientSecret, environment }) {
 /** One minimal Perplexity call. Costs a request, so it is never made without being asked for. */
 export async function validatePerplexity(apiKey) {
   try {
-    const { buildRequestBody, callAgentAPI } = await import(join(REPO, "providers", "perplexity", "src", "core.js"));
+    const { buildRequestBody, callAgentAPI } = await import(pathToFileURL(join(REPO, "providers", "perplexity", "src", "core.js")).href);
     await callAgentAPI(apiKey, buildRequestBody({ task: "Reply with the single word: ok.", preset: "fast-search" }), { retries: 0 });
     return { ok: true };
   } catch (e) {
@@ -1053,7 +1053,7 @@ export async function runCheck() {
   // deliberate — a second reader would drift from this one exactly as the composer and the checker did
   // in F41, and the drift is invisible because both sides keep passing their own arms.
   const unitDir = join(homedir(), ".config", "systemd", "user");
-  const { BACKGROUND_UNITS } = await import(join(REPO, "bin", "start.mjs"));
+  const { BACKGROUND_UNITS } = await import(pathToFileURL(join(REPO, "bin", "start.mjs")).href);
   const hosted = BACKGROUND_UNITS.some((u) => existsSync(join(unitDir, u)));
   const unitEnv = hosted
     ? unitEnvironment({
@@ -1908,8 +1908,8 @@ export async function runCheck() {
     say("\n  Register lane — proven, not inferred");
     try {
       const [{ activeProvider }, { makeLaneProbe, probeSpend, DEFAULT_CONTROLS, loadProviderCapabilities }] = await Promise.all([
-        import(join(REPO, "driver", "driver.config.mjs")),
-        import(join(REPO, "providers", "_shared", "lane-probe.mjs")),
+        import(pathToFileURL(join(REPO, "driver", "driver.config.mjs")).href),
+        import(pathToFileURL(join(REPO, "providers", "_shared", "lane-probe.mjs")).href),
       ]);
       const adapter = activeProvider();
       // NOT `adapter.capabilities` — that is null on every adapter, and reading it announced a LOCAL
@@ -1995,7 +1995,7 @@ export async function runCheck() {
   // green over that state would bless the owner's fresh-install 500.
   say("\n  Profile store");
   try {
-    const { loadProfiles } = await import(join(REPO, "driver", "profiles.mjs"));
+    const { loadProfiles } = await import(pathToFileURL(join(REPO, "driver", "profiles.mjs")).href);
     const resolved = loadProfiles({ force: true });
     const named = [...resolved.keys()];
     ok(`resolves: ${named.length} profile(s) (${named.slice(0, 6).join(", ")}${named.length > 6 ? ", …" : ""}) — the universal fallback is present`);
@@ -2024,7 +2024,7 @@ export async function runCheck() {
   // an absence of evidence is not evidence of absence, and this whole check exists because something
   // invisible was being read as fine.
   {
-    const { retiredSpellingsIn, retiredSpellingLine } = await import(join(REPO, "shared", "env-aliases.mjs"));
+    const { retiredSpellingsIn, retiredSpellingLine } = await import(pathToFileURL(join(REPO, "shared", "env-aliases.mjs")).href);
     const sources = [
       { label: "your environment file", env: fileEnv, known: true },
       { label: "this shell's environment", env: process.env, known: true },
@@ -2077,7 +2077,7 @@ export async function runCheck() {
 
   say("\n  Submit lane");
   try {
-    const { triggerLaneVerdict, HOSTED, SUPERVISED } = await import(join(REPO, "shared", "trigger-lane.mjs"));
+    const { triggerLaneVerdict, HOSTED, SUPERVISED } = await import(pathToFileURL(join(REPO, "shared", "trigger-lane.mjs")).href);
     // POSTURE FROM THE BOX, NOT FROM A FLAG. Units installed means the units serve, and the units read
     // %h/.env — so an absent value there is the incident. No units means `start` supervises and derives
     // the value at runtime, where reading this process's environment says nothing either way.
@@ -2117,7 +2117,7 @@ export async function runCheck() {
     // Stop control's availability on — one reader, two surfaces.
     let verbs = null;
     try {
-      const { opsTokenPosture } = await import(join(REPO, "driver", "portal-service.mjs"));
+      const { opsTokenPosture } = await import(pathToFileURL(join(REPO, "driver", "portal-service.mjs")).href);
       verbs = opsTokenPosture(opsToken).verbs;
     } catch { /* unreadable posture leaves verbs null, which reads as full ops — see the verdict */ }
     let probe = null;
@@ -2158,7 +2158,7 @@ export async function runCheck() {
   // measured on a default install, a revoked key completed a full handshake with nothing logged. Nothing
   // surfaced that state anywhere, which is why it survived to be found by hand.
   {
-    const { defaultDenylistPath } = await import(join(REPO, "shared", "client-door.mjs"));
+    const { defaultDenylistPath } = await import(pathToFileURL(join(REPO, "shared", "client-door.mjs")).href);
     const dl = effective("TRADEMARK_MCP_TOKEN_DENYLIST")?.v || defaultDenylistPath(homedir());
     try {
       const n = readFileSync(dl, "utf8").split("\n").map((l) => l.trim()).filter((l) => l && !l.startsWith("#")).length;
@@ -2172,8 +2172,8 @@ export async function runCheck() {
     }
   }
   try {
-    const { clientDoorState: doorState, describeDoorState, connectKeyReport, CLIENT_DOOR_UNIT: doorUnit } = await import(join(REPO, "shared", "client-door.mjs"));
-    const { loadGrants: readGrantsFile, isRevoked: revokedCheck } = await import(join(REPO, "shared", "scope.mjs"));
+    const { clientDoorState: doorState, describeDoorState, connectKeyReport, CLIENT_DOOR_UNIT: doorUnit } = await import(pathToFileURL(join(REPO, "shared", "client-door.mjs")).href);
+    const { loadGrants: readGrantsFile, isRevoked: revokedCheck } = await import(pathToFileURL(join(REPO, "shared", "scope.mjs")).href);
     // ── CONFIGURED IS NOT RUNNING, AND THIS IS THE SURFACE IT WAS MEASURED ON ──
     //
     // `describeDoorState` was written for exactly this block and then never called from it: the split
@@ -2249,7 +2249,7 @@ export async function runCheck() {
     // names the old one. A door that is up, listening, and refuses everything is the worst of the three
     // states to debug, and nothing surfaced the mismatch.
     {
-      const { clientDoorPort: portOf, allowedHosts: hostsFor } = await import(join(REPO, "shared", "client-door.mjs"));
+      const { clientDoorPort: portOf, allowedHosts: hostsFor } = await import(pathToFileURL(join(REPO, "shared", "client-door.mjs")).href);
       const declared = String(effective("CLIENT_MCP_ALLOWED_HOSTS")?.v ?? "").trim();
       if (declared) {
         const port = portOf(doorEnv);
@@ -2272,7 +2272,7 @@ export async function runCheck() {
     // null — a probe that could not be made is not a door that is absent.
     let doorListening = null;
     try {
-      const { clientDoorPort: portOf } = await import(join(REPO, "shared", "client-door.mjs"));
+      const { clientDoorPort: portOf } = await import(pathToFileURL(join(REPO, "shared", "client-door.mjs")).href);
       const { createConnection } = await import("node:net");
       doorListening = await new Promise((resolve) => {
         const sock = createConnection({ host: "127.0.0.1", port: portOf(doorEnv), timeout: 700 });
@@ -2310,8 +2310,13 @@ export async function runCheck() {
     // THE PUBLISHED ADDRESS, AND WHETHER IT ANSWERS (, acceptance 2). Reported here
     // 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;
+    const { clientDoorReachability } = await import(pathToFileURL(join(REPO, "shared", "client-door.mjs")).href);
+    // 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(pathToFileURL(join(REPO, "shared", "access-audience.mjs")).href);
+      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
@@ -2345,7 +2383,7 @@ export async function runCheck() {
     // announces the side effect first, and its control runs before any vendor.
     if (PROBE_CONNECTOR && String(published ?? "").trim()) {
       const { registrationEndpointFrom, probeRegistration, describeRegistration } =
-        await import(join(REPO, "shared", "connector-signin-probe.mjs"));
+        await import(pathToFileURL(join(REPO, "shared", "connector-signin-probe.mjs")).href);
       say("");
       say("  --probe-connector: asking this door's sign-in whether each assistant vendor could register.");
       say("  Each attempt that SUCCEEDS creates a throwaway OAuth client on your account, which you may");
@@ -3096,7 +3134,7 @@ try {
   prose("No default — it is your hostname. Skip it and this stays a local install: everything works",
         "here, and the Use-your-AI page says so rather than handing out an address that fails.");
   prose("The usual shape, and why: mcp-server/CONNECT.md.");
-  const { clientDoorReachability } = await import(join(REPO, "shared", "client-door.mjs"));
+  const { clientDoorReachability } = await import(pathToFileURL(join(REPO, "shared", "client-door.mjs")).href);
   for (;;) {
     const clientUrl = await askValue("Public connector address:", {
       skippable: true,

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/bin/stop.mjs

@@ -19,12 +19,16 @@ import { existsSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { execFileSync } from "node:child_process";
+import { systemdSaid, looksLikeBusFailure, busRemedy, CAPTURE_STDERR } from "../shared/systemd-failure.mjs";   // tracker issue 270 — a stop that could not look must not report that it stopped
 import { BACKGROUND_UNITS } from "./start.mjs";
 import { CLIENT_DOOR_UNIT } from "../shared/client-door.mjs";
 import { invoke } from "../shared/invocation.mjs";
 
 const UNIT_DIR = join(homedir(), ".config", "systemd", "user");
 const say = (s = "") => console.log(s);
+// ON STDERR, because a refusal that scrolls past in the same stream as the success lines is a
+// refusal a script cannot act on and a reader skims (tracker issue 270).
+const err = (s = "") => console.error(s);
 
 const argv = process.argv.slice(2);
 if (argv.includes("--help") || argv.includes("-h")) {
@@ -39,20 +43,76 @@ if (argv.includes("--help") || argv.includes("-h")) {
 }
 
 let found = 0;
+const failures = [];
 for (const u of BACKGROUND_UNITS) {
   if (u === CLIENT_DOOR_UNIT) continue;   // structurally unreachable (the pin's census forbids it); belt anyway
   const file = join(UNIT_DIR, u);
   if (!existsSync(file)) continue;
   found++;
-  try { execFileSync("systemctl", ["--user", "disable", "--now", u], { stdio: "ignore" }); } catch { /* already down */ }
+  // ── THE STOP IS VERIFIED, AND THE FILE GOES ONLY IF IT WORKED (tracker issue 270) ────────────────
+  //
+  // This was `catch { /* already down */ }` — a COMMENT standing in for a check. The comment guessed why
+  // the call failed, the next line deleted the unit file regardless, and the line after that announced
+  // "stopped and removed". Measured on a test box: `disable --now` failed for want of a session bus, all
+  // four services stayed up on unchanged pids holding all three ports, three unit files were deleted, and
+  // the command exited 0 saying the box ran nothing. The services were then unmanageable — running, with
+  // no unit file to stop them by — which is strictly worse than leaving both alone.
+  //
+  // `is-active` is what decides, not the exit code of the disable, because the exit code is what lied.
+  let stopped = false;
+  let why = null;
+  try {
+    execFileSync("systemctl", ["--user", "disable", "--now", u], CAPTURE_STDERR);
+  } catch (e) {
+    why = systemdSaid(e);
+  }
+  // ASKED AFTER, WHATEVER THE DISABLE SAID. A disable that reported failure may still have stopped it,
+  // and one that reported success may not have — only the state answers.
+  try {
+    const state = execFileSync("systemctl", ["--user", "is-active", u], { ...CAPTURE_STDERR, stdio: ["ignore", "pipe", "pipe"] });
+    stopped = String(state).trim() !== "active";
+  } catch (e) {
+    // `is-active` exits non-zero for an inactive unit, which is the answer we want — but it exits
+    // non-zero for "cannot reach systemd" too, and those must not read the same. The stdout is the
+    // discriminator: an unreachable systemd prints nothing there.
+    const said = String(e?.stdout ?? "").trim();
+    if (said && said !== "active") stopped = true;
+    else why = why ?? systemdSaid(e);
+  }
+
+  if (!stopped) {
+    // NOT DELETED. A running service with no unit file cannot be stopped by any ordinary means.
+    failures.push({ unit: u, why: why ?? "systemd still reports it active" });
+    say(`  COULD NOT STOP ${u} — its unit file is left in place, so it can still be stopped`);
+    continue;
+  }
   try { rmSync(file, { force: true }); } catch { /* already gone */ }
   say(`  stopped and removed ${u}`);
 }
-try { execFileSync("systemctl", ["--user", "daemon-reload"], { stdio: "ignore" }); } catch { /* no user bus */ }
+// THE COMMENT HERE ALREADY NAMED THE CAUSE AND SHRUGGED AT IT. If there is no user bus, the disables
+// above did not happen either — which is the whole of tracker issue 270 — so this is where that is said.
+try {
+  execFileSync("systemctl", ["--user", "daemon-reload"], CAPTURE_STDERR);
+} catch (e) {
+  const said = systemdSaid(e);
+  err(`  could not ask systemd to reload its units — ${said}`);
+  if (looksLikeBusFailure(said)) err(`\n${busRemedy()}\n`);
+}
 
 if (!found) {
   say("  Nothing was running in the background — no pinned unit is installed on this box.");
   say("  Nothing to do, and nothing was changed.");
+} else if (failures.length) {
+  // THE SENTENCE THAT WAS WRONG. "The background product is stopped and the box runs nothing again" was
+  // printed unconditionally — including on the run where four services stayed up. A reader who is told
+  // that has no reason to look, which is what made the state unmanageable rather than merely wrong.
+  err("");
+  err(`  ${failures.length} of ${found} service(s) could NOT be stopped, and their unit files are left in place:`);
+  for (const f of failures) err(`    ${f.unit}: ${f.why}`);
+  if (failures.some((f) => looksLikeBusFailure(f.why))) err(`\n${busRemedy()}\n`);
+  err("  Nothing was removed for these, so they can still be stopped once systemd can be reached.");
+  err("  The box is NOT idle. This exits non-zero.");
+  process.exitCode = 1;
 } else {
   say("");
   say("  The background product is stopped and the box runs nothing again — plain `clearotron start`");
@@ -60,4 +120,6 @@ if (!found) {
   const door = existsSync(join(UNIT_DIR, CLIENT_DOOR_UNIT));
   if (door) say(`  Your assistant connection is untouched and still up; \`${invoke("disconnect")}\` is what closes it and revokes its key.`);
 }
-process.exit(0);
+// NOT A BARE ZERO. A stop that could not stop something sets `exitCode` above, and exiting 0 here would
+// discard it — printing the refusal and then reporting success, which is the shape this change removes.
+process.exit(process.exitCode ?? 0);

package/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "1054d6ef379db87612033acbaa73bdb737b5128c",
-  "version": "0.2.0"
+  "commit": "061581a9789002849189ef4e55aaa74289409d13",
+  "version": "0.3.0-beta.0"
 }