@sabaiway/agent-workflow-kit 10.6.0 → 11.1.0

package/tools/commit-guard.mjs

@@ -54,11 +54,12 @@ import {
 import { resolveLcovPath } from './coverage-check.mjs';
 import { GATES_REL, loadDeclaration } from './run-gates.mjs';
 import { computeFlowDecision } from './flow-check.mjs';
+import { GIT_MAX_BUFFER, resolveGitLocation } from './git-env.mjs';
+import { escapeForDisplay } from './repo-lex.mjs';
 
 const usageFail = (message) => Object.assign(new Error(`[agent-workflow-kit] ${message}`), { exitCode: 2 });
 const sha = (text) => createHash('sha256').update(text).digest('hex');
 
-const GIT_MAX_BUFFER = 256 * 1024 * 1024;
 const gitLine = (args, cwd) => {
   const r = spawnSync('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
   if (r.error || r.status !== 0) return null;
@@ -201,28 +202,38 @@ const flowAdvisoryLines = (flow) => (flow.present && flow.armed
   : []);
 
 export const runGuard = ({ cwd = process.cwd(), env = process.env } = {}) => {
-  const rootTop = gitLine(['rev-parse', '--show-toplevel'], cwd);
-  if (rootTop == null) return { code: 1, lines: ['commit-guard: not a git work tree — nothing to guard'] };
-  // FIRST: a pure tree property needing no store read. Its recovery re-stages the tree and re-mints
+  // FIRST of all: WHICH repository. The location is a closed six-state table judged by realpath
+  // agreement (the git-env leaf); every state but work-tree refuses by its own name — a redirecting
+  // GIT_DIR, a killed or absent git, a bare repository — instead of guarding another tree or
+  // passing a tree git could not describe. A pre-commit hook's own env agrees and passes.
+  const location = resolveGitLocation(cwd, { env });
+  if (location.state !== 'work-tree') {
+    // The cause can carry a repository PATH (a newline-bearing one included) — escaped, ONE line.
+    return { code: 1, lines: [`commit-guard: REFUSED — the git location is ${location.state} (${escapeForDisplay(location.cause)}) — nothing is guarded until git names one work tree from ${escapeForDisplay(cwd)}`] };
+  }
+  const rootTop = location.top;
+  // NEXT: a pure tree property needing no store read. Its recovery re-stages the tree and re-mints
   // the receipt, so every arm below is re-decided anyway — naming a stale fingerprint ahead of it
   // would send the operator down a recovery they must redo.
-  const working = computeWorkingState(cwd);
+  const working = computeWorkingState(cwd, { env });
+  if (working === null) return { code: 1, lines: ['commit-guard: REFUSED — the working state is undecidable (a git query failed or was killed) — nothing is guarded'] };
   const indexLag = decideIndexLag(working);
   if (indexLag !== null) return indexLag;
-  const fingerprint = computeTreeFingerprint(cwd);
+  const fingerprint = computeTreeFingerprint(cwd, { env });
+  if (fingerprint === null) return { code: 1, lines: ['commit-guard: REFUSED — the tree fingerprint is undecidable (a git query failed or was killed) — nothing is guarded'] };
   // The CONTENT-FREE lanes — the second pure tree property, decided here for the same reason the
   // index lag is: no store read can answer it. A payload with no bytes states nothing about what
   // this commit will carry, and its fingerprint is the ONE value every clean moment of every
   // repository shares, so a receipt found at it was minted by some other moment, possibly at
   // another base. Such evidence must therefore decide NOTHING here — neither refuse nor attest
   // (the same fact flow-check-rungs.mjs applies to a red final). The index tells the two lanes
-  // apart, and `computeWorkingState` probes it with --ignore-submodules=none precisely so a
-  // config-hidden gitlink cannot pass for a clean one.
+  // apart. The payload runs --no-textconv and --ignore-submodules=none, so a config-hidden gitlink
+  // rides it; the arm stays because a content-free payload over a dirty index is undecidable by any receipt.
   const contentFree = fingerprint === CONTENT_FREE_FINGERPRINT;
   if (contentFree && working.stagedDirty) {
     return {
       code: 1,
-      lines: [`commit-guard: REFUSED — the index carries staged content the fingerprint domain cannot see (a submodule gitlink hidden from \`git diff\` by \`submodule.<name>.ignore\` or \`diff.ignoreSubmodules\`), so no final receipt can describe what this commit will carry. Recovery: clear that ignore setting (or set it to \`none\`) until \`git diff --cached --no-ext-diff\` shows the change, then re-run node ${FINAL_RUN_TOOL} --final`],
+      lines: [`commit-guard: REFUSED — the index carries staged content the payload cannot see, so no final receipt can describe what this commit will carry. Recovery: make the staged change visible to \`git diff --cached\`, then re-run node ${FINAL_RUN_TOOL} --final`],
     };
   }
   // The guard's OWN reads resolve FIXED git-dir paths — a stray AW_CORE_EVIDENCE / AW_LCOV_FILE

package/tools/control-bytes.mjs

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+// control-bytes.mjs — the read-only control-byte gate over the WORK TREE (the contract:
+// docs/ai/specs/kit/control-bytes.md; the mode: references/modes/control-bytes.md). Measured
+// 2026-08-30: an editor wrote a raw NUL into a test source, git classed the file as binary, the
+// letter-level checker skipped the blob by kind, and the byte reached a reviewer one round later.
+// This tool makes that byte a mechanical refusal: it judges BYTES, never letters, over tracked plus
+// untracked-not-ignored paths — the name always, a regular file's content unless a git attribute
+// says binary, a symlink's target string without following it — and refuses, never skips, on
+// anything it cannot judge. main(argv, deps) returns { code, lines } and never exits; every spawn,
+// fs and env read is injectable; the CLI half prints and sets the exit code. Read-only: it writes
+// nothing and spawns only the git argv declared below (plus the location leaf's rev-parse probes).
+
+import { closeSync, constants as fsConstants, fstatSync, lstatSync, openSync, readSync, readlinkSync, realpathSync, statSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { isDirectRun } from './direct-run.mjs';
+import { probeRegularFileNoFollow, readFileBytesNoFollowCapped } from './fs-read-nofollow.mjs';
+import { GIT_MAX_BUFFER, parseIndexEntries, resolveGitLocation, withGitPath } from './git-env.mjs';
+import { isRefusedControlByte, renderPathForDisplay } from './repo-lex.mjs';
+
+export const READ_CAP = 16 * 1024 * 1024;
+// The exact read-only git argv this tool spawns — pinned by the kit read-only tier registry.
+export const CONTROL_BYTES_GIT_ARGV = Object.freeze([
+  Object.freeze(['ls-files', '-s', '-z']),
+  Object.freeze(['ls-files', '--others', '--exclude-standard', '-z']),
+  Object.freeze(['check-attr', '--stdin', '-z', 'binary', 'diff']),
+  Object.freeze(['config', '--type=bool', '--get', 'core.symlinks']),
+  Object.freeze(['ls-files', '-v', '-z']),
+]);
+const [TRACKED_ARGV, UNTRACKED_ARGV, ATTRIBUTES_ARGV, SYMLINKS_ARGV, SPARSE_ARGV] = CONTROL_BYTES_GIT_ARGV;
+export const defaultIo = Object.freeze({ open: openSync, fstat: fstatSync, read: readSync, close: closeSync, constants: fsConstants, lstat: lstatSync, readlink: readlinkSync, realpath: realpathSync, stat: statSync });
+
+const USAGE = `usage: node control-bytes.mjs [--check] [--cwd <dir>]
+  Refuses any raw C0 or DEL byte (TAB, LF, CR admitted) in the work tree: a path's name, a regular
+  file's content (unless its git attribute says binary or -diff) or a symlink's target string.
+  --cwd <dir>   anchor at that directory's work-tree root (default: the process cwd)
+  --check       the gate spelling; the plain run prints the same report and shares the exit table
+  exit 0 clean · 1 a finding or a refusal · 2 usage`;
+
+const NUL = Buffer.from([0]);
+const render = renderPathForDisplay;
+// Every DYNAMIC diagnostic (a location cause, git stderr, an fs error code, a user argument) rides
+// the same renderer as paths before it reaches a line — SAFE (never a raw byte or U+FFFD), while
+// injectivity is promised for NAMES only: a string-originated diagnostic folds invalid bytes first.
+const safe = (text) => render(Buffer.isBuffer(text) ? text : Buffer.from(String(text), 'utf8'));
+const refusalLine = (message) => `control-bytes: REFUSED — ${message}`;
+const absent = (path, tracked) => `${render(path)}: absent (${tracked ? 'tracked but missing from the work tree — stage the deletion with git rm or git add -A, or it' : 'git named it, it'} vanished before the read)`;
+const unreadable = (path, why) => `${render(path)}: unreadable (${safe(why)})`;
+const hexByte = (byte) => `0x${byte.toString(16).padStart(2, '0')}`;
+const errorCode = (err) => err?.code ?? err?.message ?? String(err);
+
+const parseArgs = (argv, io) => {
+  const opts = { check: false, cwd: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--check') {
+      opts.check = true;
+      continue;
+    }
+    if (arg === '--cwd') {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith('--')) return { error: '--cwd needs a directory' };
+      try {
+        if (!io.stat(value).isDirectory()) return { error: `--cwd ${safe(value)} is not a directory` };
+      } catch (err) {
+        return { error: `--cwd ${safe(value)}: ${safe(errorCode(err))}` };
+      }
+      opts.cwd = value;
+      i += 1;
+      continue;
+    }
+    return { error: `unknown argument: ${safe(arg)}` };
+  }
+  return opts;
+};
+
+// One git query → { stdout } or { failure } — a synchronous throw, ENOENT, a signal and an exit
+// outside `ok` are four named failures, never a silent empty answer.
+const gitQuery = (run, args, { cwd, env, input }, ok = [0]) => {
+  let r;
+  try {
+    r = run('git', args, { cwd, env: withGitPath(env), input, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
+  } catch (err) {
+    return { failure: `git ${args.join(' ')} threw synchronously (${safe(err?.message ?? err)})` };
+  }
+  if (r.error) return { failure: `git ${args.join(' ')} could not run (${safe(errorCode(r.error))})${r.error.code === 'ENOENT' ? ' — git is not on PATH' : ''}` };
+  if (r.signal) return { failure: `git ${args.join(' ')} was killed by ${safe(r.signal)}` };
+  const stderr = String(r.stderr ?? '').trim();
+  if (!ok.includes(r.status)) return { failure: `git ${args.join(' ')} exited ${r.status}${stderr ? ` (${safe(stderr)})` : ''}` };
+  return { stdout: Buffer.isBuffer(r.stdout) ? r.stdout : Buffer.from(r.stdout ?? '') };
+};
+
+const splitZ = (buf) => {
+  const out = [];
+  for (let start = 0; start < buf.length;) {
+    let end = buf.indexOf(0, start);
+    if (end === -1) end = buf.length;
+    if (end > start) out.push(buf.subarray(start, end));
+    start = end + 1;
+  }
+  return out;
+};
+
+// `check-attr --stdin -z` answers path NUL attribute NUL value NUL; `binary` set or `diff` unset
+// is git's own "binary" — the content skip, keyed by the path's exact bytes.
+const attributeSkips = (stdout) => {
+  const skips = new Set();
+  const fields = splitZ(stdout);
+  for (let i = 0; i + 2 < fields.length; i += 3) {
+    const [path, attribute, value] = [fields[i], fields[i + 1].toString('utf8'), fields[i + 2].toString('utf8')];
+    if ((attribute === 'binary' && value === 'set') || (attribute === 'diff' && value === 'unset')) skips.add(path.toString('hex'));
+  }
+  return skips;
+};
+
+const kindOfMode = (mode) => (mode === '120000' ? 'symlink' : mode === '160000' ? 'gitlink' : mode === '100644' || mode === '100755' ? 'file' : null);
+// An UNTRACKED entry git names with a trailing slash is its nested-repository rule (the `nested/`
+// line): name-only, like a gitlink, and counted as a skip by kind beside the never-committable stat
+// classes. A directory at a slash-less entry is a leaf that changed kind — a refusal.
+const kindOfStat = (st, nested) => (st.isSymbolicLink() ? 'symlink' : st.isFile() ? 'file' : st.isDirectory() ? (nested ? 'nested-repository' : 'directory') : 'never-committable');
+
+export const main = (argv, deps = {}) => {
+  const io = { ...defaultIo, ...(deps.io ?? {}) };
+  const run = deps.spawn ?? spawnSync;
+  const env = deps.env ?? process.env;
+  const opts = parseArgs(argv, io);
+  if (opts.error) return { code: 2, lines: [`control-bytes: usage — ${opts.error}`, USAGE] };
+  const cwd = opts.cwd ?? deps.cwd ?? process.cwd();
+  const location = resolveGitLocation(cwd, { spawn: run, env, realpath: io.realpath });
+  if (location.state !== 'work-tree') return { code: 1, lines: [refusalLine(`the git location is ${location.state} — ${safe(location.cause)}`)] };
+  const top = location.top;
+  const git = (args, input, ok) => gitQuery(run, args, { cwd: top, env, input }, ok);
+  const tracked = git(TRACKED_ARGV);
+  if (tracked.failure) return { code: 1, lines: [refusalLine(tracked.failure)] };
+  const entries = parseIndexEntries(tracked.stdout);
+  const unmerged = entries.filter((e) => e.stage !== 0).length;
+  if (unmerged > 0) return { code: 1, lines: [refusalLine(`the git index is UNMERGED (${unmerged} conflict-stage entr(ies)) — resolve the conflict, then re-run`)] };
+  const others = git(UNTRACKED_ARGV);
+  if (others.failure) return { code: 1, lines: [refusalLine(others.failure)] };
+  const domain = [...entries.map((e) => ({ path: e.path, mode: e.mode })), ...splitZ(others.stdout).map((path) => ({ path, mode: null }))]
+    .sort((a, b) => Buffer.compare(a.path, b.path));
+  if (domain.length === 0) return { code: 1, lines: [refusalLine(`the domain is EMPTY — no tracked and no untracked-not-ignored path under ${render(Buffer.from(top))}`)] };
+  const attributes = git(ATTRIBUTES_ARGV, Buffer.concat(domain.flatMap((d) => [d.path, NUL])));
+  if (attributes.failure) return { code: 1, lines: [refusalLine(attributes.failure)] };
+  const skipByAttribute = attributeSkips(attributes.stdout);
+  // core.symlinks: exit 1 = unset = git's default (true); `false` = the host materialises a tracked
+  // symlink as a regular file holding the target bytes — refusing it there would refuse forever.
+  const symlinks = git(SYMLINKS_ARGV, undefined, [0, 1]);
+  if (symlinks.failure) return { code: 1, lines: [refusalLine(symlinks.failure)] };
+  const symlinksMaterialised = symlinks.stdout.toString('utf8').trim() === 'false';
+  // Sparse checkouts: a tracked path whose skip-worktree bit is set (`ls-files -v`, a tag that
+  // uppercases to S — core-evidence's rule) may be ABSENT by design: a counted skip, never a refusal.
+  const sparse = git(SPARSE_ARGV);
+  if (sparse.failure) return { code: 1, lines: [refusalLine(sparse.failure)] };
+  const sparseSkip = new Set();
+  for (const record of splitZ(sparse.stdout)) {
+    if (record.length > 2 && String.fromCharCode(record[0]).toUpperCase() === 'S') sparseSkip.add(record.subarray(2).toString('hex'));
+  }
+
+  const findings = [];
+  const refusals = [];
+  const skippedByAttribute = [];
+  let skippedByKind = 0;
+  const judge = (bytes, surface, path) => {
+    let first = -1;
+    let count = 0;
+    for (let i = 0; i < bytes.length; i += 1) {
+      if (!isRefusedControlByte(bytes[i])) continue;
+      if (first === -1) first = i;
+      count += 1;
+    }
+    if (first !== -1) findings.push(`${render(path)} ${surface} offset ${first}: ${hexByte(bytes[first])}${count > 1 ? ` (+${count - 1} more)` : ''}`);
+  };
+  // An ABSENT path: a sparse (skip-worktree) tracked one is a counted skip; every other refuses.
+  const settleAbsent = (path, tracked) => {
+    if (tracked && sparseSkip.has(path.toString('hex'))) skippedByKind += 1;
+    else refusals.push(absent(path, tracked));
+  };
+  // A descriptor read's outcome, settled: ok judges the bytes on `surface`; anything else refuses.
+  const settle = (read, path, tracked, surface, named) => {
+    if (read.outcome === 'ok') {
+      if (read.bytes) judge(read.bytes, surface, path);
+      return true;
+    }
+    if (read.outcome === 'over-cap') refusals.push(`${render(path)}: over the read cap (${READ_CAP} bytes) — the gate read cap+1 bytes on the descriptor and stopped; ${surface === 'content' ? 'declare the path binary in .gitattributes or shrink it' : 'restore the link or shorten its target'}`);
+    else if (read.outcome === 'absent') settleAbsent(path, tracked);
+    else if (read.outcome === 'foreign') refusals.push(unreadable(path, `a ${read.className} where git named a ${named}`));
+    else refusals.push(unreadable(path, read.code));
+    return false;
+  };
+  for (const { path, mode } of domain) {
+    judge(path, 'name', path);
+    // Filesystem calls drop git's nested-repository trailing slash: lstat on a slash-terminated
+    // name FOLLOWS a symlink standing there (POSIX), which would skip a swapped link unjudged.
+    const fsPath = path[path.length - 1] === 0x2f ? path.subarray(0, path.length - 1) : path;
+    const full = Buffer.concat([Buffer.from(`${top}/`), fsPath]);
+    const tracked = mode !== null;
+    let kind = null;
+    if (tracked) {
+      kind = kindOfMode(mode);
+      if (kind === null) {
+        refusals.push(unreadable(path, `index mode ${mode} names no readable kind`));
+        continue;
+      }
+    } else {
+      try {
+        kind = kindOfStat(io.lstat(full), path[path.length - 1] === 0x2f);
+      } catch (err) {
+        if (err?.code === 'ENOENT') settleAbsent(path, tracked);
+        else refusals.push(unreadable(path, errorCode(err)));
+        continue;
+      }
+    }
+    if (kind === 'gitlink') continue;
+    if (kind === 'directory') {
+      refusals.push(unreadable(path, 'a directory where git named a file'));
+      continue;
+    }
+    if (kind === 'never-committable' || kind === 'nested-repository') {
+      skippedByKind += 1;
+      continue;
+    }
+    if (kind === 'symlink') {
+      let leafIsFile = false;
+      if (symlinksMaterialised) {
+        try {
+          leafIsFile = io.lstat(full).isFile();
+        } catch (err) {
+          if (err?.code === 'ENOENT') settleAbsent(path, tracked);
+          else refusals.push(unreadable(path, errorCode(err)));
+          continue;
+        }
+      }
+      if (leafIsFile) {
+        settle(readFileBytesNoFollowCapped(full, READ_CAP, io), path, tracked, 'symlink-target', 'symlink');
+        continue;
+      }
+      try {
+        judge(io.readlink(full, { encoding: 'buffer' }), 'symlink-target', path);
+      } catch (err) {
+        if (err?.code === 'ENOENT') settleAbsent(path, tracked);
+        else refusals.push(unreadable(path, err?.code === 'EINVAL' ? 'not a symlink where git named one' : errorCode(err)));
+      }
+      continue;
+    }
+    // An attribute skip covers the CONTENT only: the leaf still owes the descriptor's kind check.
+    const skipped = skipByAttribute.has(path.toString('hex'));
+    const read = skipped ? probeRegularFileNoFollow(full, io) : readFileBytesNoFollowCapped(full, READ_CAP, io);
+    if (settle(read, path, tracked, 'content', 'file') && skipped) skippedByAttribute.push(path);
+  }
+  const lines = [
+    `control-bytes: work tree ${render(Buffer.from(top))}`,
+    `paths judged: ${domain.length} · skipped by attribute: ${skippedByAttribute.length} · skipped by kind: ${skippedByKind} · findings: ${findings.length}`,
+    ...skippedByAttribute.map((path) => `skipped by attribute: ${render(path)}`),
+    ...findings,
+    ...refusals.map(refusalLine),
+  ];
+  return { code: findings.length > 0 || refusals.length > 0 ? 1 : 0, lines };
+};
+
+if (isDirectRun(import.meta.url)) {
+  const result = main(process.argv.slice(2));
+  (result.code === 2 ? process.stderr : process.stdout).write(`${result.lines.join('\n')}\n`);
+  process.exitCode = result.code;
+}

package/tools/core-evidence.mjs

@@ -24,7 +24,7 @@
 // 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 + the pure leaves (repo-lex, fs-read-nofollow, coverage-state), and OWNS the
+// changed-surface + the pure leaves (repo-lex, fs-read-nofollow, coverage-state, git-env), 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
@@ -43,6 +43,7 @@ import { parsePositiveIntKnob, probeVerdict } from './changed-surface.mjs';
 import { isDirectRun } from './direct-run.mjs';
 import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
 import { lexicalRepoRelative } from './repo-lex.mjs';
+import { GIT_MAX_BUFFER, resolveGitLocation, withGitPath } from './git-env.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';
@@ -52,7 +53,6 @@ const stop = (message) => Object.assign(new Error(`[agent-workflow-kit] ${messag
 const usageFail = (message) => Object.assign(new Error(`[agent-workflow-kit] ${message}`), { exitCode: 2 });
 
 const isoNow = () => new Date().toISOString();
-const GIT_MAX_BUFFER = 256 * 1024 * 1024; // a full-tree diff / TAP stream can be large; never truncate
 
 const gitRaw = (args, cwd) => spawnSync('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
 
@@ -114,15 +114,32 @@ export const isNeverCommittableStat = (stat) =>
   stat != null &&
   (stat.isCharacterDevice() || stat.isBlockDevice() || stat.isFIFO() || stat.isSocket());
 
+// The git runner seam the tree computations share — (args, dir, input, env) — and its guard: a
+// runner that THROWS answers as a failed spawn (measured: a raw stack out of a fingerprint).
+const defaultRunGit = (args, dir, input, env) => spawnSync('git', args, { cwd: dir, input, env: withGitPath(env ?? process.env), maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
+const guardedRunner = (runGit, env) => (args, dir, input, override) => {
+  try { return runGit(args, dir, input, override ?? env); } catch (err) { return { error: err, status: null, signal: null, stdout: Buffer.alloc(0), stderr: '' }; }
+};
+const stdoutOf = (r) => (r.error || r.status !== 0 ? null : r.stdout);
+// Only a work-tree location is computed over (git-env's table under the runner's own env) — a redirecting GIT_DIR never hashes another repository in silence.
+const locateWorkTree = (cwd, run, env) => {
+  const location = resolveGitLocation(cwd, { spawn: (cmd, args, opts) => run(args, opts.cwd, undefined, opts.env), env });
+  return location.state === 'work-tree' ? location.top : null;
+};
+
 // The canonical payload bytes: staged diff + unstaged diff + the untracked-not-ignored section —
-// byte-identical to the wrappers' emit_fingerprint_payload, emitted from the work-tree ROOT. Null
-// outside a git work tree. The lstat is injectable ONLY for the never-committable filter tests.
-export const computeFingerprintPayload = (cwd, { lstat = lstatSync } = {}) => {
-  const top = gitLine(['rev-parse', '--show-toplevel'], cwd);
+// byte-identical to the wrappers' emit_fingerprint_payload, emitted from the work-tree ROOT. Null on
+// every location but a work tree. lstat is injectable ONLY for the never-committable filter tests.
+export const FINGERPRINT_CACHED_DIFF_ARGV = Object.freeze(['diff', '--cached', '--no-ext-diff', '--no-textconv', '--ignore-submodules=none']);
+export const FINGERPRINT_UNSTAGED_DIFF_ARGV = Object.freeze(['diff', '--no-ext-diff', '--no-textconv', '--ignore-submodules=none']);
+export const computeFingerprintPayload = (cwd, { lstat = lstatSync, runGit = null, env = process.env } = {}) => {
+  const run = guardedRunner(runGit ?? defaultRunGit, env);
+  const top = locateWorkTree(cwd, run, env);
   if (top == null) return null;
-  const staged = gitBuf(['diff', '--cached', '--no-ext-diff'], top);
-  const unstaged = gitBuf(['diff', '--no-ext-diff'], top);
-  const untrackedZ = gitBuf(['ls-files', '--others', '--exclude-standard', '-z'], top);
+  const buf = (args) => stdoutOf(run(args, top));
+  const staged = buf(FINGERPRINT_CACHED_DIFF_ARGV);
+  const unstaged = buf(FINGERPRINT_UNSTAGED_DIFF_ARGV);
+  const untrackedZ = buf(['ls-files', '--others', '--exclude-standard', '-z']);
   if (staged == null || unstaged == null || untrackedZ == null) return null;
   const chunks = [staged, unstaged];
   for (const rel of untrackedZ.toString('utf8').split('\0').filter(Boolean)) {
@@ -348,21 +365,17 @@ const flaggedIndexLag = (top, runGit, lstat, readlink) => {
   return { paths: lagging, submodules: laggingSubmodules, flagged: laggingFlags };
 };
 
-export const computeWorkingState = (cwd, { lstat = lstatSync, readlink = readlinkSync, runGit = null } = {}) => {
-  const run = runGit ?? ((args, dir, input, env) => spawnSync('git', args, { cwd: dir, input, env: env ?? process.env, maxBuffer: GIT_MAX_BUFFER, windowsHide: true }));
-  const topRun = run(['rev-parse', '--show-toplevel'], cwd);
-  if (topRun.error || topRun.status !== 0) return null;
-  const top = topRun.stdout.toString('utf8').replace(/\r?\n$/, '');
+export const computeWorkingState = (cwd, { lstat = lstatSync, readlink = readlinkSync, runGit = null, env = process.env } = {}) => {
+  const run = guardedRunner(runGit ?? defaultRunGit, env);
+  const top = locateWorkTree(cwd, run, env);
+  if (top == null) return null;
   // `--ignore-submodules=none` on the staged probe too: a config-hidden STAGED gitlink would
   // otherwise make stagedDirty false, and isTreeClean would call such a tree clean.
   const staged = run(['diff', '--cached', '--quiet', '--ignore-submodules=none'], top);
   // ONLY 0 or 1 is a usable answer: a signal-killed probe reports status null, which the old
   // `> 1` guard let through as "nothing staged" — a fail-OPEN the whole arm cannot afford.
   if (staged.error || (staged.status !== 0 && staged.status !== 1)) return null;
-  const buf = (args) => {
-    const r = run(args, top);
-    return r.error || r.status !== 0 ? null : r.stdout;
-  };
+  const buf = (args) => stdoutOf(run(args, top));
   // The FULL probe forces submodules back in: diff.ignoreSubmodules / submodule.<n>.ignore would
   // otherwise erase a dirty submodule from the comparison entirely.
   const changedZ = buf(['diff', '--name-only', '-z', '--ignore-submodules=none']);
@@ -370,7 +383,7 @@ export const computeWorkingState = (cwd, { lstat = lstatSync, readlink = readlin
   const untrackedZ = buf(['ls-files', '--others', '--exclude-standard', '-z']);
   if (changedZ == null || plainZ == null || untrackedZ == null) return null;
   const split = (b) => b.toString('utf8').split('\0').filter(Boolean);
-  const changed = split(changedZ);
+  const changed = [...new Set(split(changedZ))]; // an unmerged path is listed once per conflict side
   const plain = new Set(split(plainZ));
   const flagged = flaggedIndexLag(top, run, lstat, readlink);
   if (flagged == null) return null;
@@ -950,6 +963,7 @@ export const runRedProof = ({ cwd = process.cwd(), env = process.env, testId } =
   // captured BEFORE the runs and re-checked after them; any drift refuses below.
   const base = resolveBase(cwd);
   const fingerprint = computeTreeFingerprint(cwd);
+  if (fingerprint == null) throw stop('cannot compute the tree fingerprint — the git location is not a work tree; nothing was observed, no runs were spent');
   const { entry, file, resolveReason } = probeBound({ testId, rootTop, env, reruns, timeoutS });
   const verdict = probeVerdict(entry);
   const counts = `${entry.greens} green / ${entry.reds} red / ${entry.timeouts} timed out / ${entry.runs - entry.greens - entry.reds - entry.timeouts} unresolved of ${entry.runs} run(s)`;
@@ -974,7 +988,6 @@ export const runRedProof = ({ cwd = process.cwd(), env = process.env, testId } =
         `${entry.timeouts > 0 ? 'raise the timeout or make the test faster' : 'replace the flaky test'}, then re-observe. Nothing was recorded.`,
     );
   }
-  if (fingerprint == null) throw stop('cannot compute the tree fingerprint — not a git work tree');
   // Post-run drift recheck: fingerprint, base, and the test-file bytes must all equal the
   // pre-run capture — a mutating test / parallel edit / commit would otherwise mint a record
   // whose fields attest different trees.

package/tools/coverage-check.mjs

@@ -24,6 +24,7 @@ import { lstatSync, readFileSync, realpathSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { GIT_MAX_BUFFER } from './git-env.mjs';
 import { computeChangedSurface } from './changed-surface.mjs';
 import { isDirectRun } from './direct-run.mjs';
 import { lcovCoveredMap, uncoveredChangedFromLcov } from './lcov.mjs';
@@ -47,7 +48,6 @@ const usageFail = (message) => Object.assign(new Error(`[agent-workflow-kit] ${m
 
 export const LCOV_BASENAME = 'agent-workflow-lcov.info';
 
-const GIT_MAX_BUFFER = 256 * 1024 * 1024;
 const gitLine = (args, cwd) => {
   const r = spawnSync('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
   if (r.error || r.status !== 0) return null;

package/tools/dispatch-store-read.mjs

@@ -1,18 +1,18 @@
 import { join, isAbsolute, normalize, sep } from 'node:path';
 import { spawnSync } from 'node:child_process';
+
 import {
   validateDelegationRecord, canonicalDelegationDigest, allowedSuccessorKinds,
   isThreadTerminalRecord,
 } from './dispatch-record.mjs';
 import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+import { GIT_MAX_BUFFER } from './git-env.mjs';
 
 export const DELEGATION_STORE_STOP = 'DELEGATION_STORE_STOP';
 export const delegationStoreStop = (message) => Object.assign(new Error(`[agent-workflow-kit] ${message}`), { name: 'DelegationStoreStop', code: DELEGATION_STORE_STOP });
 const stop = delegationStoreStop;
 
 export const DELEGATION_STORE_BASENAME = 'agent-workflow-delegation.jsonl';
-const GIT_MAX_BUFFER = 256 * 1024 * 1024;
-
 const runGit = (args, cwd, spawn = spawnSync) => spawn('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
 const readGitLine = (args, cwd, spawn) => {
   const result = runGit(args, cwd, spawn);

package/tools/flow-check-git-lane.mjs

@@ -4,13 +4,14 @@
 // pure decision cores can never reach a git spawn through it.
 
 import { spawnSync } from 'node:child_process';
+import { GIT_MAX_BUFFER } from './git-env.mjs';
 
 const short = (digest) => `${digest.slice(0, 12)}…`;
 
 // computeChangedSurface exists for COVERAGE and excludes test files by design — the base-
 // intersection inputs come from these helpers instead: every changed path counts, tests included.
 const gitPathList = (args, cwd) => {
-  const r = spawnSync('git', args, { cwd, maxBuffer: 256 * 1024 * 1024, windowsHide: true });
+  const r = spawnSync('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
   if (r.error || r.status !== 0) return null;
   return r.stdout.toString('utf8').split('\0').filter(Boolean);
 };

package/tools/flow-delta-proof.mjs

@@ -13,15 +13,15 @@ import { createHash } from 'node:crypto';
 import { readFileSync, lstatSync, readlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { GIT_MAX_BUFFER } from './git-env.mjs';
 import { lstatNoFollow } from './atomic-write.mjs';
 import { FLOW_SCHEMA_VERSION, canonicalFlowDigest } from './flow-record.mjs';
-import { isNeverCommittableStat, isBinaryFile, lexicalRepoRelative, resolveBase } from './core-evidence.mjs';
+import { FINGERPRINT_CACHED_DIFF_ARGV, FINGERPRINT_UNSTAGED_DIFF_ARGV, isNeverCommittableStat, isBinaryFile, lexicalRepoRelative, resolveBase } from './core-evidence.mjs';
 import { flowStoreStop, gitLine, describeNonRegular } from './flow-store-read.mjs';
 import { appendFlowRecord } from './flow-append.mjs';
 
 const stop = flowStoreStop;
 
-const GIT_MAX_BUFFER = 256 * 1024 * 1024;
 const gitBuf = (args, cwd) => {
   const r = spawnSync('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
   if (r.error || r.status !== 0) return null;
@@ -166,8 +166,8 @@ const untrackedEntryChunks = (top, rel, lstat) => {
 const captureFingerprintPieces = (cwd, { lstat = lstatSync } = {}) => {
   const top = gitLine(['rev-parse', '--show-toplevel'], cwd);
   if (top == null) return null;
-  const staged = gitBuf(['diff', '--cached', '--no-ext-diff'], top);
-  const unstaged = gitBuf(['diff', '--no-ext-diff'], top);
+  const staged = gitBuf(FINGERPRINT_CACHED_DIFF_ARGV, top);
+  const unstaged = gitBuf(FINGERPRINT_UNSTAGED_DIFF_ARGV, top);
   const untrackedZ = gitBuf(['ls-files', '--others', '--exclude-standard', '-z'], top);
   if (staged == null || unstaged == null || untrackedZ == null) return null;
   const entries = untrackedZ.toString('utf8').split('\0').filter(Boolean)

package/tools/flow-record-shape.mjs

@@ -79,6 +79,7 @@ const FIELD_CHECKS = {
   attemptIndex: { ok: (v) => Number.isInteger(v) && v >= 1, want: 'a positive integer attempt index (monotonic per counting context)' },
   status: { ok: (v) => v === 'green' || v === 'red', want: 'the closed enum green | red' },
   diagnosis: { ok: isNonEmptyString, want: 'a non-empty diagnosis statement (Decision 8 — the recorded continuation past two reds)' },
+  walk: { ok: isPlainObject, want: 'the closed walk object' },
 };
 
 const CHAIN_COMMON_FIELDS = ['planId', 'cycle', 'round', 'commitEpoch', 'owner', 'base', 'timestamp'];
@@ -171,33 +172,54 @@ const validateDispatches = (label, list) => {
 // The per-finding disposition ledger (#13/#33): every council finding lands as exactly one of the
 // three closed arms, each carrying its proof (a consult-attestation/red-proof digest, a debt entry,
 // or a stated rejection reason).
+// The new arms are escalated with its override, and custody-lost keyed on receiptDigest with no findingDigest.
 const DISPOSITION_KEYS = {
   folded: ['findingDigest', 'action', 'proofKind', 'proofDigest'],
   queued: ['findingDigest', 'action', 'debtId', 'debtDigest'],
   rejected: ['findingDigest', 'action', 'reason'],
+  escalated: ['findingDigest', 'action', 'overrideDigest'],
+  'custody-lost': ['action', 'receiptDigest', 'findingManifestDigest', 'reason'],
 };
+const PROOF_KINDS = ['consult-attestation', 'red-proof'];
+const QUEUED_PROOF_KEYS = ['claim', 'proofKind', 'proofDigest'];
+const LOSS_REASONS = ['absent', 'foreign', 'error', 'malformed', 'foreign-identity', 'swapped'];
 
 const validateDispositions = (label, list) => {
   const seenFindings = new Set();
+  const seenLostReceipts = new Set();
   for (let i = 0; i < list.length; i += 1) {
     const d = list[i];
     const at = `${label}: dispositions[${i}]`;
     if (!isPlainObject(d)) return refuse(`${at} must be an object`);
-    const armKeys = Object.hasOwn(DISPOSITION_KEYS, d.action) ? DISPOSITION_KEYS[d.action] : undefined;
+    const baseKeys = Object.hasOwn(DISPOSITION_KEYS, d.action) ? DISPOSITION_KEYS[d.action] : undefined;
+    const armKeys = d.action === 'queued' && QUEUED_PROOF_KEYS.some((key) => key in d) ? [...baseKeys, ...QUEUED_PROOF_KEYS] : baseKeys;
     if (armKeys === undefined) return refuse(`${at}: action must be one of ${Object.keys(DISPOSITION_KEYS).join(' | ')} (got ${JSON.stringify(d.action)}) — an inherited prototype key never resolves an arm (fail closed)`);
     const stray = Object.keys(d).find((k) => !armKeys.includes(k));
     if (stray !== undefined) return refuse(`${at}: unknown field "${stray}" — the ${d.action} arm's key set is closed`);
     const missing = armKeys.find((k) => !(k in d));
     if (missing !== undefined) return refuse(`${at}: missing field "${missing}"`);
+    if (d.action === 'custody-lost') {
+      if (!isHex64(d.receiptDigest)) return refuse(`${at}: receiptDigest must be the 64-hex digest of the lost receipt`);
+      if (!isHex64(d.findingManifestDigest)) return refuse(`${at}: findingManifestDigest must be the 64-hex ledger digest of the lost manifest`);
+      if (!LOSS_REASONS.includes(d.reason)) return refuse(`${at}: reason must be one of ${LOSS_REASONS.join(' | ')}`);
+      if (seenLostReceipts.has(d.receiptDigest)) return refuse(`${at}: duplicate receiptDigest — one custody-lost entry per lost receipt`);
+      seenLostReceipts.add(d.receiptDigest);
+      continue;
+    }
     if (!isHex64(d.findingDigest)) return refuse(`${at}: findingDigest must be the 64-hex digest of the finding`);
     if (seenFindings.has(d.findingDigest)) return refuse(`${at}: duplicate findingDigest — every finding gets exactly one disposition, whichever the arm`);
     seenFindings.add(d.findingDigest);
     if (d.action === 'folded') {
-      if (d.proofKind !== 'consult-attestation' && d.proofKind !== 'red-proof') return refuse(`${at}: proofKind must be consult-attestation | red-proof (the fold's proof record class)`);
+      if (!PROOF_KINDS.includes(d.proofKind)) return refuse(`${at}: proofKind must be consult-attestation | red-proof (the fold's proof record class)`);
       if (!isHex64(d.proofDigest)) return refuse(`${at}: proofDigest must be the 64-hex digest of the proof record`);
     } else if (d.action === 'queued') {
       if (!isNonEmptyString(d.debtId)) return refuse(`${at}: debtId must be the non-empty stable debt-queue id`);
       if (!isHex64(d.debtDigest)) return refuse(`${at}: debtDigest must be the 64-hex digest of the debt entry`);
+      if ('claim' in d && !isNonEmptyString(d.claim)) return refuse(`${at}: claim must be a non-empty invariant`);
+      if ('proofKind' in d && !PROOF_KINDS.includes(d.proofKind)) return refuse(`${at}: proofKind must be consult-attestation | red-proof`);
+      if ('proofDigest' in d && !isHex64(d.proofDigest)) return refuse(`${at}: proofDigest must be the 64-hex digest of the proof record`);
+    } else if (d.action === 'escalated') {
+      if (!isHex64(d.overrideDigest)) return refuse(`${at}: overrideDigest must be the 64-hex digest of the maintainer override`);
     } else if (!isNonEmptyString(d.reason)) {
       return refuse(`${at}: reason must be a non-empty statement of why the finding is rejected`);
     }
@@ -205,6 +227,24 @@ const validateDispositions = (label, list) => {
   return { ok: true };
 };
 
+const validateWalk = (walk) => {
+  const keys = ['listVersion', 'rows', 'uncovered'];
+  if (!isPlainObject(walk)) return refuse('internal-attestation: walk must be an object');
+  const stray = Object.keys(walk).find((key) => !keys.includes(key));
+  if (stray !== undefined) return refuse(`internal-attestation: walk has unknown field "${stray}"`);
+  const missing = keys.find((key) => !(key in walk));
+  if (missing !== undefined) return refuse(`internal-attestation: walk is missing field "${missing}"`);
+  if (!Number.isInteger(walk.listVersion) || walk.listVersion < 1) return refuse('internal-attestation: walk.listVersion must be a positive integer');
+  for (const name of ['rows', 'uncovered']) {
+    if (!Array.isArray(walk[name])) return refuse(`internal-attestation: walk.${name} must be an array`);
+    const itemKeys = name === 'rows' ? ['id', 'class', 'checked'] : ['id', 'class'];
+    for (const [i, item] of walk[name].entries()) {
+      if (!isPlainObject(item) || Object.keys(item).length !== itemKeys.length || !itemKeys.every((key) => key in item && isNonEmptyString(item[key]))) return refuse(`internal-attestation: walk.${name}[${i}] must be the closed {${itemKeys.join(', ')}} string object`);
+    }
+  }
+  return { ok: true };
+};
+
 // The three-layer pre-state digest set (#60): HEAD entry, index entry, worktree bytes — null means
 // "no entry in that layer". tracked-ness is derived (a HEAD or index entry exists); the presence
 // class is the WORKTREE layer. The fingerprint domain (staged + unstaged + untracked) is exactly
@@ -272,8 +312,10 @@ export const validateFlowRecord = (record) => {
     }
     fieldToCheck.diagnosis = 'diagnosis';
   }
+  if (record.kind === 'internal-attestation' && 'walk' in record) fieldToCheck.walk = 'walk';
   const checked = checkFields(record.kind, record, fieldToCheck);
   if (!checked.ok) return checked;
+  if (record.kind === 'internal-attestation' && 'walk' in record) return validateWalk(record.walk);
   if (record.kind === 'down-mark') {
     if (!isCanonicalInstant(record.timestamp)) return refuse('down-mark: timestamp must be a canonical UTC ISO instant (toISOString round-trip) — the TTL window needs comparable instants');
     if (Date.parse(record.expiresAt) <= Date.parse(record.timestamp)) return refuse('down-mark: expiresAt must be strictly after timestamp — an already-expired mark is refused at the record level');