@sabaiway/agent-workflow-kit 2.1.0 → 3.1.0

package/tools/run-gates.mjs

@@ -18,38 +18,31 @@
 // Honest outcomes — each distinct, never a silent green (the exit-code table + the summary-line
 // schema are pinned by run-gates.test.mjs):
 //   0 ok · 1 gate failure · 2 usage · 3 missing declaration · 4 empty gates list ·
-//   5 malformed/invalid declaration · 6 bash unavailable · 7 --record asked but the gate-run
-//   record could not be written. Gate `cmd` lines are BASH command lines (brace/glob expansion);
-//   a host without bash gets the loud exit-6 preflight error, never a silent reinterpretation
-//   under another shell.
+//   5 malformed/invalid declaration · 6 bash unavailable · 8 --final receipt not written.
+//   Gate `cmd` lines are BASH command lines (brace/glob expansion); a host without bash gets the
+//   loud exit-6 preflight error, never a silent reinterpretation under another shell.
 //
-// The runner itself WRITES NOTHING by default. `--record` (BUGFREE-2 / AD-048, D5) mints ONE
-// v4 `gate-run` record — the green-baseline receipt the review-ledger writer's D5 tooth consumes —
-// by DELEGATING to the ledger's sole writer (recordGateRun in review-ledger-write.mjs): this
-// runner never opens the ledger file itself (an import/structure pin holds the boundary). The
-// record carries the FULL declaration + exactly what ran (a --only subset records honestly as a
-// subset — it never satisfies quality-green) + the tree fingerprint BEFORE and AFTER the run (a
-// mutating gate attests no particular tree). Dependency-free, Node >= 18. No side effects on import.
+// The runner itself WRITES NOTHING on a plain run. `--final` (D3(a)) is the ONE writing mode:
+// every attempt lands in the core-evidence store via its sole writer. Dependency-free.
+// No side effects on import.
 
-import { readFileSync, lstatSync } from 'node:fs';
-import { join } from 'node:path';
+import { readFileSync, lstatSync, unlinkSync, realpathSync } from 'node:fs';
+import { join, isAbsolute } from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { pathToFileURL } from 'node:url';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import { createHash, randomUUID } from 'node:crypto';
 import { computeTreeFingerprint } from './review-state.mjs';
-import { recordGateRun } from './review-ledger-write.mjs';
-// (a) BUGFREE-3 / AD-049: the one-suite-run credit. The fold runner already spawned the `unit-tests`
-// suite under coverage; --record can CREDIT that gate from the recorded evidence instead of
-// re-spawning it minutes later — read-only (the read core, never the tree-toucher).
-import { foldSuiteCredit } from './fold-completeness.mjs';
-
-// The gate id the (a) credit applies to — the SAME command the fold runner resolves as its suite.
-export const UNIT_TESTS_GATE_ID = 'unit-tests';
+// The D3(a) final receipt rides the core-evidence SOLE WRITER (the sole-writer boundary — this
+// runner never opens the store itself) + the canonical per-kind serialization its hashes bind.
+import { appendEvidenceRecord, resolveEvidencePath, readEvidence, canonicalKindSerialization, EVIDENCE_SCHEMA_VERSION } from './core-evidence.mjs';
+import { LCOV_BASENAME } from './coverage-check.mjs';
 
 // The per-project declaration (strict JSON, hand-editable). cwd-relative — errors show a path the
 // user can open (the orchestration-config CONFIG_REL idiom).
 export const GATES_REL = 'docs/ai/gates.json';
 
 // The full exit-code table — one distinct code per honest outcome (never a silent green).
+// 7 is RETIRED (the deleted --record arm's outcome) — never reused for a new meaning.
 export const EXIT = Object.freeze({
   ok: 0,
   fail: 1,
@@ -58,10 +51,9 @@ export const EXIT = Object.freeze({
   empty: 4,
   malformed: 5,
   noBash: 6,
-  // --record was asked for but the gate-run record could not be written (no in-flight loop, a
-  // malformed ledger, an fs refusal): the invocation's contract included a ledger receipt — not
-  // delivering it is its own loud outcome, never folded into ok/fail.
-  recordFailed: 7,
+  // --final could not write its receipt (a corrupt store, an fs refusal): green gates WITHOUT a
+  // written receipt never read as success (D3(a)).
+  finalFailed: 8,
 });
 
 // A tagged failure carrying its process exit code (the shared orchestration-config idiom).
@@ -74,21 +66,23 @@ const SPAWN_FAILED_CODE = -1;
 const MAX_GATE_OUTPUT_BYTES = 64 * 1024 * 1024;
 
 const USAGE = [
-  'usage: run-gates.mjs [--cwd <dir>] [--only <id>]... [--record] [--help]',
+  'usage: run-gates.mjs [--cwd <dir>] [--only <id>]... [--final] [--help]',
+  '',
+  '--final runs the FULL declared matrix as the D3(a) final verification run: it refuses a',
+  'declaration lacking the canonical core checks (the review-state + coverage-check gates),',
+  'deletes the stale git-dir lcov first, exports AW_GIT_DIR to every gate cmd, records EVERY',
+  'attempt (start + completed green/red) in the core-evidence store, and binds the receipt to',
+  '{ fingerprint before/after, the full declaration, per-gate results, the canonical red-proof +',
+  'degrade evidence hashes, the lcov sha }. --final refuses --only (a subset never attests).',
   '',
   `Runs the gates declared in <cwd>/${GATES_REL} (one bash command line each, project root as cwd).`,
   'Prints a per-gate PASS/FAIL table + one machine-readable summary line; exit 0 iff all green.',
-  '--record additionally mints ONE v4 gate-run record into the review ledger via its sole writer',
-  '(the D5 green-baseline receipt; needs a single in-flight plan): the full declaration + what ran',
-  '+ the pre/post tree fingerprints. A red run records honestly; a --only subset records as a subset.',
-  'In --record mode the unit-tests gate is CREDITED (not re-spawned) when it is the FIRST declared gate',
-  'AND the fold-completeness runner already ran that EXACT command green at the current tree',
-  '(fingerprint-bound + exit-0 + cmd-identity); positioned after another gate, it always re-spawns.',
   'Sandbox-safe: the runner itself needs no network and writes only repo-local state — the D4 sandbox',
   'lane; each DECLARED gate command is the project\'s own, so ITS sandbox-safety is command-shape',
   'dependent (first try the sandbox-safe shape — cache under $TMPDIR, offline/notifier off).',
   `Exit codes: 0 ok · 1 gate failure · 2 usage · 3 missing declaration · 4 empty gates list ·`,
-  '5 malformed/invalid declaration · 6 bash unavailable · 7 --record asked but the record failed.',
+  '5 malformed/invalid declaration · 6 bash unavailable ·',
+  '8 --final asked but its receipt could not be written (green gates never read as success without it).',
 ].join('\n');
 
 // ── declaration validation (malformed → exit 5, loud `path: reason`) ─────────────────
@@ -187,13 +181,11 @@ export const selectGates = (gates, onlyIds) => {
 // Spawn one gate cmd via bash from the project root. `cmd` is a BASH command line by contract
 // (the declaration's _README states it): this repo's own gate matrix needs brace+glob expansion,
 // which /bin/sh does not perform — hence bash explicitly, never the platform default shell.
-// NODE_TEST_CONTEXT is stripped (mirroring the fold suite's childTestEnv): a `node --test` gate spawned
-// while run-gates is itself running under a parent test context would otherwise inherit it, hit Node's
-// recursive-run guard, silently skip every file, and exit 0 — a vacuous false green. Stripping it also
-// makes the plain gate env-equivalent to the fold suite, so the (a) suite-run credit's exit-0 truthfully
-// predicts a plain-spawn exit-0 (the one remaining, documented residual is NODE_V8_COVERAGE).
-export const spawnGateViaBash = (cmd, cwd) => {
-  const env = { ...process.env };
+// NODE_TEST_CONTEXT is stripped: a `node --test` gate spawned while run-gates is itself running
+// under a parent test context would otherwise inherit it, hit Node's recursive-run guard, silently
+// skip every file, and exit 0 — a vacuous false green.
+export const spawnGateViaBash = (cmd, cwd, extraEnv = {}) => {
+  const env = { ...process.env, ...extraEnv };
   delete env.NODE_TEST_CONTEXT;
   return spawnSync('bash', ['-c', cmd], { cwd, env, encoding: 'utf8', maxBuffer: MAX_GATE_OUTPUT_BYTES });
 };
@@ -209,26 +201,17 @@ const trimTrailingNewline = (text) => text.replace(/\n$/, '');
 
 // Run the selected gates sequentially (declaration order). A green gate logs one PASS line; a
 // failing gate logs FAIL + its captured stdout/stderr VERBATIM (triage without re-running).
-export const runGates = (gates, { cwd, spawn = spawnGateViaBash, now = Date.now, log = console.log, credit = null }) => {
+export const runGates = (gates, { cwd, spawn = spawnGateViaBash, now = Date.now, log = console.log }) => {
   const results = [];
   for (const gate of gates) {
     log(`── ${gate.id} — ${gate.title}`);
-    // (a) the one-suite-run credit: for the unit-tests gate, if the fold runner already ran this exact
-    // command green at the current tree, CREDIT it instead of re-spawning (no quality loss — same
-    // execution, same tree, recorded once). Any mismatch → credit is null → the normal spawn below.
-    const credited = credit ? credit(gate) : null;
-    if (credited) {
-      log('   PASS (credited from the fold-completeness suite run — no re-spawn)');
-      results.push({ id: gate.id, title: gate.title, ok: true, code: 0, elapsedMs: 0, credited: true });
-      continue;
-    }
     const startedAt = now();
     const res = spawn(gate.cmd, cwd);
     const elapsedMs = now() - startedAt;
     const spawnError = res.error ? `spawn error: ${res.error.code || res.error.message}` : null;
     const ok = spawnError === null && res.status === 0;
     const code = spawnError === null ? res.status : SPAWN_FAILED_CODE;
-    results.push({ id: gate.id, title: gate.title, ok, code, elapsedMs });
+    results.push({ id: gate.id, title: gate.title, ok, code, elapsedMs, stdout: res.stdout ? String(res.stdout) : '' });
     if (ok) {
       log(`   PASS (${formatSeconds(elapsedMs)})`);
     } else {
@@ -264,7 +247,7 @@ export const composeSummaryLine = ({ status, results = [] }) => {
 // ── CLI ───────────────────────────────────────────────────────────────────────────────
 
 const parseArgs = (argv) => {
-  const opts = { cwd: null, only: [], record: false, help: false };
+  const opts = { cwd: null, only: [], final: false, help: false };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--help' || arg === '-h') {
@@ -277,15 +260,53 @@ const parseArgs = (argv) => {
       i += 1;
       if (argv[i] === undefined) throw fail(EXIT.usage, '--only requires a gate id argument');
       opts.only.push(argv[i]);
-    } else if (arg === '--record') {
-      opts.record = true;
+    } else if (arg === '--final') {
+      opts.final = true;
     } else {
       throw fail(EXIT.usage, `unknown argument "${arg}"\n${USAGE}`);
     }
   }
+  if (opts.final && opts.only.length > 0) {
+    throw fail(EXIT.usage, '--final refuses --only — a subset never attests (the D3(a) receipt binds the FULL declaration)');
+  }
   return opts;
 };
 
+// The canonical core checks a --final declaration must carry (D3(a)), matched as STRICT FULL
+// commands: `node` + ONE (quoted or bare) path token + the exact tool basename + ` --check` +
+// END — and the path token must REALPATH-RESOLVE to the kit's OWN tool (the canonical sibling of
+// this runner). Masked forms (`--check --help`, `--check || true`, prefix commands) never match
+// the shape; a lookalike file that merely carries the basename — whatever it prints — never
+// resolves to the canonical tool. Any form that DOES resolve (bare, relative, absolute, quoted)
+// is accepted, so the anchor adds no false refusals.
+const coreCheckRe = (basename) => new RegExp(`^node\\s+(?:"((?:[^"]*[/\\\\])?${basename})"|((?:[^\\s"]*[/\\\\])?${basename}))\\s+--check$`);
+const FINAL_CORE_CHECKS = [
+  { name: 'review-state', re: coreCheckRe('review-state\\.mjs'), canonical: fileURLToPath(new URL('./review-state.mjs', import.meta.url)) },
+  { name: 'coverage-check', re: coreCheckRe('coverage-check\\.mjs'), canonical: fileURLToPath(new URL('./coverage-check.mjs', import.meta.url)) },
+];
+const matchesCanonicalCheck = (check, cmd, projectDir) => {
+  const m = check.re.exec(cmd.trim());
+  if (!m) return false;
+  const token = m[1] ?? m[2];
+  const abs = isAbsolute(token) ? token : join(projectDir, token);
+  try {
+    return realpathSync(abs) === realpathSync(check.canonical);
+  } catch {
+    return false; // unresolvable → never canonical (fail closed)
+  }
+};
+
+// isFinalCapableDeclaration(gates, projectDir) → whether --final would accept this declaration
+// (every canonical core check present + the checker LAST) — the ONE home consumers (the
+// recommendations guard-install probe) read instead of re-deriving the rule.
+export const isFinalCapableDeclaration = (gates, projectDir) => {
+  if (!Array.isArray(gates) || gates.length === 0) return false;
+  const missing = FINAL_CORE_CHECKS.filter((c) => !gates.some((g) => matchesCanonicalCheck(c, g.cmd, projectDir)));
+  if (missing.length > 0) return false;
+  return matchesCanonicalCheck(FINAL_CORE_CHECKS[1], gates[gates.length - 1].cmd, projectDir);
+};
+const sha256Hex = (data) => createHash('sha256').update(data).digest('hex');
+
 // The full CLI, dependency-injected for hermetic tests. Returns the process exit code; the two
 // output sinks split human-facing report (log) from error channel (logError). The summary line is
 // emitted via `log` as the final line of every non-usage outcome.
@@ -299,9 +320,7 @@ export const runCli = (argv, deps = {}) => {
     readFile,
     lstat,
     now,
-    record = recordGateRun,
     fingerprint = computeTreeFingerprint,
-    foldCredit = foldSuiteCredit,
   } = deps;
   try {
     const opts = parseArgs(argv);
@@ -326,6 +345,39 @@ export const runCli = (argv, deps = {}) => {
       return EXIT.empty;
     }
     const selected = selectGates(declaration.gates, opts.only);
+    // AW_GIT_DIR rides EVERY gate child inside a git tree (plain and --only alike): declared
+    // cmds reference fixed git-dir artifacts (the unit-tests lcov destination) — a plain red-run
+    // must exercise the SAME cmd line --final will, never a broken-only-outside---final variant.
+    const dirRes = spawnSync('git', ['rev-parse', '--absolute-git-dir'], { cwd: projectDir, windowsHide: true });
+    const gitDir = dirRes.error || dirRes.status !== 0 ? null : dirRes.stdout.toString('utf8').replace(/\r?\n$/, '');
+    let gateSpawn = gitDir === null ? spawn : (cmd, cwd2) => spawn(cmd, cwd2, { AW_GIT_DIR: gitDir });
+    // ── --final preflight (D3(a)): the declaration must carry the canonical core checks; the TRUE
+    // git dir resolves AW_GIT_DIR; the stale lcov dies BEFORE the suite so it is never consumed.
+    if (opts.final) {
+      const missing = FINAL_CORE_CHECKS.filter((c) => !declaration.gates.some((g) => matchesCanonicalCheck(c, g.cmd, projectDir)));
+      if (missing.length > 0) {
+        throw fail(EXIT.malformed, `--final refuses a weakened declaration — missing the canonical core check(s): ${missing.map((c) => c.name).join(', ')} (each must be ONE plain --check invocation of the kit's OWN tool in ${GATES_REL} — a masked form, a compound, or a lookalike path never counts)`);
+      }
+      const lastGate = declaration.gates[declaration.gates.length - 1];
+      if (!matchesCanonicalCheck(FINAL_CORE_CHECKS[1], lastGate.cmd, projectDir)) {
+        throw fail(EXIT.malformed, `--final refuses the declaration — the CANONICAL coverage-check gate must be the LAST declared gate (nothing may run after the checker consumed the lcov; "${lastGate.id}" is declared last)`);
+      }
+      if (gitDir === null) throw fail(EXIT.fail, '--final needs a git work tree (cannot resolve the git dir)');
+      try {
+        unlinkSync(join(gitDir, LCOV_BASENAME)); // a stale lcov is never consumed
+      } catch (err) {
+        if (err.code !== 'ENOENT') {
+          // Anything but "absent" leaves a readable stale artifact behind — fail closed BEFORE
+          // the attempt starts (a swallowed delete error could fake coverage).
+          logError(`[run-gates] --final could not delete the stale lcov at ${join(gitDir, LCOV_BASENAME)}: ${err.message} (fail closed)`);
+          log(composeSummaryLine({ status: 'fail' }));
+          return EXIT.finalFailed;
+        }
+      }
+      // ONE lcov path for delete/check/hash/guard: the fixed git-dir file is FORCED into every
+      // gate child env — a stray host AW_LCOV_FILE can never desync the checker from the receipt.
+      gateSpawn = (cmd, cwd2) => spawn(cmd, cwd2, { AW_GIT_DIR: gitDir, AW_LCOV_FILE: join(gitDir, LCOV_BASENAME) });
+    }
     const probe = spawn(BASH_PROBE_CMD, projectDir);
     if (probe.error && probe.error.code === 'ENOENT') {
       logError(
@@ -335,51 +387,123 @@ export const runCli = (argv, deps = {}) => {
       log(composeSummaryLine({ status: 'no-bash' }));
       return EXIT.noBash;
     }
-    const fingerprintBefore = opts.record ? fingerprint(projectDir) : null;
-    // (a) the one-suite-run credit — ONLY in --record mode (the fold-loop flow), ONLY the unit-tests
-    // gate, ONLY when it is the FIRST selected gate (a gate that ran BEFORE it could have side-effected
-    // an ignored/out-of-tree artifact unit-tests depends on WITHOUT moving the fingerprint, so a
-    // later-positioned unit-tests must re-spawn — never credit a state the real matrix might fail), and
-    // ONLY when the fold evidence is fingerprint-bound + exit-0 (foldCredit) AND its recorded cmd EQUALS
-    // this gate's cmd (the --only-subset defense). Any mismatch → credit is null → the normal spawn.
-    let credit = null;
-    if (opts.record && selected[0]?.id === UNIT_TESTS_GATE_ID) {
-      const fold = foldCredit({ cwd: projectDir, env, fingerprint: fingerprintBefore });
-      credit = (gate) => (gate.id === UNIT_TESTS_GATE_ID && fold.credited && fold.evidence.cmd === gate.cmd ? fold : null);
+    // --final needs the pre-run fingerprint (the receipt binds before == after == current).
+    const finalFingerprintBefore = opts.final ? fingerprint(projectDir) : null;
+    const finalAttempt = opts.final ? randomUUID() : null;
+    let finalError = null;
+    let startEvidenceHashes = null;
+    if (opts.final) {
+      try {
+        appendEvidenceRecord({
+          path: resolveEvidencePath(projectDir, env),
+          record: { schema: EVIDENCE_SCHEMA_VERSION, kind: 'final-start', fingerprint: finalFingerprintBefore, attempt: finalAttempt, timestamp: new Date().toISOString() },
+        });
+        // The drift tooth's anchor: the canonical red-proof/degrade serializations BEFORE any
+        // gate runs — no legitimate writer appends those kinds DURING a final run, so any change
+        // by receipt time is an integrity failure, never a green.
+        const { records } = readEvidence(resolveEvidencePath(projectDir, env));
+        startEvidenceHashes = {
+          redProof: sha256Hex(canonicalKindSerialization(records, 'red-proof')),
+          degrade: sha256Hex(canonicalKindSerialization(records, 'degrade')),
+        };
+      } catch (err) {
+        // EVERY attempt is recorded — an unwritable store refuses the whole attempt up front
+        // (green gates without a written receipt never read as success).
+        logError(`[run-gates] --final could not record the attempt start: ${err.message}`);
+        log(composeSummaryLine({ status: 'fail' }));
+        return EXIT.finalFailed;
+      }
     }
-    const results = runGates(selected, { cwd: projectDir, spawn, log, now, credit });
+    const results = runGates(selected, { cwd: projectDir, spawn: gateSpawn, log, now });
     for (const line of formatTable(results)) log(line);
     const allGreen = results.every((result) => result.ok);
-    // The gate-run record (D5): minted for green AND red runs alike (an honest red is telemetry
-    // fuel), via the ledger's sole writer. Emitted BEFORE the summary line — the machine summary
-    // stays the LAST line of every non-usage outcome (pinned).
-    let recordError = null;
-    if (opts.record) {
-      const failing = results.filter((result) => !result.ok);
+    if (opts.final) {
+      // The checker's verbatim diagnostics surface even on green — skipped-no-lcov and the
+      // out-of-domain/unsupported lists must never vanish into a suppressed green stdout.
+      const checkerRow = results[results.length - 1];
+      if (checkerRow?.ok && checkerRow.stdout) {
+        log('── coverage-check diagnostics (verbatim)');
+        log(trimTrailingNewline(checkerRow.stdout));
+      }
+      // The completed attempt (D3(a)): status green/red DERIVED from results + integrity, the
+      // FULL declaration, the per-gate results, the evidence hashes over the CANONICAL
+      // authoritative serializations, and the lcov sha the CHECKER printed for the bytes it
+      // actually read — with an end re-hash agreement check (the checker's own children are the
+      // one write window that survives "coverage-check runs last").
       try {
-        const { writtenPath } = record({
-          cwd: projectDir,
-          env,
-          declared: declaration.gates.map(({ id, cmd }) => ({ id, cmd })),
-          results: results.map(({ id, ok, code }) => ({ id, ok, code })),
-          summary: {
-            status: allGreen ? 'ok' : 'fail',
-            gates: results.length,
-            passed: results.length - failing.length,
-            failed: failing.length,
-            failedIds: failing.map((result) => result.id),
+        const storePath = resolveEvidencePath(projectDir, env);
+        const endRead = readEvidence(storePath);
+        const endBroken = Boolean(endRead.readError) || (endRead.malformed ?? 0) > 0;
+        let integrityFailure = null;
+        if (endBroken) {
+          integrityFailure = 'the evidence store became unreadable under the final run';
+        } else {
+          const endHashes = {
+            redProof: sha256Hex(canonicalKindSerialization(endRead.records, 'red-proof')),
+            degrade: sha256Hex(canonicalKindSerialization(endRead.records, 'degrade')),
+          };
+          if (endHashes.redProof !== startEvidenceHashes.redProof || endHashes.degrade !== startEvidenceHashes.degrade) {
+            integrityFailure = 'the evidence store moved under the final run (the canonical red-proof/degrade serialization changed)';
+          }
+        }
+        // Exactly ONE full machine line binds the receipt — an unanchored first-match would let
+        // an injected/duplicated line shadow the real one and skip the end re-hash.
+        const shaLineRe = /^coverage-check: lcov-sha256=([0-9a-f]{64}|none)$/;
+        const shaLines = String(checkerRow?.stdout ?? '').split(/\r?\n/).filter((l) => shaLineRe.test(l));
+        const shaValue = shaLines.length === 1 ? shaLineRe.exec(shaLines[0])[1] : null;
+        const lcovSha256 = shaValue !== null && shaValue !== 'none' ? shaValue : null;
+        if (allGreen && integrityFailure === null) {
+          if (shaLines.length !== 1) {
+            integrityFailure = shaLines.length === 0
+              ? 'the coverage-check gate printed no lcov-sha256 line — the consumed lcov is unknowable (fail closed)'
+              : `the coverage-check gate printed ${shaLines.length} lcov-sha256 lines — exactly ONE full machine line binds the receipt`;
+          } else if (lcovSha256 !== null) {
+            let endSha = null;
+            try {
+              const st = lstatSync(join(gitDir, LCOV_BASENAME));
+              if (st.isFile()) endSha = sha256Hex(readFileSync(join(gitDir, LCOV_BASENAME)));
+            } catch { /* vanished → disagreement below */ }
+            if (endSha !== lcovSha256) integrityFailure = 'the lcov moved under the checker (the end re-hash differs from the checker-read bytes)';
+          }
+        }
+        const status = allGreen && integrityFailure === null ? 'green' : 'red';
+        appendEvidenceRecord({
+          path: storePath,
+          record: {
+            schema: EVIDENCE_SCHEMA_VERSION,
+            kind: 'final',
+            status,
+            attempt: finalAttempt,
+            fingerprintBefore: finalFingerprintBefore,
+            fingerprintAfter: fingerprint(projectDir),
+            declared: declaration.gates.map(({ id, cmd }) => ({ id, cmd })),
+            results: results.map(({ id, ok, code }) => ({ id, ok, code })),
+            evidenceHashes: endBroken
+              ? startEvidenceHashes
+              : {
+                redProof: sha256Hex(canonicalKindSerialization(endRead.records, 'red-proof')),
+                degrade: sha256Hex(canonicalKindSerialization(endRead.records, 'degrade')),
+              },
+            lcovSha256,
+            integrityFailure,
+            timestamp: new Date().toISOString(),
           },
-          fingerprintBefore,
-          fingerprintAfter: fingerprint(projectDir),
         });
-        log(`[run-gates] gate-run recorded → ${writtenPath}`);
+        if (integrityFailure) {
+          finalError = new Error(integrityFailure);
+          logError(`[run-gates] --final integrity failure: ${integrityFailure} — the receipt is RED`);
+        }
+        log(`[run-gates] final receipt recorded (${status}) → ${storePath}`);
+        if (status === 'green' && lcovSha256 === null) {
+          logError(`[run-gates] --final consumed NO lcov — the coverage arm ran skipped-no-lcov; the receipt records lcovSha256:null (the declared unit-tests gate must produce <git-dir>/${LCOV_BASENAME})`);
+        }
       } catch (err) {
-        recordError = err;
-        logError(`[run-gates] --record failed: ${err.message}`);
+        finalError = err;
+        logError(`[run-gates] --final could not write its receipt: ${err.message}`);
       }
     }
     log(composeSummaryLine({ status: allGreen ? 'ok' : 'fail', results }));
-    if (recordError) return EXIT.recordFailed;
+    if (finalError) return EXIT.finalFailed;
     return allGreen ? EXIT.ok : EXIT.fail;
   } catch (err) {
     logError(`[run-gates] ${err.message}`);

package/tools/sandbox-masks.mjs

@@ -31,7 +31,7 @@
 // from the hidden-mode reconcile's block (hide-footprint.mjs — that lane noops on visible
 // deployments; this one serves them too). A malformed fence (start without end / duplicated
 // markers) fails CLOSED: loud report, file untouched. Patterns are root-anchored (`/rel`),
-// glob-metacharacters escaped, NUL-safe walk. Dependency-free, Node >= 18; no side effects on
+// glob-metacharacters escaped, NUL-safe walk. Dependency-free, Node >= 22; no side effects on
 // import (the isDirectRun idiom).
 
 import { lstatSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
@@ -69,7 +69,7 @@ const listUntrackedUnfilteredZ = (root) => {
 // name can never shadow a deeper real path), glob metacharacters + leading-! / leading-# handled
 // by the anchor, trailing whitespace escaped (gitignore trims it otherwise).
 // Trailing SPACES are escapable in gitignore (`\ `); a trailing TAB is not expressible — such a
-// name is classified unrenderable by the derivation (codex R12), so it never reaches this renderer.
+// name is classified unrenderable by the derivation, so it never reaches this renderer.
 export const toExcludePattern = (rel) => {
   const escaped = rel.replace(/([\\*?[\]])/g, '\\$1').replace(/ +$/, (m) => '\\ '.repeat(m.length));
   return `/${escaped}`;
@@ -79,7 +79,7 @@ export const toExcludePattern = (rel) => {
 // lstat class is never-committable (char/block/FIFO/socket). Everything else is refused by
 // construction — tracked paths never appear in an --others walk; regular/dir/symlink/missing fail
 // the predicate. A CR/LF-carrying mask NAME cannot be expressed as ONE gitignore rule — rendering
-// it would split into several rules and could hide unrelated committable paths (codex R3) — so it
+// it would split into several rules and could hide unrelated committable paths — so it
 // is a LOUD unrenderable skip, never written (the review domain already ignores the mask itself).
 export const deriveMasks = ({ root, lstat = lstatSync, listUntracked = listUntrackedUnfilteredZ } = {}) => {
   const entries = listUntracked(root);
@@ -95,7 +95,7 @@ export const deriveMasks = ({ root, lstat = lstatSync, listUntracked = listUntra
     }
     if (!isNeverCommittableStat(stat)) continue;
     // CR/LF anywhere, or a trailing TAB (inexpressible in gitignore — only trailing SPACES escape
-    // as `\ `; codex R12), make the name unrenderable as ONE exclude rule.
+    // as `\ `), make the name unrenderable as ONE exclude rule.
     if (/[\r\n]/.test(rel) || /\t$/.test(rel)) unrenderable.push(rel);
     else masks.push(rel);
   }
@@ -115,11 +115,11 @@ export const findMasksFence = (lines) => {
 
 // A fenced pattern back to its relative path (the derivation writes only `/rel` root-anchored
 // escaped forms; unescape is its exact inverse — the escaped-space form `\ ` included, so a
-// trailing-space mask round-trips; codex R1). Non-pattern lines (blank/comment) are skipped;
+// trailing-space mask round-trips). Non-pattern lines (blank/comment) are skipped;
 // only UNESCAPED trailing whitespace is insignificant (gitignore semantics).
 const patternToRel = (line) => {
   // A trailing CR (a CRLF-saved exclude file) strips FIRST — it would otherwise ride into the rel
-  // name and false-ENOENT the revalidation lstat (agy R5); then only UNESCAPED trailing
+  // name and false-ENOENT the revalidation lstat; then only UNESCAPED trailing
   // whitespace is insignificant (gitignore semantics — an escaped `\ ` survives).
   const t = line.replace(/\r$/, '').replace(/^[ \t]+/, '').replace(/(?<!\\)[ \t]+$/, '');
   if (t === '' || t.startsWith('#') || !t.startsWith('/')) return null;
@@ -156,13 +156,13 @@ export const probeSandboxMasks = ({ cwd = process.cwd(), lstat = lstatSync, list
   const commonDirRaw = gitLine(['rev-parse', '--git-common-dir'], cwd);
   if (gitPathRaw == null || commonDirRaw == null) return null;
   const excludeFile = resolve(cwd, gitPathRaw);
-  // The write-containment root (codex R2): info/exclude lives in the COMMON git dir (worktree-safe),
+  // The write-containment root: info/exclude lives in the COMMON git dir (worktree-safe),
   // and the apply must never write through a symlinked component or a non-regular leaf.
   const gitCommonDir = resolve(cwd, commonDirRaw);
   const derived = deriveMasks({ root, lstat, listUntracked });
   if (derived == null) return null;
   const { masks, unrenderable } = derived;
-  // The WHOLE chain is guarded BEFORE any read (codex R7+R8): a symlinked exclude leaf OR a
+  // The WHOLE chain is guarded BEFORE any read: a symlinked exclude leaf OR a
   // symlinked parent (.git/info) must never be read through, and a FIFO/socket leaf would HANG
   // the read-only probe — parent-chain containment + leaf lstat first, fail closed on everything
   // but a plain absent file, then read the existing REGULAR content. The apply re-checks
@@ -190,7 +190,7 @@ export const probeSandboxMasks = ({ cwd = process.cwd(), lstat = lstatSync, list
       content = readFile(excludeFile, 'utf8');
     } catch (err) {
       // The file existed a moment ago — ANY read failure now fails CLOSED (an apply over a misread
-      // "empty" file would overwrite hand content outside the managed block; codex R4).
+      // "empty" file would overwrite hand content outside the managed block).
       throw fail(1, `cannot read ${excludeFile} (${err?.code ?? err?.message ?? err}) — refusing to treat an unreadable exclude file as empty`);
     }
   }
@@ -222,7 +222,7 @@ export const planApply = (probe, { clear = false } = {}) => {
   }
   // --clear takes PRECEDENCE over the derivation (codex, Segment-A receipt): it means "remove the
   // managed block", even while masks are visible — re-writing the block instead of the requested
-  // clear would be a silent divergence. An EMPTY fence (markers, no entries) clears too (codex R8);
+  // clear would be a silent divergence. An EMPTY fence (markers, no entries) clears too;
   // no fence at all is a stated no-op.
   if (clear && probe.fence.state !== 'ok') {
     return { action: 'noop', reason: 'no managed block present — nothing to clear' };
@@ -236,7 +236,7 @@ export const planApply = (probe, { clear = false } = {}) => {
   }
   const masks = clear ? [] : probe.masks;
   const block = masks.length === 0 ? [] : [MASKS_FENCE_START, ...masks.map(toExcludePattern), MASKS_FENCE_END];
-  // EVERY hand byte outside the managed fence is preserved EXACTLY (codex R5+R6): the first-apply
+  // EVERY hand byte outside the managed fence is preserved EXACTLY: the first-apply
   // append adds at most ONE separator newline, and the existing-block replace splices via RAW
   // string offsets around the fence lines — a split/join('\n') rebuild would silently normalize
   // CRLF hand content outside the block. Only the fenced block itself is ours (always LF).
@@ -325,18 +325,18 @@ export const main = (argv, ctx = {}) => {
       return { code: 0, stdout: formatProbe(probe), stderr: '' };
     }
     const plan = planApply(probe, { clear: argv.includes('--clear') });
-    // The unrenderable skips stay LOUD on EVERY apply path (codex R4) — the same warning the
+    // The unrenderable skips stay LOUD on EVERY apply path — the same warning the
     // probe prints; the renderable subset still applies (a refusal would block the useful masks).
     const skipWarnings = probe.unrenderable
       .map((rel) => `sandbox-masks: ⚠ mask name carries a newline or ends with a tab and cannot be expressed as ONE exclude rule — NOT written (the review domain already ignores the mask itself): ${JSON.stringify(rel)}`)
       .join('\n');
-    // A refusal carries the unrenderable warnings too (codex R5) — they are never discarded.
+    // A refusal carries the unrenderable warnings too — they are never discarded.
     if (plan.action === 'refuse') throw fail(1, skipWarnings ? `${plan.reason}\n${skipWarnings}` : plan.reason);
     if (plan.action === 'noop') return { code: 0, stdout: `sandbox-masks: ${plan.reason}`, stderr: skipWarnings };
     const writeFile = ctx.deps?.writeFile ?? writeFileSync;
     const mkdir = ctx.deps?.mkdir ?? mkdirSync;
     const lstat = ctx.deps?.lstat ?? lstatSync;
-    // The write never follows a symlink or clobbers a non-regular leaf (codex R2): every component
+    // The write never follows a symlink or clobbers a non-regular leaf: every component
     // from the common git dir down is guarded, and an existing exclude leaf must be a regular file.
     try {
       assertContainedRealPath(probe.gitCommonDir, probe.excludeFile, { lstat });

package/tools/semver-lite.mjs

@@ -7,7 +7,7 @@
 // freshness probe that cannot parse a version must degrade to "unknown" — never to a false ordering
 // claim in either direction (INV-B). No `let`: a small functional comparison (AGENTS.md §2.3).
 //
-// Pure, no imports, no side effects, Node >= 18.
+// Pure, no imports, no side effects, Node >= 22.
 
 export const parseSemver = (str) => {
   const m = typeof str === 'string' ? str.trim().match(/^(\d+)\.(\d+)\.(\d+)/) : null;

package/tools/set-autonomy.mjs

@@ -19,7 +19,7 @@
 // (malformed/unreadable policy) or a write STOP (no deployment / symlinked leaf). main(argv, ctx) →
 // { code, stdout, stderr }; cwd / fs are injectable for host-independent tests.
 //
-// Dependency-free, Node >= 18. No side effects on import (the isDirectRun idiom).
+// Dependency-free, Node >= 22. No side effects on import (the isDirectRun idiom).
 
 import { readFileSync, lstatSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';

package/tools/set-recipe.mjs

@@ -19,7 +19,7 @@
 // or a write STOP (no deployment / symlinked leaf). main(argv, ctx) → { code, stdout, stderr }; cwd /
 // env / home / detect / fs are injectable for host-independent tests.
 //
-// Dependency-free, Node >= 18. No side effects on import (the isDirectRun idiom).
+// Dependency-free, Node >= 22. No side effects on import (the isDirectRun idiom).
 
 import { readFileSync, lstatSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -210,7 +210,7 @@ export const main = (argv, ctx = {}) => {
     const { writtenPath } = writeConfig(cwd, after, ctx);
     const fileBody = serializeConfig(after);
     // The echoed handover line carries the SAME autonomy levels recipes --active-line renders —
-    // sync facts (no render-check needed for the cells; codex R1, Segment B). A malformed policy
+    // sync facts (no render-check needed for the cells; Segment B). A malformed policy
     // surfaces loudly through the line's own MALFORMED segment.
     const autonomyFacts = (() => {
       try {

package/tools/setup-backends.mjs

@@ -21,7 +21,7 @@
 // wrappers are POSIX .sh — report unsupported / use WSL and mutate nothing. Every fs primitive is
 // injectable (deps.*) so the whole module is unit-testable without touching the real filesystem.
 //
-// Dependency-free, Node >= 18.
+// Dependency-free, Node >= 22.
 
 import {
   existsSync, lstatSync, statSync, readdirSync, readlinkSync, symlinkSync, mkdirSync, copyFileSync,

package/tools/surface.mjs

@@ -6,7 +6,7 @@
 // `/agent-workflow-kit status` surface always consumes `--json` and localizes itself.
 //
 // Pure + fully injectable (argv / env / isTTY / columns / platform are inputs), no side effects on
-// import, Node >= 18. Tested in isolation against the §4.5 table.
+// import, Node >= 22. Tested in isolation against the §4.5 table.
 
 export const FORMATS = Object.freeze(['auto', 'plain', 'ansi', 'json']);
 export const FORMAT_ENV = 'AGENT_WORKFLOW_FORMAT';

package/tools/uninstall.mjs

@@ -19,7 +19,7 @@
 //                    untouched and reported, never removed.
 //
 // Pure planner (buildPlan) + guarded executor (executePlan), both dependency-injectable so the whole
-// module is unit-testable without the real filesystem. Dependency-free, Node >= 18. No side effects on
+// module is unit-testable without the real filesystem. Dependency-free, Node >= 22. No side effects on
 // import (the isDirectRun idiom).
 
 import { existsSync, statSync, lstatSync, readlinkSync, readFileSync, readdirSync, realpathSync } from 'node:fs';