clearotron 0.3.2-beta.7 → 0.3.2-beta.9

package/scripts/mint-offered-territories.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// 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
+//
+// mint-offered-territories.mjs — write the places the New Clearance form offers, derived by rule.
+//
+// The list is `searchableTerritories()` (driver/register-coverage.mjs): every place at least one supported
+// register can search, named by its shipped label or the runtime's standard English name, never by hand.
+// It is written ONCE, to shared/offered-territories.json, and read from there by both halves that must
+// agree — the form (portal-ui composerProduct.ts, at build time) and the engine's mirror of it
+// (driver/compose-read.mjs PROMPT_TERRITORIES). Two lists kept equal by a test drift in the gap between
+// runs; one file read twice cannot.
+//
+// A COMMITTED file rather than a runtime call, for two reasons. The portal is a browser bundle and cannot
+// run the engine's resolver; and what the form offers should change when somebody re-mints it and reads
+// the diff, not silently when a provider's coverage table is edited. `generated-files-are-current.mjs`
+// runs this with --check, so a coverage change that moves the list reds until it is minted.
+//
+// Usage:  node scripts/mint-offered-territories.mjs [--check]
+//   --check  exit 1 if the committed file disagrees with a fresh derivation, printing the difference
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REPO = dirname(dirname(fileURLToPath(import.meta.url)));
+const OUT = join(REPO, "shared", "offered-territories.json");
+
+/** The file's content, derived fresh. Regions first, then countries, each as `{code, name}`. */
+export async function deriveOfferedTerritories() {
+  const { searchableTerritories } = await import("../driver/register-coverage.mjs");
+  const { territoryTier } = await import("../driver/territory-tiers.mjs");
+  const { offered, unnamed } = await searchableTerritories();
+  const regions = [], countries = [], untiered = [];
+  for (const t of offered) {
+    const tier = territoryTier(t.name);
+    if (tier === "region") regions.push(t);
+    else if (tier === "country") countries.push(t);
+    else untiered.push(t.code);
+  }
+  return {
+    _generated: "by scripts/mint-offered-territories.mjs from searchableTerritories() — do not edit; re-mint",
+    regions, countries,
+    // Recorded, not dropped: a searchable place the list could not name, or could not place in a tier.
+    left_out: { unnamed, untiered },
+  };
+}
+
+const render = (doc) => JSON.stringify(doc, null, 2) + "\n";
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  const next = render(await deriveOfferedTerritories());
+  if (process.argv.includes("--check")) {
+    let current;
+    try { current = readFileSync(OUT, "utf8"); }
+    catch { console.error(`mint-offered-territories: ${OUT} is missing — run without --check to mint it.`); process.exit(1); }
+    if (current === next) {
+      const doc = JSON.parse(current);
+      console.log(`offered-territories: current, ${doc.regions.length} region(s) and ${doc.countries.length} countr(ies).`);
+      process.exit(0);
+    }
+    const names = (s) => { const d = JSON.parse(s); return new Set([...d.regions, ...d.countries].map((t) => `${t.code} ${t.name}`)); };
+    const [a, b] = [names(current), names(next)];
+    for (const x of b) if (!a.has(x)) console.error(`  + ${x}`);
+    for (const x of a) if (!b.has(x)) console.error(`  - ${x}`);
+    console.error("offered-territories: the committed list disagrees with the rule — re-mint: node scripts/mint-offered-territories.mjs");
+    process.exit(1);
+  }
+  writeFileSync(OUT, next);
+  const doc = JSON.parse(next);
+  console.log(`offered-territories: wrote ${doc.regions.length} region(s) and ${doc.countries.length} countr(ies) to ${OUT}`);
+}

package/scripts/mint-public-residue.mjs

@@ -17,7 +17,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { CLASSES, censusOf, publishedOf } from "../shared/reference-guard-classes.mjs";
+import { CLASSES, censusOf, publishedOf, publishedReader } from "../shared/reference-guard-classes.mjs";
 import { trackedFiles, skipReason } from "../shared/tracked-files.mjs";
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";
 
@@ -35,7 +35,7 @@ export function mint() {
   const p = publishedOf(tracked, ROOT);
   if (p.error) { console.error(`mint-public-residue: ${p.error}`); process.exit(2); }
   if (p.laid) console.log(`mint-public-residue: ${p.laid} tracked path(s) are not in HEAD — laid over this checkout, not published in it, and not counted`);
-  const c = censusOf(p.files, (f) => readFileSync(join(ROOT, f), "utf8"));
+  const c = censusOf(p.files, publishedReader(ROOT, (f) => readFileSync(join(ROOT, f), "utf8")));
   return { classes: CLASSES.map((x) => x.id), total: c.total, files: c.files };
 }
 

package/scripts/mint-reference-strip-backlog.mjs

@@ -14,7 +14,7 @@
 // CI runs. Without it, the table is rewritten.
 import { readFileSync, writeFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
-import { publishedOf } from "../shared/reference-guard-classes.mjs";
+import { publishedOf, publishedReader } from "../shared/reference-guard-classes.mjs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { SIGNATURES, censusOf } from "../driver/reference-strip-signatures.mjs";
@@ -34,7 +34,7 @@ const p = publishedOf(all, ROOT);
 if (p.error) { console.error(`mint-reference-strip-backlog: ${p.error}`); process.exit(2); }
 if (p.laid) console.log(`mint-reference-strip-backlog: ${p.laid} tracked path(s) are not in HEAD — laid over this checkout, not published in it, and not counted`);
 const tracked = p.files;
-const minted = censusOf(ROOT, tracked, (f) => readFileSync(join(ROOT, f), "utf8"));
+const minted = censusOf(ROOT, tracked, publishedReader(ROOT, (f) => readFileSync(join(ROOT, f), "utf8")));
 
 if (process.argv.includes("--check")) {
   const have = JSON.parse(readFileSync(TABLE, "utf8"));

package/scripts/mint-suite-census.mjs

@@ -39,7 +39,7 @@ import { CENSUS_WORKSPACES, CENSUS_ROOT_SCRIPTS, countTestSites, collectionFromM
 // THE MEASUREMENT SIDE of the root-script check: the census states the globs it expects and this
 // supplies what the corpus actually resolves to, so the two can disagree.
 import { providerTestFiles } from "./test-full.mjs";
-import { withheldEntryFor, announceWithheldMode } from "../shared/withheld-paths-access.mjs";   // — withheld is a stated absence, not a loss.: the record does not ship, and without it every absence is a loss
+import { withheldEntryFor, announceWithheldMode, CUT_RECORD_PRESENT } from "../shared/withheld-paths-access.mjs";   // — withheld is a stated absence, not a loss.: the record does not ship, and without it every absence is a loss
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";   // — realpath both sides, or a symlinked invocation exits 0 silently
 import { publishedOf } from "../shared/reference-guard-classes.mjs";
 
@@ -73,6 +73,60 @@ const README = [
   "RE-STAMP DELIBERATELY:  node scripts/mint-suite-census.mjs --apply",
 ];
 
+/**
+ * WHAT A LAID PATH MEANS DEPENDS ON THE TREE, and this census used to answer the same way for both.
+ *
+ * It printed that some tracked paths were not in HEAD and not counted, and then reported the population
+ * as "unchanged" — a summary of a population it had just said it did not read. Measured twice on
+ * 2026-09-17, from opposite directions: mid-merge it dropped every path arriving from the other parent,
+ * and with an ordinary new test file staged it dropped that, because `git add` puts a file in the index
+ * and only a commit puts it in HEAD. Both printed the note; both reported unchanged; one shipped a census
+ * six tests and twenty-three assertions short and was caught by `--check` afterwards rather than here.
+ *
+ * THE DISCRIMINATOR ALREADY EXISTS and is the cut record. Under the private overlay a laid path is the
+ * withheld corpus staged over a clone — expected, and excluding it is the whole reason HEAD is consulted
+ * rather than the index. With no cut record nothing is withheld from this tree, so a tracked path missing
+ * from HEAD is not a withheld file: it is work the author has staged and is about to leave out of the
+ * stamp. That is the strict mode this repository already declares for every other absence.
+ *
+ * So it refuses there, and names the paths. It does NOT refuse under the overlay, because that would break
+ * the case HEAD-filtering was introduced for — and a guard that fires on the legitimate use is one
+ * somebody switches off.
+ *
+ * Pure, and takes the cut-record flag rather than reading it, so both branches can be driven. The flag is
+ * fixed when its module is imported and a test cannot flip it without writing into the tree.
+ */
+export function laidPathVerdict({ laid = 0, laidPaths = [], cutRecordPresent = false, overlayLaid = null } = {}) {
+  if (!laid) return { refuse: false, message: null };
+  if (cutRecordPresent) {
+    return { refuse: false,
+      message: `mint-suite-census: ${laid} tracked path(s) are not in HEAD — laid over this checkout, not published in it, and not counted` };
+  }
+  // THE OVERLAY SAYS WHAT IT LAID, because the cut record this leaned on is carried by no tree, the
+  // overlaid one included (shared/withheld-paths-access.mjs says so of itself). So under the private
+  // overlay this refused every run, and the arm that runs every minter over the overlaid tree went red on
+  // a census that was current. The overlay now writes the paths it laid into the clone's own `.git`, where
+  // nothing tracks or ships them. A staged path on that list is laid; one that is not is still staged work
+  // and still refuses — the list excuses exactly what the overlay put there and nothing beside it.
+  const unlisted = overlayLaid ? laidPaths.filter((f) => !overlayLaid.has(f)) : laidPaths;
+  if (overlayLaid && !unlisted.length) {
+    return { refuse: false,
+      message: `mint-suite-census: ${laid} tracked path(s) are not in HEAD — laid by the private overlay, which lists every one, and not counted` };
+  }
+  laidPaths = unlisted;
+  laid = unlisted.length;
+  const named = laidPaths.slice(0, 20).map((f) => `    ${f}`).join("\n");
+  const more = laidPaths.length > 20 ? `\n    … and ${laidPaths.length - 20} more` : "";
+  return { refuse: true,
+    message: `mint-suite-census: ${laid} tracked path(s) are in the index and NOT in HEAD, and this tree carries no\n`
+      + "  cut record — so nothing here is withheld and these are not laid-over files. They are staged work,\n"
+      + "  and a census minted now would be stamped over a population it did not read:\n"
+      + `${named}${more}\n`
+      + "  Commit them first, then mint. `git add` puts a file in the index; only a commit puts it in HEAD,\n"
+      + "  and this reads HEAD so the private overlay's withheld corpus is not counted as an addition.\n"
+      + "  Mid-merge this is the same fault wearing different clothes: commit the merge, then mint." };
+}
+
 /**
  * The tracked files matching `globs` that HEAD actually carries.
  *
@@ -94,6 +148,22 @@ const README = [
  * A tree with no HEAD cannot say what it published. That is a failure to look, and it exits rather
  * than reading as "nothing is laid here", which is the permissive answer and the one that passes.
  */
+/**
+ * The paths the private overlay says it laid over this clone, or null where it laid nothing.
+ *
+ * Read from the clone's own git directory, `info/overlay-laid`, one path per line. Inside `.git` on
+ * purpose: nothing there is tracked, so it can never reach the published tree or be counted by a guard,
+ * and a developer's checkout has no such file unless an overlay wrote it.
+ */
+export function overlayLaidOf(root) {
+  try {
+    const gitDir = execFileSync("git", ["-C", root, "rev-parse", "--absolute-git-dir"], { encoding: "utf8" }).trim();
+    const list = join(gitDir, "info", "overlay-laid");
+    if (!existsSync(list)) return null;
+    return new Set(readFileSync(list, "utf8").split("\n").map((x) => x.trim()).filter(Boolean));
+  } catch { return null; }
+}
+
 function publishedFiles(root, globs) {
   let all = [];
   try {
@@ -103,7 +173,10 @@ function publishedFiles(root, globs) {
   if (!all.length) return [];
   const p = publishedOf(all, root);
   if (p.error) { console.error(`mint-suite-census: ${p.error}`); process.exit(2); }
-  if (p.laid) console.log(`mint-suite-census: ${p.laid} tracked path(s) are not in HEAD — laid over this checkout, not published in it, and not counted`);
+  const verdict = laidPathVerdict({ laid: p.laid, laidPaths: p.laidPaths ?? [], cutRecordPresent: CUT_RECORD_PRESENT,
+    overlayLaid: overlayLaidOf(root) });
+  if (verdict.refuse) { console.error(verdict.message); process.exit(2); }
+  if (verdict.message) console.log(verdict.message);
   return p.files.slice().sort();
 }
 

package/scripts/mint-writing-standard-backlog.mjs

@@ -25,7 +25,7 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CLASSES, censusOf } from "../shared/writing-standard-classes.mjs";
-import { publishedOf } from "../shared/reference-guard-classes.mjs";
+import { publishedOf, publishedReader } from "../shared/reference-guard-classes.mjs";
 import { trackedFiles, skipReason } from "../shared/tracked-files.mjs";
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";
 
@@ -43,7 +43,7 @@ export function mint() {
   const p = publishedOf(tracked, ROOT);
   if (p.error) { console.error(`mint-writing-standard-backlog: ${p.error}`); process.exit(2); }
   if (p.laid) console.log(`mint-writing-standard-backlog: ${p.laid} tracked path(s) are not in HEAD — laid over this checkout, not published in it, and not counted`);
-  const c = censusOf(p.files, (f) => readFileSync(join(ROOT, f), "utf8"));
+  const c = censusOf(p.files, publishedReader(ROOT, (f) => readFileSync(join(ROOT, f), "utf8")));
   return { classes: CLASSES.map((x) => x.id), total: c.total, files: c.files };
 }
 

package/scripts/purge-runs.mjs

@@ -13,8 +13,8 @@
 // republishable from the workspace archive, which does not satisfy "gone":
 //
 //   1. pool     <poolRoot>/<runId>/                                    — published, Caddy-served
-//   2. archive  <ws>/studio/prelim-search/archive/<YYYY-MM>/<matter>/<codename>/  — republish source
-//   3. live     <ws>/studio/prelim-search/<matter>/<codename>/         — running/failed, never published
+//   2. archive  <ws>/studio/clearance-search/archive/<YYYY-MM>/<matter>/<codename>/  — republish source
+//   3. live     <ws>/studio/clearance-search/<matter>/<codename>/         — running/failed, never published
 //
 // Dry-run is the default and --apply is required to remove anything. The guards below exist because
 // the failure that matters is not "deleted too little" — it is deleting the one run someone wanted
@@ -24,7 +24,7 @@ import "../shared/env-local.mjs";   // — FIRST: the CLEAROTRON_* translation m
                                      // module-top capture below it evaluates. A call in this file's BODY
                                      // would run too late — that was the repair that left this open.
 import { readdirSync, statSync, readFileSync, rmSync, existsSync, appendFileSync } from "node:fs";
-import { join, basename } from "node:path";
+import { join, basename } from "node:path"; import { studioDirFor } from "../shared/pre-rename-spellings.mjs";
 import { driverDir } from "../shared/driver-dir.mjs";   //
 import { pendingRunIds, noticeOwed } from "../shared/notice-owed.mjs";   // one reading of "still owes a notice", shared with the delivery path
 // The ONE exception to this script's no-driver-imports posture, and it is the reason that posture exists:
@@ -94,10 +94,10 @@ const WORKSPACE_ROOT = requireRoot("CLEAROTRON_WORK_DIR", "workspace");
 // same answer to a careless reader, and the careless answer is DELETE.
 // THE SAME RESOLUTION THE DELIVERY PATH USES, including its default. Reading only the environment
 // variable would be a SECOND resolution, and a wrong one: `driver.config.mjs` falls back to
-// `<workspaceRoot>/prelim-outbox`, so on every box that does not set the variable — which is most of
+// `<workspaceRoot>/clearance-outbox`, so on every box that does not set the variable — which is most of
 // them — an env-only read answers "no outbox" for an outbox that exists and has markers in it. That is
 // the same class of defect as not looking at all.
-const OUTBOX_DIR = String(process.env.CLEAROTRON_OUTBOX_DIR ?? "").trim() || join(WORKSPACE_ROOT, "prelim-outbox");
+const OUTBOX_DIR = String(process.env.CLEAROTRON_OUTBOX_DIR ?? "").trim() || join(WORKSPACE_ROOT, "clearance-outbox");
 const OUTBOX_NAMES = (() => {
   try { return readdirSync(OUTBOX_DIR); } catch (e) {
     // AN OUTBOX THAT WAS NEVER CREATED IS EMPTY; ONE THAT WILL NOT OPEN IS UNKNOWN. Collapsing the two
@@ -172,7 +172,7 @@ const POOL_NON_RUN = new Set(["assets", "customer", "_state"]);
 // system's own state is not.
 const RUN_ARTIFACTS = ["meta.json", "report.html", "report.md", "findings.json", "status.json"];
 const looksLikeRun = (dir) => RUN_ARTIFACTS.some((f) => existsSync(join(dir, f)));
-// Not matter directories inside a workspace prelim-search root.
+// Not matter directories inside a workspace clearance-search root.
 const WS_NON_MATTER = new Set(["STATUS.md", "archive", "queue", "_known-conflicts"]);
 
 const readJson = (p) => { try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; } };
@@ -210,7 +210,7 @@ function collect() {
   }
 
   for (const agent of AGENTS) {
-    const base = join(WORKSPACE_ROOT, `workspace-${agent}`, "studio", "prelim-search");
+    const base = studioDirFor(join(WORKSPACE_ROOT, `workspace-${agent}`));
     if (!isDir(base)) continue;
 
     // 2. Workspace archive — <YYYY-MM>/<matter>/<codename>. runId is matter+codename, matching the

package/scripts/reconcile-runs.mjs

@@ -35,7 +35,7 @@
 import "../shared/env-local.mjs";   // — FIRST: applies the CLEAROTRON_* translation before any module-top
 // capture evaluates. Reads no `.env` here — that load is gated on isCliEntry(argv[1]).
 import { readdirSync, readFileSync, writeFileSync, renameSync, existsSync } from "node:fs";
-import { join } from "node:path";
+import { join } from "node:path"; import { studioDirFor } from "../shared/pre-rename-spellings.mjs";
 import { DRIVER_DIR } from "../shared/driver-dir.mjs";   //
 import { classifyRun, terminalPatch, DEFAULT_QUIET_MS } from "../driver/reconcile-runs.mjs";
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";   // — realpath both sides, or a symlinked invocation exits 0 silently
@@ -120,7 +120,7 @@ function main() {
   const now = Date.now();
   const rows = [];
   for (const agent of AGENTS) {
-    const studio = join(WORKSPACE_ROOT, `workspace-${agent}`, "studio", "prelim-search");
+    const studio = studioDirFor(join(WORKSPACE_ROOT, `workspace-${agent}`));
     for (const dir of findRunDirs(studio)) rows.push({ agent, ...reconcileRunDir(dir, { apply: APPLY, now, quietMs: QUIET_MS }) });
   }
 

package/scripts/release-approve-parked.mjs

@@ -99,7 +99,25 @@ async function branchHead() {
   return (await br.json())?.commit?.sha ?? null;
 }
 
-async function main() {
+/**
+ * ONE PASS: read the version branch's head, and approve any run parked on exactly that head.
+ *
+ * EXPORTED BECAUSE ONCE IS NOT ENOUGH. The step that calls this runs before a wait that then lasts
+ * minutes, and the version branch is force-pushed whenever the version step runs — so main moving
+ * during the wait leaves a fresh parked run on a fresh head with nobody left to approve it. Measured on
+ * the 0.3.2-beta.8 cut: two heads, one approval, cleared by hand. `awaitCut` calls this once per poll
+ * so the second head gets the same look the first did.
+ *
+ * IT NEVER THROWS AND NEVER RETURNS NON-ZERO. A pass that cannot look says so and reports nothing
+ * approved; the cut's own wait ends the way it always did. Approving is a convenience, and a
+ * convenience that can fail a release is not one.
+ */
+export async function approvePass() {
+  try { return await onePass(); }
+  catch (e) { say(`could not run (${e?.message ?? e}) — nothing approved.`); return 0; }
+}
+
+async function onePass() {
   // THE ABSENT SECRET IS THE ORDINARY CASE UNTIL THE TOKEN IS MINTED, and it must read as ordinary.
   if (!TOKEN) {
     say("no ACTIONS_APPROVE_TOKEN — nothing approved; the version run waits for a person, as before.");
@@ -148,4 +166,4 @@ async function main() {
 // RUN WHEN INVOKED, whatever the file is called. The old guard compared argv[1] to this file's NAME, so
 // a rename made the step print nothing and exit 0 — a script that never ran, wearing the face of a
 // successful no-op. Comparing the resolved URLs asks the real question instead.
-if (import.meta.url === pathToFileURL(argv[1] ?? "").href) main().then((c) => exit(c)).catch((e) => { say(`could not run (${e?.message ?? e}) — nothing approved.`); exit(0); });
+if (import.meta.url === pathToFileURL(argv[1] ?? "").href) approvePass().then((c) => exit(c));

package/scripts/release-await-cut.mjs

@@ -48,6 +48,7 @@
 // one question is how a pipeline comes to publish something nobody merged.
 import { appendFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
+import { approvePass } from "./release-approve-parked.mjs";
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";
 import { cutDecision, versionAtHead, tagsHere } from "./release-cut-decision.mjs";
 
@@ -117,10 +118,23 @@ export const STEP_MS = 30 * 1000;
  *
  * Returns `{ cut, version, waitedMs, gaveUp }`. `gaveUp` is not a failure — see the header.
  */
-export async function awaitCut({ refresh, read, sleep, waitMs = WAIT_MS, stepMs = STEP_MS, now = () => 0 } = {}) {
+export async function awaitCut({ refresh, read, sleep, tend = null, waitMs = WAIT_MS, stepMs = STEP_MS, now = () => 0 } = {}) {
   const started = now();
   let waitedMs = 0;
   for (;;) {
+    // ── THE SECOND LOOK, EVERY PASS ────────────────────────────────────────────────────────────────
+    //
+    // `tend` is the parked-run approval, and it is here rather than once before the loop because the
+    // version branch is force-pushed whenever the version step runs. If main moves while this waits,
+    // the version pull request is refreshed onto a new head, that head parks a run of its own, and the
+    // approval already spent was spent on a head that no longer exists.
+    //
+    // IT CANNOT BREAK THE WAIT. A tend that throws is reported and the pass continues: this loop's job
+    // is to notice a merge, and it must keep doing that whether or not a convenience beside it worked.
+    if (tend) {
+      try { await tend(); }
+      catch (e) { console.log(`release-await-cut: the parked-run look failed (${String(e?.message ?? e).slice(0, 120)}) — the wait continues.`); }
+    }
     await refresh();
     const d = read();
     // ASKED BEFORE THE FIRST SLEEP, so a merge that landed while CI was finishing costs no wait at all —
@@ -135,6 +149,91 @@ export async function awaitCut({ refresh, read, sleep, waitMs = WAIT_MS, stepMs
 
 const git = (args) => execFileSync("git", args, { encoding: "utf8" });
 
+/**
+ * Was a cut ASKED FOR by this run, and which pull request is it waiting on.
+ *
+ * A push and the schedule set nothing in motion — they ask main a question and the cron floor sits
+ * underneath either answer. A dispatch is different: the same run opened the version pull request and
+ * told it to merge itself, so the wait expiring means the thing this run was for did not happen.
+ */
+export function cutRequest(env = process.env) {
+  const asked = String(env.CLEAROTRON_CUT_REQUESTED ?? "").trim() === "true";
+  const pr = String(env.CLEAROTRON_CUT_PR ?? "").trim();
+  return { asked, pr: /^[0-9]+$/.test(pr) ? Number(pr) : null };
+}
+
+/**
+ * What to say when the budget expires, and whether it is a failure. PURE.
+ *
+ * THE DISTINCTION THIS EXISTS FOR. Three ways to publish nothing look identical from outside:
+ * nothing was set in motion, this run set something in motion and it did not land, and the loop could
+ * not look at all. The third is exit 2 and is decided before this is reached. The first two are what
+ * this separates, and until it did, a dispatched cut that released nothing reported success — measured
+ * twice on 2026-09-17, on runs 35202212206 and 35260883981.
+ *
+ * NAMING WHICH IS HALF THE POINT. A red that says only "did not merge" sends the next reader to the
+ * same log this was written from. The reason is read off the pull request rather than guessed.
+ */
+export function expiryVerdict({ cut, requested, pr = null }) {
+  if (cut) return { red: false, reason: null };
+  if (!requested) return { red: false, reason: null };
+  if (!pr) return { red: true, reason: "a cut was dispatched, and no version pull request was found to wait on" };
+  // A PULL REQUEST THAT COULD NOT BE READ IS NOT ONE THAT WAS NOT FOUND. Both used to arrive here as
+  // `null`, so a failed read reported "no version pull request was found" about a pull request that was
+  // standing open — a confident wrong reason, on the one line this function exists to get right.
+  if (pr.unread) {
+    return { red: true, reason: `the version pull request (${pr.number}) could not be read, so why it did not merge is unknown — read it by hand (${pr.why})` };
+  }
+  if (pr.merged) return { red: true, reason: "the version pull request merged, yet main carries no untagged version — the publish this run was for has gone missing" };
+  const bad = (pr.checks ?? []).filter((c) => ["failure", "error", "timed_out", "cancelled", "action_required"].includes(c.conclusion));
+  if (bad.length) {
+    const named = bad.map((c) => `${c.context} (${c.conclusion})`).join(", ");
+    return { red: true, reason: `the version pull request did not merge: ${named}` };
+  }
+  if (!(pr.checks ?? []).some((c) => c.conclusion)) {
+    return { red: true, reason: "the version pull request did not merge: no check on it had concluded when the budget expired — it is most likely waiting for approval before its run will start" };
+  }
+  if (pr.mergeable === false) return { red: true, reason: "the version pull request did not merge: it is not mergeable" };
+  return { red: true, reason: "the version pull request did not merge, and nothing on it says why — read it by hand" };
+}
+
+/**
+ * One entry of the rollup, as a conclusion or `null` while it has none.
+ *
+ * THE ROLLUP HOLDS TWO SHAPES. A check run carries `conclusion`; a commit status carries `state` and no
+ * `conclusion` at all, so reading only the first counts every red status as not-yet-concluded.
+ */
+function conclusionOf(c) {
+  if (c.conclusion) return String(c.conclusion).toLowerCase();
+  if (c.state && !["PENDING", "EXPECTED"].includes(String(c.state).toUpperCase())) return String(c.state).toLowerCase();
+  return null;
+}
+
+/**
+ * The version pull request's state and its checks' conclusions. Injected so an arm can drive it.
+ *
+ * `null` means there was no number to read. A read that FAILED returns `{ unread: true }` instead, so the
+ * verdict can tell "no pull request" from "could not look at it".
+ */
+export async function readVersionPr(number, { run = ((args) => execFileSync("gh", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })) } = {}) {
+  if (!number) return null;
+  try {
+    const j = JSON.parse(run(["pr", "view", String(number), "--repo", "CordilleraSarl/clearotron",
+      "--json", "merged,mergeable,statusCheckRollup"]));
+    return {
+      merged: Boolean(j.merged),
+      mergeable: j.mergeable === "MERGEABLE" ? true : j.mergeable === "CONFLICTING" ? false : null,
+      checks: (j.statusCheckRollup ?? []).map((c) => ({
+        context: String(c.name ?? c.context ?? "a check"),
+        conclusion: conclusionOf(c),
+      })),
+    };
+  } catch (e) {
+    const why = String(e?.stderr || e?.message || e).trim().split("\n")[0].slice(0, 160);
+    return { unread: true, number, why };
+  }
+}
+
 /**
  * One read of `main`: the version it carries, whether that version is tagged, and WHICH COMMIT said so.
  *
@@ -209,6 +308,8 @@ function main() {
     // answer this pipeline cannot afford, so it is refreshed on every pass rather than once at checkout.
     refresh: async () => { git(["fetch", "--no-tags", "--prune", "origin", "+refs/heads/main:refs/remotes/origin/main"]); git(["fetch", "--tags", "--force", "origin"]); },
     read: () => readMain(),
+    // THE SAME SCRIPT THE STEP ABOVE RUNS, not a second implementation of the same decision.
+    tend: () => approvePass(),
     sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
     now: () => Date.now() - started,
   }).catch((e) => {
@@ -229,7 +330,10 @@ function main() {
   }).then((r) => {
     if (!r) return;
     const secs = Math.round(r.waitedMs / 1000);
+    // A DISPATCHED CUT DOES NOT GET THE REASSURANCE. The error below says what happened, and a line
+    // calling it ordinary directly above that error is the one a reader skimming the log stops at.
     if (r.cut) console.log(`release-await-cut: main carries ${r.version} with no tag, after ${secs}s. Publishing.`);
+    else if (cutRequest().asked) console.log(`release-await-cut: nothing to publish after ${secs}s — main carries ${r.version} and it is already tagged.`);
     else console.log(`release-await-cut: nothing to publish after ${secs}s — main carries ${r.version} and it is `
       + "already tagged, or the version branch did not merge. This is the ordinary outcome and not a fault; "
       + "the scheduled check is still underneath it.");
@@ -239,6 +343,21 @@ function main() {
     // `sha` IS WRITTEN ON BOTH ANSWERS, not only on a cut. It records which commit this loop's verdict is
     // about, so a run that published nothing can still be read back against the tree it looked at.
     if (out) appendFileSync(out, `cut=${r.cut ? "true" : "false"}\nversion=${r.version}\nsha=${r.sha ?? ""}\nlooked=true\n`);
+    return r;
+  }).then(async (r) => {
+    // ── A DISPATCHED CUT THAT PUBLISHED NOTHING IS A FAILED RUN ─────────────────────────────────────
+    //
+    // Everything above stays exit 0, and on a push or the schedule that is right: nothing was asked
+    // for, and the cron floor sits underneath. A dispatch is a request, and THIS run is what tries to
+    // satisfy it — it opened the version pull request and armed it. So the budget expiring means the
+    // one thing the run existed to do did not happen, and reporting success for that is how a release
+    // goes missing with every light green.
+    if (!r) return;                                   // could-not-look already exited 2 above
+    const { asked, pr } = cutRequest();
+    const v = expiryVerdict({ cut: r.cut, requested: asked, pr: asked && !r.cut ? await readVersionPr(pr) : null });
+    if (!v.red) return;
+    console.error(`::error::release-await-cut: this run dispatched a cut and released nothing. ${v.reason}`);
+    process.exitCode = 1;
   });
 }