clearotron 0.4.0-beta.0 → 0.4.0-beta.2

package/driver/deferral-row.mjs

@@ -0,0 +1,139 @@
+// 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
+//
+// deferral-row.mjs — the row a reader gets for anything left open this run, and the words its reasons
+// are given in. Moved out of pipeline.mjs unchanged so that publishing and the audit workbook can reuse the
+// shipped words without importing the pipeline. A pure leaf: no imports at all.
+
+// wp50/wi9 — machine directives reworded at the authoring point: "frame-reopen / source:who inn list…"
+// with note "deferred this run — mechanical-fail:timeout" is machinery-speak on a lawyer's report.
+export const plainDirective = (s) => String(s ?? "").replace(/\b(source|variant|field|axis):\s*/gi, "").replace(/\s+/g, " ").trim();
+// ── — TRANSLATE AT THE BOUNDARY, NEVER FILTER ──────────────────────────────────────────────────
+//
+// This switch is a CODE-MINTED, CODE-ENUMERATED set of reason prefixes, not a dictionary. Every token
+// it matches is minted by this same file (`regDeferReason`) and written to _driver/frame-reopen.json;
+// none of it is ever authored by a model, and none of it comes from client prose or the register. That is the whole distinction drew — the `mechanical-fail:*` arms below
+// have sat here since wp50/wi9 and nobody called them a ban list, because a switch over your own
+// output is not a find-and-replace over somebody else's.
+//
+// DROPPING THE SENTENCE IS NOT AN OPTION. Adding `no-code-remedy:` to parse.mjs's ENGINE_INTERNAL_RE
+// would delete the whole sentence (that filter drops per sentence) and with it the disclosure the row
+// exists to make — injectDeferralCoverage's own contract is that "the reader-visible disclosure is the
+// whole point of 'can't close → disclose'". A reader who is told nothing about an unsearched slice is
+// worse off than one told about it in engine words. So: translate, never filter.
+//
+// The engine wording is KEPT on the internal record — regTermRows' `dispatch_reason` and the
+// frame-reopen.json `reason` are unchanged, so remedy-accounting and the audit still read the token.
+export const plainDeferralReason = (r) => {
+  const t = String(r ?? "unclosed").trim();
+  if (/mechanical-fail:timeout/i.test(t)) return "the source timed out this run";
+  if (/mechanical-fail:(.+)/i.test(t)) return `a tool failed this run (${t.replace(/^mechanical-fail:/i, "")})`;
+  if (/^no-code-remedy:/i.test(t)) {
+    // The two forms regDeferReason mints, in the reader's words. Both must still say the slice was NOT
+    // searched and why — a translation that loses that has filtered the disclosure by other means.
+    if (/class-gap/i.test(t))
+      return "no search could be built for it: the gap names classes but no searchable name, and re-running the matter's own classes would only repeat the main sweep, so it is left open here rather than reported as clean";
+    if (/\blabel\b/i.test(t))
+      return "no search could be built for it: the item names a category rather than a name a register can be searched for, so searching the wording literally would return nothing and read as clean, and it is left open here";
+    return "no search could be built for it this run, so it is left open here rather than reported as clean";
+  }
+  // ── — THE ARMS DID NOT REACH, AND A FALLBACK THAT CANNOT LEAK ────────────────────────
+  //
+  // built this switch for the two families it had met and left `return t` under them, so every
+  // OTHER token `regDeferReason` and `partitionFiring` mint reached the coverage row verbatim. The
+  // worst shape is a hash-bearing one — `slice-not-landed:supp:<axis>:<predicate>:<term>:<hash>` — which
+  // is not a sentence anybody can act on, and the row it lands in is one a reader relies on to tell a
+  // searched slice from an unsearched one.
+  //
+  // THIS IS THE ONLY PLACE IT CAN BE REPAIRED. The portal's embed strip passes coverage rows through
+  // untouched, so whatever this function returns is what the served page carries — there is no second
+  // surface downstream that could catch a token this one let past.
+  if (/^no-resumable-session\b/i.test(t))
+    return "the earlier search session could not be resumed to finish it, so the slice was left open rather than reported as clean";
+  if (/^unchanged-after-resume\b/i.test(t))
+    return "it was re-run and the result did not change, so it stands as it was — open, not cleared";
+  if (/^not-verified-closed\b/i.test(t))
+    return "nothing in the run's own record confirms it was searched, so it is left open rather than assumed done";
+  if (/^source-not-swept\b/i.test(t))
+    return "the channel it needed was never swept this run, so nothing is known about it either way";
+  if (/^digest-locked-resume\b/i.test(t))
+    return "the earlier pass was still holding the record when the re-run was attempted, so it could not be completed this run";
+  if (/^resume-arm-unverifiable\b/i.test(t))
+    return "the re-run left no evidence of what it actually searched, so it cannot be treated as having closed this — disclosed rather than assumed clean";
+  if (/^proposals-rejected\b/i.test(t))
+    return "the searches proposed for it could not be put to this register, so it was never searched";
+  if (/^slice-not-landed\b/i.test(t))
+    return "the search for it was planned and never reached the register, so nothing is known about it either way";
+  if (/^redigest-fail\b/i.test(t))
+    return "the re-read of the results failed this run, so what it holds was never established";
+  // THE FALLBACK IS THE FIX, and the arms above are the courtesy.
+  //
+  // `return t` was the defect: it made every UNKNOWN token a rendered string, so the leak was not
+  // the nine arms above — it was that the set is open and the default published whatever it did not
+  // recognise. A tenth token minted tomorrow would have leaked on the day it was minted. This says the
+  // one thing every branch here must say — the slice was not completed and is not clean — and says it
+  // without the token.
+  //
+  // AND IT DROPS NOTHING PROTECTED. Its ruling is "translate, never filter", because a reader told
+  // nothing about an unsearched slice is worse off than one told in engine words. The row still renders,
+  // still says it was not completed, and still reads as open. The engine wording is untouched on the
+  // internal record — `regTermRows`' `dispatch_reason` and `frame-reopen.json`'s `reason` — exactly as
+  // that ruling stipulates, so remedy-accounting and the audit still read the token.
+  return "it could not be completed this run, so it is left open here rather than reported as clean";
+};
+
+/**
+ * A RAW CAUSE, IN THE READER'S WORDS. A lookup or a listing that failed carries the provider's own text —
+ * an exception's message, a status line — and that text belongs to the run's record, never to a client's
+ * cell. A timeout reads as the timeout line and anything else as the line for a search left open; the
+ * cause itself stays where it was written.
+ */
+export const plainCause = (cause) =>
+  plainDeferralReason(/timeout|timed out/i.test(String(cause ?? "")) ? "mechanical-fail:timeout" : "unfinished");
+
+// ── — A HEADING IS NOT THE PLACE FOR A DIRECTIVE ───────────────────────────────────────────────
+//
+// What shipped: `Follow-up / ${plainDirective(directive).slice(0, 60)}` — a hard character cut with no
+// word boundary and no ellipsis. Two delivered specimens in demo:
+//   "Follow-up / consumer and prosumer water testing (pool, spa, aquarium, ho"   (mid-"home")
+//   "Follow-up / agri-tech, irrigation, aquaculture and hydrology monitoring "   (mid-"software", and
+//                                                                                a trailing space)
+// That string is a CLIENT HEADING — render.mjs's coverageGrid prints it under "What we covered — and
+// what's open", and it rides verbatim into report-data.json.
+//
+// THE FIX IS HERE, NOT IN THE RENDERER, deliberately. coverageGrid carries the ruling that
+// "NOTHING IS SUBSTITUTED HERE ANY MORE — `area` and `note` ride verbatim". Clipping in the renderer
+// would re-open substitution over a client string at exactly the seam that ruling closed. The heading
+// is wrong where it is MINTED, so it is fixed where it is minted.
+//
+// A smarter truncation would still be a truncation. The real defect is that a whole search directive
+// was being asked to serve as a heading. So the heading gets a short, word-boundary-cut label with an
+// explicit "…" saying it was shortened, and the FULL directive moves into `note`, which has room for
+// it. Nothing is lost from the reader's view; it moves to where it fits.
+//
+// "Follow-up / " STAYS LITERAL. coverage-ledger.coverageUnitLabel keys label suppression off that exact
+// shape ("a driver-authored plain-English area … must not be touched"), so only what follows it moves.
+const DEFERRAL_AREA_ITEM_BUDGET = 48;      // characters after "Follow-up / " — a heading, not a sentence
+
+/** Cut `s` to at most `max` characters at a WORD boundary, marking the cut with an explicit "…".
+ *  Trailing punctuation and whitespace are trimmed before the ellipsis so no heading ends "monitoring …"
+ *  or with a dangling bracket. Returns `s` unchanged when it already fits. PURE. */
+export function clipToWord(s, max) {
+  const t = String(s ?? "").trim();
+  if (t.length <= max) return t;
+  const cut = t.slice(0, max);
+  const sp = cut.lastIndexOf(" ");
+  const head = (sp > 0 ? cut.slice(0, sp) : cut).replace(/[\s,;:.\-–—(/[]+$/, "");
+  return head ? `${head}…` : `${cut.trim()}…`;
+}
+
+/** — ONE deferral's reader-visible coverage row. Exported so the shape a client reads is testable
+ *  without a run directory: injectDeferralCoverage below is the file-I/O wrapper around this. PURE. */
+export function deferralCoverageRow(directive, reason) {
+  const full = plainDirective(directive);
+  return {
+    area: `Follow-up / ${clipToWord(full, DEFERRAL_AREA_ITEM_BUDGET)}`,
+    state: "open",
+    note: `${full} — not completed this run — ${plainDeferralReason(reason)}`,
+  };
+}

package/driver/degraded-parts.mjs

@@ -0,0 +1,377 @@
+// 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
+//
+// degraded-parts.mjs — the parts of a report that failed, degraded or were skipped while the report still
+// shipped, read from the run's record at delivery so the audit workbook can say so.
+//
+// THE RULE (ruled 2026-09-25): run clean first time; if not, retry and recover; and anything that still
+// failed, short of a failure that makes the report meaningless, is delivered and flagged in the audit. The
+// defect this module exists for is the part that fails silently: the report ships without it and nothing
+// in the delivery says so.
+//
+// READ FROM THE STATE AT DELIVERY, NEVER FROM HISTORY. The run log is append-only across resumes, so a
+// failure that a retry or a resume later recovered is still in it. Each check reads what the delivery can
+// see: the stage's own last attempt, the artifact the part is built from, or the last event its step
+// wrote. A part that recovered writes no row.
+//
+// THE WORDS ARE THE WORKBOOK'S OWN. A check names its part with a label the report or the workbook already
+// prints (PART_NAMES, each held to its source by a test) and gives a reason token that the shipped
+// deferral row translates into its reader's words. The row is that builder's, so this module writes no
+// sentence, and no raw cause reaches a reader's cell: the cause stays on the run's record.
+//
+// A pure leaf: node:fs, node:path, shared/driver-dir.mjs, the row's own module and the publisher's table of
+// stores (itself node:fs and node:path only), so it cannot drag driver.config.mjs, whose unset-env defaults
+// are PRODUCTION, into anything that imports it.
+import { readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { driverDir, labelOfDriverFile } from "../shared/driver-dir.mjs";   // a card's label carries a colon, which Windows writes %3A
+import { deferralCoverageRow } from "./deferral-row.mjs";
+import { PUBLISH_INPUTS, readStore } from "./publish/publish-inputs.mjs";
+
+// The name each part is given: a label the report or the workbook already prints. Never a new phrase.
+export const PART_NAMES = {
+  courtDecisions: "Court decisions",   // the report's search-coverage row (publish/render.mjs)
+  searchLog: "What was searched",      // the workbook's tab (publish/xlsx.mjs)
+  register: "Register",                // the report's search-coverage row (publish/render.mjs)
+  localLanguage: "Local-language investigation",   // the report's search-coverage row (publish/render.mjs)
+  findings: "Findings",                // the workbook's tab (publish/xlsx.mjs)
+  machineQc: "Machine QC",             // the workbook's Summary row for the checks (publish/xlsx.mjs)
+  conditions: "Conditions",            // the gaps sheet's area for a condition that reaches no page (publish/index.mjs)
+  coverage: "Coverage & gaps",         // the workbook's tab (publish/xlsx.mjs)
+  marketplaceWeb: "Marketplace and web",   // the report's search-coverage row (publish/render.mjs)
+  machineChecks: "Machine Checks",     // the knockout workbook's sheet (publish/knockout.mjs)
+  aboutThisRequest: "About this request",   // the knockout report's heading (publish/render-knockout.mjs)
+};
+
+// The words the owner ruled where no shipped label or line fitted (537 and 539, 2026-09-25), each held to
+// the ruling verbatim by a test. They are his; nothing here composes around them.
+export const RULED_WORDS = {
+  officialRecords: "Official records",          // the register records behind a clearance's cards
+  plainLanguageReview: "Plain-language review", // the knockout pass that rewrites the rater's wording
+  // A knockout web search that ran, whose answer reached the report, and whose trail entry was never written.
+  recordNotKept: "The record of this search was not kept this run; its answer was used",
+};
+
+/** A filing's Note when its link was removed because the address is not on the register's own site (537). */
+export const linkNotOnRegisterSite = (register) => `Address not on this register's own site (${register}); cited by number`;
+
+// Reason tokens the shipped deferral row translates (deferral-row.mjs, plainDeferralReason). Only these two
+// reach it from here, so the reader's line is one of the row's own and never the raw cause.
+export const TIMED_OUT = "mechanical-fail:timeout";   // → "the source timed out this run"
+export const NOT_COMPLETED = "unfinished";            // → the row's fallback: "it could not be completed this run, …"
+
+export const DEGRADED_PARTS_FILE = "degraded-parts.json";
+
+const readJsonl = (p) => {
+  try {
+    return readFileSync(p, "utf8").split("\n").filter((l) => l.trim())
+      .map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+  } catch { return []; }
+};
+
+/** The stage's own last attempt row, or null when the stage wrote none. */
+export function lastAttempt(runDir, stage) {
+  const rows = readJsonl(driverDir(runDir, `${stage}.jsonl`))
+    .filter((r) => Number.isFinite(Number(r?.attempt)) && typeof r.ok === "boolean");
+  return rows.length ? rows[rows.length - 1] : null;
+}
+
+/** The last run-log event carrying one of `names`, or null. */
+const lastEvent = (log, names) => {
+  for (let i = log.length - 1; i >= 0; i--) if (names.includes(log[i]?.event)) return log[i];
+  return null;
+};
+
+const reasonFor = (fail) => (/timeout|timed out/i.test(String(fail ?? "")) ? TIMED_OUT : NOT_COMPLETED);
+
+// ── The checks. Each returns null, or {part, name, reason, cause}: `cause` is the raw fact for the run's
+// record and never reaches a cell.
+
+// Court decisions, on a run that was due them: the stage ended failed, or its file is absent or empty. An
+// empty file reads "not in scope" on the report (publish/search-depth.mjs), so nothing else says it.
+function courtDecisions(runDir, log) {
+  if (lastEvent(log, ["case-law-decision"])?.run !== true) return null;
+  const last = lastAttempt(runDir, "case-law");
+  const part = { part: "court-decisions", name: PART_NAMES.courtDecisions };
+  if (last?.ok === false) return { ...part, reason: reasonFor(last.fail), cause: `the case-law stage ended failed: ${last.fail ?? "no cause recorded"}` };
+  let text;
+  try { text = readFileSync(join(runDir, "case-law-findings.md"), "utf8"); } catch { text = null; }
+  if (text === null) return { ...part, reason: NOT_COMPLETED, cause: "case-law-findings.md is absent" };
+  if (!text.trim()) return { ...part, reason: NOT_COMPLETED, cause: "case-law-findings.md is empty" };
+  return null;
+}
+
+// The search log the workbook's "What was searched" tab is built from. Without it the tab lists no
+// register search at all.
+function searchLog(runDir) {
+  let text;
+  try { text = readFileSync(join(runDir, "audit.md"), "utf8"); } catch { text = null; }
+  if (text !== null && text.trim()) return null;
+  return { part: "search-log", name: PART_NAMES.searchLog, reason: NOT_COMPLETED,
+    cause: text === null ? "audit.md is absent" : "audit.md is empty" };
+}
+
+// A step whose last word in the run log was its failure: `ok` names the event it writes when it succeeds,
+// so a later success on a resume clears it.
+const failedStep = (log, ok, failed) => {
+  const last = lastEvent(log, [ok, failed]);
+  return last?.event === failed ? last : null;
+};
+const stageEnded = (runDir, stage) => {
+  const last = lastAttempt(runDir, stage);
+  return last?.ok === false ? last : null;
+};
+
+// The register's own steps, each of which the run survives without: the band's shape (the floors and the
+// full cards read it), the mechanical form floor, the owner screen, and the digest's folding in of re-runs.
+function register(runDir, log) {
+  const part = { part: "register", name: PART_NAMES.register, reason: NOT_COMPLETED };
+  const steps = [
+    ["band-shape-derived", "band-shape-failed", "the band shape"],
+    ["form-neighbourhood-derived", "form-neighbourhood-skipped", "the form floor"],
+    ["owner-screen-derived", "owner-screen-failed", "the owner screen"],
+    ["digest-flush", "digest-flush-failed", "the digest flush"],
+  ];
+  const failed = steps.map(([ok, bad, what]) => [failedStep(log, ok, bad), what]).filter(([e]) => e);
+  if (!failed.length) return null;
+  return { ...part, cause: failed.map(([e, what]) => `${what}: ${e.fail ?? e.reason ?? e.event}`).join("; ") };
+}
+
+// A finding's written card: its stage ended failed, so the card shipped with its structured rows only.
+//
+// MATCHED ON THE LABEL, NEVER ON THE FILE NAME. A card's stage label carries a colon — `report-card:3` —
+// and Windows cannot hold one, so `driverFileName` writes it `%3A` there and this filter's raw colon
+// matched nothing: `degradedParts` returned an empty list, and the audit workbook then reported coverage
+// CLOSED over a card that failed. On Linux the two spellings are the same string, which is why every arm
+// was green and only the scheduled Windows run showed it.
+//
+// `labelOfDriverFile` decodes `%3A` on every platform and strips the extension, so the label is the same
+// on both and the predicate reads it rather than the bytes on disk. The label is also what `stageEnded`
+// wants: it resolves its path through `driverDir`, which re-encodes the colon for the platform it is on,
+// so handing it the raw name would send Windows looking for a file it never wrote.
+function findingCards(runDir) {
+  let files = [];
+  try { files = readdirSync(driverDir(runDir)).filter((f) => f.endsWith(".jsonl")); } catch { return null; }
+  const failed = files.map((f) => labelOfDriverFile(f)).filter((stage) => /^report-card:.+/.test(stage))
+    .filter((stage) => stageEnded(runDir, stage));
+  if (!failed.length) return null;
+  return { part: "finding-cards", name: PART_NAMES.findings, reason: NOT_COMPLETED, cause: `card stages ended failed: ${failed.join(", ")}` };
+}
+
+// The checks that stand behind the report without appearing in it: the frame's omission check (the blind
+// frame and the frame diff), the reviewer's pass and its re-check, a corrective pass that rolled back, and
+// the crowd counts the judgment reads. Each shares the one name, so they are one reader's line.
+function checks(runDir, log) {
+  const failed = [];
+  const blind = stageEnded(runDir, "blind-frame");
+  if (blind) failed.push(["the blind frame", blind.fail]);
+  const diff = failedStep(log, "frame-diff", "frame-diff-skipped");
+  if (diff && !blind) failed.push(["the frame diff", diff.reason]);
+  const skeptic = stageEnded(runDir, "skeptic");
+  if (skeptic) failed.push(["the reviewer's pass", skeptic.fail]);
+  const recheck = stageEnded(runDir, "narrative-refutation");
+  if (recheck) failed.push(["the review's re-check", recheck.fail]);
+  const rollback = failedStep(log, "corrective-cycle-receipt", "corrective-rollback");
+  if (rollback) failed.push(["the corrective pass, rolled back", rollback.reason]);
+  const crowd = failedStep(log, "crowd-context", "crowd-context-failed");
+  if (crowd) failed.push(["the crowd counts", crowd.fail]);
+  if (!failed.length) return null;
+  return { part: "checks", name: PART_NAMES.machineQc, reason: reasonFor(failed.map(([, why]) => why).join("; ")),
+    cause: failed.map(([what, why]) => `${what}: ${why ?? "no cause recorded"}`).join("; ") };
+}
+
+// The native-language investigation, where lanes were asked and none of them ran. The caller hands in the
+// state publishing prints (publish/search-depth.mjs, localLanguageDepth): the lanes' own record is read
+// through jx.mjs, which this leaf may not import. A lane that ran short of its depth is not read here, because
+// the run cannot yet tell a shortfall from a limit of the product.
+function localLanguage(runDir, log, { localLanguage: state = null } = {}) {
+  if (state !== "not-run") return null;
+  return { part: "local-language", name: PART_NAMES.localLanguage, reason: NOT_COMPLETED, cause: "native-language lanes were asked and none of them ran" };
+}
+
+/**
+ * The fetched official records, `_records/*.json`: "absent" with no file, "damaged" when files are there
+ * and none of them parses, "read" otherwise. It asks what registry-fidelity.mjs readRecordArtifacts asks
+ * of the same folder, which skips a file it cannot parse, only whether anything survived.
+ */
+export function recordsState(runDir) {
+  let files;
+  try { files = readdirSync(join(runDir, "_records")).filter((f) => f.endsWith(".json")); } catch { return "absent"; }
+  if (!files.length) return "absent";
+  for (const f of files) {
+    try {
+      const body = JSON.parse(readFileSync(join(runDir, "_records", f), "utf8"));
+      if (body && typeof body === "object" && !Array.isArray(body)) return "read";
+    } catch { /* the next file */ }
+  }
+  return "damaged";
+}
+
+// The official records behind the cards, where the run's record set was built from a fetch ledger it could
+// not read: the set is empty for that reason, and the cards print what the model wrote with nothing to check
+// it against and no mark that it went unchecked. Two cases are left out on purpose. A merely empty set is the
+// product's design on a register whose report cites no record address, which never fetches one. And the
+// count of fetches whose bodies went missing is taken before the closure fetch, which can still close it.
+function officialRecords(runDir, log) {
+  const last = lastEvent(log, ["record-artifacts"]);
+  if (!last?.ledgerError) return null;
+  return { part: "official-records", name: RULED_WORDS.officialRecords, reason: NOT_COMPLETED,
+    cause: `the fetch ledger could not be read: ${last.ledgerError}` };
+}
+
+const CHECKS = [courtDecisions, searchLog, register, localLanguage, findingCards, checks, officialRecords];
+
+/**
+ * Every part of this clearance run that failed and still ships, read from the run directory as it stands
+ * at delivery. `opts.localLanguage` is the native-language state publishing prints, when the run has lanes. A check that cannot read its input reads nothing and reports nothing; the run's own record
+ * already carries that input's failure. PURE apart from reading `runDir`.
+ */
+export function degradedParts(runDir, opts = {}) {
+  const log = readJsonl(driverDir(runDir, "run.jsonl"));
+  return CHECKS.map((check) => check(runDir, log, opts)).filter(Boolean);
+}
+
+/**
+ * The rows the audit workbook prints for `parts`: the shipped deferral row. One row per name: two parts
+ * that share a name are one reader's line, and both causes stay on the record.
+ */
+export function degradedPartRows(parts) {
+  const seen = new Set();
+  const rows = [];
+  for (const p of parts) {
+    if (seen.has(p.name)) continue;
+    seen.add(p.name);
+    rows.push(deferralCoverageRow(p.name, p.reason));
+  }
+  return rows;
+}
+
+/**
+ * Write the parts and their rows to the run's record, where publishing and a later republish read them,
+ * with the state of every store the publisher reads as delivery found it: the evidence a republish needs
+ * to tell a store this run lost from one it never had.
+ */
+export function writeDegradedParts(runDir, parts) {
+  const record = { parts, rows: degradedPartRows(parts), stores: storeStates(runDir) };
+  writeFileSync(driverDir(runDir, DEGRADED_PARTS_FILE), JSON.stringify(record, null, 2) + "\n");
+  return record;
+}
+
+/** The rows written at delivery, or [] for a run that wrote none (every run before this change). */
+export function readDegradedPartRows(runDir) {
+  try {
+    const rows = JSON.parse(readFileSync(driverDir(runDir, DEGRADED_PARTS_FILE), "utf8"))?.rows;
+    return Array.isArray(rows) ? rows.filter((r) => r && typeof r.area === "string" && typeof r.note === "string") : [];
+  } catch { return []; }
+}
+
+// ── AT PUBLISH: THE STORES A REPUBLISH OR A DISK FAULT CAN TAKE ──────────────────────────────────────
+//
+// Two things only the publisher sees. A store that is PRESENT AND UNREADABLE when it is read: an archived
+// run is never in that state, only a missing one, so it cannot fire on older work. And a store that
+// delivery read and a later republish finds MISSING: the delivery's own record of what it read is the
+// evidence, so a run delivered before that record existed writes nothing, as before.
+//
+// Each store the publisher reads is the part it feeds, named with a label the report or workbook prints,
+// or it is declared out with the reason, so a new store cannot be added without deciding which.
+export const STORE_PARTS = {
+  "findings.json": "findings",
+  "_driver/receipts.json": "officialRecords",
+  "_driver/senior-rights.json": "officialRecords",
+  "_driver/verdict.json": "conditions",
+  "_driver/framework.json": "findings",
+  "_driver/register-recall.json": "coverage",
+  "_driver/register-plan.json": "register",
+  "register-named-band.json": "register",
+  "_driver/instructed-scope.json": "register",
+  "_driver/jx-lanes.json": "localLanguage",
+  "_driver/jx/units.json": "localLanguage",
+  "case-law-findings.md": "courtDecisions",
+  "case-law-citations.json": "courtDecisions",
+  "_driver/predelivery-lint.json": "machineQc",
+  "_driver/escalation-state.json": "machineQc",
+  "_driver/reasoning-integrity.json": "machineQc",
+  "_driver/corrections-state.json": "machineQc",
+  "common-law-grid.json": "marketplaceWeb",
+};
+
+/** The stores no row describes honestly, each with its reason. */
+export const STORES_WITHOUT_A_PART = {
+  "_driver/enforcer-signals.json": "presentation-only lines about enforcement, and no shipped name describes them",
+  "status.json": "the pool's mark name and a machine note, neither of them a part of the report",
+  "_driver/search-policy.json": "the product's identity, which no shipped name describes",
+  "_driver/profile.json": "the pool's profile stamp, not a part of the report",
+};
+
+// The record set is a folder, not a named store (publish-inputs.mjs NOT_READ_BY_NAME), and is read as one.
+const RECORDS = "_records/";
+
+const partName = (key) => PART_NAMES[key] ?? RULED_WORDS[key];
+
+/** The state of every store the publisher reads, as `base` holds it now: read, damaged or absent. */
+export function storeStates(base) {
+  const states = {};
+  for (const name of Object.keys(PUBLISH_INPUTS)) {
+    try { states[name] = readStore(base, name).state; } catch { states[name] = "damaged"; }
+  }
+  states[RECORDS] = recordsState(base);
+  return states;
+}
+
+/** The store states delivery recorded, or null for a run delivered before it recorded them. */
+export function readDeliveredStores(runDir) {
+  try {
+    const stores = JSON.parse(readFileSync(driverDir(runDir, DEGRADED_PARTS_FILE), "utf8"))?.stores;
+    return stores && typeof stores === "object" && !Array.isArray(stores) ? stores : null;
+  } catch { return null; }
+}
+
+/**
+ * The parts publishing finds degraded, from the store states now and, where delivery recorded them, then.
+ * PURE over its inputs. `now` is `storeStates(base)`; `delivered` is `readDeliveredStores(runDir)`.
+ */
+export function degradedAtPublish(now = {}, delivered = null) {
+  const parts = [];
+  const mapped = { ...STORE_PARTS, [RECORDS]: "officialRecords" };
+  for (const [store, key] of Object.entries(mapped)) {
+    const state = now[store];
+    const cause = state === "damaged" ? `${store} is present and cannot be read`
+      : state === "absent" && delivered?.[store] === "read" ? `${store} was read at delivery and is missing now`
+        : null;
+    if (cause) parts.push({ part: `store:${store}`, name: partName(key), reason: NOT_COMPLETED, cause });
+  }
+  return parts;
+}
+
+/** One row per area across lists, the first kept: delivery's rows, then publishing's. */
+export function mergeDegradedRows(...lists) {
+  const seen = new Set();
+  const rows = [];
+  for (const r of lists.flat()) {
+    if (!r || typeof r.area !== "string" || seen.has(r.area)) continue;
+    seen.add(r.area);
+    rows.push(r);
+  }
+  return rows;
+}
+
+// ── THE KNOCKOUT: A STEP THAT FAILED AS A WHOLE ───────────────────────────────────────────────────────
+//
+// The listing of filings and the owner lookups each end in one run-log event, a success or a failure, and
+// the last of the pair is the step's state at delivery, so a resume that succeeded clears it. The
+// plain-language review logs its outcome; the three that ship the rater's wording unreviewed are failures.
+const REVIEW_FAILED = ["stage-failed", "artifact-unreadable", "rewrite-refused-by-the-merged-gate"];
+
+/** Which of the knockout's whole steps ended failed, each with its raw cause for the run's record. */
+export function knockoutStepFailures(runDir) {
+  const log = readJsonl(driverDir(runDir, "run.jsonl"));
+  const listing = lastEvent(log, ["knockout-register-records", "knockout-register-records-refused", "knockout-register-records-failed"]);
+  const owners = failedStep(log, "knockout-owner-checks", "knockout-owner-checks-failed");
+  const review = lastEvent(log, ["knockout-review"]);
+  const cause = (e) => String(e?.cause ?? e?.reason ?? e?.outcome ?? e?.event ?? "no cause recorded");
+  return {
+    listing: listing?.event === "knockout-register-records-failed" ? { reason: reasonFor(cause(listing)), cause: cause(listing) } : null,
+    ownerChecks: owners ? { reason: reasonFor(cause(owners)), cause: cause(owners) } : null,
+    review: REVIEW_FAILED.includes(review?.outcome) ? { reason: reasonFor(cause(review)), cause: `${review.outcome}: ${cause({ reason: review.reason })}` } : null,
+  };
+}

package/driver/deliver-trigger.sh

@@ -43,7 +43,7 @@ MSG="The trademark engine's outbox has pending events. Run the clearotron-delive
 # slim container. Without it `timeout …` is simply a command that is not there: bash answers 127, and
 # because this script runs under `set -u` and NOT `set -e`, it sails straight on. outbox-backoff.mjs
 # then judges 127 the way it judges any nonzero exit and records `nonzero_exit_127` — a WAKE FAILURE.
-# So the operator reads "wake for clawdi failed" in the journal, goes looking at the CLI, at auth, at
+# So the operator reads "wake for <agent> failed" in the journal, goes looking at the CLI, at auth, at
 # the agent, and the answer is that a package is missing on the box. Deliveries stop, backoff climbs,
 # every diagnosis points somewhere real and wrong. That is the silent class this repo keeps paying
 # for, so it is turned into one sentence that names the cause.

package/driver/demo-container.mjs

@@ -26,6 +26,7 @@
 import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, resolve, sep } from "node:path"; import { studioDirFor } from "../shared/pre-rename-spellings.mjs";
+import { config } from "./driver.config.mjs";   // — the install's own default agent, never a literal
 
 /** The entry file each lane's publisher reads as its source, in the order a child is probed for one. */
 export const ENTRY_FILES = Object.freeze(["report.md", "knockout-findings.json"]);
@@ -200,7 +201,9 @@ export function seedDemoRuns({ workspace, examplesDir, portalOrigin = null }) {
     let s;
     try { s = JSON.parse(readFileSync(join(run, "status.json"), "utf8")); } catch { continue; }
     if (!s?.slug || !s?.codename || !s?.date) continue;
-    const dir = join(studioDirFor(join(workspace, `workspace-${s.agent || "clawdi"}`)), s.slug, `${s.date}-${s.codename}`);
+    // THE FALLBACK IS THE INSTALL'S OWN DEFAULT AGENT, not a literal (ruling 563). It fires only for a
+    // sample whose status.json carries no agent; all four shipped samples carry one.
+    const dir = join(studioDirFor(join(workspace, `workspace-${s.agent || config.defaultAgent}`)), s.slug, `${s.date}-${s.codename}`);
     if (existsSync(join(dir, "status.json"))) already.push(s.runId);
     else {
       // ONE SAMPLE'S UNREADABLE FILE COSTS THAT SAMPLE ONLY, and is named, never a throw out of the loop.

package/driver/dev-portal.mjs

@@ -32,7 +32,7 @@
 import { envFileRead } from "../shared/env-local.mjs";   // side effect: apply this install's .env when THIS file is the CLI entry (never on library import)
 import { createServer, request as httpRequest } from "node:http";
 import { readFileSync, existsSync, statSync, readdirSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
-import { join, resolve, extname, dirname } from "node:path"; import { studioDirFor } from "../shared/pre-rename-spellings.mjs";
+import { join, resolve, extname, dirname, sep } from "node:path"; import { studioDirFor } from "../shared/pre-rename-spellings.mjs";
 import { fileURLToPath } from "node:url";
 import { config } from "./driver.config.mjs";
 import { BRAND } from "../shared/brand.mjs";
@@ -78,7 +78,7 @@ export const DEV_COCKPIT_JOB_FIELDS = Object.freeze({
       + "is a form for composing REAL dev runs; a fixture run is declared by the job file that wants one, so "
       + "the fact travels with the run rather than with whoever filled in a form.",
     promptParts: "the requester's declaration that the prose rides as SIDECAR files. The cockpit composes a job "
-      + "from its own form and writes no sidecars, so it may not claim that shape (#1085).",
+      + "from its own form and writes no sidecars, so it may not claim that shape.",
     forwarderDomain: "the cockpit's assembler defaults it; a dev form has no forwarding domain to state.",
     provider: "which register vendor answers is the dev instance's own configuration, not a form field.",
     name: "the pre-markName spelling of the search subject. The form posts `mark`.",
@@ -253,7 +253,7 @@ function cockpitHtml() {
   <label>Extra marketplaces (comma — ADDED to the account's own)</label><input name="platforms" placeholder="gnc.com">
   <label><input type="checkbox" name="worldwide" style="width:auto"> worldwide (search everywhere; NOT the same as leaving countries blank)</label>
   <label><input type="checkbox" name="nativeLanguage" style="width:auto"> native-language investigation (multi-country focus search only)</label>
-  <label>Saved search (recipe key — leave the product blank)</label><input name="recipeKey" id="f_recipe" placeholder="quarterly-screen">
+  <label>Saved search (recipe key — leave the product blank)</label><input name="recipeKey" id="f_recipe" placeholder="standard-clearance">
   <label>Batch marks (knockout — one per line, optional "NAME [9, 42]")</label><textarea name="marks" placeholder="IRONWHISK [8, 21]&#10;CLUVENDRA&#10;SUNDAY ROAST CLUB [21, 35]"></textarea>
   <label>Classes (comma)</label><input name="classes" placeholder="9,42">
   <label>Goods / services</label><textarea name="goods"></textarea>
@@ -271,7 +271,7 @@ function cockpitHtml() {
  <div id="searches" style="margin-top:8px">loading…</div></section>
 <section><h2>Compose a saved search</h2>
  <form id="sf">
-  <label>Slug (filename + trigger key) *</label><input name="slug" placeholder="quarterly-screen" required>
+  <label>Slug (filename + trigger key) *</label><input name="slug" placeholder="standard-clearance" required>
   <label>Label (display name) *</label><input name="label" placeholder="Quarterly product-name screen" required>
   <label>Base search (the product this saved search runs) *</label><select name="base" id="sf_base"></select>
   <label><input type="checkbox" name="registerProbe" style="width:auto"> + register filing counts (knockout bases only)</label>
@@ -470,7 +470,7 @@ export function startPortal({ poolRoot = null, port = 18899, host = "127.0.0.1",
       // Static pool files. decodeURIComponent + resolve + prefix check = traversal-guarded.
       let p;
       try { p = resolve(root, "." + decodeURIComponent(url.pathname)); } catch { res.writeHead(400); return res.end(); }
-      if (p !== root && !p.startsWith(root + "/")) { res.writeHead(400); return res.end("bad path"); }
+      if (p !== root && !p.startsWith(root + sep)) { res.writeHead(400); return res.end("bad path"); }   // resolve() gives this machine's separator
       if (existsSync(p) && statSync(p).isDirectory()) p = join(p, "index.html");
       if (!existsSync(p)) { res.writeHead(404, { "content-type": "text/plain" }); return res.end("not found in the dev pool"); }
       sendFile(res, p);

package/driver/dispatch-record.mjs

@@ -37,7 +37,7 @@
 import { createHash } from "node:crypto";
 import { mkdirSync, readFileSync, renameSync, writeFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
-import { driverDir } from "../shared/driver-dir.mjs";   //
+import { driverDir, driverFileName } from "../shared/driver-dir.mjs";   //
 
 export const DISPATCH_SUFFIX = "dispatch.txt";
 
@@ -115,7 +115,7 @@ export function dispatchGrantState(dispatch, ranTools) {
  */
 export function recordDispatch(runDir, stage, { attempt, repair = 0, kind = "fresh", message, grant } = {}) {
   if (!runDir) return null;
-  const name = dispatchFileName(stage, attempt, repair);
+  const name = driverFileName(dispatchFileName(stage, attempt, repair));   // on Windows the label's colon is written %3A
   try {
     const text = String(message ?? "");
     const buf = Buffer.from(text, "utf8");