@sabaiway/agent-workflow-kit 5.3.0 → 5.5.0

package/references/scripts/migrate-gates.mjs

@@ -5,7 +5,9 @@
 // COMPLETELY in one consented step: it REMOVES the canonical legacy entries, EXTENDS the
 // canonical `unit-tests` cmd with the built-in lcov reporters (the D3(d) coverage source), and
 // ADDS the coverage-check gate LAST (removal alone is not a migration — the result must satisfy
-// `run-gates --final` and carry a working commit path).
+// `run-gates --final` and carry a working commit path). The checker is added ONLY over a
+// declaration that PRODUCES the lcov it reads; with no producer it is WITHHELD with a loud
+// warning, because a checker with no producer passes (`skipped-no-lcov`) while verifying nothing.
 //
 // Matching is by the DOCUMENTED cmd forms ONLY (hand-wired history included — never by seed
 // provenance): a legacy entry is `node <path>/review-ledger.mjs --check` or
@@ -45,12 +47,69 @@ export const LEGACY_FORMS = Object.freeze([
   { name: 'fold-completeness', re: legacyRe('fold-completeness\\.mjs') },
 ]);
 
-// The D3(d) reporter flags the canonical unit-tests cmd gains — lcov at the fixed git-dir path
-// run-gates --final exports, plus an explicit stdout reporter (without it the lcov reporter
-// swallows the human TAP/spec stream).
+// coverage-producer canon >>> BEGIN drift-guarded region
+// Authored TWICE, byte-identically: in the memory substrate's references/scripts/migrate-gates.mjs
+// and in the composition root's tools/coverage-producer.mjs. Neither side imports the other — the
+// substrate is standalone and must not depend on the root, and the root must not import mirrored
+// bytes — so a TEXT drift guard beside the root's copy holds them equal. Edit BOTH, then re-run the
+// mirror sync.
+//
+// The destination is written against AW_GIT_DIR, which run-gates exports to every gate child on a
+// plain run AND on --final (AW_LCOV_FILE is --final only), so one cmd survives the unmet
+// producer-variable preflight in both modes. The explicit stdout reporter is not decoration:
+// without it the lcov reporter swallows the human TAP/spec stream.
 export const UNIT_TESTS_COVERAGE_FLAGS =
   '--experimental-test-coverage --test-reporter=lcov --test-reporter-destination="$AW_GIT_DIR/agent-workflow-lcov.info" --test-reporter=spec --test-reporter-destination=stdout';
 
+// The ONE suite body that produces that lcov with no extra dependency.
+export const COVERAGE_PRODUCER_BODY = `node --test ${UNIT_TESTS_COVERAGE_FLAGS}`;
+
+// The per-PM exec wrappers a fill offer puts that body behind. Recognition must cover every form
+// the kit has EMITTED, so the prefixes are matched literally; gates-init's execCmdFor stays the one
+// EMITTER and is bound to this list by a named acceptance test, never by a second grammar.
+const PRODUCER_EXEC_PREFIXES = Object.freeze([
+  'COREPACK_ENABLE_NETWORK=0 npm exec --offline --script-shell /bin/sh -- ',
+  'COREPACK_ENABLE_NETWORK=0 pnpm exec -- ',
+  'COREPACK_ENABLE_NETWORK=0 yarn exec -- ',
+]);
+
+// A trailing suffix is the project's own test paths; a leading one would mean the body is not what
+// this cmd runs. The tail passes a POSITIVE closed grammar — every whitespace-separated token must
+// be path-shaped — never an operator blocklist: `node --test <flags> && rm -f <lcov>` runs the
+// suite and then DELETES the file, so an open-ended tail would certify a producer that leaves
+// nothing behind, and scanning for operator BYTES would put the incomplete-scan failure on the
+// unsafe side (a missed operator is a dead pair) instead of the mild one (an unrecognised
+// legitimate tail merely withholds the offer — add the gate by hand).
+// The token set is everything that appears in a PATH or a glob and can never sequence, redirect or
+// substitute a command — quoting and `~` included, `( ) $ ` ; & | < > # \` excluded. SCOPE, stated
+// exactly: the screen judges each token's SOURCE bytes. Quote removal adds none, but brace SEQUENCE
+// expansion does — `{Y..a}` yields ``[ \ ] ^ _ ` `` (probed) — so "no new bytes" would be a false
+// claim. What holds is the property that matters: bash does not re-scan an expansion result as
+// syntax, so a byte arriving that way is literal argument DATA, never an operator. The leading-`-`
+// exclusion is weaker still — a FIRST-ORDER screen only, defeated by `'--flag'` and
+// `{path,--flag}`. It is kept because the tail is the project's test PATHS and it costs only a loud
+// withhold. Deciding an argument's post-expansion identity needs a shell lexer, which this family
+// deliberately has NOWHERE (AD-079). So the claim is "configured with the reporters", never "the
+// lcov survives the command"; a run that produces none is caught honestly at runtime as
+// `skipped-no-lcov`.
+const PRODUCER_PATH_TOKEN = /^(?!-)[A-Za-z0-9_./*{},:@+=~?[\]!'"-]+$/;
+const pathShapedTail = (tail) => tail === '' || tail.split(/[ \t]+/).every((token) => PRODUCER_PATH_TOKEN.test(token));
+const carriesProducerBody = (text) =>
+  text === COVERAGE_PRODUCER_BODY ||
+  (text.startsWith(`${COVERAGE_PRODUCER_BODY} `) && pathShapedTail(text.slice(COVERAGE_PRODUCER_BODY.length).trim()));
+
+// matchesCoverageProducer(cmd) → CLOSED-WORLD over the full command forms the kit emits, never a
+// substring probe: `echo "$AW_GIT_DIR/agent-workflow-lcov.info"`, a half-written reporter flag set,
+// or the path as a bare substring must all read as NOT a producer — otherwise the checker is
+// declared over a gate that writes nothing and then PASSES while certifying nothing.
+export const matchesCoverageProducer = (cmd) => {
+  if (typeof cmd !== 'string') return false;
+  const trimmed = cmd.trim();
+  if (carriesProducerBody(trimmed)) return true;
+  return PRODUCER_EXEC_PREFIXES.some((prefix) => trimmed.startsWith(prefix) && carriesProducerBody(trimmed.slice(prefix.length)));
+};
+// coverage-producer canon <<< END drift-guarded region
+
 // The RETIRED kit-owned git-dir stores the deleted machinery wrote — dead data a consumer's
 // upgrade would otherwise strand forever. The migration cleans them (consented via the preview;
 // ENOENT is a silent no-op; any other unlink error is reported loudly but never fails the
@@ -147,13 +206,20 @@ export const buildMigrationPlan = (gates, kitToolsDir) => {
     plan.push({ action: 'keep', entry: gate, reason: null });
   }
   const kept = plan.filter((r) => r.action === 'keep' || r.action === 'extend');
+  // The checker READS an lcov; something has to WRITE it. Adding the checker over a declaration
+  // with no producer creates the dead pair — the gate PASSES (`skipped-no-lcov`) and certifies
+  // nothing, so the migration withholds it and says why instead.
+  const hasProducer = kept.some((r) => matchesCoverageProducer(r.entry.cmd));
   let collision = null;
+  let checkerWithheld = false;
   if (checkerRow === null) {
     // A surviving NON-canonical entry already holding the checker's id blocks the add — two
     // `coverage-check` rows would be ambiguous; the customized entry must be resolved by hand
     // FIRST (the caller turns this into a loud STOP on preview and apply alike).
     if (kept.some((r) => r.entry.id === 'coverage-check')) {
       collision = 'coverage-check';
+    } else if (!hasProducer) {
+      checkerWithheld = true;
     } else {
       plan.push({
         action: 'add',
@@ -165,8 +231,23 @@ export const buildMigrationPlan = (gates, kitToolsDir) => {
     checkerRow.action = 'move';
     checkerRow.reason = 'the canonical checker must be the LAST declared gate (nothing may run after it consumed the lcov)';
   }
+  // An ALREADY-declared checker over no producer is the same dead pair the withhold prevents — an
+  // earlier deployment could have created it. The migration removes no declared gate, so it reports
+  // the inertness and refuses to call the result final-run-capable.
+  const checkerInert = checkerRow !== null && !hasProducer;
   const reviewStateCandidate = `{ "id": "review-state", "title": "Review receipts converged (D3(b))", "cmd": "node \\"${join(kitToolsDir, 'review-state.mjs')}\\" --check" }`;
-  return { plan, customized, unitTestsExtended, finalCapable: hasReviewState, reviewStateCandidate, collision };
+  return {
+    plan,
+    customized,
+    unitTestsExtended,
+    finalCapable: hasReviewState && !checkerWithheld && !checkerInert,
+    hasProducer,
+    hasReviewState,
+    checkerWithheld,
+    checkerInert,
+    reviewStateCandidate,
+    collision,
+  };
 };
 
 export const resultingGates = (plan) => {
@@ -184,7 +265,7 @@ const customizedRecovery = (gate) =>
     ? `declare the canonical suite gate by hand so the coverage contract is verifiable: node --test ${UNIT_TESTS_COVERAGE_FLAGS} <your test paths>`
     : 'remove the entry, or repoint it at a living check — the review-ledger / fold-completeness tools no longer exist.';
 
-const warningLines = ({ customized, finalCapable, reviewStateCandidate }) => {
+const warningLines = ({ customized, finalCapable, hasReviewState = finalCapable, checkerWithheld = false, checkerInert = false, reviewStateCandidate }) => {
   const lines = [];
   for (const gate of customized) {
     lines.push(`  CUSTOMIZED (untouched): ${gate.id}: ${gate.cmd}`);
@@ -193,7 +274,15 @@ const warningLines = ({ customized, finalCapable, reviewStateCandidate }) => {
   if (customized.length) {
     lines.push('  IMPORTANT: do NOT install the commit guard until every customized entry above is resolved — a declaration that cannot pass run-gates --final would block every commit.');
   }
-  if (!finalCapable) {
+  if (checkerWithheld) {
+    lines.push('  WARNING: the canonical coverage-check gate was NOT added — no declared gate would PRODUCE the lcov it reads, and a checker with no producer passes while verifying nothing. Declare the suite gate first, then re-run this migration:');
+    lines.push(`    node --test ${UNIT_TESTS_COVERAGE_FLAGS} <your test paths>`);
+  }
+  if (checkerInert) {
+    lines.push('  WARNING: the DECLARED coverage-check gate is INERT — no declared gate PRODUCES the lcov it reads, so it passes while verifying nothing. Nothing is removed for you; declare the suite gate:');
+    lines.push(`    node --test ${UNIT_TESTS_COVERAGE_FLAGS} <your test paths>`);
+  }
+  if (!hasReviewState) {
     lines.push('  WARNING: the result is NOT final-run-capable — no canonical review-state check is declared. Add it (paste-ready), then run-gates --final can mint the receipt:');
     lines.push(`    ${reviewStateCandidate}`);
   }
@@ -201,7 +290,7 @@ const warningLines = ({ customized, finalCapable, reviewStateCandidate }) => {
 };
 
 export const formatPreview = (analysis, applyHint) => {
-  const { plan, unitTestsExtended, finalCapable, retiredStores = [] } = analysis;
+  const { plan, unitTestsExtended, finalCapable, hasProducer = unitTestsExtended, retiredStores = [] } = analysis;
   const lines = ['[agent-workflow] legacy gates.json migration preview (dry-run — nothing was written):'];
   const acted = plan.filter((r) => r.action !== 'keep');
   for (const r of acted) {
@@ -217,7 +306,9 @@ export const formatPreview = (analysis, applyHint) => {
         : '  nothing to migrate mechanically — no canonical legacy entries and no retired stores; the warnings below still need a hand.',
     );
   }
-  if (!unitTestsExtended && !plan.some((r) => r.entry.id === 'unit-tests')) {
+  // Keyed on the ID, but a PRODUCER is recognized under any id — repeating this advice over a
+  // working producer sends the user to fix nothing.
+  if (!hasProducer && !unitTestsExtended && !plan.some((r) => r.entry.id === 'unit-tests')) {
     lines.push('  note: no canonical `unit-tests` entry found — declare your suite gate with the lcov reporters by hand (the coverage-check gate reads the file it produces).');
   }
   lines.push(...warningLines(analysis));
@@ -317,7 +408,8 @@ Usage:
 Default is a dry-run PREVIEW (writes nothing). --apply rewrites ${GATES_REL} atomically:
 canonical legacy entries (review-ledger / fold-completeness --check, matched by their documented
 single-invocation forms) are REMOVED; the canonical unit-tests cmd gains the built-in lcov
-reporters; the coverage-check gate is ADDED last (resolved, QUOTED path). Customized entries are
+reporters; the coverage-check gate is ADDED last (resolved, QUOTED path) — and WITHHELD, loudly,
+when no declared gate produces the lcov it reads. Customized entries are
 NEVER auto-touched — the preview names each with a paste-ready recovery, and the commit guard
 must not be installed until they are resolved.`;
 

package/references/scripts/migrate-gates.test.mjs

@@ -12,6 +12,7 @@ import { spawnSync } from 'node:child_process';
 import {
   LEGACY_FORMS,
   UNIT_TESTS_COVERAGE_FLAGS,
+  COVERAGE_PRODUCER_BODY,
   RETIRED_STORE_BASENAMES,
   findRetiredStores,
   buildMigrationPlan,
@@ -71,6 +72,42 @@ describe('migrate-gates — the pure migration plan', () => {
     assert.ok(!again.plan.some((r) => r.action === 'add'), 'a declaration already carrying the checker gains no duplicate');
   });
 
+  it('a declaration with NO producer never GAINS the checker — the pair is declared together or not at all', () => {
+    const npmSuite = { id: 'suite', title: 'S', cmd: 'npm test' };
+    const analysis = buildMigrationPlan([LEGACY_LEDGER, npmSuite], KIT_TOOLS);
+    assert.ok(!analysis.plan.some((r) => r.action === 'add'), 'no checker is added over a declaration that produces no lcov');
+    assert.deepEqual(resultingGates(analysis.plan).map((g) => g.id), ['suite'], 'the legacy entry still goes, nothing dead arrives');
+    assert.equal(analysis.finalCapable, false, 'a declaration with no checker is not final-run-capable');
+    const preview = formatPreview(analysis, 'APPLY');
+    assert.match(preview, /coverage-check/, 'the withheld checker is named');
+    assert.match(preview, /produce/i, 'the preview says WHY — no gate produces the lcov it would read');
+  });
+
+  it('an ALREADY-declared checker over no producer is reported INERT, is never removed, and is not final-run-capable', () => {
+    const checker = { id: 'coverage-check', title: 'CC', cmd: `node "${join(KIT_TOOLS, 'coverage-check.mjs')}" --check` };
+    const reviewState = { id: 'review-state', title: 'RS', cmd: `node "${join(KIT_TOOLS, 'review-state.mjs')}" --check` };
+    const analysis = buildMigrationPlan([{ id: 'suite', title: 'S', cmd: 'npm test' }, reviewState, checker], KIT_TOOLS);
+    assert.equal(analysis.finalCapable, false, 'a review-state present must NOT make an inert pair read as final-run-capable');
+    assert.ok(resultingGates(analysis.plan).some((g) => g.id === 'coverage-check'), 'the declared checker is never removed');
+    const preview = formatPreview(analysis, 'APPLY');
+    assert.match(preview, /INERT/, 'the inert pair is named');
+    assert.match(preview, /--experimental-test-coverage/, 'the paste-ready suite cmd is carried');
+    assert.doesNotMatch(preview, /already final-run-capable/);
+  });
+
+  it('a gates-init-shaped producer (the exec-wrapped offer form) is recognized — the checker IS added over it', () => {
+    const offered = {
+      id: 'test',
+      title: 'T',
+      cmd: `COREPACK_ENABLE_NETWORK=0 npm exec --offline --script-shell /bin/sh -- ${COVERAGE_PRODUCER_BODY}`,
+    };
+    const analysis = buildMigrationPlan([offered], KIT_TOOLS);
+    assert.deepEqual(resultingGates(analysis.plan).map((g) => g.id), ['test', 'coverage-check']);
+    // The `no canonical unit-tests entry` advice is keyed on the ID, but a producer is recognized
+    // under ANY id — repeating the advice over a working producer sends the user to fix nothing.
+    assert.doesNotMatch(formatPreview(analysis, 'APPLY'), /declare your suite gate with the lcov reporters by hand/);
+  });
+
   it('a CUSTOMIZED dead-tool reference (compound form) is kept untouched and reported', () => {
     const analysis = buildMigrationPlan([CUSTOM], KIT_TOOLS);
     assert.equal(analysis.plan.find((r) => r.entry.id === 'my-ledger-wrap').action, 'keep');

package/tools/commands.mjs

@@ -259,6 +259,13 @@ const CATALOG = [
     kind: READ_ONLY,
     oneLine: 'Check that the documented contract tokens still match the live code constants they describe — a read-only lint that fails closed on drift; --check turns it into a gate exit code.',
   },
+  {
+    key: 'dispatch',
+    invocation: invocationOf('dispatch'),
+    group: 'Orchestrate',
+    kind: WRITER,
+    oneLine: 'Measure delegation: check a sub-task brief’s contract block (form only — never whether the task is genuinely bounded), pre-register an acceptance wave with its thresholds, record one observation, open a delegated thread from that brief, wait for that one dispatch to answer — a wait that ends without an answer says so and authorizes nothing — absorb the wrapper’s receipt back into the ledger, fold the returned work or close the thread with a recorded degrade, and print the per-class report of how much a delegated sub-task actually bought, derived from what was dispatched, returned and folded. Writes only its own ledger file beside the repo; never commits.',
+  },
   {
     // NEVER `guarded` — that kind promises dry-run-first, which these writers do not have; the
     // honest strongest caution is `writer` with the destructive arm named in the line itself.

package/tools/core-evidence.mjs

@@ -24,7 +24,8 @@
 // re-derived): safe repo-relative path resolution, no-follow real-path containment, shell-free
 // argv, per-run timeout, N/N reruns, the quarantine lane (reruns 3, timeout 120s).
 // Import posture: this module is the DAG BOTTOM — it imports only node built-ins + atomic-write +
-// changed-surface, and OWNS the canonical review-domain primitives (tree fingerprint, receipt read
+// changed-surface + the pure leaves (repo-lex, fs-read-nofollow, coverage-state), and OWNS the
+// canonical review-domain primitives (tree fingerprint, receipt read
 // path, attesting predicate, verdict vocabulary, testId format, base resolution). review-state
 // RE-EXPORTS its historical public API from here, so its consumers (and the bash-twin parity
 // tests) are unchanged while review-state can import the degrade reader without an import cycle.
@@ -42,6 +43,9 @@ import { writeContainedFileAtomic } from './atomic-write.mjs';
 import { parsePositiveIntKnob, probeVerdict } from './changed-surface.mjs';
 import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
 import { lexicalRepoRelative } from './repo-lex.mjs';
+// The coverage vocabulary leaf: run-gates RECORDS the token this validator checks, and run-gates
+// imports THIS module (the sole-writer boundary), so their shared home sits below both.
+import { COVERAGE, FINAL_COVERAGE_STATES } from './coverage-state.mjs';
 
 export const CORE_EVIDENCE_STOP = 'CORE_EVIDENCE_STOP';
 const stop = (message) => Object.assign(new Error(`[agent-workflow-kit] ${message}`), { name: 'CoreEvidenceStop', code: CORE_EVIDENCE_STOP });
@@ -52,7 +56,9 @@ const GIT_MAX_BUFFER = 256 * 1024 * 1024; // a full-tree diff / TAP stream can b
 
 const gitRaw = (args, cwd) => spawnSync('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
 
-const gitBuf = (args, cwd) => {
+// Exported so a consumer computing over the SAME domain (the exec metric producer) reads git through
+// this one runner instead of growing a second spawnSync wrapper with its own buffer bound.
+export const gitBuf = (args, cwd) => {
   const r = gitRaw(args, cwd);
   if (r.error || r.status !== 0) return null;
   return r.stdout;
@@ -670,6 +676,17 @@ export const validateEvidenceRecord = (record) => {
     if (record.lcovSha256 !== null && (typeof record.lcovSha256 !== 'string' || !HEX64_RE.test(record.lcovSha256))) {
       return { ok: false, reason: 'final: lcovSha256 must be a 64-hex sha256 of the consumed lcov file, or null when none was produced' };
     }
+    // The run's coverage token is ADDITIVE (absent = a pre-token receipt, still valid) and CLOSED.
+    // `certified` is cross-checked against the bound digest — a run that certified a verdict read
+    // bytes, so the two fields can never disagree in the store.
+    if ('coverage' in record) {
+      if (!FINAL_COVERAGE_STATES.includes(record.coverage)) {
+        return { ok: false, reason: `final: coverage, when present, must be one of ${FINAL_COVERAGE_STATES.join(' | ')} (got ${JSON.stringify(record.coverage)}; a final run always selects the canonical checker, so "none" never rides a final receipt)` };
+      }
+      if (record.coverage === COVERAGE.certified && record.lcovSha256 === null) {
+        return { ok: false, reason: 'final: coverage "certified" requires a bound lcovSha256 — a certified verdict was issued over lcov bytes that were read' };
+      }
+    }
     if (!isNonEmptyString(record.timestamp)) return { ok: false, reason: 'final: timestamp must be a non-empty string' };
     return { ok: true };
   }
@@ -997,6 +1014,26 @@ export const runDegrade = ({ cwd = process.cwd(), env = process.env, backend, re
 
 // ── the summary verb (D6): ONE stateless render — receipts + evidence store, no ledger ────────────
 
+// A red-proof binds the BYTES of the test file it was observed on, and the final-run checker refuses
+// when those bytes have moved (coverage-check.mjs, the hash-mismatch arm). This render used to print a
+// stale record byte-identically to a live one, so the only place staleness surfaced was that gate —
+// after both council dispatches, at the commit boundary, which is the most expensive discovery point
+// in the loop. The currency is therefore computed HERE, from the SAME two helpers the checker uses, so
+// the render and the gate can never disagree about what stale means.
+//
+// An unresolvable or unreadable file is STALE, not unknown: a proof nobody can re-check is not a proof
+// anyone should read as current.
+export const redProofCurrency = (rootTop, record) => {
+  if (rootTop == null) return { state: 'stale', detail: 'the work-tree root is not resolvable' };
+  const resolved = resolveTestFile(rootTop, record.file);
+  if (!resolved.ok) return { state: 'stale', detail: resolved.reason };
+  const current = hashFileBytes(resolved.abs);
+  if (current == null) return { state: 'stale', detail: `cannot read "${record.file}"` };
+  return current === record.fileHash
+    ? { state: 'current' }
+    : { state: 'stale', detail: 'the bound test file changed after the mint' };
+};
+
 export const buildSummaryState = ({ cwd = process.cwd(), env = process.env } = {}) => {
   const fingerprint = computeTreeFingerprint(cwd);
   const base = resolveBase(cwd);
@@ -1011,7 +1048,10 @@ export const buildSummaryState = ({ cwd = process.cwd(), env = process.env } = {
     backend: b,
     summary: summarizeReviewReceiptsForTree(receipts.filter((r) => r.backend === b), fingerprint),
   }));
-  const redProofs = authoritativeOfKind(store.records, 'red-proof').filter((r) => r.base === base);
+  const rootTop = gitLine(['rev-parse', '--show-toplevel'], cwd);
+  const redProofs = authoritativeOfKind(store.records, 'red-proof')
+    .filter((r) => r.base === base)
+    .map((r) => ({ ...r, currency: redProofCurrency(rootTop, r) }));
   const degrades = authoritativeOfKind(store.records, 'degrade').filter((r) => r.fingerprint === fingerprint);
   const finalRun = authoritativeOfKind(store.records, 'final').find((r) => r.fingerprintBefore === fingerprint) ?? null;
   // A malformed/unreadable store makes the AUTHORITATIVE selection untrustworthy (a dropped later
@@ -1037,13 +1077,40 @@ const verdictLine = ({ backend, summary }) => {
   return `${backend}: no attesting receipt for the current tree (stale or missing)`;
 };
 
+// Why the run issued no verdict, keyed by the token IT recorded. `certified` maps to nothing —
+// there is no absence to name. A legacy receipt predates the token: the only honest thing to say
+// is what the RECORD carries, which is true by construction. Exported as a test seam (keyFor).
+const COVERAGE_QUALIFIER = Object.freeze({
+  [COVERAGE.notRun]: 'the recorded run issued no coverage verdict',
+  [COVERAGE.unknown]: 'the recorded run produced no readable coverage signal',
+});
+const LEGACY_COVERAGE_QUALIFIER = `coverage=${COVERAGE.unknown}: this legacy receipt carries no coverage token and binds no lcov digest`;
+
+export const coverageQualifierFor = (finalRun) => {
+  if (!finalRun) return '';
+  if (typeof finalRun.coverage === 'string') {
+    const why = COVERAGE_QUALIFIER[finalRun.coverage];
+    return why ? ` — coverage=${finalRun.coverage}: ${why}` : '';
+  }
+  return finalRun.lcovSha256 == null ? ` — ${LEGACY_COVERAGE_QUALIFIER}` : '';
+};
+
 export const renderSummary = (s) => {
   const short = (hex) => (typeof hex === 'string' ? `${hex.slice(0, 12)}…` : String(hex));
   const evidenceSections = s.evidenceUnavailable
     ? [`  evidence sections WITHHELD — the store is unavailable (${s.storeMalformed} malformed line(s)${s.storeReadError ? `, read error: ${s.storeReadError}` : ''}); a dropped line could resurrect a superseded record — inspect ${s.storePath}`]
     : [
         `  red-proof records (current base): ${s.redProofs.length ? '' : '(none)'}`,
-        ...s.redProofs.map((r) => `    ${r.testId} — ${r.reds}/${r.runs} red, hash ${short(r.fileHash)}, pre-fix fingerprint ${short(r.fingerprint)}`),
+        ...s.redProofs.map((r) => {
+          const stale = r.currency?.state === 'stale';
+          const mark = stale ? `STALE (${r.currency.detail})` : 'CURRENT';
+          return `    ${r.testId} — ${mark} · ${r.reds}/${r.runs} red, hash ${short(r.fileHash)}, pre-fix fingerprint ${short(r.fingerprint)}`;
+        }),
+        // The recovery, printed once and only when it is needed — it was written down nowhere, and
+        // the loop paid for that three times.
+        ...(s.redProofs.some((r) => r.currency?.state === 'stale')
+          ? ['    ↳ a STALE proof is refused by run-gates --final: park the fix so the bound test fails again, re-observe it with `core-evidence red-proof "<testId>"`, then restore the fix. Edit test files FIRST and re-observe ONCE per park — every proof bound to an edited file goes stale together.']
+          : []),
         `  degrade records (current tree): ${s.degrades.length ? '' : '(none)'}`,
         ...s.degrades.map((d) => `    ${d.backend} — ${d.reason} (${d.timestamp})`),
       ];
@@ -1053,10 +1120,17 @@ export const renderSummary = (s) => {
         '  review verdicts (current tree):',
         ...(s.verdicts.length ? s.verdicts.map((v) => `    ${verdictLine(v)}`) : ['    (no receipts)']),
       ];
+  // The withheld coverage verdict travels here too: an unqualified GREEN repeats, one surface
+  // further on, the false reassurance the checker's own attested=no exists to close. It is read
+  // from the token the RUN recorded — `lcovSha256` says what the receipt binds, never whether a
+  // verdict was issued — and it rides RED as well: an absent verdict is a property of the run, not
+  // of its colour. A LEGACY receipt (no token) is named as exactly that, never as a claim about
+  // what it read. DETAIL beside an unchanged status word.
+  const coverageQualifier = coverageQualifierFor(s.finalRun);
   const finalLine = s.evidenceUnavailable
     ? null
     : s.finalRun
-      ? `  final gate run: ${s.finalRun.status === 'green' ? 'GREEN' : 'RED'} (${s.finalRun.results.filter((r) => r.ok).length}/${s.finalRun.results.length} gates, ${s.finalRun.timestamp})`
+      ? `  final gate run: ${s.finalRun.status === 'green' ? 'GREEN' : 'RED'}${coverageQualifier} (${s.finalRun.results.filter((r) => r.ok).length}/${s.finalRun.results.length} gates, ${s.finalRun.timestamp})`
       : '  final gate run: (none recorded for the current tree)';
   const lines = [
     'core-evidence summary — stateless render (review receipts + evidence store; no ledger, no rounds)',

package/tools/coverage-check.mjs

@@ -179,6 +179,11 @@ export const attestationState = ({ env, records, fingerprint, base }) => {
   return { attesting: true };
 };
 
+// The withheld-verdict reason for the one case a VALID context cannot rescue: the run owned the
+// artifact's lifetime and read NO bytes — an absent file and a refused path alike, which is why
+// this states the bytes rather than the skip.
+const NO_BYTES_NO_VERDICT = 'no lcov bytes were read at the checked path, so no verdict could be issued — a run that read nothing certifies nothing; if no gate produces the file, declare a coverage PRODUCER beside the checker (references/modes/gates.md names the exact form)';
+
 // ── the red-proof verification arm (D3(c)) ────────────────────────────────────────────────────────
 
 // verifyRedProofs({ rootTop, cwd, env }) → { failures: [...], verified: n } | { storeFailure }.
@@ -276,7 +281,13 @@ export const runCheck = ({ cwd = process.cwd(), env = process.env } = {}) => {
   const identityAfter = { fingerprint: computeTreeFingerprint(cwd), base: resolveBase(cwd) };
   const attestAfter = attestationState({ env, records: storeRecords, ...identityAfter });
   const attestation = attestBefore.refusal ? attestBefore : attestAfter;
-  const attesting = attestation.attesting === true && attestBefore.attesting === true;
+  const contextValid = attestation.attesting === true && attestBefore.attesting === true;
+  // `attested=` states whether a coverage VERDICT was ISSUED — pass OR fail — never that coverage
+  // passed: a valid handshake over uncovered lines still reads yes and still exits 1. What no
+  // context can rescue is an EMPTY read, and the honest predicate is the BYTES CONSUMED, not the
+  // skip flag: an absent lcov and a refused path (a symlink) both read nothing, and attesting over
+  // either is the same false green this whole arm exists to close, one layer up.
+  const attesting = contextValid && cov.lcovSha256 !== null;
   // EXACTLY ONE fully anchored machine line, the lcov-sha256 contract's sibling — the runner binds
   // it, so a missing/duplicated/injected one is an integrity failure rather than a silent green.
   lines.push(`coverage-check: attested=${attesting ? 'yes' : 'no'}`);
@@ -284,11 +295,11 @@ export const runCheck = ({ cwd = process.cwd(), env = process.env } = {}) => {
     failed = true;
     lines.push(`coverage-check: REFUSED — ${attestation.refusal}`);
   } else if (!attesting) {
-    lines.push(`coverage-check: NO VERDICT — ${attestation.reason}`);
+    lines.push(`coverage-check: NO VERDICT — ${contextValid ? NO_BYTES_NO_VERDICT : attestation.reason}`);
   }
   // The attestation gates ONLY the coverage claim. Every pre-existing fail-closed refusal above
   // (symlinked lcov, malformed evidence store, unmet red-proof obligation) keeps its own exit 1.
-  if (attesting && !failed && !cov.skipped && cov.failures.length === 0) {
+  if (attesting && !failed && cov.failures.length === 0) {
     lines.push('coverage-check: PASS — every changed Node line is covered');
   }
   return { code: failed ? 1 : 0, lines };
@@ -314,10 +325,15 @@ store fails (exit 1).
 A coverage VERDICT is issued ONLY inside the run that owns the artifact's lifetime: run-gates
 --final deletes the lcov before any gate spawns and hands this checker an attestation context
 (a nonce whose one-way commitment over {nonce, fingerprint, base} is the final-start attempt id).
-One anchored machine line rides every run: coverage-check: attested=<yes|no>.
-  attested=yes → the verdict, exactly as before.
-  attested=no  → NO VERDICT (exit 0): findings are still printed, uncovered lines still exit 1;
-                 only the PASS attestation is withheld.
+One anchored machine line rides every run: coverage-check: attested=<yes|no>. It states whether a
+coverage VERDICT was ISSUED — pass OR fail — never that coverage passed.
+  attested=yes → a verdict was issued over the lcov BYTES this run read (a failing one still
+                 exits 1); the predicate is the consumed digest, never the skip flag.
+  attested=no  → NO VERDICT: no handshake, or no lcov bytes were read at all (an absent file or a
+                 refused path — nothing read, nothing certified). Withholding a verdict never
+                 changes an exit code: an absent lcov stays exit 0, a refused non-regular path
+                 keeps its own fail-closed exit 1, and uncovered lines still exit 1. Findings are
+                 still printed; run-gates carries the withheld verdict as coverage=not-run.
   REFUSED (exit 1) → the context describes another tree, or matches no recorded attempt.
 Residual, stated: ownership of the fixed path is CONVENTION, not enforcement — a concurrent writer
 to it can still place foreign evidence (queued as LCOV-EXCLUSIVE-OWNERSHIP).

package/tools/coverage-producer.mjs

@@ -0,0 +1,68 @@
+// coverage-producer.mjs — the kit's half of the shared coverage-producer vocabulary: the reporter
+// flags the canonical suite gate carries, and the CLOSED predicate deciding whether a declared gate
+// cmd actually WRITES the lcov the canonical checker reads. A LEAF — imports nothing, so every
+// consumer (gates-init, gates-declaration, the advisor) decides through ONE predicate.
+// Dependency-free, Node >= 22. No side effects on import.
+
+// coverage-producer canon >>> BEGIN drift-guarded region
+// Authored TWICE, byte-identically: in the memory substrate's references/scripts/migrate-gates.mjs
+// and in the composition root's tools/coverage-producer.mjs. Neither side imports the other — the
+// substrate is standalone and must not depend on the root, and the root must not import mirrored
+// bytes — so a TEXT drift guard beside the root's copy holds them equal. Edit BOTH, then re-run the
+// mirror sync.
+//
+// The destination is written against AW_GIT_DIR, which run-gates exports to every gate child on a
+// plain run AND on --final (AW_LCOV_FILE is --final only), so one cmd survives the unmet
+// producer-variable preflight in both modes. The explicit stdout reporter is not decoration:
+// without it the lcov reporter swallows the human TAP/spec stream.
+export const UNIT_TESTS_COVERAGE_FLAGS =
+  '--experimental-test-coverage --test-reporter=lcov --test-reporter-destination="$AW_GIT_DIR/agent-workflow-lcov.info" --test-reporter=spec --test-reporter-destination=stdout';
+
+// The ONE suite body that produces that lcov with no extra dependency.
+export const COVERAGE_PRODUCER_BODY = `node --test ${UNIT_TESTS_COVERAGE_FLAGS}`;
+
+// The per-PM exec wrappers a fill offer puts that body behind. Recognition must cover every form
+// the kit has EMITTED, so the prefixes are matched literally; gates-init's execCmdFor stays the one
+// EMITTER and is bound to this list by a named acceptance test, never by a second grammar.
+const PRODUCER_EXEC_PREFIXES = Object.freeze([
+  'COREPACK_ENABLE_NETWORK=0 npm exec --offline --script-shell /bin/sh -- ',
+  'COREPACK_ENABLE_NETWORK=0 pnpm exec -- ',
+  'COREPACK_ENABLE_NETWORK=0 yarn exec -- ',
+]);
+
+// A trailing suffix is the project's own test paths; a leading one would mean the body is not what
+// this cmd runs. The tail passes a POSITIVE closed grammar — every whitespace-separated token must
+// be path-shaped — never an operator blocklist: `node --test <flags> && rm -f <lcov>` runs the
+// suite and then DELETES the file, so an open-ended tail would certify a producer that leaves
+// nothing behind, and scanning for operator BYTES would put the incomplete-scan failure on the
+// unsafe side (a missed operator is a dead pair) instead of the mild one (an unrecognised
+// legitimate tail merely withholds the offer — add the gate by hand).
+// The token set is everything that appears in a PATH or a glob and can never sequence, redirect or
+// substitute a command — quoting and `~` included, `( ) $ ` ; & | < > # \` excluded. SCOPE, stated
+// exactly: the screen judges each token's SOURCE bytes. Quote removal adds none, but brace SEQUENCE
+// expansion does — `{Y..a}` yields ``[ \ ] ^ _ ` `` (probed) — so "no new bytes" would be a false
+// claim. What holds is the property that matters: bash does not re-scan an expansion result as
+// syntax, so a byte arriving that way is literal argument DATA, never an operator. The leading-`-`
+// exclusion is weaker still — a FIRST-ORDER screen only, defeated by `'--flag'` and
+// `{path,--flag}`. It is kept because the tail is the project's test PATHS and it costs only a loud
+// withhold. Deciding an argument's post-expansion identity needs a shell lexer, which this family
+// deliberately has NOWHERE (AD-079). So the claim is "configured with the reporters", never "the
+// lcov survives the command"; a run that produces none is caught honestly at runtime as
+// `skipped-no-lcov`.
+const PRODUCER_PATH_TOKEN = /^(?!-)[A-Za-z0-9_./*{},:@+=~?[\]!'"-]+$/;
+const pathShapedTail = (tail) => tail === '' || tail.split(/[ \t]+/).every((token) => PRODUCER_PATH_TOKEN.test(token));
+const carriesProducerBody = (text) =>
+  text === COVERAGE_PRODUCER_BODY ||
+  (text.startsWith(`${COVERAGE_PRODUCER_BODY} `) && pathShapedTail(text.slice(COVERAGE_PRODUCER_BODY.length).trim()));
+
+// matchesCoverageProducer(cmd) → CLOSED-WORLD over the full command forms the kit emits, never a
+// substring probe: `echo "$AW_GIT_DIR/agent-workflow-lcov.info"`, a half-written reporter flag set,
+// or the path as a bare substring must all read as NOT a producer — otherwise the checker is
+// declared over a gate that writes nothing and then PASSES while certifying nothing.
+export const matchesCoverageProducer = (cmd) => {
+  if (typeof cmd !== 'string') return false;
+  const trimmed = cmd.trim();
+  if (carriesProducerBody(trimmed)) return true;
+  return PRODUCER_EXEC_PREFIXES.some((prefix) => trimmed.startsWith(prefix) && carriesProducerBody(trimmed.slice(prefix.length)));
+};
+// coverage-producer canon <<< END drift-guarded region

package/tools/coverage-state.mjs

@@ -0,0 +1,24 @@
+// coverage-state.mjs — the coverage vocabulary LEAF (kit-inert-gate Phase 2, Decision 8).
+//
+// Two consumers need the same closed value set and cannot import each other: run-gates.mjs REPORTS
+// the token on its summary line and records it on the `--final` receipt, and core-evidence.mjs
+// VALIDATES that recorded field — and run-gates already imports core-evidence (the sole-writer
+// boundary), so the dependency can only run this way. ONE home, no drift guard needed: the
+// repo-lex.mjs / gates-declaration.mjs leaf idiom.
+//
+// No imports, no CLI, no side effects. Dependency-free, Node >= 22.
+
+// The CLOSED set, with ONE value defined for every run outcome. It is DETAIL, never a new state:
+// no exit code, no `status=` token, no receipt status and no commit-guard disposition reads it.
+export const COVERAGE = Object.freeze({
+  certified: 'certified', // the canonical checker consumed lcov bytes and ISSUED a verdict — pass OR fail
+  notRun: 'not-run', // the checker ran and issued NO verdict: nothing was read, or the run holds no attestation context
+  none: 'none', // no canonical checker ran here (an --only subset, the --pre-review derived subset)
+  unknown: 'unknown', // the run ended before the gates produced the signal, or the signal is unreadable
+});
+
+// What may ride a `final` receipt. `none` never can: --final REFUSES a declaration that does not
+// carry the canonical checker last, so a final run always selects it (run-gates.mjs --final
+// preflight) — a recorded `none` would mean the receipt describes a run that could not have
+// happened, and the validator says so instead of storing it.
+export const FINAL_COVERAGE_STATES = Object.freeze([COVERAGE.certified, COVERAGE.notRun, COVERAGE.unknown]);

package/tools/declared-paths.mjs

@@ -0,0 +1,32 @@
+// declared-paths.mjs — the shared resolution + containment leaf for a DECLARED settings path
+// (`sandbox.filesystem.allowWrite`). Two consumers must never disagree about what such an entry
+// MEANS: the advisor's worktrees-dir convergence lane asks "does a declared entry cover this dir?",
+// and the autonomy render's allowWrite degrade asks "does this entry resolve outside the repo?" —
+// the same resolution and the same containment rule, read from opposite ends. A second resolver
+// would let those two answers drift, so the rule lives here once.
+//
+// A LEAF: imports node:path only (never the advisor, never the render — the advisor already imports
+// the render). No side effects on import. Dependency-free, Node >= 22.
+
+import { resolve, sep } from 'node:path';
+
+// What counts as a RESOLVABLE declared entry, shared by both consumers so they cannot disagree about
+// which entries are readable at all. A blank entry is rejected deliberately: it means nothing to a
+// host, but it would resolve to the project root and thereby read as a grant on the whole repo.
+export const isResolvableDeclaredEntry = (entry) => typeof entry === 'string' && entry.trim() !== '';
+
+// Resolve a declared entry the way a host that honors the key resolves it: `~` and `~/…` against the
+// resolved home, every other form (relative or absolute) against the project root.
+export const resolveDeclaredDir = (entry, { home, root }) => {
+  if (entry === '~') return resolve(home);
+  if (entry.startsWith('~/')) return resolve(home, entry.slice(2));
+  return resolve(root, entry);
+};
+
+// Ancestor-or-equal containment on PATH SEGMENTS, never a raw string prefix — a grant on `<p>/farm`
+// must never read as a grant on the sibling `<p>/farmhouse`. A grant on a DESCENDANT never covers
+// its parent: the parent dir is the one a provision writes into.
+export const dirCovers = (containerDir, candidateDir) => {
+  const base = containerDir.endsWith(sep) ? containerDir.slice(0, -sep.length) : containerDir;
+  return candidateDir === base || candidateDir.startsWith(`${base}${sep}`);
+};

package/tools/detect-backends.mjs

@@ -67,14 +67,15 @@ const RAW_BACKENDS = [
     roleContracts: {
       execute: {
         invocations: [
-          'codex-exec <plan-file|->',
-          'codex-exec <plan-file|-> -- <extra codex flags...>',
+          'codex-exec [--nonce <n>] <plan-file|->',
+          'codex-exec [--nonce <n>] <plan-file|-> -- <extra codex flags...>',
         ],
         grounding: "automatic — the root AGENTS.md (Hard Constraints) is auto-merged into codex's context and the wrapper prepends the orchestrator execution contract; no grounding flags",
         continue: [
-          'codex-exec --resume-last <plan-file|->',
-          'codex-exec --resume <session-id> <plan-file|->',
+          'codex-exec --resume-last [--nonce <n>] <plan-file|->',
+          'codex-exec --resume <session-id> [--nonce <n>] <plan-file|->',
         ],
+        receipt: "side effect — a NONCED run mints ONE exec receipt beside the delegation store: the dispatch nonce seam is the AW_DISPATCH_NONCE environment value or its plain-argument equivalent --nonce <n>, recognised ONLY before the prompt operand (after the operand or a literal '--' it is passthrough payload, never a flag), under the safe grammar [A-Za-z0-9._-]{1,64} — anything else, a duplicate, or a flag disagreeing with a non-empty env value refuses PRE-SPEND. The store directory resolves exactly as the kit's delegation store does: the dirname of an ABSOLUTE AW_DELEGATION_STORE (a relative one, or one ending in a path separator, refuses), else the git common dir. The artifact is agent-workflow-exec-receipt-<backendLength>-<backend>-<nonce>.json in two states: 'reserved' is written atomically and NO-CLOBBER immediately before the CLI runs — that write IS the nonce reservation, so a second dispatch on the same nonce, or an already-taken report name, refuses BEFORE any spend — and 'terminal' replaces it in place at exit. A nonced run also refuses pre-spend when no timeout/gtimeout binary can cap it (an accounted dispatch that cannot be capped can never honour the terminal-exit rule; a nonce-LESS run still warns and runs uncapped), when node is missing (the mint core), and when the prompt rides on stdin instead of a contract FILE — contractDigest is computed BY THIS WRAPPER from the dispatch file it was actually handed, so the kit can refuse a run that executed a different contract than the one it opened. That digest is taken from the SAME bytes already read as the prompt, never a second open of the path: two reads leave a window in which the file can be swapped, and the run would then execute one contract while its receipt claimed the digest of another. The header's own nonce must EQUAL the dispatch nonce — 'dispatch open' copies the nonce FROM the header, so a disagreeing --nonce could only reserve an identity no return would ever absorb, and it refuses pre-spend. A contract file edited BETWEEN 'dispatch open' and the run is caught at ABSORB by the contractDigest comparison, not pre-spend: the wrapper never reads the ledger, and that boundary is what the whole lane rests on. At exit the wrapper FIRST re-reads its reservation and verifies its own opaque owner token — a foreign owner refuses having published NOTHING, neither report nor receipt — THEN writes the delegate's final message atomically to agent-workflow-exec-report-<backendLength>-<backend>-<nonce>.txt, THEN re-verifies the owner and REPLACES the reservation with the terminal receipt {schema, kind, state, backend, nonce, owner, contractDigest, wrapperVersion, posture {model, effort, tier}, capS, killGraceS, sessionId, exitStatus, outcome, reportDigest, reportLength, timestamp}: the report is complete on disk before any artifact says the run arrived. capS and killGraceS are the cap the run ACTUALLY applied. outcome is the wrapper's own SUBSET of the ledger's vocabulary — exit 0 with a session id -> success, exit 0 without one -> missing-identity, ANY nonzero exit including the timeout codes 124 and 137 -> transport-failure; every orchestrator judgment is recorded at absorb time, never claimed here. The session id is captured BEFORE outcome branching, so a FAILED run records one too; in resume mode it is the validated resume id. FAIL-CLOSED, deliberately NOT the review lane's warn-only receipt: a publication that cannot complete exits nonzero with a DISTINCT status, and the message states only what the run can still prove. 70: the reservation could not be verified BEFORE any publication — NOTHING was published, not the report and not the receipt, and because the artifact found there belongs to another run it is never a '--no-receipt' source. 71: a publication stopped after that point — either the report write failed (nothing beyond the reservation was published; the '--no-receipt' absorb then records reportLength 0, ineligible by the name empty-report) or the report IS on disk and the terminal receipt was not completed (the absorb reads it, report-if-present). The post-report lane never claims the reservation still stands, because after that point its fate is no longer something this run observed. Every lane names the tree as partial/dirtied rather than untouched. A nonce-LESS invocation is byte-unchanged: no reservation, no receipt, no artifact, no node.",
         passthrough: {
           policy: 'guarded',
           blocked: ['-c*', '--config*', '-s*', '--sandbox*', '--dangerously-bypass-approvals-and-sandbox', '--dangerously-bypass-hook-trust', '--full-auto', '--oss', '--local-provider*', '-p*', '--profile*', '-m*', '--model*', '-o*', '--output-last-message*', '--json*', '--color*', '--output-schema*', '--ephemeral*'],