@sabaiway/agent-workflow-kit 1.38.0 → 1.40.0

package/tools/review-state.mjs

@@ -52,6 +52,11 @@ export const PLANS_REL = 'docs/plans';
 const ACTIVITY = 'plan-execution';
 const SLOT = 'review';
 const GIT_MAX_BUFFER = 256 * 1024 * 1024; // a full-tree diff can be large; never truncate silently
+// --await (BUGFREE-3 / AD-049, item (d)) bounds + poll cadence. The default timeout is generous —
+// a real grounded bridge review can take minutes — and every value is overridable (--timeout / the
+// injectable clock) so hermetic tests never spend wall-clock.
+export const DEFAULT_AWAIT_TIMEOUT_S = 900;
+export const AWAIT_POLL_MS = 5000;
 
 // ── git plumbing (read-only queries; injectable for tests) ─────────────────────────
 
@@ -387,11 +392,72 @@ export const main = (argv, ctx = {}) => {
   }
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (isDirectRun) {
-  const r = main(process.argv.slice(2));
+// ── --await: block until every recipe-named backend has receipted the current tree ─────
+// (BUGFREE-3 / AD-049, item (d)). It waits for ALL recipe-named backends — review-state has NO
+// durable degraded-backend source before a round is recorded (degraded is a review-LEDGER round
+// field, not a review-state input), so "non-degraded" is not knowable here; awaiting a backend the
+// operator KNOWS is degraded is the operator's call (don't --await it). The completion signal is the
+// RECEIPT (i.e. `--check` would PASS), NEVER a process event — a harness "completed" notification
+// fires early and a bridge's output late-flushes, so polling a pid/receipt-file is the durable
+// mechanization of receipts-not-pgrep. Stays read-only (it only re-reads state); the clock is
+// injectable (ctx.now / ctx.sleep / ctx.pollMs) so hermetic tests never spend wall-clock.
+
+const AWAIT_ALLOWED_ARGS = new Set(['--await', '--timeout']);
+
+const parseAwaitTimeoutS = (argv) => {
+  const i = argv.indexOf('--timeout');
+  if (i === -1) return DEFAULT_AWAIT_TIMEOUT_S;
+  const raw = argv[i + 1];
+  if (!raw || !/^\d+$/.test(raw) || Number(raw) < 1) throw fail(2, '--timeout requires a positive integer number of seconds');
+  return Number(raw);
+};
+
+export const mainAwait = async (argv, ctx = {}) => {
+  const cwd = ctx.cwd ?? process.cwd();
+  const env = ctx.env ?? process.env;
+  const detect = ctx.detect ?? detectBackends;
+  const now = ctx.now ?? (() => Date.now());
+  const sleep = ctx.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const pollMs = ctx.pollMs ?? AWAIT_POLL_MS;
+  try {
+    for (let i = 0; i < argv.length; i += 1) {
+      const a = argv[i];
+      if (a === '--timeout') { i += 1; continue; } // its value is consumed by parseAwaitTimeoutS
+      if (!AWAIT_ALLOWED_ARGS.has(a)) throw fail(2, `--await accepts only --timeout <s> (got ${a})`);
+    }
+    const timeoutS = parseAwaitTimeoutS(argv);
+    const timeoutMs = timeoutS * 1000;
+    const start = now();
+    // Poll the SAME normative decision --check computes: ready == `--check` would pass (solo / no
+    // plan / a clean tree / not-a-git-tree all resolve instantly — nothing to await). Re-read state
+    // every poll so a landed receipt (or a tree edit that re-staled one) is seen fresh. The DEADLINE
+    // is checked BEFORE readiness (codex council R2): once elapsed reaches the timeout the await is
+    // over, so a receipt that only lands AT/after the deadline never flips it to READY; and each
+    // sleep is BOUNDED to the remaining time so a full poll interval can never overshoot the timeout.
+    let lastReason = 'no poll completed before the deadline';
+    for (;;) {
+      const elapsed = now() - start;
+      if (elapsed >= timeoutMs) return { code: 1, stdout: '', stderr: `review-state --await: TIMEOUT after ${timeoutS}s — ${lastReason}` };
+      const check = decideCheck(buildState({ cwd, env, detect }));
+      lastReason = check.reason;
+      if (check.code === 0) return { code: 0, stdout: `review-state --await: READY — ${check.reason}`, stderr: '' };
+      await sleep(Math.min(pollMs, timeoutMs - elapsed));
+    }
+  } catch (err) {
+    return { code: err.exitCode ?? 1, stdout: '', stderr: `review-state: ${err.message}` };
+  }
+};
+
+const emitResult = (r) => {
   // Exact writes + a natural exit: process.exit() can truncate unflushed piped stdio (codex R2).
   if (r.stdout) process.stdout.write(r.stdout.endsWith('\n') ? r.stdout : `${r.stdout}\n`);
   if (r.stderr) process.stderr.write(r.stderr.endsWith('\n') ? r.stderr : `${r.stderr}\n`);
   process.exitCode = r.code;
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) {
+  const argv = process.argv.slice(2);
+  if (argv.includes('--await')) mainAwait(argv).then(emitResult);
+  else emitResult(main(argv));
 }

package/tools/run-gates.mjs

@@ -18,16 +18,32 @@
 // Honest outcomes — each distinct, never a silent green (the exit-code table + the summary-line
 // schema are pinned by run-gates.test.mjs):
 //   0 ok · 1 gate failure · 2 usage · 3 missing declaration · 4 empty gates list ·
-//   5 malformed/invalid declaration · 6 bash unavailable. Gate `cmd` lines are BASH command
-//   lines (brace/glob expansion); a host without bash gets the loud exit-6 preflight error,
-//   never a silent reinterpretation under another shell.
+//   5 malformed/invalid declaration · 6 bash unavailable · 7 --record asked but the gate-run
+//   record could not be written. Gate `cmd` lines are BASH command lines (brace/glob expansion);
+//   a host without bash gets the loud exit-6 preflight error, never a silent reinterpretation
+//   under another shell.
 //
-// The runner itself WRITES NOTHING. Dependency-free, Node >= 18. No side effects on import.
+// The runner itself WRITES NOTHING by default. `--record` (BUGFREE-2 / AD-048, D5) mints ONE
+// v4 `gate-run` record — the green-baseline receipt the review-ledger writer's D5 tooth consumes —
+// by DELEGATING to the ledger's sole writer (recordGateRun in review-ledger-write.mjs): this
+// runner never opens the ledger file itself (an import/structure pin holds the boundary). The
+// record carries the FULL declaration + exactly what ran (a --only subset records honestly as a
+// subset — it never satisfies quality-green) + the tree fingerprint BEFORE and AFTER the run (a
+// mutating gate attests no particular tree). Dependency-free, Node >= 18. No side effects on import.
 
 import { readFileSync, lstatSync } from 'node:fs';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { pathToFileURL } from 'node:url';
+import { computeTreeFingerprint } from './review-state.mjs';
+import { recordGateRun } from './review-ledger-write.mjs';
+// (a) BUGFREE-3 / AD-049: the one-suite-run credit. The fold runner already spawned the `unit-tests`
+// suite under coverage; --record can CREDIT that gate from the recorded evidence instead of
+// re-spawning it minutes later — read-only (the read core, never the tree-toucher).
+import { foldSuiteCredit } from './fold-completeness.mjs';
+
+// The gate id the (a) credit applies to — the SAME command the fold runner resolves as its suite.
+export const UNIT_TESTS_GATE_ID = 'unit-tests';
 
 // The per-project declaration (strict JSON, hand-editable). cwd-relative — errors show a path the
 // user can open (the orchestration-config CONFIG_REL idiom).
@@ -42,6 +58,10 @@ export const EXIT = Object.freeze({
   empty: 4,
   malformed: 5,
   noBash: 6,
+  // --record was asked for but the gate-run record could not be written (no in-flight loop, a
+  // malformed ledger, an fs refusal): the invocation's contract included a ledger receipt — not
+  // delivering it is its own loud outcome, never folded into ok/fail.
+  recordFailed: 7,
 });
 
 // A tagged failure carrying its process exit code (the shared orchestration-config idiom).
@@ -54,12 +74,18 @@ const SPAWN_FAILED_CODE = -1;
 const MAX_GATE_OUTPUT_BYTES = 64 * 1024 * 1024;
 
 const USAGE = [
-  'usage: run-gates.mjs [--cwd <dir>] [--only <id>]... [--help]',
+  'usage: run-gates.mjs [--cwd <dir>] [--only <id>]... [--record] [--help]',
   '',
   `Runs the gates declared in <cwd>/${GATES_REL} (one bash command line each, project root as cwd).`,
   'Prints a per-gate PASS/FAIL table + one machine-readable summary line; exit 0 iff all green.',
+  '--record additionally mints ONE v4 gate-run record into the review ledger via its sole writer',
+  '(the D5 green-baseline receipt; needs a single in-flight plan): the full declaration + what ran',
+  '+ the pre/post tree fingerprints. A red run records honestly; a --only subset records as a subset.',
+  'In --record mode the unit-tests gate is CREDITED (not re-spawned) when it is the FIRST declared gate',
+  'AND the fold-completeness runner already ran that EXACT command green at the current tree',
+  '(fingerprint-bound + exit-0 + cmd-identity); positioned after another gate, it always re-spawns.',
   `Exit codes: 0 ok · 1 gate failure · 2 usage · 3 missing declaration · 4 empty gates list ·`,
-  '5 malformed/invalid declaration · 6 bash unavailable.',
+  '5 malformed/invalid declaration · 6 bash unavailable · 7 --record asked but the record failed.',
 ].join('\n');
 
 // ── declaration validation (malformed → exit 5, loud `path: reason`) ─────────────────
@@ -158,8 +184,16 @@ export const selectGates = (gates, onlyIds) => {
 // Spawn one gate cmd via bash from the project root. `cmd` is a BASH command line by contract
 // (the declaration's _README states it): this repo's own gate matrix needs brace+glob expansion,
 // which /bin/sh does not perform — hence bash explicitly, never the platform default shell.
-export const spawnGateViaBash = (cmd, cwd) =>
-  spawnSync('bash', ['-c', cmd], { cwd, encoding: 'utf8', maxBuffer: MAX_GATE_OUTPUT_BYTES });
+// NODE_TEST_CONTEXT is stripped (mirroring the fold suite's childTestEnv): a `node --test` gate spawned
+// while run-gates is itself running under a parent test context would otherwise inherit it, hit Node's
+// recursive-run guard, silently skip every file, and exit 0 — a vacuous false green. Stripping it also
+// makes the plain gate env-equivalent to the fold suite, so the (a) suite-run credit's exit-0 truthfully
+// predicts a plain-spawn exit-0 (the one remaining, documented residual is NODE_V8_COVERAGE).
+export const spawnGateViaBash = (cmd, cwd) => {
+  const env = { ...process.env };
+  delete env.NODE_TEST_CONTEXT;
+  return spawnSync('bash', ['-c', cmd], { cwd, env, encoding: 'utf8', maxBuffer: MAX_GATE_OUTPUT_BYTES });
+};
 
 // The command the bash preflight runs before ANY gate: proves bash itself spawns on this host,
 // so "no bash" is one loud exit-6 error up front — never a per-gate spawn-failure cascade.
@@ -172,10 +206,19 @@ const trimTrailingNewline = (text) => text.replace(/\n$/, '');
 
 // Run the selected gates sequentially (declaration order). A green gate logs one PASS line; a
 // failing gate logs FAIL + its captured stdout/stderr VERBATIM (triage without re-running).
-export const runGates = (gates, { cwd, spawn = spawnGateViaBash, now = Date.now, log = console.log }) => {
+export const runGates = (gates, { cwd, spawn = spawnGateViaBash, now = Date.now, log = console.log, credit = null }) => {
   const results = [];
   for (const gate of gates) {
     log(`── ${gate.id} — ${gate.title}`);
+    // (a) the one-suite-run credit: for the unit-tests gate, if the fold runner already ran this exact
+    // command green at the current tree, CREDIT it instead of re-spawning (no quality loss — same
+    // execution, same tree, recorded once). Any mismatch → credit is null → the normal spawn below.
+    const credited = credit ? credit(gate) : null;
+    if (credited) {
+      log('   PASS (credited from the fold-completeness suite run — no re-spawn)');
+      results.push({ id: gate.id, title: gate.title, ok: true, code: 0, elapsedMs: 0, credited: true });
+      continue;
+    }
     const startedAt = now();
     const res = spawn(gate.cmd, cwd);
     const elapsedMs = now() - startedAt;
@@ -218,7 +261,7 @@ export const composeSummaryLine = ({ status, results = [] }) => {
 // ── CLI ───────────────────────────────────────────────────────────────────────────────
 
 const parseArgs = (argv) => {
-  const opts = { cwd: null, only: [], help: false };
+  const opts = { cwd: null, only: [], record: false, help: false };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--help' || arg === '-h') {
@@ -231,6 +274,8 @@ const parseArgs = (argv) => {
       i += 1;
       if (argv[i] === undefined) throw fail(EXIT.usage, '--only requires a gate id argument');
       opts.only.push(argv[i]);
+    } else if (arg === '--record') {
+      opts.record = true;
     } else {
       throw fail(EXIT.usage, `unknown argument "${arg}"\n${USAGE}`);
     }
@@ -244,12 +289,16 @@ const parseArgs = (argv) => {
 export const runCli = (argv, deps = {}) => {
   const {
     cwd = process.cwd(),
+    env = process.env,
     log = console.log,
     logError = console.error,
     spawn = spawnGateViaBash,
     readFile,
     lstat,
     now,
+    record = recordGateRun,
+    fingerprint = computeTreeFingerprint,
+    foldCredit = foldSuiteCredit,
   } = deps;
   try {
     const opts = parseArgs(argv);
@@ -283,10 +332,51 @@ export const runCli = (argv, deps = {}) => {
       log(composeSummaryLine({ status: 'no-bash' }));
       return EXIT.noBash;
     }
-    const results = runGates(selected, { cwd: projectDir, spawn, log, now });
+    const fingerprintBefore = opts.record ? fingerprint(projectDir) : null;
+    // (a) the one-suite-run credit — ONLY in --record mode (the fold-loop flow), ONLY the unit-tests
+    // gate, ONLY when it is the FIRST selected gate (a gate that ran BEFORE it could have side-effected
+    // an ignored/out-of-tree artifact unit-tests depends on WITHOUT moving the fingerprint, so a
+    // later-positioned unit-tests must re-spawn — never credit a state the real matrix might fail), and
+    // ONLY when the fold evidence is fingerprint-bound + exit-0 (foldCredit) AND its recorded cmd EQUALS
+    // this gate's cmd (the --only-subset defense). Any mismatch → credit is null → the normal spawn.
+    let credit = null;
+    if (opts.record && selected[0]?.id === UNIT_TESTS_GATE_ID) {
+      const fold = foldCredit({ cwd: projectDir, env, fingerprint: fingerprintBefore });
+      credit = (gate) => (gate.id === UNIT_TESTS_GATE_ID && fold.credited && fold.evidence.cmd === gate.cmd ? fold : null);
+    }
+    const results = runGates(selected, { cwd: projectDir, spawn, log, now, credit });
     for (const line of formatTable(results)) log(line);
     const allGreen = results.every((result) => result.ok);
+    // The gate-run record (D5): minted for green AND red runs alike (an honest red is telemetry
+    // fuel), via the ledger's sole writer. Emitted BEFORE the summary line — the machine summary
+    // stays the LAST line of every non-usage outcome (pinned).
+    let recordError = null;
+    if (opts.record) {
+      const failing = results.filter((result) => !result.ok);
+      try {
+        const { writtenPath } = record({
+          cwd: projectDir,
+          env,
+          declared: declaration.gates.map(({ id, cmd }) => ({ id, cmd })),
+          results: results.map(({ id, ok, code }) => ({ id, ok, code })),
+          summary: {
+            status: allGreen ? 'ok' : 'fail',
+            gates: results.length,
+            passed: results.length - failing.length,
+            failed: failing.length,
+            failedIds: failing.map((result) => result.id),
+          },
+          fingerprintBefore,
+          fingerprintAfter: fingerprint(projectDir),
+        });
+        log(`[run-gates] gate-run recorded → ${writtenPath}`);
+      } catch (err) {
+        recordError = err;
+        logError(`[run-gates] --record failed: ${err.message}`);
+      }
+    }
     log(composeSummaryLine({ status: allGreen ? 'ok' : 'fail', results }));
+    if (recordError) return EXIT.recordFailed;
     return allGreen ? EXIT.ok : EXIT.fail;
   } catch (err) {
     logError(`[run-gates] ${err.message}`);

package/tools/sarif.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// sarif.mjs — a dependency-free SARIF (2.1.0) reader for the OPTIONAL advisory findings surface
+// (BUGFREE-3, AD-049, step 1.4 — the reviewdog pattern). Findings are ADVISORY ONLY: they are NEVER
+// recorded on a fold run record (SARIF stays entirely out of the fold result schema — no v4 quartet
+// coupling, no sequencing dependency) and NEVER gate-blocking (fold-completeness --check never reads
+// SARIF). A malformed SARIF fails the advisory READ loudly (a nonzero exit on the advisory verb), but
+// the fold gate — fold-completeness --check — is unaffected. No side effects on import; Node >= 18.
+
+export const SARIF_STOP = 'SARIF_STOP';
+const stop = (message) => Object.assign(new Error(`[agent-workflow-kit] ${message}`), { name: 'SarifStop', code: SARIF_STOP });
+
+// parseSarif(text) → { findings: [{ ruleId, level, message, file, line }] }. THROWS on a malformed
+// SARIF (not JSON, or no runs[] array) — the advisory read is LOUD, never a silent empty result. A
+// well-formed run with zero results yields an empty findings list (a clean advisory).
+export const parseSarif = (text) => {
+  let doc;
+  try {
+    doc = JSON.parse(text);
+  } catch (err) {
+    throw stop(`SARIF is not valid JSON (${err.message})`);
+  }
+  if (!doc || typeof doc !== 'object' || !Array.isArray(doc.runs)) {
+    throw stop('SARIF has no runs[] array — not a SARIF 2.1.0 document');
+  }
+  const findings = [];
+  for (const run of doc.runs) {
+    const results = Array.isArray(run?.results) ? run.results : [];
+    for (const r of results) {
+      const loc = r?.locations?.[0]?.physicalLocation ?? {};
+      findings.push({
+        ruleId: typeof r?.ruleId === 'string' ? r.ruleId : '(no rule)',
+        level: typeof r?.level === 'string' ? r.level : 'warning',
+        message: typeof r?.message?.text === 'string' ? r.message.text : '',
+        file: typeof loc?.artifactLocation?.uri === 'string' ? loc.artifactLocation.uri : null,
+        line: Number.isInteger(loc?.region?.startLine) ? loc.region.startLine : null,
+      });
+    }
+  }
+  return { findings };
+};
+
+// renderSarifFindings(findings) → a human advisory block (one line per finding). Empty → a stated
+// "no findings" note. Always advisory — the caller never blocks a gate on this.
+export const renderSarifFindings = (findings) => {
+  if (findings.length === 0) return 'SARIF advisory: no findings (advisory only — never gate-blocking).';
+  const lines = [`SARIF advisory: ${findings.length} finding(s) (advisory only — never gate-blocking):`];
+  for (const f of findings) {
+    const at = f.file ? `${f.file}${f.line != null ? `:${f.line}` : ''}` : '(no location)';
+    lines.push(`  [${f.level}] ${f.ruleId} — ${at}${f.message ? ` — ${f.message}` : ''}`);
+  }
+  return lines.join('\n');
+};

package/tools/verification-profile.mjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+// verification-profile.mjs — read-only schema/read core for the per-project VERIFICATION PROFILE
+// (docs/ai/verification-profile.json), the language-independence contract (BUGFREE-3, AD-049).
+// Companion read-core to the fold-completeness runner. NO writer — the runner is the sole
+// tree-toucher. An ABSENT profile reproduces today's exact behaviour (V8 coverage + node:test
+// TAP-on-stdout); the profile only generalizes the coverage SOURCE, the single-test RESULT FORMAT,
+// and an optional SARIF path — coverage/probe INPUTS, never the suite command.
+//
+// The suite COMMAND is deliberately NOT a profile field: it stays the docs/ai/gates.json unit-tests
+// cmd so the fold run and the unit-tests gate share command-identity (the (a) suite-evidence credit
+// requires the SAME command).
+//
+// Path safety (Decision 4; grounding.mjs assertScratchDestination model): every profile-declared
+// artifact path MUST be gitignored or outside the work tree, checked on the REALPATH (a symlink leaf
+// is refused). An in-tree, not-ignored file the suite writes would move the review fingerprint the
+// run binds to; a symlinked path could route the write onto a tracked file. validateProfile fails
+// CLOSED on any such path.
+//
+// Dependency-free, Node >= 18. No side effects on import.
+
+import { readFileSync, lstatSync, realpathSync } from 'node:fs';
+import { join, resolve, relative, isAbsolute, dirname, basename } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fail } from './orchestration-config.mjs';
+
+// cwd-relative so error prefixes show a path the user can open, never an absolute temp/host path.
+export const PROFILE_REL = 'docs/ai/verification-profile.json';
+export const PROFILE_SCHEMA_VERSION = 1;
+
+export const COVERAGE_KINDS = new Set(['v8', 'lcov']);
+export const RESULT_FORMATS = new Set(['tap-stdout', 'tap-file', 'junit-xml']);
+// File-based formats must be TOLD where to write, so their argv carries {resultPath} (the runner
+// substitutes a fresh out-of-tree path per probe and reads THAT back). tap-stdout reads stdout.
+export const FILE_BASED_FORMATS = new Set(['tap-file', 'junit-xml']);
+export const RESULT_PATH_TOKEN = '{resultPath}';
+export const FILE_TOKEN = '{file}';
+export const PATTERN_TOKEN = '{pattern}';
+
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const isNonEmptyString = (v) => typeof v === 'string' && v.length > 0;
+const isNonEmptyStringArray = (v) => Array.isArray(v) && v.length > 0 && v.every((x) => typeof x === 'string');
+
+// Unknown-key-fails-closed. Returns a reason string or null.
+const unknownKeyReason = (obj, allowed, where) => {
+  for (const k of Object.keys(obj)) {
+    if (!allowed.has(k)) return `${where}: unknown key "${k}" (allowed: ${[...allowed].join(', ')})`;
+  }
+  return null;
+};
+
+const COVERAGE_KEYS = new Set(['kind', 'lcovPath']);
+const SINGLE_TEST_KEYS = new Set(['argv', 'resultFormat']);
+const FINDINGS_KEYS = new Set(['sarifPath']);
+const TOP_KEYS = new Set(['_README', 'schema', 'coverage', 'singleTest', 'findings']);
+
+const defaultGitLine = (args, cwd) => {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8', windowsHide: true });
+  return r.error || r.status == null ? null : { status: r.status, stdout: r.stdout ?? '' };
+};
+
+// Reason string when the declared path is unsafe, else null. Unsafe = a symlink leaf, or an
+// in-work-tree path that is NOT gitignored (writing there moves the review fingerprint; a tracked
+// path reads as not-ignored too). Checked on the REAL destination (parent realpath-resolved) so a
+// symlinked parent cannot route an "outside/ignored" path back onto a tracked file. Outside any git
+// tree → safe. deps.{gitLine,lstat,realpath} are injectable for hermetic tests.
+export const declaredPathUnsafeReason = (label, p, cwd, deps = {}) => {
+  const gitLine = deps.gitLine ?? defaultGitLine;
+  const lstat = deps.lstat ?? lstatSync;
+  const realpath = deps.realpath ?? realpathSync;
+  if (!isNonEmptyString(p)) return `${label} must be a non-empty string`;
+  const lexical = isAbsolute(p) ? p : resolve(cwd, p);
+  let leaf = null;
+  try {
+    leaf = lstat(lexical);
+  } catch {
+    leaf = null; // absent → a fresh file; the parent is realpath-checked below
+  }
+  if (leaf && leaf.isSymbolicLink()) {
+    return `${label} "${p}" is a symlink — refused (the write would follow it onto another file; name the real path)`;
+  }
+  let realParent;
+  try {
+    realParent = realpath(dirname(lexical));
+  } catch {
+    return `${label} "${p}" parent directory does not exist — create the (gitignored) output dir first, or fix the path`;
+  }
+  const full = join(realParent, basename(lexical));
+  const top = gitLine(['rev-parse', '--show-toplevel'], cwd);
+  if (top == null || top.status !== 0) return null; // not a git work tree → not fingerprint-relevant
+  // Realpath the repo root too so both sides of relative() are physical — a checkout opened via a
+  // symlink must not misclassify an in-tree path as OUTSIDE. Fail CLOSED if it can't resolve.
+  let root;
+  try {
+    root = realpath(top.stdout.replace(/\r?\n$/, ''));
+  } catch {
+    return `${label} "${p}" — cannot resolve the repo root's real path (fail closed)`;
+  }
+  const rel = relative(root, full);
+  if (rel.startsWith('..') || isAbsolute(rel)) return null; // outside the work tree → safe
+  const ignored = gitLine(['check-ignore', '-q', '--', rel], root);
+  if (ignored == null || ignored.status !== 0) {
+    return `${label} "${p}" is an in-tree path that is not gitignored — the suite writing there would move the review fingerprint the run binds to; gitignore it (or place it outside the repo)`;
+  }
+  return null;
+};
+
+// validateProfile(obj, { cwd, gitLine, lstat, realpath }?) → { ok, reason }. Strict schema first;
+// then, ONLY when `cwd` is supplied, the declared-path safety check (Decision 4). A pure-schema unit
+// test omits `cwd`; loadProfile passes it so malformed OR unsafe both fail closed.
+export const validateProfile = (obj, ctx = {}) => {
+  if (!isPlainObject(obj)) return { ok: false, reason: `${PROFILE_REL}: must be a JSON object` };
+  const topUnknown = unknownKeyReason(obj, TOP_KEYS, PROFILE_REL);
+  if (topUnknown) return { ok: false, reason: topUnknown };
+  if (obj.schema !== PROFILE_SCHEMA_VERSION) return { ok: false, reason: `${PROFILE_REL}: schema must be ${PROFILE_SCHEMA_VERSION}` };
+  if (obj._README !== undefined && typeof obj._README !== 'string') return { ok: false, reason: `${PROFILE_REL}: "_README" must be a string` };
+
+  // coverage (optional; absent → V8). lcovPath REQUIRED iff lcov, forbidden otherwise.
+  if (obj.coverage !== undefined) {
+    if (!isPlainObject(obj.coverage)) return { ok: false, reason: `${PROFILE_REL}: coverage must be an object` };
+    const ck = unknownKeyReason(obj.coverage, COVERAGE_KEYS, `${PROFILE_REL}: coverage`);
+    if (ck) return { ok: false, reason: ck };
+    if (!COVERAGE_KINDS.has(obj.coverage.kind)) return { ok: false, reason: `${PROFILE_REL}: coverage.kind must be one of ${[...COVERAGE_KINDS].join(', ')}` };
+    if (obj.coverage.kind === 'lcov') {
+      if (!isNonEmptyString(obj.coverage.lcovPath)) return { ok: false, reason: `${PROFILE_REL}: coverage.lcovPath (a non-empty path) is required when coverage.kind is "lcov"` };
+    } else if (obj.coverage.lcovPath !== undefined) {
+      return { ok: false, reason: `${PROFILE_REL}: coverage.lcovPath is only valid when coverage.kind is "lcov"` };
+    }
+  }
+
+  // singleTest (optional; absent → default node:test argv + tap-stdout). argv must carry {file} +
+  // {pattern}; a file-based resultFormat additionally requires {resultPath}.
+  if (obj.singleTest !== undefined) {
+    if (!isPlainObject(obj.singleTest)) return { ok: false, reason: `${PROFILE_REL}: singleTest must be an object` };
+    const sk = unknownKeyReason(obj.singleTest, SINGLE_TEST_KEYS, `${PROFILE_REL}: singleTest`);
+    if (sk) return { ok: false, reason: sk };
+    if (!isNonEmptyStringArray(obj.singleTest.argv)) return { ok: false, reason: `${PROFILE_REL}: singleTest.argv must be a non-empty array of strings` };
+    const argvJoined = obj.singleTest.argv.join(' ');
+    if (!argvJoined.includes(FILE_TOKEN)) return { ok: false, reason: `${PROFILE_REL}: singleTest.argv must carry a ${FILE_TOKEN} placeholder (the runner substitutes the test file)` };
+    if (!argvJoined.includes(PATTERN_TOKEN)) return { ok: false, reason: `${PROFILE_REL}: singleTest.argv must carry a ${PATTERN_TOKEN} placeholder (the runner substitutes the test-name pattern)` };
+    const rf = obj.singleTest.resultFormat;
+    if (rf !== undefined && !RESULT_FORMATS.has(rf)) return { ok: false, reason: `${PROFILE_REL}: singleTest.resultFormat must be one of ${[...RESULT_FORMATS].join(', ')}` };
+    if (FILE_BASED_FORMATS.has(rf) && !argvJoined.includes(RESULT_PATH_TOKEN)) {
+      return { ok: false, reason: `${PROFILE_REL}: singleTest.resultFormat "${rf}" is file-based — singleTest.argv must carry a ${RESULT_PATH_TOKEN} placeholder (the runner substitutes a fresh out-of-tree result path per probe)` };
+    }
+  }
+
+  // findings (optional; an empty object is valid — no SARIF path declared).
+  if (obj.findings !== undefined) {
+    if (!isPlainObject(obj.findings)) return { ok: false, reason: `${PROFILE_REL}: findings must be an object` };
+    const fk = unknownKeyReason(obj.findings, FINDINGS_KEYS, `${PROFILE_REL}: findings`);
+    if (fk) return { ok: false, reason: fk };
+    if (obj.findings.sarifPath !== undefined && !isNonEmptyString(obj.findings.sarifPath)) {
+      return { ok: false, reason: `${PROFILE_REL}: findings.sarifPath must be a non-empty string when present` };
+    }
+  }
+
+  // Declared-path safety — only when a cwd is supplied (Decision 4).
+  if (ctx.cwd != null) {
+    const deps = { gitLine: ctx.gitLine, lstat: ctx.lstat, realpath: ctx.realpath };
+    if (obj.coverage?.kind === 'lcov') {
+      const r = declaredPathUnsafeReason('coverage.lcovPath', obj.coverage.lcovPath, ctx.cwd, deps);
+      if (r) return { ok: false, reason: `${PROFILE_REL}: ${r}` };
+    }
+    if (obj.findings?.sarifPath !== undefined) {
+      const r = declaredPathUnsafeReason('findings.sarifPath', obj.findings.sarifPath, ctx.cwd, deps);
+      if (r) return { ok: false, reason: `${PROFILE_REL}: ${r}` };
+    }
+  }
+  return { ok: true };
+};
+
+// resolvers — env WINS over the profile (ad-hoc override precedence, Decision 3)
+
+export const resolveCoverage = (profile) => {
+  const kind = profile?.coverage?.kind ?? 'v8';
+  return { kind, lcovPath: kind === 'lcov' ? profile.coverage.lcovPath : null };
+};
+
+// argv precedence: AW_FOLD_BOUND_CMD (applied in the runner's resolveBoundArgv, keeping the
+// malformed-override refusal one home) > profile.singleTest.argv > built-in default. This resolver
+// returns the PROFILE view only: argv = the profile template or null → runner default.
+export const resolveSingleTest = (profile) => ({
+  argv: profile?.singleTest?.argv ?? null,
+  resultFormat: profile?.singleTest?.resultFormat ?? 'tap-stdout',
+});
+
+export const resolveSarifPath = (profile) => profile?.findings?.sarifPath ?? null;
+
+// IO — config errors → loud fail(1); an absent FILE → defaults path, NOT an error
+
+// loadProfile(cwd, deps?) → { profile, source }. Absent FILE → { profile: null, source: 'none' }.
+// A directory / dangling symlink / permission error is PRESENT-but-unreadable → loud fail(1), never
+// silently treated as absent. Malformed JSON, schema-invalid, or an unsafe declared path → fail(1).
+export const loadProfile = (cwd, deps = {}) => {
+  const readFile = deps.readFile ?? readFileSync;
+  const lstat = deps.lstat ?? lstatSync;
+  const full = join(cwd, PROFILE_REL);
+  try {
+    lstat(full);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { profile: null, source: 'none' };
+    throw fail(1, `${PROFILE_REL}: unreadable (${(err && err.code) || (err && err.message) || err})`);
+  }
+  let raw;
+  try {
+    raw = readFile(full, 'utf8');
+  } catch (err) {
+    throw fail(1, `${PROFILE_REL}: unreadable (${(err && err.code) || (err && err.message) || err})`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw fail(1, `${PROFILE_REL}: malformed JSON (${err.message})`);
+  }
+  const v = validateProfile(parsed, { cwd, gitLine: deps.gitLine, lstat: deps.lstat, realpath: deps.realpath });
+  if (!v.ok) throw fail(1, v.reason);
+  return { profile: parsed, source: PROFILE_REL };
+};