@sabaiway/agent-workflow-kit 5.2.0 → 5.4.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/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 });
@@ -670,6 +674,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 };
   }
@@ -1037,6 +1052,24 @@ 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
@@ -1053,10 +1086,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

@@ -86,6 +86,7 @@ const RAW_BACKENDS = [
           'threat model: the sidecar byte and grammar screens detect corrupted input under a trusted parent environment. A hostile parent environment — including exported shell functions or PATH substitution of core/backend commands — is outside the threat model and can substitute the backend itself. Targeted shadow-proof resolution protects banner/dispatch honesty from accidental shadowing; it is not an environment security boundary',
           'the exec posture banner appends a banner-only timeout=<duration|uncapped> field — exactly the duration handed to timeout(1), uncapped when no timeout/gtimeout binary caps the run; INFORMATIONAL only: it is never persisted in a receipt or session sidecar',
           'quote the posture banner verbatim when labeling this dispatch — the banner is the machine-stated posture; a prose re-type drifts',
+          'every-run nested-sandbox scan (DUAL policy, deliberately two different rules): the scan runs on EVERY completed run, not only a failed one, because a run that SURVIVES the nested-sandbox failure exits 0 with an ungrounded answer and nothing said so. Failed run (rc != 0): the existing loose whole-trace combination rule prints the recovery hint. Successful run (rc == 0): a warning fires ONLY on precise per-item evidence — both a sandbox-mechanism token AND a permission/read-only failure token inside the aggregated_output of ONE command_execution item whose failure is PROVEN (a nonzero exit_code, or the serialized status "failed"); a null exit_code is never failure by itself, tokens split across two items never fire, and a successful command\'s output never fires. The answer is printed FIRST on stdout, then the warning on stderr. HONEST RESIDUAL: the exit status does NOT change on that lane (a distinct nonzero exit would give a heuristic scan DENY polarity, refusing real work whenever the scan over-warns), so an orchestrator keying on exit status alone can still bank an ungrounded answer — the stderr warning is the signal',
         ],
       },
       review: {