shapeup-sdlc 3.5.0 → 3.7.0

package/kernel/probe/concurrency.mjs

@@ -30,13 +30,16 @@
 //
 // Usage: node kernel/harness.mjs probe concurrency --slug <slug> [--cwd <dir>] [--run-root <dir>]
 //                                                  [--round N] [--gap-s N] [--format json|table]
+//                                                  [--require-run-args]
 // Exit:  0 = a report was produced with at least one usable leg · 1 = ran, and no leg in scope had
 //        a usable interval (the report still prints, and says why) · 2 = malformed argv.
+//        With --require-run-args the report is skipped: 0 = run-args.json exists at this run root ·
+//        6 = it does not (mirrors `probe resume --require`'s "artifact absent" convention).
 
 import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { runArgs } from "../lib/argv.mjs";
-import { localRoot, runIdFromRoot, RECEIPT_FILE } from "../lib/paths.mjs";
+import { localRoot, runIdFromRoot, RECEIPT_FILE, RUN_ARGS_FILE } from "../lib/paths.mjs";
 
 /** The round-addressed order id forms `<scope>-r<N>-a<M>` and `<phase>-r<N>`. */
 const ROUND_SUFFIX = /^(.*?)-r(\d+)(?:-a(\d+))?$/;
@@ -301,16 +304,18 @@ export function summarise(index, legs) {
 /**
  * Which fan-out width the run was launched with — read, never assumed.
  *
- * The dial is written into `run-args.json` by the launcher. It is absent from every run recorded so
- * far, so the honest answer is the effective default WITH the fact that it is a default: reporting
- * `4` unqualified would assert an operator choice nobody made.
+ * The dial is written into `run-args.json` by `harness init run-args` (GATE L0.9b), the kernel
+ * writer tech-lead invokes right before the launch. A run opened before that writer existed, or one
+ * whose launcher never passed `--parallel-scopes`, still has no file or no key — so the honest
+ * answer stays the effective default WITH the fact that it is a default: reporting `4` unqualified
+ * would assert an operator choice nobody made.
  *
  * @param {string} runRoot - The run's LOCAL root.
  * @returns {{max_parallel_scopes:number, source:string}} The value and where it came from.
  */
 export function dialFrom(runRoot) {
   try {
-    const a = JSON.parse(readFileSync(join(runRoot, "run-args.json"), "utf8"));
+    const a = JSON.parse(readFileSync(join(runRoot, RUN_ARGS_FILE), "utf8"));
     const n = Number(a?.maxParallelScopes);
     if (Number.isFinite(n) && n >= 1) return { max_parallel_scopes: n, source: "run-args" };
     return { max_parallel_scopes: DEFAULT_MAX_PARALLEL_SCOPES, source: "default (run-args.json declares none)" };
@@ -474,7 +479,7 @@ export function table(r) {
 /** The typed argv contract (see `./lib/argv.mjs`). */
 export const ARGV_SPEC = {
   usage: "harness.mjs probe concurrency (--slug <slug> | --run-root <dir>) [--cwd <dir>] [--round N] " +
-         "[--gap-s N] [--format json|table]",
+         "[--gap-s N] [--format json|table] [--require-run-args]",
   _: { arity: 0, max: 0, name: "(no positional operands)" },
   slug: { type: "str" },
   // The archived-trace and post-export cases, and the same escape `verify t0 --out` has: a caller
@@ -484,6 +489,10 @@ export const ARGV_SPEC = {
   round: { type: "int", min: 1 },
   "gap-s": { type: "int", min: 1, default: DEFAULT_GAP_S },
   format: { type: "enum", values: ["json", "table"], default: "json" },
+  // The positive enforcer for the launch record (see the banner below). Skips the concurrency
+  // report entirely — this is a presence check, not a measurement, and the two must not be
+  // confused by sharing an exit code.
+  "require-run-args": { type: "flag" },
 };
 
 /**
@@ -492,6 +501,14 @@ export const ARGV_SPEC = {
  * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
  * @returns {void} Exits 0 when at least one leg had a usable interval, 1 when none did — and the
  *   report prints either way, because "nothing was measurable" is the answer, not an error.
+ *
+ *   `--require-run-args` is a different question with its own exit convention, mirroring
+ *   `probe resume --require`'s 0 (satisfied) / 6 (artifact absent): it never reaches the report at
+ *   all. The launch record had exactly one reader (`dialFrom()`, below) and zero enforcers — a
+ *   run missing it proceeded green with a silently substituted default, "indistinguishable from an
+ *   operator choice" (`gates.md` L0.9b). This flag is what `shapeup-run.js` calls at Preflight, before
+ *   ORIENT, so that state stops being invisible: this module already owns run-root resolution and the
+ *   file's path, so the check is a few lines here rather than a new kernel entry point.
  */
 export function cli(rawArgv) {
   const args = runArgs(ARGV_SPEC, rawArgv);
@@ -504,6 +521,14 @@ export function cli(rawArgv) {
     ? resolve(args.runRoot)
     : localRoot(resolve(args.cwd || process.cwd()), args.slug);
 
+  if (args.requireRunArgs) {
+    const path = join(runRoot, RUN_ARGS_FILE);
+    const present = existsSync(path);
+    console.log(JSON.stringify({ ok: present, run_root: runRoot, run_args_path: path,
+      reason: present ? null : "no run-args.json at this run root — GATE L0.9b's launch record was never written before this launch" }));
+    process.exit(present ? 0 : 6);
+  }
+
   const r = report(runRoot, { round: args.round ?? null, gapS: args.gapS });
   console.log(args.format === "table" ? table(r) : JSON.stringify(r));
   process.exit(r.launches.length ? 0 : 1);

package/kernel/probe/digest.mjs

@@ -6,7 +6,9 @@
 // Script-first by design: regex over known log formats is free (no model tokens); an
 // unrecognized line becomes a "raw" triple (file/line unknown) rather than being silently
 // dropped, so a Sonnet fallback (or a human) still has something to look at — this module never
-// invents a file:line it didn't find in the text.
+// invents a file:line it didn't find in the text. `file` and `line` are independent: a
+// diagnostic that names a file but no line number (a resource-compiler error, for example)
+// still yields its file — `line` stays null rather than being guessed at.
 //
 // Zero dependencies, zero network — same discipline as oracles/*.
 
@@ -19,6 +21,18 @@ const PATTERNS = [
   { re: /^(?:✗|not ok\b.*?)[^()]*\((.+?):(\d+)\)\s*$/, kind: "test-failure" },
   // ESLint/tsc style: "path/to/file.ts:12:34 - error TS2345: message"
   { re: /^(.+?):(\d+):\d+\s*[-–]\s*(?:error|warning)\b.*$/, kind: "compiler-diagnostic" },
+  // File-level diagnostic with NO line number: "resource.xml: error: message" or
+  // "resource.xml - fatal error: message" (resource compilers and linkers report this way —
+  // the failure is the whole file, so there is no line to cite). The file must look like a
+  // path (ends in a dotted extension, no embedded whitespace/colon) so this stays anchored to
+  // real diagnostics rather than matching arbitrary prose that happens to contain "error:".
+  { re: /^([^\s:]+?\.[A-Za-z0-9]{1,10})\s*[:\-–—]\s*(?:fatal\s+error|error|warning)\b.*$/i, kind: "compiler-diagnostic" },
+  // Bundler style: "ERROR in ./src/components/Foo.tsx" (webpack et al.) — file, no line. The
+  // captured token must look like a path — leads with "./"/"../", or ends in a dotted extension
+  // of 1-10 alnum chars (same anchor the sibling pattern above uses) — so prose after "ERROR in"
+  // ("ERROR in the build pipeline", "ERROR in test suite failed to run") is left unmatched
+  // instead of handing back a fabricated file.
+  { re: /^(?:ERROR|WARNING)\s+in\s+(\.{1,2}\/[^\s:]*|[^\s:]+\.[A-Za-z0-9]{1,10})\b/i, kind: "compiler-diagnostic" },
   // Generic "Error: message" line followed later by a stack — capture the message alone.
   { re: /^\s*(?:Error|TypeError|ReferenceError|AssertionError)\s*:\s*(.+)$/, kind: "error-message" },
 ];

package/kernel/probe/owner.mjs

@@ -46,8 +46,11 @@ import { matchesAny } from "../../hooks/sandbox-guard.mjs";
  */
 export function ownership(path, scopes, cwd = null) {
   const rel = String(path).replace(/^\.\//, "");
-  const writers = (scopes || []).filter((s) => matchesAny(rel, s.allowed)).map((s) => s.scope_id).sort();
   const shared = (scopes || []).filter((s) => matchesAny(rel, s.shared || [])).map((s) => s.scope_id).sort();
+  // `writers` is admits-the-path, the same union the sandbox fence composes (allowed ++ shared) —
+  // a path declared only in a contract's `shared` list is still a scope this path may write, and
+  // must read as owned rather than UNOWNED. `shared_with` (below) stays the narrower subset.
+  const writers = (scopes || []).filter((s) => matchesAny(rel, s.allowed) || matchesAny(rel, s.shared || [])).map((s) => s.scope_id).sort();
   return { path: rel, owner: electOwner(rel, scopes), writers, shared_with: shared, exists: cwd ? existsSync(join(cwd, rel)) : null };
 }
 

package/kernel/probe/resume.mjs

@@ -59,18 +59,89 @@
 import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { runArgs } from "../lib/argv.mjs";
-import { splitFrontmatter } from "../lib/contract.mjs";
+import { splitFrontmatter, uncoerce } from "../lib/contract.mjs";
 import { globToRegExp } from "../verify/spec.mjs";
 import {
   intake, harnessRun, wiringMap, projectProfile, scopesDir, resultsDir, ordersDir,
   orientDir, activeOrder, usecasesDir, breadboard, receipt, readReceipt, requirements,
+  exportRunDir,
 } from "../lib/paths.mjs";
 import { evalVerdict } from "./eval.mjs";
+import { collectRun, writeRun } from "../report/export.mjs";
 
 /** The run-state values `references/protocol.md` (Part 4 — State) defines. A typo'd status is a rejection,
  *  not a write — the whole point of this file is that a write nobody validates is a write nobody
- *  can trust. */
-export const RUN_STATUSES = ["orienting", "mapping", "building", "evaluating", "shipped", "escalated"];
+ *  can trust. `aborted` is the terminal counterpart `escalated` already was: a gate
+ *  resolving "abort", or a hard stop, ends the run the same way an operator-declared escalation
+ *  does — neither resumes on relaunch — so both are TERMINAL_STATUSES below. */
+export const RUN_STATUSES = ["orienting", "mapping", "building", "evaluating", "shipped", "escalated", "aborted"];
+
+/**
+ * The statuses a run does not come back from. `closeRun` refuses every other member of
+ * {@link RUN_STATUSES} — `orienting`/`mapping`/`building`/`evaluating` are mid-flight, and writing
+ * a close over one of those would stamp `closed_at` on a run a relaunch is still meant to resume.
+ */
+export const TERMINAL_STATUSES = ["shipped", "aborted", "escalated"];
+
+/**
+ * The RunReturn union (`kernel/schemas/domain.schema.json` `$defs/RunReturn.properties.status.enum`)
+ * mapped to what closing the run means for each arm — the derivation `closeIfTerminal`
+ * (`skills/tech-lead/workflows/shapeup-run.js`) now reads instead of a hand-typed
+ * `status !== "aborted" && status !== "shipped"` pair that referenced {@link TERMINAL_STATUSES}
+ * zero times and so could not see when a new arm went unhandled.
+ *
+ * A lookup answers one of three ways, and the distinction is load-bearing for what this map must
+ * catch: an arm ABSENT from this object (never listed as a key) returns `undefined` — an arm the
+ * schema carries that nobody has mapped, which a caller must treat as a defect, never as "fine to
+ * skip". An arm mapped to a terminal status closes the run as that status. An arm mapped to `null`
+ * is EXPLICITLY non-terminal — `paused` resumes on relaunch and `ok` is one inner round finishing,
+ * not the run — so it is a key with a falsy value, not an omission a reader could mistake for "not
+ * decided yet".
+ *
+ * `gate_h` → `escalated`: the breaker that tripped (`outer`/`inner`/`deadline`) travels in
+ * `close_cause`, never as a new member of {@link TERMINAL_STATUSES} or {@link RUN_STATUSES} — a
+ * circuit breaker tripping is not a new way a run ends, it is the reason an existing one
+ * (`escalated`) fires this time.
+ *
+ * @type {Object<string, (string|null)>}
+ */
+export const RUN_RETURN_CLOSE = {
+  shipped: "shipped",
+  aborted: "aborted",
+  gate_h: "escalated",
+  paused: null,
+  ok: null,
+};
+
+/**
+ * Resolve one RunReturn arm to a close outcome and, when the arm is terminal, perform the close —
+ * the single call `closeIfTerminal` makes instead of deciding locally which arms are terminal.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {string} arm - A `RunReturn.status` value.
+ * @param {(string|null)} [cause] - Why the run ended there; only used when `arm` is terminal.
+ * @param {boolean} [withExport] - Forwarded to {@link closeRun} — defaults true. The one caller
+ *   that ever passes `false` is a test fixture proving the export assertion is real — a check that
+ *   cannot fail did not happen; production call sites never set this.
+ * @returns {({ok:true, arm:string, terminal:false, reason:string} |
+ *   {ok:false, arm:string, reason:string} |
+ *   ({ok:boolean, arm:string, terminal:true} & ReturnType<typeof closeRun>))} `terminal:false` when
+ *   `arm` maps to `null` (nothing closed, not an error). `ok:false` with no `terminal` field when
+ *   `arm` is not a key of {@link RUN_RETURN_CLOSE} at all — a schema arm this map has not been
+ *   taught, which must never be silently treated as non-terminal. Otherwise the {@link closeRun}
+ *   outcome, tagged with the arm that produced it.
+ */
+export function closeArm(cwd, slug, arm, cause = null, withExport = true) {
+  if (!Object.hasOwn(RUN_RETURN_CLOSE, arm)) {
+    return { ok: false, arm, reason: `closeArm: "${arm}" is not a RunReturn arm this kernel maps — known arms: ${Object.keys(RUN_RETURN_CLOSE).join(", ")}` };
+  }
+  const status = RUN_RETURN_CLOSE[arm];
+  if (!status) {
+    return { ok: true, arm, terminal: false, reason: `"${arm}" is explicitly non-terminal — no close` };
+  }
+  return { ...closeRun(cwd, slug, { status, cause, withExport }), arm, terminal: true };
+}
 
 /** ORIENT's four artifacts (skills/orient/SKILL.md §Outputs): three by exact name, plus a spike
  *  whose filename carries the area it spiked (`spike-<area>.md`, or `spike-not-needed.md` when
@@ -462,6 +533,215 @@ export function setRunStatus(cwd, slug, status) {
   return { ok: true, path: p, status };
 }
 
+/**
+ * Rewrite `status:`, `closed_at:`, `closed_status:` and `close_cause:` together, in one pass,
+ * appending any of the last three that a pre-migration ledger carries no line for yet (the same
+ * tolerant-of-old-ledgers discipline `close_cause` itself shipped under).
+ *
+ * @param {string} body - The ledger's current text.
+ * @param {{status:string, closedAt:string, cause:(string|null)}} o - What to write. `cause` is
+ *   already normalized prose (newlines collapsed, truncated) — this function only `uncoerce`s it.
+ * @returns {string} The rewritten text.
+ */
+function writeCloseLines(body, { status, closedAt, cause }) {
+  const causeLine = `close_cause: ${uncoerce(cause || null)}`;
+  const closedStatusLine = `closed_status: ${status}`;
+  let out = body
+    .replace(/^status:.*$/m, `status: ${status}`)
+    .replace(/^closed_at:.*$/m, `closed_at: ${closedAt}`);
+  out = /^closed_status:.*$/m.test(out)
+    ? out.replace(/^closed_status:.*$/m, closedStatusLine)
+    // A ledger written before this field existed carries no line to replace — appended right after
+    // `closed_at:`, the one line every TERMINAL_STATUSES write also touches.
+    : out.replace(/^closed_at:.*$/m, (m) => `${m}\n${closedStatusLine}`);
+  out = /^close_cause:.*$/m.test(out)
+    ? out.replace(/^close_cause:.*$/m, causeLine)
+    : out.replace(/^closed_at:.*$/m, (m) => `${m}\n${causeLine}`);
+  return out;
+}
+
+/**
+ * Export a just-closed run's own records into fact tables, best-effort
+ * (`report export`, `kernel/report/export.mjs`). {@link closeRun} calls this for every terminal
+ * status except `"shipped"`: the Ship phase (`skills/tech-lead/workflows/shapeup-run.js`) already
+ * calls `report export` itself, several lines before this file's own close-out runs, and that call
+ * site is left untouched on purpose — the shipped path's export stays byte-comparable to what it
+ * wrote before Stage 2. `aborted`, `escalated` and `gate_h` (which closes as `escalated`, see
+ * {@link RUN_RETURN_CLOSE}) never reached that call site at all, because it sits inside a phase
+ * those endings never enter — so a run ending any of them left its whole trace (orders, results,
+ * T0 verdicts, hook decisions, `graph.jsonl`) in the gitignored LOCAL tier with nothing durable
+ * surviving the next `init run`'s wipe. This is the read that was missing for those endings, run at
+ * the one point every one of them passes through: the close itself.
+ *
+ * FAIL-OPEN, the hook discipline (CLAUDE.md) extended to a write that is not a hook: an export that
+ * cannot write — a blocked or missing exports directory, a full disk — must never turn a close that
+ * DID take into one that looks like it did not. The three facts {@link closeRun} just wrote
+ * (`closed_status`/`close_cause`/`closed_at`) are never touched by this function; a failure here is
+ * handed back to the caller as a warning string, never thrown.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @returns {(string|null)} A one-line warning when the export did not complete; `null` on success.
+ */
+function exportOnClose(cwd, slug) {
+  try {
+    const collected = collectRun(cwd, slug);
+    if (!collected) return `export on close: no readable receipt for "${slug}" — nothing to export`;
+    writeRun(collected, exportRunDir(cwd, collected.run_id ?? slug));
+    return null;
+  } catch (e) {
+    return `export on close: ${e.message}`;
+  }
+}
+
+/**
+ * Close the run: a terminal status, its cause, and a close timestamp, written together in ONE
+ * pass.
+ *
+ * Measured: after an EVAL worker escalated and the run aborted, `harness-run.md` still read
+ * `status: evaluating`, `closed_at: ~`, with no cause recorded anywhere — a live EVAL and a dead
+ * one were indistinguishable from the trace alone. Two writers made that possible: `setRunStatus`
+ * above replaces the `status:` line and NOTHING ELSE, and `closed_at` was written exactly once, as
+ * the literal `~`, by `init run` — nothing ever replaced it. This function is the one call site
+ * that closes a run, so a terminal RunReturn cannot leave one of the three facts behind.
+ *
+ * Refuses rather than silently no-ops, the same discipline as `setRunStatus`: an absent ledger, one
+ * missing the lines this writes, or a non-terminal `status` (closing a run still `building` would
+ * stamp a live run as done) is a fact to act on, not a write to skip quietly.
+ *
+ * THE ONCE-ONLY GUARD READS `closed_status`, NEVER `status`. REWORK (round 2): the guard used to key
+ * on `before.status`, and `status:` is a LIVE field every phase rewrites via `setRunStatus` —
+ * including the product's own ship path, which stamps `status: shipped`
+ * (`skills/tech-lead/workflows/shapeup-run.js`'s Ship phase) immediately before this call runs. So a
+ * run closed `aborted` at Preflight on one launch, relaunched, and carried through to a `shipped`
+ * RunReturn on a later one had its `status:` line rewritten to `shipped` by that ordinary phase
+ * traffic BEFORE `closeIfTerminal` ever called this function — the guard read `before.status ===
+ * "shipped"`, matched the very close it was about to perform, and treated a run that was actually
+ * closed `aborted` as already closed `shipped`: `ok:true`, an "idempotent no-op" that silently kept
+ * the abort's own `closed_at`/`close_cause` under a `status:` line now reading `shipped`. `closed_status`
+ * is written ONLY here, exactly once per distinct close-writing call, so nothing between two calls to
+ * this function can move it — it is the one field that actually answers "has this run been closed,
+ * and to what" regardless of how many times `status:` has been rewritten since.
+ *
+ * WHAT A SECOND CLOSE MEANS, decided explicitly rather than left implicit. `run_id` is reused across
+ * relaunches by design (AGENTS.md), so "the run's close" and "this launch's own close" are two
+ * different facts a single `closed_at`/`close_cause` pair cannot both hold:
+ *   - The IDENTICAL status and the IDENTICAL cause is the ordinary case a retried or duplicated call
+ *     produces (the same `withWarnings` call, or a relaunch that re-executes an already-applied
+ *     close) — a true no-op, `ok:true`, nothing rewritten.
+ *   - The SAME terminal status but a DIFFERENT cause is a SECOND, real close — most often a later
+ *     relaunch aborting again for its own reason, or shipping again after an earlier ship's close
+ *     record was never superseded. Discarding it (the pre-rework behavior) silently drops the later
+ *     launch's own reason with no trace of the loss. It is recorded instead: this call's cause
+ *     becomes the ledger's `close_cause`, folded together with the prior cause it is superseding —
+ *     the earlier fact survives inside the new line rather than the ledger simply losing it — and the
+ *     return carries `superseded:true` so a caller (`closeIfTerminal`) can flag the trace as degraded
+ *     rather than reporting a clean success.
+ *   - A DIFFERENT terminal status altogether (aborted vs. shipped) is refused outright — flipping the
+ *     actual OUTCOME of a run after the fact is not a fact a later launch gets to silently overwrite,
+ *     so the original `closed_status`/`closed_at`/`close_cause` are left completely untouched and
+ *     handed back to the caller.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {{status:string, cause:(string|null), withExport?:boolean}} o - The terminal status (one
+ *   of {@link TERMINAL_STATUSES}) and why the run ended there. `cause` travels through `uncoerce`
+ *   (the one dialect `harness-run.md`'s frontmatter is read and written in), so free prose — quotes
+ *   and colons included — round-trips as one frontmatter line; an embedded newline is collapsed to
+ *   a space first, because this dialect is line-based and could not carry one either way.
+ *   `withExport` (default true) gates {@link exportOnClose} — every status except `"shipped"` runs
+ *   it on a successful close; `false` exists only for a test fixture proving the export assertion
+ *   is real, never for a production call site.
+ * @returns {{ok:boolean, path:string, status:string, closed_at?:string, cause?:(string|null),
+ *   reason?:string, closed_status?:string, superseded?:boolean, decision?:string,
+ *   prior_cause?:(string|null), prior_closed_at?:string, export_warning?:string}} Outcome. A refused
+ *   overwrite (already closed with a DIFFERENT terminal status) carries
+ *   `closed_status`/`closed_at`/`cause` naming what is actually on disk. A successful supersede
+ *   (same status, different cause) carries `superseded:true`, `decision:"superseded"` (the
+ *   one-token signal the courier boundary in `shapeup-run.js` relays verbatim — see its own
+ *   `cmd()` banner) and the prior close it folded in. Any successful, non-`"shipped"` close carries
+ *   `export_warning` when {@link exportOnClose} could not write the run's fact tables — the close
+ *   itself still stands; this is advisory only.
+ */
+export function closeRun(cwd, slug, { status, cause = null, withExport = true } = {}) {
+  const p = harnessRun(cwd, slug);
+  if (!TERMINAL_STATUSES.includes(status)) {
+    return { ok: false, path: p, status, reason: `closeRun: "${status}" is not terminal — expected one of ${TERMINAL_STATUSES.join(" | ")}` };
+  }
+  if (!existsSync(p)) {
+    return { ok: false, path: p, status, reason: `no harness-run.md for slug "${slug}" — open the run with harness init run (GATE L0.1) before closing it` };
+  }
+  let body = readFileSync(p, "utf8");
+  if (!/^status:.*$/m.test(body) || !/^closed_at:.*$/m.test(body)) {
+    return { ok: false, path: p, status, reason: `harness-run.md carries no "status:"/"closed_at:" line to replace — the ledger's frontmatter is malformed (references/protocol.md)` };
+  }
+
+  // The Ship phase (`shapeup-run.js`) already exports a shipped run itself, before this call ever
+  // runs — Stage 2 adds the endings that wrote nothing, and leaves that path untouched.
+  const shouldExport = withExport && status !== "shipped";
+  const withExportWarning = (result) => {
+    if (!shouldExport) return result;
+    const warning = exportOnClose(cwd, slug);
+    return warning ? { ...result, export_warning: warning } : result;
+  };
+
+  // Truncated, not elided: a cause this long has already done its job in the run's own log — the
+  // ledger line is a pointer back to it, not the full transcript. Newlines are collapsed to spaces
+  // FIRST — this dialect is line-based, so a raw embedded newline would split one field into a value
+  // line and a stray, unparsed one.
+  const normCause = String(cause ?? "").replace(/\r?\n/g, " ").trim().slice(0, 4000) || null;
+
+  const before = parseFrontmatter(body);
+  const priorClosedStatus = before.closed_status && before.closed_status !== "~" ? before.closed_status : null;
+  const priorClosedAt = before.closed_at && before.closed_at !== "~" ? before.closed_at : null;
+  const priorCause = before.close_cause && before.close_cause !== "~" ? before.close_cause : null;
+
+  if (priorClosedStatus && priorClosedAt) {
+    if (priorClosedStatus === status && normCause === priorCause) {
+      // The identical fact, restated — a retried or duplicated call costs nothing.
+      return withExportWarning({ ok: true, path: p, status, closed_at: priorClosedAt, cause: priorCause, decision: "idempotent", reason: `already closed as "${status}" at ${priorClosedAt} — idempotent no-op` });
+    }
+    if (priorClosedStatus !== status) {
+      // A DIFFERENT terminal status over an already-closed run — refused outright, the original
+      // close left completely untouched so the caller can see what it was refused permission to
+      // destroy, rather than losing it silently.
+      return {
+        ok: false, path: p, status,
+        reason: `closeRun: this run is already closed as "${priorClosedStatus}" at ${priorClosedAt} (cause: ${JSON.stringify(priorCause)}) — refusing to overwrite it with "${status}". A terminal close is a once-only fact; the first cause is not destroyed.`,
+        closed_status: priorClosedStatus, closed_at: priorClosedAt, cause: priorCause,
+      };
+    }
+    // SAME terminal status, a DIFFERENT cause — a second, real close (see the function banner's
+    // "what a second close means"). Superseded, not discarded: the prior cause is folded into the
+    // new line rather than lost, and the return says so explicitly.
+    const closedAt = new Date().toISOString();
+    const foldedCause = `${normCause || "no reason recorded"} — supersedes an earlier close recorded ${priorClosedAt} (cause: ${JSON.stringify(priorCause)})`.slice(0, 4000);
+    body = writeCloseLines(body, { status, closedAt, cause: foldedCause });
+    try { writeFileSync(p, body); } catch (e) {
+      return { ok: false, path: p, status, reason: `could not write the ledger: ${e.message}` };
+    }
+    const afterSup = parseFrontmatter(readFileSync(p, "utf8"));
+    if (afterSup.status !== status || !afterSup.closed_at || afterSup.closed_at === "~") {
+      return { ok: false, path: p, status, reason: `wrote the superseding close but the ledger reads back status="${afterSup.status}" closed_at="${afterSup.closed_at}" — the write did not take` };
+    }
+    return withExportWarning({
+      ok: true, path: p, status, closed_at: afterSup.closed_at, cause: afterSup.close_cause ?? null,
+      superseded: true, decision: "superseded", prior_cause: priorCause, prior_closed_at: priorClosedAt,
+    });
+  }
+
+  const closedAt = new Date().toISOString();
+  body = writeCloseLines(body, { status, closedAt, cause: normCause });
+  try { writeFileSync(p, body); } catch (e) {
+    return { ok: false, path: p, status, reason: `could not write the ledger: ${e.message}` };
+  }
+  const after = parseFrontmatter(readFileSync(p, "utf8"));
+  if (after.status !== status || !after.closed_at || after.closed_at === "~") {
+    return { ok: false, path: p, status, reason: `wrote the close but the ledger reads back status="${after.status}" closed_at="${after.closed_at}" — the write did not take` };
+  }
+  return withExportWarning({ ok: true, path: p, status, closed_at: after.closed_at, cause: after.close_cause ?? null, decision: "closed" });
+}
+
 /**
  * Point the substrate pointer at the order about to be executed.
  *
@@ -488,13 +768,21 @@ export function writeActiveOrder(cwd, slug, orderPath) {
 
 /** The typed argv contract (see `./lib/argv.mjs`). */
 export const ARGV_SPEC = {
-  usage: "harness.mjs probe resume --slug <slug> [--cwd <dir>] [--require <phase> | --set-status <status> | --set-active-order <path>]",
+  usage: "harness.mjs probe resume --slug <slug> [--cwd <dir>] " +
+         "[--require <phase> | --set-status <status> | --set-active-order <path> | " +
+         "--close <status> | --close-arm <RunReturn.status> [--cause <text>]]",
   _: { arity: 0, max: 0, name: "(no positional operands)" },
   slug: { type: "str", required: true },
   cwd: { type: "path" },
   require: { type: "enum", values: PHASES },
   "set-status": { type: "enum", values: RUN_STATUSES },
   "set-active-order": { type: "str" },
+  // The one call site that stamps a terminal status, its cause and closed_at together.
+  close: { type: "enum", values: TERMINAL_STATUSES },
+  // Not `--close`: the caller (shapeup-run.js's closeIfTerminal) hands over a RunReturn arm, never
+  // a status it decided was terminal itself — RUN_RETURN_CLOSE/closeArm above make that call.
+  "close-arm": { type: "str" },
+  cause: { type: "str" },
 };
 
 /**
@@ -508,11 +796,15 @@ export function cli(rawArgv) {
   const args = runArgs(ARGV_SPEC, rawArgv);
   const cwd = args.cwd || process.cwd();
 
-  const ops = [args.require && "--require", args.setStatus && "--set-status", args.setActiveOrder && "--set-active-order"].filter(Boolean);
+  const ops = [args.require && "--require", args.setStatus && "--set-status", args.setActiveOrder && "--set-active-order", args.close && "--close", args.closeArm && "--close-arm"].filter(Boolean);
   if (ops.length > 1) {
     process.stderr.write(JSON.stringify({ error: "conflicting_flags", flags: ops, expected: "one operation per invocation" }) + "\n");
     process.exit(2);
   }
+  if (args.cause !== undefined && !args.close && !args.closeArm) {
+    process.stderr.write(JSON.stringify({ error: "conflicting_flags", flags: ["--cause"], expected: "--cause is only meaningful with --close or --close-arm" }) + "\n");
+    process.exit(2);
+  }
 
   // The post-condition. It prints the SAME ResumeState the derivation prints — plus which phase was
   // asked about and whether its artifact is there — so a caller that wants to act on the facts
@@ -541,6 +833,23 @@ export function cli(rawArgv) {
     process.exit(r.ok ? 0 : 3);
   }
 
+  if (args.close) {
+    const r = closeRun(cwd, args.slug, { status: args.close, cause: args.cause ?? null });
+    console.log(JSON.stringify(r));
+    process.exit(r.ok ? 0 : 3);
+  }
+
+  // The arm-derived close: the caller hands a RunReturn arm and this kernel decides — via
+  // RUN_RETURN_CLOSE/closeArm above — whether it is terminal and, if so, what status it closes as.
+  // Exit 0 for both a real close AND a correctly-declined non-terminal arm (`terminal:false`) —
+  // neither is an error the caller (shapeup-run.js's closeIfTerminal) should treat as failed; only
+  // an arm this map does not recognize at all, or a close `closeRun` itself refuses, exits non-zero.
+  if (args.closeArm) {
+    const r = closeArm(cwd, args.slug, args.closeArm, args.cause ?? null);
+    console.log(JSON.stringify(r));
+    process.exit(r.ok ? 0 : 3);
+  }
+
   console.log(JSON.stringify(deriveResumeState(cwd, args.slug)));
   process.exit(0);
 }

package/kernel/probe/rounds.mjs

@@ -0,0 +1,104 @@
+// rounds — how many BUILD/EVAL rounds a run actually reached, derived from disk.
+//
+// WHY THIS EXISTS (measured, not theorized).
+//
+// `harness-run.md`'s `rounds_used` frontmatter is written ONCE, at GATE L0.1 (`init run`), as `0`,
+// and nothing in the round loop ever rewrites it — the orchestrator's own RunReturn carries the
+// real count, but that value lives in a JS variable a relaunch loses, and it never reached the
+// ledger. `reduce ship`'s own derivation partly compensated by counting the highest
+// `evaluate-r<N>.json` result on disk, which is right for "rounds the judge saw" and wrong for
+// "rounds the run built": measured after two full BUILD rounds with neither reaching EVAL,
+// `round_count: 0` and `rounds_used: 0` both — a run that did real work reported having done none.
+//
+// TWO NUMBERS, NOT ONE. A round can be built and die before EVAL ever sees it (a circuit breaker,
+// a kill mid-round), so "rounds built" and "rounds judged" are different facts and collapsing them
+// into a single field is exactly what made the fallback silently wrong. Both are returned here, and
+// both are meant to survive to wherever a run's numbers are read — the ship report and the export.
+//
+// PURE. Reads the run's own trace, writes nothing — the same discipline as `reduce ship`'s other
+// derivations (`t0Summary`, `boardCensus`, …). A run before any of these artifacts existed, or a
+// lane with no round concept at all (`--tiny`), falls back to the caller-supplied ledger value,
+// non-regression with the earlier, EVAL-only behaviour.
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ordersDir, verdictsDir, roundBuildDir, resultsDir } from "../lib/paths.mjs";
+
+/** Parse a JSON file, returning null rather than throwing — every reader here is best-effort. */
+function readJson(p) {
+  try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; }
+}
+
+/**
+ * The round a build-addressed order id encodes, e.g. `checkout/sc-01-r2-a1` → 2.
+ * @param {*} orderId - The order's own id, whatever shape it happens to be.
+ * @returns {(number|null)} The round, or null when the id carries none (`orient`, `wire`, `hammer`, …).
+ */
+export function orderRound(orderId) {
+  const suffix = String(orderId ?? "").split("/").slice(1).join("/");
+  const m = suffix.match(/-r(\d+)(?:-a\d+)?$/);
+  return m ? Number(m[1]) : null;
+}
+
+const maxOf = (nums) => (nums.length ? Math.max(...nums) : null);
+
+/**
+ * How many rounds this run actually reached — built, and separately, judged.
+ *
+ * `rounds_used` is the highest round carrying ANY build evidence: a compiled order, a T0 verdict
+ * artifact, a round build-gate artifact, or an EVAL result — the brief's own list, plus EVAL results
+ * because a judged round is, by construction, a round that was also built. `rounds_judged` is the
+ * highest round EVAL actually returned a verdict for (`evaluate-r<N>.json` on disk), kept as its own
+ * field rather than folded into the only number a reader can see.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {*} [fallback] - What to report for `rounds_used` when nothing on disk is derivable — the
+ *   caller's own ledger value, passed through untouched (some callers hand this on already coerced
+ *   to a number, some as the raw frontmatter string; this function does not care which).
+ * @returns {{rounds_used:*, rounds_judged:(number|null)}} Both counts.
+ */
+export function deriveRounds(cwd, slug, fallback) {
+  const orderRounds = [];
+  const oDir = ordersDir(cwd, slug);
+  if (existsSync(oDir)) {
+    for (const f of readdirSync(oDir)) {
+      if (!f.endsWith(".json")) continue;
+      const r = orderRound(readJson(join(oDir, f))?.order_id);
+      if (r !== null) orderRounds.push(r);
+    }
+  }
+
+  const verdictRounds = [];
+  const vDir = verdictsDir(cwd, slug);
+  if (existsSync(vDir)) {
+    for (const f of readdirSync(vDir).filter((x) => x.endsWith(".json"))) {
+      const v = readJson(join(vDir, f));
+      if (typeof v?.round === "number") verdictRounds.push(v.round);
+    }
+  }
+
+  const buildGateRounds = [];
+  const bDir = roundBuildDir(cwd, slug);
+  if (existsSync(bDir)) {
+    for (const f of readdirSync(bDir)) {
+      const m = f.match(/^r(\d+)-t\d+\.json$/);
+      if (m) buildGateRounds.push(Number(m[1]));
+    }
+  }
+
+  const evalRounds = [];
+  const rDir = resultsDir(cwd, slug);
+  if (existsSync(rDir)) {
+    for (const f of readdirSync(rDir)) {
+      const m = f.match(/^evaluate-r(\d+)\.json$/);
+      if (m) evalRounds.push(Number(m[1]));
+    }
+  }
+
+  const built = maxOf([...orderRounds, ...verdictRounds, ...buildGateRounds, ...evalRounds]);
+  return {
+    rounds_used: built !== null ? built : fallback,
+    rounds_judged: maxOf(evalRounds),
+  };
+}