@sabaiway/agent-workflow-kit 4.2.0 → 4.4.0

package/tools/repo-search.mjs

@@ -9,10 +9,16 @@
 //
 //   lane 1  --pattern <literal>        for a pattern with no shell-significant byte
 //   lane 2  --pattern-file <path>      the pattern's bytes NEVER enter the command string
+//   lane 3  --paths-file <path>        the TARGETS' bytes never enter it either
 //
-// The selection rule is enforced by the hook, not by memory: this tool's invocation is in the
-// hook's scanned list, so choosing lane 1 for a byte-carrying pattern earns an ASK whose reason
-// names lane 2. A wrong choice costs one guiding prompt; it never costs silence.
+// Lane 3 exists because lanes 1-2 answered only half the arguments: a search could name a pattern it
+// could not spell in a shell, but not a PATH it could not spell, and this kit ships shell-byte
+// fixtures as a genre. Both lane files are excluded from the search itself, by REAL path.
+//
+// The hook covers this tool's invocation: choosing lane 1 for a byte-carrying pattern raises an ASK
+// whose reason names lane 2. Stated exactly: that ask goes to the HUMAN, and the reason is context for
+// their decision — it is not delivered to the caller that composed the command. So the ask costs one
+// human decision and never costs silence, but it is not by itself a correction mechanism.
 //
 // CONTRACT
 //   LITERAL only — no regex dialect, and none is planned for this slice: a bounded walk cannot
@@ -58,6 +64,15 @@ export const DEFAULT_WALK_BUDGET = 20000;
 // bounds are advisory, which is the same as absent.
 export const HARD_MAX_RESULTS = 100000;
 export const HARD_MAX_FILE_BYTES = 64 * 1024 * 1024;
+// The `--paths-file` lane's own bounds. A target list arrives as a FILE, so neither its size nor its
+// entry count is visible in the command string the caller composed — without ceilings here the lane
+// would be the one unbounded input on a tool whose every other input is bounded.
+export const HARD_MAX_TARGETS = 5000;
+export const HARD_MAX_PATHS_FILE_BYTES = 4 * 1024 * 1024;
+// The AGGREGATE read budget. The walk budget counts ENTRIES; without a byte ceiling a run may read up
+// to the per-file limit for every one of them, which is unbounded work no bound was consulted about.
+export const DEFAULT_MAX_TOTAL_BYTES = 256 * 1024 * 1024;
+export const HARD_MAX_TOTAL_BYTES = 4 * 1024 * 1024 * 1024;
 const BINARY_SNIFF_BYTES = 8192;
 // Characters of context kept on EACH side of a match, and a HARD ceiling on the whole snippet.
 // The ceiling is the load-bearing one: bounding only the context still lets a huge --pattern-file
@@ -73,8 +88,12 @@ const NOFOLLOW = constants.O_NOFOLLOW ?? 0;
 const NONBLOCK = constants.O_NONBLOCK ?? 0;
 const OPEN_FLAGS = constants.O_RDONLY | NOFOLLOW | NONBLOCK;
 
-class UsageError extends Error {}
-class IoError extends Error {}
+// Exported so a sibling kit tool reusing `parsePathsFile` maps the SAME failure to the SAME exit
+// code by construction — an `instanceof` against a private class would silently degrade a usage
+// error into a generic one, and exit-code parity between the two file lanes would be a promise
+// instead of a mechanism.
+export class UsageError extends Error {}
+export class IoError extends Error {}
 
 // The pattern is echoed as a DIGEST plus a byte length — never as a first content line. A first
 // line cannot separate two multiline patterns that share it, and it is unsafe for NUL/control
@@ -104,7 +123,7 @@ export const parseCount = (raw, flag, ceiling) => {
 };
 
 const parseArgs = (argv) => {
-  const opts = { pattern: null, patternFile: null, paths: [], max: DEFAULT_MAX_RESULTS, maxBytes: DEFAULT_MAX_FILE_BYTES, json: false };
+  const opts = { pattern: null, patternFile: null, paths: [], pathsFile: null, max: DEFAULT_MAX_RESULTS, maxBytes: DEFAULT_MAX_FILE_BYTES, maxTotalBytes: DEFAULT_MAX_TOTAL_BYTES, json: false };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     const next = () => {
@@ -115,8 +134,10 @@ const parseArgs = (argv) => {
     if (arg === '--pattern') opts.pattern = next();
     else if (arg === '--pattern-file') opts.patternFile = next();
     else if (arg === '--path') opts.paths.push(next());
+    else if (arg === '--paths-file') opts.pathsFile = next();
     else if (arg === '--max') opts.max = parseCount(next(), '--max', HARD_MAX_RESULTS);
     else if (arg === '--max-bytes') opts.maxBytes = parseCount(next(), '--max-bytes', HARD_MAX_FILE_BYTES);
+    else if (arg === '--max-total-bytes') opts.maxTotalBytes = parseCount(next(), '--max-total-bytes', HARD_MAX_TOTAL_BYTES);
     else if (arg === '--json') opts.json = true;
     else throw new UsageError(`unknown argument: ${arg} (see --help)`);
   }
@@ -124,14 +145,107 @@ const parseArgs = (argv) => {
     throw new UsageError('--pattern and --pattern-file are mutually exclusive — the lane must be unambiguous');
   }
   if (opts.pattern === null && opts.patternFile === null) throw new UsageError('one of --pattern or --pattern-file is required');
-  if (opts.paths.length === 0) opts.paths.push('.');
+  // The default target is applied only when the caller named NEITHER lane: `--paths-file` supplies
+  // targets after argv is parsed, so defaulting here on an empty `--path` list would silently union
+  // the whole root into an explicitly named list.
+  if (opts.paths.length === 0 && opts.pathsFile === null) opts.paths.push('.');
   return opts;
 };
 
+// The `--paths-file` format, pinned rather than discovered: one target per line, UTF-8, LF or CRLF, a
+// trailing delimiter is not an extra entry, EMPTY lines are ignored, duplicates collapse. There is no
+// comment syntax and no escaping, so a filename containing a newline CANNOT be expressed by this lane
+// — stated here because an unstated gap in a lane that exists to carry awkward names is the defect,
+// not the gap.
+//
+// A line is NOT trimmed. This lane exists to carry names a command string cannot, and a leading or
+// trailing space is exactly such a name: trimming would silently rewrite the caller's target, which is
+// the failure mode the lane was built to remove. A whitespace-only line is therefore a real target and
+// either resolves or fails loudly — never a silent stand-in for the root.
+//
+// THREE name classes this lane CANNOT express, stated rather than discovered: one containing a
+// newline (there is no escaping); one ENDING in a carriage return (a trailing CR is stripped as the
+// CRLF delimiter it almost always is, and no line-oriented format can tell those apart without an
+// encoding this lane deliberately does not have); and one whose bytes are not valid UTF-8. The first
+// two are refused by silence — the target simply will not be found, loudly. The third is refused
+// EXPLICITLY, because `Buffer.toString('utf8')` would replace the offending bytes with U+FFFD and the
+// lane would then search a DIFFERENT path that happens to exist, which is worse than any refusal.
+// `ignoreBOM: true` means "do not TREAT a leading U+FEFF as a byte-order mark", i.e. keep it as a
+// character. The default strips it, which would rewrite a legitimate name beginning with U+FEFF into
+// a different one — the same silent-substitution class as a lossy decode, one layer down.
+const strictUtf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+
+export const decodeLaneFile = (buf, flag) => {
+  try {
+    return strictUtf8.decode(buf);
+  } catch {
+    throw new UsageError(`${flag} is not valid UTF-8 — a lossy decode would silently name a different path`);
+  }
+};
+export const parsePathsFile = (raw, flag = '--paths-file') => {
+  const entries = raw.split('\n').map((line) => (line.endsWith('\r') ? line.slice(0, -1) : line)).filter((line) => line !== '');
+  // The ceiling counts TARGETS, so it is applied after dedupe: a file repeating one path 5001 times
+  // names one target and refusing it would be a bound on the file's shape rather than on the work.
+  const unique = [...new Set(entries)];
+  if (unique.length > HARD_MAX_TARGETS) {
+    throw new UsageError(`${flag} lists ${unique.length} distinct targets, above the ceiling of ${HARD_MAX_TARGETS}`);
+  }
+  if (unique.length === 0) throw new UsageError(`${flag} names no target — a blank list is never "search everything"`);
+  return unique;
+};
+
+// ── the acceptance predicate for a caller-supplied TARGET ─────────────────────────────
+//
+// ONE closed rule set, applied before any target reaches `resolve()`. It replaces what were seven
+// checks discovered one review round at a time, all of which turned out to be the same defect: a
+// caller string is handed to `path.resolve()` / `realpathSync`, whose semantics differ from the
+// operating system's, so the tool can end up answering about a DIFFERENT object than the string
+// denotes. That is the one outcome worse than any refusal.
+//
+// The rule the predicate enforces: **a target is accepted only if it names exactly one filesystem
+// object unambiguously.** Awkward-but-unambiguous names are supported on purpose — edge whitespace,
+// backticks, control bytes — because carrying those is what the out-of-band lane exists for.
+//
+// Separators are PLATFORM-CORRECT, and that is load-bearing: on POSIX a backslash is an ordinary
+// byte in a filename, so splitting on it would refuse `\..` — a legal file the OS answers about
+// normally. An over-refusal is a smaller defect than a wrong answer, but it is still a defect.
+const TARGET_SEPARATORS = Object.freeze(sep === '\\' ? ['/', '\\'] : ['/']);
+const TARGET_SEPARATOR_SPLIT = sep === '\\' ? /[\\/]/u : /\//u;
+
+// A trailing separator, or a trailing `.` component, is an ASSERTION by the caller that the target is
+// a DIRECTORY — that is what it means to the operating system, which answers ENOTDIR when it is not.
+// `resolve()` erases both forms before the filesystem sees them, so the assertion has to be carried
+// separately and checked after resolution. Refusing these outright was wrong in both directions: it
+// rejected `existing-directory/`, which names one object unambiguously, while still accepting
+// `regular-file/.`, which the OS refuses.
+//
+// Stated divergence, and it differs per tool. `path-inventory` reports a symlink BY TYPE and never
+// follows it, so `symlink-to-a-directory/` is not a directory there, while the OS would dereference
+// it — following it would contradict that tool's louder promise. `repo-search` DOES resolve an
+// explicitly named target (its threat model says so at the top of this file), so the assertion is
+// checked against the resolved object and it agrees with the OS.
+export const requiresDirectory = (target) => {
+  if (TARGET_SEPARATORS.some((separator) => target.endsWith(separator))) return true;
+  const components = target.split(TARGET_SEPARATOR_SPLIT);
+  return components[components.length - 1] === '.';
+};
+
+export const assertNameableTarget = (target, flag = '--path') => {
+  const refuse = (why) => {
+    throw new UsageError(`${flag} ${why} — got ${JSON.stringify(target)}`);
+  };
+  if (target === '') refuse('must not be empty; an empty target resolves to the whole root');
+  if (target.includes('\0')) refuse('must not contain a NUL byte; no filesystem path can hold one');
+  if (target.split(TARGET_SEPARATOR_SPLIT).includes('..')) {
+    refuse('must not contain a ".." component; resolve() collapses it lexically, so the answer could be about a different object than the OS would reach');
+  }
+};
+
 // Containment on the REAL path. A lexical check passes `link/secret.txt` whenever `link` resolves
 // outside, and on Windows a cross-drive `relative()` returns an absolute path carrying no `..` —
 // both were live review findings, not hypotheticals.
 export const resolveTarget = (realRoot, target) => {
+  assertNameableTarget(target);
   const lexical = resolve(realRoot, target);
   let real;
   try {
@@ -144,12 +258,15 @@ export const resolveTarget = (realRoot, target) => {
   if (rel !== '' && (isAbsolute(rel) || rel === '..' || rel.startsWith(`..${sep}`))) {
     throw new IoError(`target resolves outside the search root: ${target}`);
   }
+  if (requiresDirectory(target) && !lstatSync(real).isDirectory()) {
+    throw new IoError(`no such path: ${target} — a trailing separator or "." asserts a directory, and this is not one`);
+  }
   return real;
 };
 
 // Open → fstat the DESCRIPTOR → read bounded. The descriptor is what was actually opened, so a swap
 // after the check cannot substitute a different node; O_NOFOLLOW refuses a symlinked leaf outright.
-const readRegularFile = (abs, maxBytes, state, io = {}) => {
+const readRegularFile = (abs, maxBytes, state, io = {}, boundName = 'max-file-bytes') => {
   const open = io.open ?? openSync;
   const fstat = io.fstat ?? fstatSync;
   const read = io.read ?? readSync;
@@ -174,7 +291,7 @@ const readRegularFile = (abs, maxBytes, state, io = {}) => {
       // A skipped file is NOT a silent omission: the search is incomplete and says which bound did
       // it. Reporting it only as a counter would let a partial search read as "no matches".
       if (state.incomplete === null) {
-        state.incomplete = { bound: 'max-file-bytes', detail: `at least one file exceeds ${maxBytes} byte(s) and was not searched` };
+        state.incomplete = { bound: boundName, detail: `at least one file exceeds ${maxBytes} byte(s) and was not searched` };
       }
       return null;
     }
@@ -184,6 +301,10 @@ const readRegularFile = (abs, maxBytes, state, io = {}) => {
       const n = read(fd, buf, got, stat.size - got, got);
       if (n <= 0) break;
       got += n;
+      // Charged INSIDE the loop, per successful chunk. After the loop is too late: a `read` that
+      // throws mid-file skips the charge entirely, so a series of partial reads that end in a fault
+      // would move real bytes the aggregate budget never learns about.
+      state.bytesRead += n;
     }
     // A short read means the file changed under us. Returning the partial buffer would let a
     // truncated file come back as a confident "no matches" — the file is classified unreadable
@@ -293,11 +414,29 @@ const walk = (root, abs, pattern, state, isExplicitTarget = false) => {
     }
     return;
   }
-  if (state.excludePath !== null && abs === state.excludePath) {
-    state.skipped.patternFile += 1;
+  const excludedAs = state.excludePaths.get(abs);
+  if (excludedAs !== undefined) {
+    state.skipped[excludedAs] += 1;
+    return;
+  }
+  // The walk budget counts ENTRIES, not bytes, so without this a run may read up to the per-file
+  // ceiling for every one of them — twenty thousand files at the hard per-file ceiling is work no
+  // bound was ever consulted about. The sibling inventory tool already carries an aggregate byte
+  // budget for exactly this reason; this closes the asymmetry rather than stating it.
+  const remaining = state.maxTotalBytes - state.bytesRead;
+  if (remaining <= 0) {
+    state.incomplete = state.incomplete ?? {
+      bound: '--max-total-bytes',
+      detail: `stopped after reading ${state.bytesRead} byte(s); the tree was not fully searched`,
+    };
     return;
   }
-  const buf = readRegularFile(abs, state.maxBytes, state, state.io);
+  // The read is bounded by whichever ceiling binds FIRST. Checking the aggregate only BEFORE the file
+  // and then handing the reader the full per-file limit lets a single file larger than the remaining
+  // budget be read whole — the budget would bound the accounting, not the work.
+  const limit = Math.min(state.maxBytes, remaining);
+  const boundName = limit < state.maxBytes ? '--max-total-bytes' : 'max-file-bytes';
+  const buf = readRegularFile(abs, limit, state, state.io, boundName);
   if (buf === null) return;
   if (isBinary(buf)) {
     state.skipped.binary += 1;
@@ -310,15 +449,20 @@ const walk = (root, abs, pattern, state, isExplicitTarget = false) => {
 // directory, a symlink refused by O_NOFOLLOW, a file truncated mid-read — are reachable from tests.
 // Every one of them is a COUNTED skip in production, and a counted skip that no test ever exercises
 // is indistinguishable from a silent one.
-export const search = ({ root, pattern, paths, max, maxBytes, excludePath = null, walkBudget = DEFAULT_WALK_BUDGET, io = {} }) => {
+// `excludePaths` maps a REAL path to the skip counter it belongs to: BOTH lane files must be kept out
+// of their own search (a `--paths-file` under a searched target would otherwise match on its own
+// contents), and a skip that is not attributed to its lane is indistinguishable from a silent one.
+export const search = ({ root, pattern, paths, max, maxBytes, excludePaths = new Map(), walkBudget = DEFAULT_WALK_BUDGET, maxTotalBytes = DEFAULT_MAX_TOTAL_BYTES, io = {} }) => {
   const state = {
     matches: [],
     incomplete: null,
-    skipped: { symlinks: 0, binary: 0, special: 0, unreadable: 0, large: 0, patternFile: 0 },
-    excludePath,
+    skipped: { symlinks: 0, binary: 0, special: 0, unreadable: 0, large: 0, patternFile: 0, pathsFile: 0 },
+    excludePaths,
     io,
     walked: 0,
     walkBudget,
+    bytesRead: 0,
+    maxTotalBytes,
     max,
     maxBytes,
   };
@@ -334,6 +478,9 @@ export const search = ({ root, pattern, paths, max, maxBytes, excludePath = null
     incomplete: state.incomplete,
     skipped: state.skipped,
     scanned: state.walked,
+    // Reported so the aggregate budget is observable rather than internal: a bound that nobody can
+    // read is a bound nobody can test.
+    bytesRead: state.bytesRead,
   };
 };
 
@@ -351,14 +498,27 @@ const formatResult = (result) => {
 
 const HELP = `repo-search — literal repository search that never has to ride a shell metacharacter.
 
-Usage:
-  node repo-search.mjs --pattern <literal> [--path <p>]... [--max <n>] [--max-bytes <n>] [--json]
-  node repo-search.mjs --pattern-file <path> [--path <p>]... [--max <n>] [--max-bytes <n>] [--json]
+Usage — pick ONE pattern lane and ANY combination of target lanes:
+  pattern lane   --pattern <literal>   |   --pattern-file <path>          (mutually exclusive)
+  target lanes   [--path <p>]...       and/or   --paths-file <path>       (union; default: .)
+  shared flags   [--max <n>] [--max-bytes <n>] [--max-total-bytes <n>] [--json]
+
+A target must NAME EXACTLY ONE filesystem object: no empty value, no NUL byte, and no ".."
+component (resolve() collapses it before the filesystem sees it). A trailing "/" or "/." is NOT
+rejected — it ASSERTS the target is a directory, exactly as it does to the OS: it holds for a real
+directory and fails for anything else. Awkward-but-unambiguous names — edge whitespace, backticks,
+control bytes — are supported, and --paths-file is the lane for the ones a command string cannot
+carry.
+
+Two out-of-band lanes, one per argument half — their bytes never enter the command string, so the
+residual guard has nothing to scan:
+  --pattern-file <path>   a PATTERN carrying shell-significant bytes (\`>\`, \`$(\`, a backtick)
+  --paths-file <path>     TARGET paths carrying the same, one per line
 
---pattern-file is the lane for a pattern carrying shell-significant bytes (\`>\`, \`$(\`, a backtick):
-its bytes never enter the command string, so the residual guard has nothing to scan. Write the file
-with your host's file-write tool, then pass the plain path here, and delete it when you are done —
-this tool never writes.
+Write either file with your host's file-write tool, pass the plain path here, and delete it when you
+are done — this tool never writes. --paths-file format: one target per line, UTF-8, LF or CRLF; blank
+lines ignored; duplicates collapse; no comment syntax and no escaping, so a filename containing a
+newline cannot be expressed by this lane. Both lane files are excluded from the search itself.
 
 LITERAL only, multiline patterns supported. Reads regular files only, opened no-follow. Skipped
 entries (symlinks, non-regular, binary, oversized, unreadable) are counted and reported, never
@@ -372,21 +532,49 @@ export const main = (argv, ctx = {}) => {
     if (argv.includes('--help') || argv.includes('-h')) return { code: EXIT_OK, stdout: HELP, stderr: '', result: null };
     const root = realpathSync(resolve(ctx.cwd ?? process.cwd()));
     const opts = parseArgs(argv);
+    const excludePaths = new Map();
+    // ONE reader for both out-of-band lanes, so their failure classification cannot drift: a missing,
+    // unreadable or non-regular lane file is an IoError (exit 1) for the pattern lane and for the
+    // target lane alike.
+    const readLaneFile = (rel, flag, maxBytes, counter) => {
+      const abs = resolveTarget(root, rel);
+      // `bytesRead` is present but SEPARATE from the search's budget: reading a lane file is the
+      // caller's own instruction, not tree traversal, so it is accounted and then discarded.
+      const state = { skipped: { symlinks: 0, special: 0, unreadable: 0, large: 0 }, incomplete: null, bytesRead: 0 };
+      const buf = readRegularFile(abs, maxBytes, state);
+      if (buf === null) throw new IoError(`cannot read ${flag} ${rel} as a regular file`);
+      excludePaths.set(abs, counter);
+      return decodeLaneFile(buf, flag);
+    };
     let raw;
-    let excludePath = null;
     if (opts.patternFile !== null) {
-      excludePath = resolveTarget(root, opts.patternFile);
-      const state = { skipped: { symlinks: 0, special: 0, unreadable: 0, large: 0 }, incomplete: null };
-      const buf = readRegularFile(excludePath, HARD_MAX_FILE_BYTES, state);
-      if (buf === null) throw new IoError(`cannot read --pattern-file ${opts.patternFile} as a regular file`);
-      raw = buf.toString('utf8');
+      raw = readLaneFile(opts.patternFile, '--pattern-file', HARD_MAX_FILE_BYTES, 'patternFile');
     } else {
       raw = opts.pattern;
     }
     const pattern = opts.patternFile !== null ? resolvePattern(raw) : raw;
     if (pattern === '') throw new UsageError('the pattern is empty — it would match every line of every file');
 
-    const result = search({ root, pattern, paths: opts.paths, max: opts.max, maxBytes: opts.maxBytes, excludePath });
+    const named = [...opts.paths];
+    if (opts.pathsFile !== null) {
+      const listed = readLaneFile(opts.pathsFile, '--paths-file', HARD_MAX_PATHS_FILE_BYTES, 'pathsFile');
+      named.push(...parsePathsFile(listed));
+    }
+    // Dedupe across the UNION, not only within each lane: the same target named by `--path` and by
+    // the file would otherwise be walked twice.
+    const paths = [...new Set(named)];
+    // EVERY target is validated BEFORE any of them is walked. Validating lazily per target means an
+    // invalid one late in the list is only refused if the walk gets that far — and a bound that fires
+    // on an earlier target ends the loop first, so the same invocation would be accepted or refused
+    // depending on how much work happened to be done. A refusal must not depend on scheduling.
+    for (const target of paths) assertNameableTarget(target);
+    // The ceiling holds over the UNION. `parsePathsFile` bounds the file, but thousands of `--path`
+    // values would otherwise walk straight past it.
+    if (paths.length > HARD_MAX_TARGETS) {
+      throw new UsageError(`more than the ceiling of ${HARD_MAX_TARGETS} targets`);
+    }
+
+    const result = search({ root, pattern, paths, max: opts.max, maxBytes: opts.maxBytes, maxTotalBytes: opts.maxTotalBytes, excludePaths });
     const stdout = opts.json ? JSON.stringify(result, null, 2) : formatResult(result);
     return { code: result.incomplete ? EXIT_INCOMPLETE : EXIT_OK, stdout, stderr: '', result };
   } catch (err) {

package/tools/run-gates.mjs

@@ -34,8 +34,14 @@ import { createHash, randomUUID } from 'node:crypto';
 import { computeTreeFingerprint } from './review-state.mjs';
 // 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';
+import { appendEvidenceRecord, resolveEvidencePath, readEvidence, canonicalKindSerialization, EVIDENCE_SCHEMA_VERSION, resolveBase } from './core-evidence.mjs';
+import {
+  LCOV_BASENAME,
+  commitmentFor,
+  ATTEST_NONCE_ENV,
+  ATTEST_FINGERPRINT_ENV,
+  ATTEST_BASE_ENV,
+} 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).
@@ -196,10 +202,19 @@ export const selectGates = (gates, onlyIds) => {
 // silently attest against the wrong git dir or lcov instead of the computed one.
 export const RESERVED_PRODUCER_ENV = Object.freeze(['AW_GIT_DIR', 'AW_LCOV_FILE']);
 
+// The attestation variables ride the same STRIP but are NOT producer variables: a producer variable
+// is something a gate cmd may legitimately reference, and a missing one refuses the run up front.
+// A capability is the opposite — no gate may reference it, exactly one gate is handed it, and every
+// other child (and any descendant it spawns) must see it absent, host-set copies included, or that
+// descendant could certify a foreign lcov later. Conflating the two lists made a gate that merely
+// MENTIONS the name refuse the whole run.
+export const RESERVED_CAPABILITY_ENV = Object.freeze([ATTEST_NONCE_ENV, ATTEST_FINGERPRINT_ENV, ATTEST_BASE_ENV]);
+
 export const spawnGateViaBash = (cmd, cwd, extraEnv = {}) => {
   const env = { ...process.env };
   delete env.NODE_TEST_CONTEXT;
   for (const name of RESERVED_PRODUCER_ENV) delete env[name];
+  for (const name of RESERVED_CAPABILITY_ENV) delete env[name];
   return spawnSync('bash', ['-c', cmd], { cwd, env: { ...env, ...extraEnv }, encoding: 'utf8', maxBuffer: MAX_GATE_OUTPUT_BYTES });
 };
 
@@ -327,13 +342,22 @@ const matchesCanonicalCheck = (check, cmd, projectDir) => {
   }
 };
 
+// canonicalCheckerGates(gates, projectDir) → every gate that IS the canonical coverage-check. The
+// count is load-bearing twice over: --final refuses more than one (the attestation capability would
+// reach more than one process) and this predicate must refuse the same declaration, or a consumer
+// would advertise final-capability for a declaration --final then rejects.
+export const canonicalCheckerGates = (gates, projectDir) =>
+  gates.filter((g) => matchesCanonicalCheck(FINAL_CORE_CHECKS[1], g.cmd, projectDir));
+
 // 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.
+// (every canonical core check present + EXACTLY ONE canonical checker + that checker LAST) — the
+// ONE home consumers (the recommendations guard-install probe, the worktrees report) 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;
+  if (canonicalCheckerGates(gates, projectDir).length !== 1) return false;
   return matchesCanonicalCheck(FINAL_CORE_CHECKS[1], gates[gates.length - 1].cmd, projectDir);
 };
 const sha256Hex = (data) => createHash('sha256').update(data).digest('hex');
@@ -389,6 +413,13 @@ export const runCli = (argv, deps = {}) => {
       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)`);
       }
+      // EXACTLY ONE canonical checker. Two gates may carry the same canonical cmd under different
+      // ids, and the capability is handed to every match — so without this the "exactly one gate
+      // holds it" guarantee is prose, and an extra copy would run with a live attestation context.
+      const canonicalCheckers = canonicalCheckerGates(declaration.gates, projectDir);
+      if (canonicalCheckers.length > 1) {
+        throw fail(EXIT.malformed, `--final refuses the declaration — ${canonicalCheckers.length} gates are the canonical coverage-check (${canonicalCheckers.map((g) => JSON.stringify(g.id)).join(', ')}); exactly ONE may be, or the attestation context would be handed to more than one process`);
+      }
       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)`);
@@ -430,7 +461,29 @@ export const runCli = (argv, deps = {}) => {
     }
     // --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;
+    const finalBase = opts.final ? resolveBase(projectDir) ?? '' : null;
+    // The attestation handshake (see coverage-check.mjs): a fresh random nonce rides the child
+    // environment, and the attempt id this run records is the one-way COMMITMENT over it plus the
+    // identity. Persisting only the commitment is what makes the context unreproducible from the
+    // repository afterwards — a plain recorded id is public, and attesting from one let an ordinary
+    // interrupted run certify a later run's lcov. The commitment is also the only place the BASE is
+    // bound, since no record stores it.
+    const finalNonce = opts.final ? randomUUID() : null;
+    const finalAttempt = opts.final ? commitmentFor(finalNonce, finalFingerprintBefore ?? '', finalBase) : null;
+    if (opts.final) {
+      // ONLY the canonical checker receives the capability — the same predicate the --final preflight
+      // uses to recognise it. Every other gate gets the producer variables and nothing else.
+      gateSpawn = (cmd, cwd2) => {
+        const producers = { AW_GIT_DIR: gitDir, AW_LCOV_FILE: join(gitDir, LCOV_BASENAME) };
+        if (!matchesCanonicalCheck(FINAL_CORE_CHECKS[1], cmd, projectDir)) return spawn(cmd, cwd2, producers);
+        return spawn(cmd, cwd2, {
+          ...producers,
+          [ATTEST_NONCE_ENV]: finalNonce,
+          [ATTEST_FINGERPRINT_ENV]: finalFingerprintBefore ?? '',
+          [ATTEST_BASE_ENV]: finalBase,
+        });
+      };
+    }
     let finalError = null;
     let startEvidenceHashes = null;
     if (opts.final) {
@@ -458,6 +511,19 @@ export const runCli = (argv, deps = {}) => {
     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);
+    // A green gate's stdout is deliberately not echoed — the table IS the report. But the checker
+    // exits 0 both when it certifies and when it WITHHOLDS a verdict, so on a plain run the table
+    // would read PASS over a coverage claim that was never made: the same false reassurance one
+    // layer up from the defect this whole mechanism exists to close. Surface it, and only it.
+    if (!opts.final) {
+      const checkerAt = selected.findIndex((gate) => matchesCanonicalCheck(FINAL_CORE_CHECKS[1], gate.cmd, projectDir));
+      const checkerRow = checkerAt === -1 ? null : results[checkerAt];
+      if (checkerRow?.ok && /^coverage-check: attested=no$/m.test(String(checkerRow.stdout ?? ''))) {
+        log(`── ${checkerRow.id} — NO COVERAGE VERDICT (the gate passed; it did not certify)`);
+        for (const line of String(checkerRow.stdout).split(/\r?\n/).filter((l) => /^coverage-check: (NO VERDICT|skipped-no-lcov)/.test(l))) log(line);
+        log('   A coverage verdict is issued only by run-gates.mjs --final, which owns the lcov for the whole run.');
+      }
+    }
     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.
@@ -493,6 +559,22 @@ export const runCli = (argv, deps = {}) => {
         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;
+        // The attestation line, on the SAME exactly-one-anchored-line contract as the sha: a green
+        // exit status alone never proves the checker certified anything — it exits 0 both when it
+        // attests and when it withholds a verdict. Without this arm a gate that removed the start
+        // record mid-run would yield a green receipt carrying no coverage claim at all.
+        const attestLineRe = /^coverage-check: attested=(yes|no)$/;
+        const attestLines = String(checkerRow?.stdout ?? '').split(/\r?\n/).filter((l) => attestLineRe.test(l));
+        const attested = attestLines.length === 1 ? attestLineRe.exec(attestLines[0])[1] : null;
+        if (allGreen && integrityFailure === null && lcovSha256 !== null) {
+          if (attestLines.length !== 1) {
+            integrityFailure = attestLines.length === 0
+              ? 'the coverage-check gate printed no attested= line — whether coverage was certified is unknowable (fail closed)'
+              : `the coverage-check gate printed ${attestLines.length} attested= lines — exactly ONE full machine line binds the receipt`;
+          } else if (attested !== 'yes') {
+            integrityFailure = 'the coverage-check gate consumed an lcov but did NOT certify it — the final run reached the checker without a valid attestation context';
+          }
+        }
         if (allGreen && integrityFailure === null) {
           if (shaLines.length !== 1) {
             integrityFailure = shaLines.length === 0
@@ -543,7 +625,10 @@ export const runCli = (argv, deps = {}) => {
         logError(`[run-gates] --final could not write its receipt: ${err.message}`);
       }
     }
-    log(composeSummaryLine({ status: allGreen ? 'ok' : 'fail', results }));
+    // The summary line is the MACHINE report, so it must agree with the exit code: an integrity
+    // failure mints a RED receipt and exits finalFailed, and a line still saying status=ok there
+    // would be a silent green in the one place a reader parses instead of reads.
+    log(composeSummaryLine({ status: allGreen && finalError === null ? 'ok' : 'fail', results }));
     if (finalError) return EXIT.finalFailed;
     return allGreen ? EXIT.ok : EXIT.fail;
   } catch (err) {

package/tools/velocity-profile.mjs

@@ -149,6 +149,10 @@ export const KIT_READONLY_TOOLS = Object.freeze([
   // NO decision from the hook, which is not the same as an allow, so without this rule the lane
   // falls through to whatever the host policy happens to be.
   'tools/repo-search.mjs',
+  // The inventory lane, in the tier for the same reason and with the same dependency: the corpus of
+  // useless approvals is mostly small path questions batched into a composed shell because no single
+  // call answered them, and a lane the agent must still ask about is not a lane.
+  'tools/path-inventory.mjs',
 ]);
 // Writer previews: ONLY writers whose ARG-FREE invocation is a documented dry-run ("Default is
 // --dry-run" in their usage) seed an EXACT preview byte-string — every --apply/--write/--yes keeps
@@ -342,7 +346,7 @@ const USAGE = `usage: velocity-profile [--dry-run | --apply] [--kit-tools] [--br
 
 Allowlist mode (default): seeds the fixed read-only Claude Code allowlist into .claude/settings.json.
 Default is --dry-run. --apply writes; --accept-edits only sets defaultMode when applying.
---kit-tools additionally seeds the audited kit-tool tier: 9 read-only kit tools by resolved
+--kit-tools additionally seeds the audited kit-tool tier: ${KIT_WILDCARD_TOOLS.length} read-only kit tools by resolved
 absolute path (args wildcard), run-gates.mjs as ONE exact project-root-pinned byte-string
 (project-exec - it runs YOUR declared gates.json), and the writers' exact arg-free dry-run
 preview byte-strings. Never touches settings.local.json.
@@ -644,7 +648,7 @@ const formatAllowlist = (result) => [
 // The tier's honest posture, printed on every --kit-tools run: run-gates is project-exec (never
 // "read-only"), previews stay dry-run-only, and the tier gets none of the hook's residual ask-net.
 const KIT_TIER_NOTICE =
-  'kit-tools tier: paths are resolved absolute at seed time (fail-safe - a moved skill or stale path simply prompts again); run-gates.mjs is seeded as ONE exact byte-string pinned to this project root and is project-exec - it runs YOUR declared gates.json commands, never "read-only"; writer previews are exact dry-run byte-strings - every --apply/--write/--yes still prompts; tier entries get NO PreToolUse-hook residual coverage (settings-level posture only - see the velocity mode notes).';
+  'kit-tools tier: paths are resolved absolute at seed time (fail-safe - a moved skill or stale path simply prompts again); run-gates.mjs is seeded as ONE exact byte-string pinned to this project root and is project-exec - it runs YOUR declared gates.json commands, never "read-only"; writer previews are exact dry-run byte-strings - every --apply/--write/--yes still prompts; tier entries get NO PreToolUse-hook residual coverage EXCEPT repo-search.mjs and path-inventory.mjs, whose invocations the hook scans because they take caller-supplied argument bytes (settings-level posture only for the rest - see the velocity mode notes).';
 
 const formatKitTier = (result) =>
   result.kitTools