clearotron 0.3.0-beta.9 → 0.3.1-beta.0

package/INSTALL.md

@@ -295,6 +295,71 @@ keeps working throughout.
 provider, so it is safe to run on any machine that has the repository. "Safe anywhere" is about spend,
 not about where it will run — on a packaged tree it refuses, as above.
 
+## 2a. Removing it
+
+An install is not one directory, so removing it is not one command. Everything it writes is listed here.
+Read the list before you delete anything: one of these directories holds your reports.
+
+**Stop it first.** If the product is running in a terminal, Ctrl-C in that terminal. If you installed the
+background services, `clearotron stop` stops them and removes their unit files. `clearotron status` says
+which of the two you have.
+
+**The program.** Installed globally, `npm rm -g clearotron` removes it. Installed by `clearotron install`
+(which is also what a demo run from `npx` leaves behind), it lives in two places under `~/.local`:
+
+```
+~/.local/lib/node_modules/clearotron
+~/.local/bin/clearotron
+```
+
+**The settings, and the keys.** `~/.config/clearotron/.env` holds this install's signing secrets, so
+deleting it invalidates every key it ever issued. Beside it: `~/.config/clearotron/token-denylist`, the
+list of keys you revoked, and `~/.config/clearotron/running`, which records a product running in a
+terminal and is rewritten on every start.
+
+**Your work.** The install keeps it all under one directory, `~/trademark` by default — wherever
+`CLEAROTRON_REPORTS_DIR`'s parent points if you moved it:
+
+```
+~/trademark/pool                              THE REPORTS. Every clearance this install delivered.
+~/trademark/workspace                         the working files of each run, including unfinished ones
+~/trademark/queue                             work ordered and not yet run
+~/trademark/outbox                            what the product prepared to send
+~/trademark/locks                             which runs are in flight
+~/trademark/config                            your companies, their projects and your saved searches
+~/trademark/config/recipes                    the saved searches themselves
+~/trademark/config/profiles                   the company profiles
+~/trademark/grants.json                       who may use this install
+~/trademark/portal-audit.log                  what the portal was asked to do
+~/trademark/portal-local-credential.json      the sign-in this install minted for you
+```
+
+**Keep the pool if you want the reports.** They are finished documents and nothing else reads them: move
+`~/trademark/pool` somewhere of your own and delete the rest. Deleting the pool deletes the clearances.
+
+**The demo, if you ran one.** `~/trademark-demo` holds the demo's own copy of everything above, including
+its own copy of the program under `~/trademark-demo/program`. It is one directory to remove and it shares
+nothing with an install.
+
+**The background services, if you installed them.** `clearotron stop` removes the four unit files; if you
+would rather see them, they are in `~/.config/systemd/user`:
+
+```
+clearotron-portal.service
+clearotron-mcp-face.service
+clearotron-worker.service
+clearotron-client-mcp.service
+```
+
+**And `~/.env`, which only a background install writes.** A service inherits nothing from the terminal
+that installed it, so `clearotron start --background` writes everything those services need into `~/.env`,
+mode 600 — your register credential, your research key and the engine's settings among it. It is not the
+same file as `~/.config/clearotron/.env`, which configures the product when you run it yourself. Delete
+both, or you leave a file of credentials in your home for services that no longer exist.
+
+Nothing else on the machine is ours: no system-wide files, no services outside your own user, and nothing
+in `/etc`, `/usr` or `/var`.
+
 ## 3. Configuration (environment)
 
 Runtime configuration is by environment variable, and there are two ways to supply them.

package/README.md

@@ -59,6 +59,9 @@ npx clearotron@beta install
 What each channel promises, and when a stable is cut: [docs/RELEASES.md](docs/RELEASES.md). If you are not
 sure, the first command is the one you want.
 
+Removing it later: **[INSTALL.md §2a](INSTALL.md#2a-removing-it)** lists every path an install writes, and
+says which one holds your reports so you can keep them deliberately.
+
 ## Quick start
 
 With it installed, check what it found before it does anything. `doctor` only reads — it writes nothing,

package/bin/example.mjs

@@ -46,7 +46,7 @@ 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
-import { isFrozen, demoChildren, publishSource } from "../driver/demo-container.mjs";   // — one definition of what a frozen demo is, for the player AND the gate
+import { isFrozen, demoChildren, demoInventory, prepareSample } from "../driver/demo-container.mjs";   // — one definition of what a frozen demo is, for the player AND the gate
 import { ensureDemoProgram, demoProgramEnv } from "../shared/permanent-install.mjs";
 
 const REPO = join(dirname(fileURLToPath(import.meta.url)), "..");
@@ -109,7 +109,10 @@ const DEMO_ROOT = join(REPO, "demo");
 // --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);
+// EVERY SAMPLE THE CONTAINER HOLDS, the unusable ones named (driver/demo-container.mjs says why).
+const inventory = demoInventory(DEMO_ROOT);
+const children = inventory.children;
+const ALL = !flag("--run-dir") && !wanted;
 
 // ── ALL OF THEM, UNLESS THE CALLER NARROWED IT ──────────────────────────────────────────────────────
 //
@@ -129,6 +132,9 @@ const sampleDirs = flag("--run-dir")
 // 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);
+// EVERY SAMPLE UNUSABLE is the absence below with its reasons, not "no frozen demo" over a full container.
+if (ALL && !sampleDirs.length && inventory.unusable.length)
+  die("demo: no demo could be replayed.", "", ...inventory.unusable.map((u) => `  ${u.name}: ${u.why}`));
 if (!sampleDirs.length || !isFrozen(sampleDir)) {
   // AN ABSENCE IS A FINDING, AND IT NAMES WHAT IT LOOKED AT. This exits 1 and always has; a report of
   // it exiting 0 did not reproduce at v0.1.0 or at main's tip. An arm pins it.
@@ -153,15 +159,22 @@ if (!sampleDirs.length || !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.
-// 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) };
-});
+// EVERY ONE THAT WAS ASKED FOR IS READ BEFORE ANY IS PUBLISHED. One named by --product or --run-dir that
+// cannot be used is a refusal about it by name. With every sample asked for, ONE THAT CANNOT BE USED MUST
+// NOT COST THE OTHERS: it joins the failures the replay below collects, named with its reason, and the
+// rest are published. An unreadable file inside one sample used to throw out of the copy here and take
+// every demo down with a stack trace (measured on a published beta, 2026-09-11).
+const failures = ALL ? inventory.unusable.map((u) => ({ name: u.name, why: u.why })) : [];
+const samples = [];
+for (const dir of sampleDirs) {
+  const r = prepareSample(dir, { repoRoot: REPO });
+  if (r.sample) samples.push(r.sample);
+  else if (ALL) failures.push({ name: r.name, why: r.why });
+  else die(`demo: ${dir} cannot be replayed — ${r.why}.`);
+}
+if (!samples.length) die("demo: no demo could be replayed.", "", ...failures.map((f) => `  ${f.name}: ${f.why}`));
+// How many samples this tree ships: the ones replayed and the ones named as failures, never the readable ones.
+const shipped = samples.length + failures.length;
 const publishFrom = samples[0].publishFrom;
 const meta = samples[0].meta;
 
@@ -226,7 +239,7 @@ if (existsSync(poolRoot) && !statSync(poolRoot).isDirectory()) die(`demo: ${pool
 console.log(`\n  ${BRAND.name} ${BRAND.product.toLowerCase()} — demo\n`);
 console.log(samples.length === 1
   ? `  sample:  ${samples[0].dir}`
-  : `  samples: ${samples.length} — ${samples.map((x) => x.name).join(", ")}`);
+  : `  samples: ${samples.length}${failures.length ? ` of ${shipped}` : ""} — ${samples.map((x) => x.name).join(", ")}`);
 console.log(`  reports folder:  ${poolRoot}\n`);
 
 mkdirSync(poolRoot, { recursive: true });
@@ -242,7 +255,6 @@ const { republishRun } = await import(pathToFileURL(join(REPO, "driver", "publis
 // 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
@@ -291,11 +303,12 @@ const spineOf = (pub) =>
              evidence, on ${pub.receipts.citing}/${pub.receipts.marks} mark(s)`
       : `this lane's publisher reported no finding count — the report itself is the record`;
 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.`);
+// "ONE PER PRODUCT" ONLY WHEN IT IS TRUE: with a sample missing, the count below says how many of how many.
+if (results.length > 1 && !failures.length) 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:`);
+  console.error(`\n  ${failures.length} of ${shipped} 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;

package/bin/onboard.mjs

@@ -116,7 +116,7 @@ import { isEntrypoint } from "../shared/is-entrypoint.mjs";   // — one entry-p
 // one synopsis reader for every verb that prints one.
 import { usageBlock } from "../shared/usage-block.mjs";
 import { invoke } from "../shared/invocation.mjs";   // — name a command the reader can actually type
-import { parseEnvFile } from "../driver/systemd/render-units.mjs";   // — ONE KEY=value reader; a second copy would drift from what systemd actually reads
+import { parseEnvFile } from "../shared/env-file-merge.mjs";   // — ONE KEY=value reader, taken from a leaf: the unit renderer re-exports this same function, and it is a COMMAND, so importing it from here would put a command in this binary's graph
 import { unitEnvironment, unitValue, couldNotDetermine } from "../driver/unit-environment.mjs";   // — F34: claim about the UNITS only from the units' own environment
 
 /**
@@ -2579,8 +2579,14 @@ 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".
+        // AND SO DOES THE REFUSAL'S OWN SENTENCE, for the same reason one line up: absence and
+        // did-not-look are different answers. A proxy-fronted door and a key door both refuse with 401
+        // and no challenge header, so the body is what separates them — doctor must read it too, or it
+        // would answer this question differently from the portal off the same shared verdict.
+        let body = null;
+        if (res.status === 401) { try { body = (await res.text()).slice(0, 400); } catch { body = null; } }
         probe = { ok: res.status < 500, status: res.status, error: null,
-          challenge: res.headers.get("www-authenticate") };
+          challenge: res.headers.get("www-authenticate"), body };
       } catch (e) { probe = { ok: false, status: null, error: String(e?.cause?.code ?? e?.name ?? e?.message ?? e) }; }
     }
     // THE PREFIX TRAVELS WITH THE MESSAGE. Doctor's own guard runs every command

package/bin/start.mjs

@@ -1435,8 +1435,11 @@ if (isMain) {
     // SEEDED FROM A COPY, for the reason the player publishes from one: republishing writes a receipt
     // into the run directory it reads, and `demo/` is tracked. This is the path a reader actually takes
     // — `clearotron demo` hands over to this — so fixing the player alone left the defect where it was.
-    const { publishSource, seedDemoRuns } = await import("../driver/demo-container.mjs");
-    const seed = await seedPool({ pool: paths.pool, examplesDir: publishSource(join(REPO, "demo"), { repoRoot: REPO }), republish: republishRun });
+    // ONE SAMPLE AT A TIME: one whose files cannot be read is left out and named below, and the others
+    // seed. Copied in one call, a single unreadable file emptied the whole archive.
+    const { publishContainer, seedDemoRuns } = await import("../driver/demo-container.mjs");
+    const container = publishContainer(join(REPO, "demo"), { repoRoot: REPO });
+    const seed = await seedPool({ pool: paths.pool, examplesDir: container.dir, republish: republishRun });
     // AND AS RUNS, so the assistant this demo's connect line wires has them to list, brief and open. Under
     // the demo's own workspace only: nothing of it reaches an install started afterwards. Their report
     // links are stamped with this portal's address, the one the Open line prints.
@@ -1461,10 +1464,16 @@ 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}`);
+    // A SAMPLE LEFT OUT IS NAMED ONCE, by the first copy that could not take it (its report or its run).
+    const leftOut = new Map();
+    for (const u of [...container.unusable, ...runs.failed]) if (!leftOut.has(u.name)) leftOut.set(u.name, u.why);
+    // The seeder counts "every example this package ships" off the copy it was handed, so with a sample
+    // left out that sentence would name the copy's count as the package's; the warnings below say instead.
+    if (seed.skipped && !leftOut.size) say(`  archive        ${seed.skipped}`);
     for (const p of seed.problems) err(`  WARNING: sample seeding — ${p}`);
+    for (const [name, why] of leftOut) err(`  WARNING: demo sample ${name} left out — ${why}`);
   } 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.`);
+    err(`  WARNING: the example report could not be seeded (${String(e?.message ?? e)}) — the archive will come up empty. Everything else works; \`${invoke("demo")}\` shows a sample without touching this install.`);
   }
 
   let roster = [];

package/bin/status.mjs

@@ -15,7 +15,7 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { execFileSync } from "node:child_process";
 import { BACKGROUND_UNITS, resolvePorts } from "./start.mjs";
-import { parseEnvFile } from "../driver/systemd/render-units.mjs";   // ONE KEY=value reader — what systemd actually reads
+import { parseEnvFile } from "../shared/env-file-merge.mjs";   // ONE KEY=value reader — what systemd actually reads, taken from the leaf the unit renderer re-exports it from
 import { CLIENT_DOOR_UNIT, clientDoorPort } from "../shared/client-door.mjs";
 import { invoke } from "../shared/invocation.mjs";
 import { readRunning, probe } from "../shared/running-start.mjs";

package/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "8f26558701f6930799f7d8f724ab2ea91e302103",
-  "version": "0.3.0-beta.9"
+  "commit": "ee3ad6c3a561265588b8db72f153e3eb6694d9fe",
+  "version": "0.3.1-beta.0"
 }

package/docs/DELIVERY.md

@@ -136,8 +136,26 @@ drives the whole delivery side over the ops MCP face — mint its token verb-sco
    `sendPending`, clears the marker — idempotent). **A settle is a receipt, not an intention:** with
    neither `messageId` nor an `attestation` it REFUSES, and if the send was blocked or
    failed you do not call it at all — the marker stays and the send stays owed.
-3. For every other kind: route the packet's ready-made `text` → **`ack_event(file)`** (idempotent;
-   validated as a bare `*.pending` name).
+3. For `run-failed`: the requester is **owed** this notice exactly as they are owed a report. Route the
+   packet's ready-made `text`, then settle it with **`mark_sent`**, not `ack_event`. A failed run carries
+   `sendPending` until a send is confirmed, whichever lane wrote the packet, and `mark_sent` is the only
+   thing that clears it. Acknowledging the event instead removes the marker and leaves the run owed, so
+   the backstop scan re-arms it and the requester is told again on the next sweep.
+4. For the remaining kinds — `intake-rejected`, `duplicate-skipped`, `late-bind-ack` — route the
+   packet's `text` → **`ack_event(file)`** (idempotent; validated as a bare `*.pending` name). These
+   describe something that did not become a run, so there is no run to settle.
+
+**Poll at any hour.** Owed work does not keep office hours: a run that fails at 03:00 owes its requester
+a notice at 03:00. Ask the door directly with **`list_runs({ sendPending: true })`** — the no-filesystem
+equivalent of the backstop scan below, returning every run still owed a send, live or archived, with no
+cap. An integrator that only runs during the day leaves a failure unreported until it next wakes, and
+nothing in the product can compensate for that: the product composes the notice and records that it is
+owed, and sending is yours.
+
+**Two things that make that list incomplete, both silent.** A token scoped to named accounts sees only
+those accounts' runs, so a run for an account the token does not carry is invisible rather than absent —
+mint the integrator's token to cover every account it delivers for, and re-mint it when one is added.
+And a `limit` you pass yourself is obeyed as given: for this query, do not pass one.
 
 The filesystem loop below remains equivalent for integrators that do have data-plane access.
 

package/docs/RELEASES.md

@@ -54,5 +54,5 @@ Downgrading is an ordinary install of the older version. Your configuration and
 by either — they live outside the package — so moving between channels is not a migration.
 
 Every version's notes are on the [releases page](https://github.com/CordilleraSarl/clearotron/releases)
-and in `CHANGELOG.md`, grouped New / Fixed / For operators. A beta's notes are the same notes; the stable
+and in `CHANGELOG.md`, grouped Before you upgrade / New / Fixed / For operators. A beta's notes are the same notes; the stable
 that follows aggregates all of them into one entry.

package/driver/CHANGELOG.md

@@ -1,5 +1,49 @@
 # clearotron-driver
 
+## 0.3.1-beta.0
+
+### Patch Changes
+
+- a2c4b94: Fixed: A correction to a coverage note or an action is now applied, or the run records why it was not.
+- b320c65: Fixed: A demo sample that cannot be read is named in the demo's output, and the other demos still publish.
+- d9798db: Fixed: A clearance that stops now always records that its notice is still owed, so a failure cannot be passed over as already handled.
+- ae2cc82: For operators: an assistant asking which searches still owe someone a notice now gets all of them, not just the fifty most recent. Asking for recent searches is unchanged.
+- e390417: For operators: The portal's start-up check now says when its engine address is behind a sign-in it cannot pass, instead of reporting that address as reachable.
+
+## 0.3.0
+
+### Minor Changes
+
+- d2afa5e: Before you upgrade: Name every person who uses your installation in the file that lists who may sign in, or the portal will not start. That file is in your install folder.
+- d2afa5e: New: Switch between companies from any screen, and set a new one up in the browser.
+- d2afa5e: New: Add people from the portal, and give each the right to run clearances, to manage people and companies, or both.
+- d2afa5e: New: Every register finding in a report links to the trade mark office's own page for that record.
+- d2afa5e: New: A clearance records any territory it could not cover, so a partial search never reads as a complete one.
+- d2afa5e: New: Connect Clearotron to your own AI assistant — Claude Code, Codex, or ChatGPT — on your computer or a shared server.
+- d2afa5e: New: A saved search is available in every company, in the portal and in your AI assistant.
+- d2afa5e: New: Check a risk framework for errors before it rates a clearance, and point a company at its own.
+- d2afa5e: New: Group companies under an organisation, each with its own daily limit on clearances.
+- d2afa5e: New: Clearotron installs to a fixed location, so the commands it prints and your AI assistant's connection keep working.
+- d2afa5e: New: `clearotron update` moves an installation, beta included, to the current release.
+
+### Patch Changes
+
+- d2afa5e: Fixed: You sign in, open your companies, and run your first clearance on a new installation.
+- d2afa5e: Fixed: The demo reads and writes only its own companies, reports, and saved searches.
+- d2afa5e: Fixed: `clearotron doctor` checks what a clearance needs, so an installation it clears can run one.
+- d2afa5e: Fixed: A key you paste at a yes-or-no question stays off the screen and out of your command history.
+- d2afa5e: Fixed: Clearotron stays signed in to a paid Codex plan when Codex renews the sign-in.
+- d2afa5e: Fixed: The dashboard shows only the chosen company's clearances, and keeps the filters on screen.
+- d2afa5e: Fixed: The Stop button ends a run before its report goes out, and its dialog says what stopping does.
+- d2afa5e: Fixed: A knockout report names the filings behind each finding, and marks the reviewer's notes as reference.
+
+## 0.3.0-beta.10
+
+### Patch Changes
+
+- fd3a4f7: Fixed: A portal address that does not exist now says so wherever it is. Addresses under the admin path used to show the Global config screen.
+- fd3a4f7: New: The install guide now says how to remove Clearotron, naming every path it writes and which one holds your reports.
+
 ## 0.3.0-beta.9
 
 ### Patch Changes

package/driver/band-size.mjs

@@ -0,0 +1,66 @@
+// 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
+//
+// band-size.mjs — how big the register band was when a stage was dispatched against it.
+//
+// WHY A BUDGET NEEDS THIS BESIDE IT. Two judgment stages carry hand-set walls — 2700s and 2400s — and
+// each was raised after a kill on one crowded matter. The numbers are in the stage table with their
+// post-mortems, and not one of them records the BAND SIZE it was sized against, so the next person
+// asking "is 2400 enough" has no denominator and re-derives it from an archived run by hand. That
+// happened; it is why this exists.
+//
+// IT READS THE SHAPE, NOT THE BAND. `band-shape.json` is derived once per run and already carries the
+// record and crowd totals, so the cost here is one small read rather than parsing the merged band on
+// every dispatch. The band's own file supplies bytes, which is a stat.
+//
+// AN ABSENT BAND IS A NAMED REASON, NEVER A ZERO. A register-only run with nothing retrieved, a matter
+// with no Nice classes (which compiles no register plan at all), and a replay of an archived run that
+// predates the shape all reach a dispatch with no band on disk. Written as `0` those become a
+// measurement saying the band was empty, which is a different and false claim — and every rollup that
+// averages this field would silently take it. The same distinction `toolWaitByTool` draws: an object is
+// a measurement, and the absence says which absence it is.
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { BAND_READING_STAGES } from "./stages.mjs";
+
+/**
+ * The band this dispatch is about to be judged against, as a measurement or a named absence.
+ *
+ * @param {{bandShape: string, registerNamedBand: string}} paths  the run's own paths (`ctx.paths`)
+ * @param {object} [io]  injectable for tests — the real fs by default
+ * @returns {{records:number, crowds:number, bytes:number}|{absent:string}}
+ */
+export function bandSizeAtDispatch(paths, {
+  exists = existsSync, read = readFileSync, stat = statSync,
+} = {}) {
+  const shapePath = paths?.bandShape;
+  const bandPath = paths?.registerNamedBand;
+  if (!shapePath || !bandPath) return { absent: "no run paths" };
+  if (!exists(bandPath)) return { absent: "no merged register band on disk" };
+  // Bytes first: it is a stat, it cannot fail the way a parse can, and a band whose shape has not been
+  // derived yet is still a band whose size is worth recording.
+  let bytes = null;
+  try { bytes = stat(bandPath).size; } catch (e) { return { absent: `band unstatable (${e?.code ?? "unknown"})` }; }
+  if (!exists(shapePath)) return { absent: "no band shape derived yet", bytes };
+  let shape;
+  try { shape = JSON.parse(read(shapePath, "utf8")); }
+  catch (e) { return { absent: `band shape unreadable (${e?.code ?? "parse"})`, bytes }; }
+  const t = shape?.totals;
+  // A shape whose totals are not numbers is not a measurement of anything — say so rather than coercing.
+  if (!t || !Number.isFinite(t.records) || !Number.isFinite(t.crowds)) {
+    return { absent: "band shape carries no totals", bytes };
+  }
+  return { records: t.records, crowds: t.crowds, bytes };
+}
+
+/**
+ * The band size to record for `stage`, or undefined for a stage that does not read the band.
+ *
+ * THE DECISION LIVES HERE RATHER THAN AT THE CALL SITE, and that is the lesson of a plant that did not
+ * red: with the branch written inline in the dispatch, disabling the measurement outright changed
+ * nothing any test could see. A stage outside the set gets `undefined` and not a named absence, because
+ * "this stage does not read the band" is not a fact about the band.
+ */
+export function bandSizeForStage(stage, paths, io) {
+  if (!BAND_READING_STAGES.has(stage)) return undefined;
+  return bandSizeAtDispatch(paths, io);
+}

package/driver/corrections-feedforward.mjs

@@ -55,6 +55,100 @@ export function targetsOf(flagText, known) {
   return hits;
 }
 
+/**
+ * The identity a non-finding line keeps across a rewrite, per register. One implementation, because the
+ * observation below and the removal backstop in pipeline.mjs must agree on which row is which. PURE.
+ */
+export const REPORT_LINE_KEY = Object.freeze({
+  coverage: (c) => `coverage:${norm(c?.area)}`,
+  actions: (a) => `action:${a?.id ?? a?.kind ?? ""}`,
+});
+
+/**
+ * The reader's name for such a row. One implementation, because three surfaces print it: the plain-words
+ * pre-check that hands the reviewer its labels, the observation below, and the driver's own account of
+ * what it restored — and a reviewer comparing two of those must not be reading two vocabularies. PURE.
+ */
+export const REPORT_LINE_LABEL = Object.freeze({
+  coverage: (c) => `the coverage line for "${c?.area ?? "an area"}"`,
+  actions: (a) => `the action "${a?.id ?? a?.kind ?? ""}"`.replace(/ ""$/, ""),
+});
+
+/**
+ * THE LINES A CLEARANCE READER MEETS FIRST THAT ARE NOT A FINDING — each coverage row's note, each
+ * action's text and the mark assessment's two reads — with the identity each keeps across a rewrite.
+ *
+ * A finding carries an ordinal and a name, and a flag joins to it by either. These lines carry neither,
+ * so a flag rewriting one came out `not-entity-scoped` whatever the corrective pass did with it: seven
+ * such flags survived one clearance on the test box, and a production matter showed the same split
+ * (2026-09-11). The label is the one the plain-words pre-check hands the reviewer, so a flag repeating it
+ * joins on the driver's own words.
+ *
+ * Reads the parsed record (`markAssessment`) and the raw one (`mark_assessment`) alike. PURE.
+ */
+export function reportLines(doc) {
+  const out = [];
+  const add = (key, label, v) => {
+    const text = typeof v === "string" ? v : (typeof v?.read === "string" ? v.read : "");
+    if (text.trim()) out.push({ key, label, text });
+  };
+  for (const c of Array.isArray(doc?.coverage) ? doc.coverage : [])
+    add(REPORT_LINE_KEY.coverage(c), REPORT_LINE_LABEL.coverage(c), c?.note);
+  for (const a of Array.isArray(doc?.actions) ? doc.actions : [])
+    add(REPORT_LINE_KEY.actions(a), REPORT_LINE_LABEL.actions(a), a?.text);
+  const ma = doc?.markAssessment ?? doc?.mark_assessment;
+  for (const k of ["distinctiveness", "connotation"]) add(`mark-assessment:${k}`, `the mark assessment's ${k}`, ma?.[k]);
+  return out;
+}
+
+const QUOTE_WORDS = 8;
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** A flag that carries the line's identity: its label, or the plain ways of saying it. PURE. */
+function namesLine(hay, l) {
+  const at = l.key.indexOf(":");
+  const kind = l.key.slice(0, at), id = norm(l.key.slice(at + 1));
+  if (!id) return false;
+  if (kind === "coverage") return new RegExp(` coverage (?:line|note|row|entry) (?:for |on |about )?(?:the )?${escapeRe(id)} `).test(hay);
+  if (kind === "action") return hay.includes(` action ${id} `);
+  return new RegExp(` mark assessment (?:s )?(?:[a-z]+ )?${escapeRe(id)} `).test(hay);
+}
+
+/** A flag that quotes the line: eight running words of it, or all of a shorter one of four or more. PURE. */
+function quotesLine(hay, text) {
+  const words = norm(text).split(" ").filter(Boolean);
+  if (words.length < QUOTE_WORDS) return words.length >= 4 && hay.includes(` ${words.join(" ")} `);
+  for (let i = 0; i + QUOTE_WORDS <= words.length; i++)
+    if (hay.includes(` ${words.slice(i, i + QUOTE_WORDS).join(" ")} `)) return true;
+  return false;
+}
+
+/**
+ * Which of `lines` a flag is about — named by its label, or quoted, which is what the reviewer is told
+ * to do with a sentence it rewrites.
+ *
+ * THIS OBSERVES; IT APPLIES NOTHING. Matching prose is how a rewrite lands on the wrong thing, which is
+ * why no correction is ever routed by it. Here a miss leaves the row where it was, `not-entity-scoped`,
+ * and a hit prints the line's label beside the flag, where the reviewer reading the table can see it. PURE.
+ */
+export function linesOf(flagText, lines) {
+  const hay = ` ${norm(flagText)} `;
+  return (lines ?? []).filter((l) => namesLine(hay, l) || quotesLine(hay, l.text));
+}
+
+/** The corrective pass's own words about a line it was flagged on, from the `corrections` register. PURE. */
+function reasonFor(hit, doc) {
+  const c = doc?.corrections;
+  const said = [
+    ...(Array.isArray(c?.entries) ? c.entries.map((e) => [e?.entity, e?.disposition, e?.note].filter(Boolean).join(": ")) : []),
+    ...String(c?.note ?? "").split(/\n|;\s+/),
+  ].map((s) => s.trim()).filter(Boolean);
+  const hitSays = said.find((s) => linesOf(s, hit).length);
+  return hitSays ? hitSays.slice(0, 300) : null;
+}
+
+const squash = (s) => String(s ?? "").replace(/\s+/g, " ").trim();
+
 /** A finding's comparable state — the fields a correction can move. PURE. */
 const stateOf = (f) => JSON.stringify({
   disposition: f?.disposition ?? null,
@@ -82,7 +176,10 @@ function byName(doc) {
  *   findings-removed      — a finding this flag names was present before the pass and is GONE after it;
  *   findings-changed      — at least one finding this flag names has a different comparable state;
  *   findings-unchanged    — it named findings and none of them moved;
- *   not-entity-scoped     — the flag names no finding (a prose/structure correction);
+ *   line-removed          — a non-finding line this flag names or quotes (`reportLines`) is GONE after it;
+ *   line-changed          — that line's text is different after the pass;
+ *   line-unchanged        — it reads the same; the row carries the pass's reason, or null for none;
+ *   not-entity-scoped     — the flag names no finding and no such line (a prose/structure correction);
  *   not-checkable         — the pre-corrective snapshot is missing, so nothing can be compared.
  *
  * "findings-unchanged" is NOT a failure and must never be rendered as one: correcting a narrative
@@ -162,6 +259,7 @@ export function buildCorrectionsApplied(rows, preDoc, postDoc) {
   const known = knownEntities(preDoc, postDoc);
   const pre = byName(preDoc), post = byName(postDoc);
   const preOrd = byOrdinal(preDoc), postOrd = byOrdinal(postDoc);
+  const preLines = reportLines(preDoc), postLine = new Map(reportLines(postDoc).map((l) => [l.key, l]));
   return (rows ?? []).map((r) => {
     // — a DECLARED ordinal wins over the name match. `targetsOf` is a normalised prose join and it
     // is why six of nine flags on a delivered run resolved to nothing; the declaration is the reviewer's
@@ -185,10 +283,22 @@ export function buildCorrectionsApplied(rows, preDoc, postDoc) {
     const declaredOrds = (Array.isArray(r.ordinals) ? r.ordinals : [])
       .filter((o) => preOrd.has(o) || postOrd.has(o));
     const label = (o) => { const f = preOrd.get(o) ?? postOrd.get(o); return f?.mark ?? f?.owner?.name ?? `finding ${o}`; };
-    const targets = declaredOrds.length ? declaredOrds.map(label) : targetsOf(r.text, known);
+    // — A LINE THAT IS NOT A FINDING, asked before the name match. A flag that names or quotes a coverage
+    // note, an action or the mark assessment is about that line, and a mark or owner named inside the
+    // line it quotes is incidental. Asked only where no ordinal was declared: a declaration still wins.
+    const hit = preDoc && !declaredOrds.length ? linesOf(r.text, preLines) : [];
+    const targets = declaredOrds.length ? declaredOrds.map(label)
+      : hit.length ? hit.map((l) => l.label) : targetsOf(r.text, known);
     let outcome;
     let removed = [];
     if (!preDoc) outcome = "not-checkable";
+    else if (hit.length) {
+      // The same three answers a finding gets, asked of the line's own text. REMOVAL WINS, as it does
+      // for a finding: a line gone after the pass was answered by deletion, and that is the question.
+      const gone = hit.filter((l) => !postLine.has(l.key));
+      if (gone.length) { outcome = "line-removed"; removed = gone.map((l) => l.label); }
+      else outcome = hit.some((l) => squash(postLine.get(l.key).text) !== squash(l.text)) ? "line-changed" : "line-unchanged";
+    }
     else if (declaredOrds.length) {
       // The certain path. Every question below is asked of the finding the reviewer NAMED, by ordinal.
       removed = declaredOrds.filter((o) => preOrd.has(o) && !postOrd.has(o)).map(label);
@@ -229,7 +339,10 @@ export function buildCorrectionsApplied(rows, preDoc, postDoc) {
     // unrecoverable; one field makes it answerable from the next run on. It also feeds the report's
     // open-points section, which prints `(finding N)` beside a point and had no ordinals to print.
     return { n: r.n, kind: r.kind, typed: r.typed, text: r.text,
-      ordinals: Array.isArray(r.ordinals) ? r.ordinals : null, targets, outcome, removed };
+      ordinals: Array.isArray(r.ordinals) ? r.ordinals : null, targets, outcome, removed,
+      // A line's row carries the pass's own reason for it, or null when the pass gave none: "declined
+      // with a reason" is then a fact the run recorded, and "neither applied nor declined" is too.
+      ...(hit.length && preDoc ? { reason: reasonFor(hit, postDoc) } : {}) };
   });
 }
 
@@ -256,9 +369,12 @@ export function buildCorrectionsApplied(rows, preDoc, postDoc) {
  * belongs on the printed side. Deciding it here rather than at the report keeps one implementation of a
  * question this file already answered once.
  *
+ * `line-changed` is the same fact about a line that is not a finding, so it is resolved too; its
+ * `line-removed` and `line-unchanged` stay printed for the reasons their finding twins do.
+ *
  * PURE.
  */
-export const RESOLVED_OUTCOMES = Object.freeze(["findings-changed"]);
+export const RESOLVED_OUTCOMES = Object.freeze(["findings-changed", "line-changed"]);
 
 /** The rows to print. Anything not positively resolved, including a row of an outcome nobody has met. */
 export const unresolvedFlags = (rows) =>
@@ -307,8 +423,9 @@ export function correctionsAppliedTable(applied) {
   for (const r of applied) {
     // — a removal NAMES what left. `findings-removed` alone would tell the recheck that something
     // was deleted and not which fact, which is the half it needs to decide whether the deletion was legitimate.
-    const what = r.outcome === "findings-removed" && r.removed?.length
+    const what = (r.outcome === "findings-removed" || r.outcome === "line-removed") && r.removed?.length
       ? `${r.outcome}: ${r.removed.join(", ")}`
+      : r.reason ? `${r.outcome} — the pass said: ${r.reason.slice(0, 120)}${r.reason.length > 120 ? "…" : ""}`
       : r.outcome;
     out.push(`| ${r.n} | ${r.kind} | ${r.text.slice(0, 90)}${r.text.length > 90 ? "…" : ""} | ${r.targets.join(", ") || "—"} | ${what} |`);
   }
@@ -322,5 +439,11 @@ export function correctionsAppliedTable(applied) {
       + "so it reads as resolved while the report is no truer than before. Check each named finding: a "
       + "withdrawal the evidence supports is legitimate and belongs in the record AS a withdrawal with its "
       + "reason; a fact removed because it was inconvenient to correct is the defect this row exists to show you.");
+  if (applied.some((r) => String(r.outcome).startsWith("line-")))
+    out.push("",
+      "`line-*` rows compare a line the reader sees that is not a finding — a coverage note, an action, the mark "
+      + "assessment — as the flag named or quoted it, before and after the pass. A `line-unchanged` row with no "
+      + "reason beside it is a flag the pass neither applied nor declined; `line-removed` means the line is gone "
+      + "rather than rewritten.");
   return out.join("\n");
 }