@sabaiway/agent-workflow-kit 10.6.0 → 11.0.0

package/references/robustness-literals.json

@@ -0,0 +1,107 @@
+{
+  "schema": 1,
+  "version": 1,
+  "classes": [
+    {
+      "id": "git-location",
+      "prove": "Prove that every git query reaches the intended repository: every GIT_-named variable is stripped before cwd discovery, the git-dir, common-dir and work-tree identities agree between the ambient and the stripped discovery, and the hermetic environment is the fixtures' own, never a consumer's.",
+      "members": [
+        { "literal": "GIT_", "kind": "env", "note": "Strip every ASCII-case-insensitive git location variable before cwd discovery.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "GIT_DIR", "kind": "env", "note": "An ambient git directory can redirect discovery to another repository.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "GIT_WORK_TREE", "kind": "env", "note": "An ambient work-tree override can pair one git directory with another tree.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "GIT_COMMON_DIR", "kind": "env", "note": "An ambient common directory can redirect shared repository state.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "GIT_INDEX_FILE", "kind": "env", "note": "A pre-commit hook can name a temporary or copied index.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "GIT_PREFIX", "kind": "env", "note": "A hook inherits the prefix git measured for its invocation.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "GIT_CONFIG_PARAMETERS", "kind": "env", "note": "Command-line git configuration reaches hooks through this variable.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "GIT_EXEC_PATH", "kind": "env", "note": "A hook-shaped environment carries git's executable path.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "HOME", "kind": "env", "note": "Pin the home directory for hermetic git configuration.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "XDG_CONFIG_HOME", "kind": "env", "note": "Pin the XDG configuration home beside HOME.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "GIT_CONFIG_GLOBAL", "kind": "env", "note": "Disable the host's global git configuration file.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "GIT_CONFIG_SYSTEM", "kind": "env", "note": "Disable the host's system git configuration file.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "GIT_CONFIG_NOSYSTEM", "kind": "env", "note": "Tell git not to consult system configuration.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "GIT_ATTR_NOSYSTEM", "kind": "env", "note": "Tell git not to consult system attributes.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "LC_ALL", "kind": "env", "note": "Pin git's diagnostic language before matching its answers.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "PATH", "kind": "env", "note": "A supplied PATH is honored and an omitted PATH borrows the process value.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "--absolute-git-dir", "kind": "argv", "note": "Compare the ambient and stripped git-directory identities.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "--git-common-dir", "kind": "argv", "note": "Compare the ambient and stripped common-directory identities.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "--show-toplevel", "kind": "argv", "note": "Compare the ambient and stripped work-tree identities.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "work-tree", "kind": "state", "note": "All three ambient and stripped identities agree.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "not-a-repository", "kind": "state", "note": "Both discoveries report that cwd reaches no repository.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "error", "kind": "state", "note": "A probe, process result, path identity or answer failed closed.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "redirected", "kind": "state", "note": "Ambient and stripped discovery reach different repository identities.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "no-work-tree", "kind": "state", "note": "The git directory agrees but names no work tree.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "env-only", "kind": "state", "note": "Only the ambient git environment reaches a repository.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "GIT_MAX_BUFFER", "kind": "state", "note": "Every declared non-test git spawn buffer under agent-workflow-kit/tools/ uses the 256 MiB GIT_MAX_BUFFER; git-env.mjs declares it and every other scanned use imports it.", "source": "agent-workflow-kit/tools/git-env.mjs" }
+      ]
+    },
+    {
+      "id": "git-operation-state",
+      "prove": "Prove that an interrupted or conflicted git operation cannot be mistaken for an ordinary clean work tree.",
+      "members": [
+        { "literal": "rebase-apply", "kind": "state", "note": "A stopped git am leaves the apply-backend directory even when ordinary diffs are clean.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "rebase-merge", "kind": "state", "note": "A stopped rebase on the merge backend leaves this directory and REBASE_HEAD while status names the conflicted path.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "MERGE_HEAD", "kind": "ref", "note": "A merge in progress leaves this sequencer reference.", "source": "scripts/release/release-run.mjs" },
+        { "literal": "CHERRY_PICK_HEAD", "kind": "ref", "note": "A cherry-pick in progress leaves this sequencer reference.", "source": "scripts/release/release-run.mjs" },
+        { "literal": "REVERT_HEAD", "kind": "ref", "note": "A revert in progress leaves this sequencer reference.", "source": "scripts/release/release-run.mjs" },
+        { "literal": "REBASE_HEAD", "kind": "ref", "note": "A rebase in progress leaves this sequencer reference.", "source": "scripts/release/release-run.mjs" },
+        { "literal": "index.lock", "kind": "state", "note": "A held index lock blocks writes while read-only index queries still answer.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "unmerged stage 1", "kind": "state", "note": "The conflicted path carries the common-ancestor index stage.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "unmerged stage 2", "kind": "state", "note": "The conflicted path carries the current-side index stage.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "unmerged stage 3", "kind": "state", "note": "The conflicted path carries the other-side index stage.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "unmerged path twice", "kind": "state", "note": "Git 2.43 lists one conflicted path once per unmerged side; git am and bisect leave none of the four sequencer refs above.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" }
+      ]
+    },
+    {
+      "id": "git-read-flags",
+      "prove": "Prove that host git configuration, attributes and output framing cannot hide bytes or paths from a read.",
+      "members": [
+        { "literal": "status.showUntrackedFiles", "kind": "flag", "note": "Porcelain status can hide untracked files when this config is no.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "core.autocrlf", "kind": "flag", "note": "Work-tree CRLF and blob LF can compare clean under this config.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "core.symlinks", "kind": "flag", "note": "A host can materialize a tracked symlink as a placeholder regular file.", "source": "agent-workflow-kit/tools/control-bytes.mjs" },
+        { "literal": "--no-textconv", "kind": "flag", "note": "Disable textconv so configured filters cannot erase staged content from a diff.", "source": "scripts/release/release-run.mjs" },
+        { "literal": "--ignore-submodules=none", "kind": "flag", "note": "Override a host config that hides every submodule change.", "source": "scripts/release/release-run.mjs" },
+        { "literal": "-z", "kind": "flag", "note": "Use NUL framing for path-bearing git output.", "source": "agent-workflow-kit/tools/control-bytes.mjs" },
+        { "literal": "--exclude-standard", "kind": "flag", "note": "Apply repository ignore rules only where the query explicitly intends them.", "source": "agent-workflow-kit/tools/control-bytes.mjs" },
+        { "literal": "%B", "kind": "flag", "note": "Raw subject and body output carries its terminating newline and needs explicit framing.", "source": "scripts/check-ascii-letters.mjs" },
+        { "literal": "LC_ALL=C", "kind": "env", "note": "Pin git's own diagnostic wording before matching it.", "source": "agent-workflow-kit/tools/git-env.mjs" }
+      ]
+    },
+    {
+      "id": "spawn-outcome",
+      "prove": "Prove that every process-launch and process-result state is handled explicitly and never collapses into an empty success.",
+      "members": [
+        { "literal": "ENOENT", "kind": "errno", "note": "The executable may be absent from PATH before a child starts.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "EACCES", "kind": "errno", "note": "The executable or a required path may be present but inaccessible.", "source": "agent-workflow-kit/tools/fs-safe.mjs" },
+        { "literal": "EPERM", "kind": "errno", "note": "A sandbox or host policy may refuse the attempted process or filesystem operation.", "source": "agent-workflow-kit/tools/fs-safe.mjs" },
+        { "literal": "signal", "kind": "state", "note": "A child killed by a signal has no ordinary exit status.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "synchronous throw", "kind": "state", "note": "An injected or native runner can throw before returning a process result.", "source": "agent-workflow-kit/tools/control-bytes.mjs" },
+        { "literal": "exit 128", "kind": "state", "note": "Git's own not-a-repository or no-work-tree wording classifies only the matching exit 128 answer.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "empty answer", "kind": "state", "note": "A zero exit with no identity text is an error, never a repository path.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "maxBuffer", "kind": "state", "note": "A declared output ceiling is shared rather than silently truncated or copied.", "source": "agent-workflow-kit/tools/git-env.mjs" }
+      ]
+    },
+    {
+      "id": "durable-write",
+      "prove": "Prove that a durable write binds the intended regular file, publishes atomically and refuses an existing exclusive target.",
+      "members": [
+        { "literal": "O_NOFOLLOW", "kind": "syscall", "note": "Refuse a symlink leaf at descriptor open.", "source": "agent-workflow-kit/tools/fs-read-nofollow.mjs" },
+        { "literal": "O_NONBLOCK", "kind": "syscall", "note": "Prevent a hostile FIFO from blocking a descriptor open forever.", "source": "agent-workflow-kit/tools/fs-read-nofollow.mjs" },
+        { "literal": "fsync", "kind": "syscall", "note": "Sync the temporary file before rename and the directory after publication where supported.", "source": "scripts/release/release-run.mjs" },
+        { "literal": "rename", "kind": "syscall", "note": "Publish the fully written temporary file atomically after fsync.", "source": "scripts/release/release-run.mjs" },
+        { "literal": "wx", "kind": "flag", "note": "Open a temporary file or lock with exclusive creation.", "source": "scripts/release/release-run.mjs" },
+        { "literal": "EEXIST", "kind": "errno", "note": "An existing exclusive lock is a named busy state, never permission to clobber.", "source": "scripts/release/release-run.mjs" }
+      ]
+    },
+    {
+      "id": "bytes-not-strings",
+      "prove": "Prove that byte-domain identities remain bytes until a deliberate lossless decoding boundary.",
+      "members": [
+        { "literal": "undecoded", "kind": "state", "note": "Path records remain Buffer slices through NUL framing.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "NUL", "kind": "state", "note": "Git path records are split on the byte delimiter rather than whitespace or lines.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "partial UTF-8 sequence", "kind": "state", "note": "A file can be observed while its last multibyte sequence is incomplete.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "raw control byte", "kind": "state", "note": "A report line must never carry a raw line-breaking control character.", "source": "agent-workflow-kit/tools/repo-lex.mjs" },
+        { "literal": "U+FFFD", "kind": "state", "note": "Lossy decoding can fold distinct invalid byte sequences to the replacement character.", "source": "agent-workflow-kit/tools/repo-lex.mjs" }
+      ]
+    }
+  ]
+}

package/tools/changed-surface.mjs

@@ -14,7 +14,7 @@ import { readFileSync, lstatSync } from 'node:fs';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 
-const GIT_MAX_BUFFER = 256 * 1024 * 1024; // a full-tree diff can be large; never truncate
+import { GIT_MAX_BUFFER } from './git-env.mjs';
 
 // ── the CLOSED changed-path classification rule (AD-046 Decision 5; no heuristics) ───────────────
 

package/tools/commands.mjs

@@ -224,6 +224,20 @@ const CATALOG = [
     kind: READ_ONLY,
     oneLine: 'Check that every configured review backend has receipted the current uncommitted tree with a fresh grounded review; --check turns it into a gate exit code.',
   },
+  {
+    key: 'control-bytes',
+    invocation: invocationOf('control-bytes'),
+    group: 'Orchestrate',
+    kind: READ_ONLY,
+    oneLine: 'Refuse any raw control byte (C0 or DEL; TAB, LF, CR admitted) in the work tree — a path name, a regular file\'s content unless a git attribute says binary, a symlink target; --check is the gate spelling of the same report and exit code.',
+  },
+  {
+    key: 'robustness-brief',
+    invocation: invocationOf('robustness-brief'),
+    group: 'Orchestrate',
+    kind: READ_ONLY,
+    oneLine: 'Generate the concrete robustness literals for every tagged row in a plan, or for one selected row.',
+  },
   {
     key: 'receipt-deadline',
     invocation: invocationOf('receipt-deadline'),

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;