@sabaiway/agent-workflow-kit 1.37.1 → 1.39.0

package/tools/fold-completeness-run.mjs

@@ -12,10 +12,15 @@
 //      TS-JSX / out-of-domain) and derive per-file changed line ranges;
 //   3. M3a — run the suite ONCE under NODE_V8_COVERAGE (a dir OUTSIDE the work tree, Decision 8) and
 //      map every changed executable line to covered/uncovered via V8 innermost-range-wins (Decision 6);
-//   4. probe each of the loop's fixable-bug bound testIds once (Decision 3 / 10, shell-free) for
-//      resolvability + a green baseline;
-//   5. append ONE machine-only result record, bound to BOTH the tree fingerprint AND the sorted
-//      fixable-bug testId set (Decision 9), to <git dir>/agent-workflow-fold-completeness.jsonl.
+//   4. probe each of the loop's fixable-bug bound testIds N times (Decision 3 / 10 + D4, shell-free,
+//      per-run timeout) for resolvability + an N/N-green baseline, hashing each bound test file
+//      (the D5 custody anchor);
+//   5. append ONE machine-only v3 run record — segment-framed (base = git rev-parse HEAD, AD-048 D7)
+//      and bound to BOTH the tree fingerprint AND the SEGMENT's sorted fixable-bug testId set
+//      (Decision 9) — to <git dir>/agent-workflow-fold-completeness.jsonl.
+// A SECOND verb, --red "<testId>" (BUGFREE-1 / AD-047), observes a testId RED on the current
+// (pre-fold) tree and mints a red-probe receipt — the observed-red half of the honest red→green
+// proof; observed-green / unresolvable / mixed / timed-out are distinguished refusals, nothing written.
 // The researched mutation half (M3b) was SHELVED — bounded local-boundary mutation adds too little
 // over coverage and is not language-independent — so the `mutation` field stays the reserved empty shape.
 //
@@ -24,19 +29,28 @@
 // TS/JSX source is out of scope v1. Dependency-free, Node >= 18. No side effects on import.
 
 import { readFileSync, readdirSync, mkdtempSync, rmSync, realpathSync, lstatSync } from 'node:fs';
-import { join, dirname, basename } from 'node:path';
+import { join, dirname, basename, isAbsolute, normalize, posix, sep } from 'node:path';
 import { tmpdir } from 'node:os';
 import { pathToFileURL, fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { writeContainedFileAtomic } from './atomic-write.mjs';
 import { computeTreeFingerprint, plansInFlight } from './review-state.mjs';
-import { resolveLedgerPath, readLedger } from './review-ledger.mjs';
+import { resolveLedgerPath, resolveBase, readLedger, isWellFormedTestId, splitTestId } from './review-ledger.mjs';
 import {
   RESULT_SCHEMA_VERSION,
   resolveResultsPath,
   validateRunRecord,
   collectBoundTestIds,
+  probeVerdict,
 } from './fold-completeness.mjs';
+// The changed-surface computation lives in the NEUTRAL shared module (BUGFREE-2 / AD-048, D4): the
+// review-ledger writer's diff-size cap and this runner's coverage domain consume ONE computation,
+// and the writer never imports this runner (the sole-tree-toucher boundary — import-split pinned).
+// Re-exported below so the runner's tests (and any consumer) keep one entry point per concern.
+import { classifyChangedPath, parseUnifiedDiff, unquoteDiffPath, computeChangedSurface, DIFF_FLAGS, parsePositiveIntKnob } from './changed-surface.mjs';
+
+export { classifyChangedPath, parseUnifiedDiff, unquoteDiffPath, computeChangedSurface };
 
 const ACTIVITY = 'plan-execution';
 const GIT_MAX_BUFFER = 256 * 1024 * 1024; // a full-tree diff / full-suite TAP can be large; never truncate
@@ -61,65 +75,6 @@ const childTestEnv = (env, extra = {}) => {
   return out;
 };
 
-// ── Decision 5: the CLOSED changed-path classification rule (no heuristics) ───────────────────────
-
-const TEST_FILE_RE = /\.(test|spec)\.[^./]+$/; // a.test.mjs, b.spec.js, c.test.cjs, d.spec.ts
-const ASSESSABLE_EXT = new Set(['.mjs', '.cjs', '.js']);
-const UNSUPPORTED_EXT = new Set(['.ts', '.tsx', '.jsx', '.mts', '.cts']);
-
-// classifyChangedPath(rel) → 'assessable' | 'unsupported' | 'out-of-domain' | 'excluded-test'.
-export const classifyChangedPath = (rel) => {
-  const base = rel.split('/').pop();
-  if (TEST_FILE_RE.test(base)) return 'excluded-test';
-  const dot = base.lastIndexOf('.');
-  const ext = dot >= 0 ? base.slice(dot) : '';
-  if (ASSESSABLE_EXT.has(ext)) return 'assessable';
-  if (UNSUPPORTED_EXT.has(ext)) return 'unsupported';
-  return 'out-of-domain';
-};
-
-// ── unified-diff → new-side changed line numbers (line numbers only; content lines are ignored) ───
-
-const DIFF_HUNK_RE = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/;
-
-// parseUnifiedDiff(diffText) → Map<rel, number[]>. Robust against a content line that happens to look
-// like a `+++ ` header: a `+++ ` line is a FILE header only in the header region (right after a
-// `diff --git`, before any `@@`); inside a hunk body it is ignored. New-side lines come purely from the
-// `@@` headers, so no content-line disambiguation is needed for the line numbers themselves.
-export const parseUnifiedDiff = (diffText) => {
-  const map = new Map();
-  let current = null;
-  let inHeader = false;
-  for (const line of String(diffText).split('\n')) {
-    if (line.startsWith('diff --git ')) {
-      current = null;
-      inHeader = true;
-      continue;
-    }
-    if (inHeader && line.startsWith('--- ')) continue;
-    if (inHeader && line.startsWith('+++ ')) {
-      const p = line.slice(4).trim();
-      current = p === '/dev/null' ? null : p.startsWith('b/') ? p.slice(2) : p;
-      inHeader = false;
-      continue;
-    }
-    const m = DIFF_HUNK_RE.exec(line);
-    if (m) {
-      inHeader = false;
-      if (current == null) continue;
-      const start = Number(m[1]);
-      const count = m[2] === undefined ? 1 : Number(m[2]);
-      if (count > 0) {
-        const arr = map.get(current) ?? [];
-        for (let i = 0; i < count; i += 1) arr.push(start + i);
-        map.set(current, arr);
-      }
-    }
-  }
-  for (const [k, v] of map) map.set(k, [...new Set(v)].sort((a, b) => a - b));
-  return map;
-};
-
 // ── Decision 6: V8 coverage → uncovered changed lines (innermost-range-wins) ──────────────────────
 
 // lineStartOffsets(sourceText) → char offset of each line start (index i == line i+1). Splitting on
@@ -210,8 +165,65 @@ export const parseProbeOutput = ({ stdout, code, fileArg }) => {
   return { resolvable, executed: matched, baselineGreen: resolvable && code === 0 && fails === 0 };
 };
 
-// defaultBoundArgv(file, pattern) → the shell-free node:test argv (testId content never reaches a shell).
-export const defaultBoundArgv = (file, pattern) => ['node', '--test', '--test-reporter', 'tap', '--test-name-pattern', pattern, file];
+// defaultBoundArgv(file, pattern) → the shell-free node:test argv (testId content never reaches a
+// shell). The pattern rides in the `=`-joined form: as a SEPARATE argv token a pattern beginning
+// with "-"/"--" (a test name like "--telemetry refuses …") parses as an OPTION and the probe
+// silently selects no test — the pattern-half sibling of the AD-047 dash-spawn file fix (found
+// live by this plan's own --red loop).
+export const defaultBoundArgv = (file, pattern) => ['node', '--test', '--test-reporter', 'tap', `--test-name-pattern=${pattern}`, file];
+
+// ── the shared safe test-file resolver (BUGFREE-1, codex R1+R2) ───────────────────────────────────
+// Custody hashing and every probe spawn go through THIS one resolver — the testId format itself is
+// deliberately suffix-free and format-only (review-ledger.mjs), so path safety lives here: the file
+// half must be repo-relative (absolute + parent-escaping refused), a REGULAR file under the no-follow
+// lstat discipline, and its RESOLVED real path must be contained under the REAL repo root — a leaf
+// check alone would let a symlinked PARENT directory escape the work tree.
+
+// resolveTestFile(rootTop, rel, deps?) → { ok: true, abs } | { ok: false, reason } (never throws).
+// deps.{lstat,realpath} are injectable so the defensive fs-race catch is unit-testable (the family
+// deps idiom — review-ledger-write.mjs).
+export const resolveTestFile = (rootTop, rel, deps = {}) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const realpath = deps.realpath ?? realpathSync;
+  if (typeof rel !== 'string' || rel.length === 0) return { ok: false, reason: 'empty file path' };
+  if (isAbsolute(rel)) return { ok: false, reason: `absolute path "${rel}" — the testId file half must be repo-relative` };
+  const norm = normalize(rel);
+  if (norm === '..' || norm.startsWith(`..${sep}`)) return { ok: false, reason: `path "${rel}" escapes the repo root` };
+  const abs = join(rootTop, norm);
+  let st;
+  try {
+    st = lstat(abs);
+  } catch {
+    return { ok: false, reason: `file "${rel}" does not exist` };
+  }
+  if (!st.isFile()) return { ok: false, reason: `"${rel}" is not a regular file (a symlink/directory/device is never followed — fail closed)` };
+  let realAbs;
+  let realRoot;
+  try {
+    realAbs = realpath(abs);
+    realRoot = realpath(rootTop);
+  } catch {
+    return { ok: false, reason: `cannot resolve the real path of "${rel}"` };
+  }
+  if (!containsPath(realRoot, realAbs)) return { ok: false, reason: `"${rel}" resolves outside the repo root (a symlinked parent directory) — fail closed` };
+  return { ok: true, abs: realAbs };
+};
+
+// containsPath(realRoot, realAbs) → realAbs is strictly INSIDE realRoot. Segment-safe ('/a' never
+// contains '/ab') and correct for a repo at the filesystem root, where realRoot already ends with
+// the separator ('/'+sep would be '//' and reject every valid path — agy R1).
+export const containsPath = (realRoot, realAbs) => realAbs.startsWith(realRoot.endsWith(sep) ? realRoot : realRoot + sep);
+
+// The D5 custody hash: sha-256 over the file's BYTES (no encoding normalization). null on a read
+// failure — the caller reads that as an unresolvable file (exported for the unit test of exactly
+// that fail-closed edge).
+export const hashFileBytes = (abs) => {
+  try {
+    return createHash('sha256').update(readFileSync(abs)).digest('hex');
+  } catch {
+    return null;
+  }
+};
 
 // resolveBoundArgv(env) → (file, pattern) => argv[]. Default = the node:test shape; AW_FOLD_BOUND_CMD
 // overrides with a JSON array of argv strings using {file}/{pattern} placeholders (the universality
@@ -232,7 +244,7 @@ export const resolveBoundArgv = (env = process.env) => {
   return (file, pattern) => tmpl.map((a) => a.replace(/\{file\}/g, () => file).replace(/\{pattern\}/g, () => pattern));
 };
 
-// ── the changed surface (git-driven) ──────────────────────────────────────────────────────────────
+// ── read-only git plumbing (the changed-surface computation itself lives in changed-surface.mjs) ──
 
 const runGit = (args, cwd) => spawnSync('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, encoding: 'utf8', windowsHide: true });
 const gitStdout = (args, cwd) => {
@@ -253,60 +265,72 @@ const canon = (path) => {
     return path;
   }
 };
-// A changed assessable LEAF is assessed only if it is a REGULAR file. lstat (no-follow): a symlinked
-// or non-regular *.mjs must NEVER be read/canonicalized — following it could read outside the work
-// tree or HANG on a FIFO/device (codex R2). A non-regular leaf fails closed (routed to `unsupported`).
-const isRegularLeaf = (abs) => {
-  try {
-    return lstatSync(abs).isFile();
-  } catch {
-    return false;
-  }
-};
+// ── the oracle-tamper surface (BUGFREE-1 Phase 2.2, Approach-3) ───────────────────────────────────
 
-// computeChangedSurface(root) → { assessable: Map<rel, number[]>, unsupported: [rel], outOfDomain: [rel] }.
-// Domain = the review-payload domain (tracked working-vs-HEAD changes + untracked-not-ignored files),
-// classified by the CLOSED rule. Tracked changed lines come from `git diff HEAD -U0`; an untracked file
-// is wholly new, so all its lines are "changed".
-export const computeChangedSurface = (root) => {
-  const trackedDiff = gitStdout(['diff', 'HEAD', '--unified=0', '--no-color', '--no-ext-diff', '--no-renames'], root)
-    ?? gitStdout(['diff', '--unified=0', '--no-color', '--no-ext-diff', '--no-renames'], root) // no HEAD yet (unborn branch)
-    ?? '';
-  const trackedLines = parseUnifiedDiff(trackedDiff);
-  const untrackedZ = gitStdout(['ls-files', '--others', '--exclude-standard', '-z'], root) ?? '';
-  const untracked = untrackedZ.split('\0').filter(Boolean);
-
-  const assessable = new Map();
-  const unsupported = [];
-  const outOfDomain = [];
-  const place = (rel, cls, lines) => {
-    if (cls === 'excluded-test') return;
-    if (cls === 'assessable') {
-      if (isRegularLeaf(join(root, rel))) assessable.set(rel, lines);
-      else unsupported.push(rel); // a symlinked / non-regular source → fail closed, never followed
-      return;
+const DIFF_HUNK_OLD_RE = /^@@ -\d+(?:,(\d+))? \+\d+(?:,\d+)? @@/;
+
+// parseDiffOldSide(diffText) → Map<oldRel, { removals: boolean }> — the OLD-side view of a -U0
+// tracked diff: which pre-existing (HEAD) files carry any removed/modified line (a hunk whose
+// old-count > 0). A file ADDED by the diff (--- /dev/null) has no old side and never appears; a
+// DELETED file's hunks remove every line, so it reads removals: true. Renames under --no-renames
+// read as delete+add — the delete side lands here (stated).
+export const parseDiffOldSide = (diffText) => {
+  const map = new Map();
+  let current = null;
+  let inHeader = false;
+  for (const line of String(diffText).split('\n')) {
+    if (line.startsWith('diff --git ')) {
+      current = null;
+      inHeader = true;
+      continue;
     }
-    if (cls === 'unsupported') unsupported.push(rel);
-    else outOfDomain.push(rel);
-  };
-  for (const [rel, lines] of trackedLines) place(rel, classifyChangedPath(rel), lines);
-  for (const rel of untracked) {
-    const cls = classifyChangedPath(rel);
-    if (cls !== 'assessable') {
-      place(rel, cls, []);
+    if (inHeader && line.startsWith('--- ')) {
+      // Strip ONLY the git-appended trailing TAB (space-carrying paths) and a CRLF \r — never a
+      // legitimate trailing character of the filename itself (agy R6; a raw TAB in a name is
+      // C-quoted anyway, so [\t\r]+$ can only match git artifacts).
+      const p = unquoteDiffPath(line.slice(4).replace(/[\t\r]+$/, ''));
+      current = p === '/dev/null' ? null : p.startsWith('a/') ? p.slice(2) : p;
+      if (current != null && !map.has(current)) map.set(current, { removals: false });
       continue;
     }
-    // Guard the leaf BEFORE reading — never follow a symlink to count an untracked file's lines.
-    const abs = join(root, rel);
-    if (!isRegularLeaf(abs)) {
-      unsupported.push(rel);
+    if (inHeader && line.startsWith('+++ ')) {
+      inHeader = false;
       continue;
     }
-    const src = readFileSafe(abs);
-    const count = src == null || src.length === 0 ? 0 : src.split('\n').length;
-    assessable.set(rel, Array.from({ length: count }, (_, i) => i + 1));
+    const m = DIFF_HUNK_OLD_RE.exec(line);
+    if (m) {
+      inHeader = false;
+      if (current == null) continue;
+      const oldCount = m[1] === undefined ? 1 : Number(m[1]);
+      if (oldCount > 0) map.get(current).removals = true;
+    }
+  }
+  return map;
+};
+
+// computeTamperedTests(root, boundFiles) → { tampered: [rel...] } — the tamper surface is the union
+// of test-classified paths (TEST_FILE_RE) and the loop's bound-testId file halves (the testId format
+// carries no suffix rule, so a bound test at a nonstandard path must not escape the guard),
+// restricted to files that exist at HEAD (having an old side in the tracked diff IS existing at
+// HEAD). Tampered = any removed/modified line; pure additions and new/untracked files never trip it
+// (widening to any-change-is-tamper would flag the standard append-a-new-test flow — the FP churn
+// this series exists to kill).
+export const computeTamperedTests = (root, boundFiles = new Set()) => {
+  const trackedDiff = gitStdout(['diff', 'HEAD', ...DIFF_FLAGS], root)
+    ?? gitStdout(['diff', ...DIFF_FLAGS], root) // no HEAD yet (unborn branch)
+    ?? '';
+  // The file halves are user-authored — './checks/x.mjs' probes and hashes as 'checks/x.mjs', so
+  // the surface compares NORMALIZED halves or a modified bound file escapes the guard (codex R5).
+  // Normalization happens in GIT/POSIX path space (codex+agy R6): node's OS-local normalize emits
+  // backslashes on Windows while git diff paths stay slash-separated — the compare must never
+  // depend on the host separator.
+  const boundSet = new Set([...boundFiles].map((f) => posix.normalize(f)));
+  const tampered = [];
+  for (const [rel, info] of parseDiffOldSide(trackedDiff)) {
+    if (!info.removals) continue;
+    if (classifyChangedPath(rel) === 'excluded-test' || boundSet.has(rel)) tampered.push(rel);
   }
-  return { assessable, unsupported: unsupported.sort(), outOfDomain: outOfDomain.sort() };
+  return { tampered: tampered.sort() };
 };
 
 // ── coverage (run the suite once under NODE_V8_COVERAGE, outside the tree) ─────────────────────────
@@ -382,12 +406,60 @@ const appendRecord = (resultsPath, record) => {
 
 // ── the run ───────────────────────────────────────────────────────────────────────────────────────
 
-const budgetsFromEnv = (env) => ({
+export const budgetsFromEnv = (env) => ({
   mutantsMax: Number.parseInt(env.AW_FOLD_MUTANTS_MAX ?? '200', 10) || 200,
   hunkMutantsMax: Number.parseInt(env.AW_FOLD_HUNK_MUTANTS_MAX ?? '25', 10) || 25,
   timeBudgetS: Number.parseInt(env.AW_FOLD_TIME_BUDGET_S ?? '600', 10) || 600,
+  // D4: N reruns per probe side; the per-RUN probe timeout (each of the N runs gets its own budget,
+  // never one shared series budget — agy R1). Probes only: the suite run keeps the no-timeout status
+  // quo. The fail-closed parser is the shared one (changed-surface.mjs), thrown as THIS tool's STOP.
+  foldReruns: parsePositiveIntKnob(env, 'AW_FOLD_RERUNS', 3, stop),
+  probeTimeoutS: parsePositiveIntKnob(env, 'AW_FOLD_PROBE_TIMEOUT_S', 120, stop),
 });
 
+// ── the shared N-rerun probe (D4) — ONE helper for both the run's green side and the --red verb ───
+
+// probeBound({ id, rootTop, env, boundArgv, reruns, timeoutS }) → { entry, resolveReason }. The entry
+// is the v2 per-testId record shape: rerun counts (evidence) + the custody content hash + the derived
+// booleans. The custody hash is taken BEFORE the runs (the content the observation attests). A
+// timed-out or signal-killed run is neither red nor green — it lands in `timeouts` (quarantine fuel).
+const probeBound = ({ id, rootTop, env, boundArgv, reruns, timeoutS }) => {
+  const { file, pattern } = splitTestId(id);
+  const resolved = resolveTestFile(rootTop, file);
+  const fileHash = resolved.ok ? hashFileBytes(resolved.abs) : null;
+  let executed = 0;
+  let greens = 0;
+  let reds = 0;
+  let timeouts = 0;
+  if (resolved.ok && fileHash != null) {
+    // ALWAYS spawn the resolver's canonical absolute path — the executed file must be the hashed
+    // file independent of runner path semantics (codex R1+R2, BUGFREE-1 live loop): a raw
+    // leading-dash filename parses as an OPTION (and a ./-prefix does not survive node's runner
+    // normalization), and a raw traversal path like linkdir/../x lets an OS-resolving runner
+    // execute a different filesystem target than the lexically-normalized file the hash covers.
+    const argv = boundArgv(resolved.abs, pattern);
+    for (let i = 0; i < reruns; i += 1) {
+      const res = spawnSync(argv[0], argv.slice(1), {
+        cwd: rootTop, env: childTestEnv(env), encoding: 'utf8', maxBuffer: GIT_MAX_BUFFER, timeout: timeoutS * 1000,
+      });
+      if ((res.error && res.error.code === 'ETIMEDOUT') || res.signal != null) {
+        timeouts += 1;
+        continue;
+      }
+      const p = parseProbeOutput({ stdout: res.stdout ?? '', code: res.error ? 1 : res.status ?? 1, fileArg: file });
+      executed = Math.max(executed, p.executed);
+      if (!p.resolvable) continue; // an unresolved run (the pattern selected nothing)
+      if (p.baselineGreen) greens += 1;
+      else reds += 1;
+    }
+  }
+  const entry = {
+    id, executed, runs: reruns, greens, reds, timeouts, fileHash,
+    resolvable: greens + reds === reruns, baselineGreen: greens === reruns,
+  };
+  return { entry, resolveReason: resolved.ok ? (fileHash == null ? `cannot read "${file}"` : null) : resolved.reason };
+};
+
 // runFoldCompleteness({ cwd, env, suiteCmd }) → { writtenPath, record }. THROWS a typed STOP (loop
 // derivation / suite discovery / a malformed record / an fs error) or a native fs error.
 export const runFoldCompleteness = ({ cwd = process.cwd(), env = process.env, suiteCmd } = {}) => {
@@ -430,28 +502,33 @@ export const runFoldCompleteness = ({ cwd = process.cwd(), env = process.env, su
     for (const n of computeUncoveredLines({ perProcessRanges: perProc, sourceText: src, changedLines: lines })) uncoveredChanged.push({ file: rel, line: n });
   }
 
-  // Decision 3 / 10: probe each fixable-bug bound testId once (shell-free).
+  // Decision 3 / 10 + D4: probe each of the SEGMENT's fixable-bug bound testIds N times
+  // (shell-free, per-run timeout). Segment scope (D7): a committed phase's folds are closed
+  // obligations — only triages recorded at the current base bind.
   const ledgerPath = resolveLedgerPath(cwd, env);
   const { records: reviewRecords } = ledgerPath ? readLedger(ledgerPath) : { records: [] };
-  const boundTestIds = collectBoundTestIds(reviewRecords, { activity: ACTIVITY, loop });
-  const testIds = boundTestIds.map((id) => {
-    const at = id.indexOf('#');
-    const file = id.slice(0, at);
-    const pattern = id.slice(at + 1);
-    const argv = boundArgv(file, pattern);
-    const res = spawnSync(argv[0], argv.slice(1), { cwd: rootTop, env: childTestEnv(env), encoding: 'utf8', maxBuffer: GIT_MAX_BUFFER });
-    return { id, ...parseProbeOutput({ stdout: res.stdout ?? '', code: res.error ? 1 : res.status ?? 1, fileArg: file }) };
-  });
+  const base = resolveBase(cwd);
+  const boundTestIds = collectBoundTestIds(reviewRecords, { activity: ACTIVITY, loop, base });
+  const testIds = boundTestIds.map(
+    (id) => probeBound({ id, rootTop, env, boundArgv, reruns: budgets.foldReruns, timeoutS: budgets.probeTimeoutS }).entry,
+  );
+
+  // Approach-3: the oracle-tamper pass over the tracked working-vs-HEAD diff, restricted to the
+  // test surface ∪ the bound-testId file halves. Recorded; the checker enforces overrides.
+  const tamper = computeTamperedTests(rootTop, new Set(boundTestIds.map((id) => splitTestId(id).file)));
 
   const record = {
     schema: RESULT_SCHEMA_VERSION,
+    kind: 'run',
     loop,
+    base,
     fingerprint,
     boundTestIds,
     testIds,
     unsupported,
     outOfDomain,
     coverage: { uncoveredChanged },
+    tamper,
     mutation: { total: 0, killed: 0, survived: [], skipped: 0, killSetBasis: null }, // reserved — mutation not shipped (shelved)
     budgets,
     timestamp: isoNow(),
@@ -464,28 +541,109 @@ export const runFoldCompleteness = ({ cwd = process.cwd(), env = process.env, su
   return appendRecord(resultsPath, record);
 };
 
+// ── the --red verb (D6): observe RED when it actually happens, mint the custody receipt ──────────
+
+// runRedProbe({ cwd, env, testId }) → { writtenPath, record }. Observes `testId` on the CURRENT
+// (pre-fold) tree: resolvable + failing on N/N runs → appends a red-probe receipt (testId, counts,
+// the test file's content hash, fingerprint, timestamp) to the fold results ledger. Observed green,
+// unresolvable, mixed, or timed out → a typed refusal DISTINGUISHED by name, and NOTHING is written
+// (D4: mixed/timeout is QUARANTINE — it never converts and has no override lane). No triage-order
+// requirement: the checker joins receipts to the bound set at gate time (D6).
+export const runRedProbe = ({ cwd = process.cwd(), env = process.env, testId } = {}) => {
+  if (!isWellFormedTestId(testId)) {
+    throw usageFail(`--red needs a well-formed testId "<test-file>#<test-name-pattern>" (a "#" separator, both halves non-empty; got ${JSON.stringify(testId)})`);
+  }
+  const root = gitStdout(['rev-parse', '--show-toplevel'], cwd);
+  if (root == null) throw stop('not a git work tree — nothing to observe');
+  const rootTop = root.replace(/\r?\n$/, '');
+  const plans = plansInFlight(rootTop);
+  if (plans.length === 0) throw stop('no plan in flight (docs/plans/ holds no active plan) — nothing to observe');
+  if (plans.length > 1) throw stop(`more than one plan in flight (${plans.join(', ')}) — ambiguous loop id; resolve to one active plan`);
+  const loop = plans[0].replace(/\.md$/, '');
+
+  const boundArgv = resolveBoundArgv(env);
+  const budgets = budgetsFromEnv(env);
+  const { entry, resolveReason } = probeBound({ id: testId, rootTop, env, boundArgv, reruns: budgets.foldReruns, timeoutS: budgets.probeTimeoutS });
+  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)`;
+  if (verdict === 'unresolvable') {
+    throw stop(
+      `--red refused for "${testId}": unresolvable — ${resolveReason ?? 'the pattern selects no test'} (${counts}). ` +
+        `If the test cannot even LOAD pre-fold (it imports an export the fix introduces), author it with a dynamic import() so it loads and FAILS pre-fold; ` +
+        `if the red is genuinely unestablishable, the loud escape is a recorded red-proof override (review-ledger-write override). Nothing was recorded.`,
+    );
+  }
+  if (verdict === 'green') {
+    throw stop(
+      `--red refused for "${testId}": observed GREEN on ${entry.greens}/${entry.runs} runs — the test does not fail on the current (pre-fold) tree, so it proves nothing about the fix. ` +
+        `Write a test that FAILS before the fix is applied, then re-run --red BEFORE folding the fix. Nothing was recorded.`,
+    );
+  }
+  if (verdict === 'quarantine') {
+    const flavor = entry.timeouts > 0
+      ? `${entry.timeouts} of ${entry.runs} probe run(s) timed out (AW_FOLD_PROBE_TIMEOUT_S=${budgets.probeTimeoutS}) — a timed-out run is neither red nor green`
+      : `mixed outcomes (${counts}) — a flaky test can launder a fake red`;
+    throw stop(
+      `--red refused for "${testId}": QUARANTINE — ${flavor}. QUARANTINE never converts and has no override lane: ` +
+        `${entry.timeouts > 0 ? 'raise the timeout or make the test faster' : 'replace the flaky test'}, then re-observe. Nothing was recorded.`,
+    );
+  }
+
+  const record = {
+    schema: RESULT_SCHEMA_VERSION,
+    kind: 'red-probe',
+    loop,
+    base: resolveBase(cwd), // the SEGMENT frame (D7): a receipt attests red within its segment
+    testId,
+    fileHash: entry.fileHash,
+    runs: entry.runs,
+    reds: entry.reds,
+    fingerprint: computeTreeFingerprint(cwd),
+    timestamp: isoNow(),
+  };
+  const v = validateRunRecord(record);
+  if (!v.ok) throw stop(`refusing to write a malformed red-probe record: ${v.reason}`);
+  const resultsPath = resolveResultsPath(cwd, env);
+  if (resultsPath == null) throw stop('cannot resolve the result-ledger path — not a git work tree and AW_FOLD_RESULTS is unset');
+  return appendRecord(resultsPath, record);
+};
+
 // ── CLI ───────────────────────────────────────────────────────────────────────────────────────────
 
-const HELP = `fold-completeness-run — the M3 fold-completeness RUNNER (agent-workflow family, AD-046).
+const HELP = `fold-completeness-run — the M3 fold-completeness RUNNER (agent-workflow family, AD-046 + AD-047).
 
 Usage:
   node fold-completeness-run.mjs [--suite "<cmd>"] [--cwd <dir>]
-
-Runs the in-flight plan-execution loop's suite ONCE under coverage, maps every changed executable line
-to covered/uncovered, probes each fixable-bug bound testId for resolvability + a green baseline, and
-appends one result record to <git dir>/${'agent-workflow-fold-completeness.jsonl'} (AW_FOLD_RESULTS
-overrides). The read-only gate is a SEPARATE tool: node fold-completeness.mjs --check / --status / --json.
+  node fold-completeness-run.mjs --red "<test-file>#<test-name-pattern>" [--cwd <dir>]
+
+The default run: runs the in-flight plan-execution loop's suite ONCE under coverage, maps every
+changed executable line to covered/uncovered, probes each of the SEGMENT's fixable-bug bound testIds
+N times (AW_FOLD_RERUNS, default 3) for resolvability + an N/N-green baseline, records each bound test
+file's content hash (custody), and appends one v3 run record — segment-framed (base = git rev-parse
+HEAD; the bound set is the current segment's, AD-048 D7) — to
+<git dir>/${'agent-workflow-fold-completeness.jsonl'} (AW_FOLD_RESULTS overrides).
+
+--red observes a testId RED on the CURRENT (pre-fold) tree — the honest fold-time order is: classify
+the fixable-bug with its testId → write the test → --red observes it FAIL (N/N) BEFORE the fix is
+applied → fold the fix → the normal run observes green → the gate checks receipt + order + custody.
+An N/N red mints a red-probe receipt (testId, counts, content hash, fingerprint, and base — the
+current SEGMENT frame: a receipt never crosses a commit boundary); observed-green /
+unresolvable / mixed / timed-out are DISTINGUISHED typed refusals and nothing is written
+(mixed/timeout = QUARANTINE — never converts, no override lane).
 
 Suite command: --suite "<cmd>" or AW_FOLD_SUITE_CMD, else the unit-tests gate cmd in docs/ai/gates.json.
-Bound-test runs default to node --test --test-name-pattern (shell-free); AW_FOLD_BOUND_CMD overrides
-with a JSON argv array using {file}/{pattern}. Budgets: AW_FOLD_MUTANTS_MAX / AW_FOLD_HUNK_MUTANTS_MAX /
-AW_FOLD_TIME_BUDGET_S (recorded but inert — the mutation half is not shipped).
+Bound-test probes default to node --test --test-name-pattern (shell-free); AW_FOLD_BOUND_CMD overrides
+with a JSON argv array using {file}/{pattern}. Probe knobs (fail-closed positive integers):
+AW_FOLD_RERUNS (default 3) · AW_FOLD_PROBE_TIMEOUT_S (default 120, per probe RUN, probes only).
+Inert budgets: AW_FOLD_MUTANTS_MAX / AW_FOLD_HUNK_MUTANTS_MAX / AW_FOLD_TIME_BUDGET_S (mutation shelved).
 
-Exit codes: 0 written; 1 a typed STOP (loop derivation / suite discovery / malformed record / fs error);
-2 usage.`;
+The read-only gate is a SEPARATE tool: node fold-completeness.mjs --check / --status / --json.
+
+Exit codes: 0 written; 1 a typed STOP (loop derivation / suite discovery / a --red refusal / malformed
+record / fs error); 2 usage.`;
 
 const parseArgs = (argv) => {
-  const opts = { cwd: undefined, suite: undefined };
+  const opts = { cwd: undefined, suite: undefined, red: undefined };
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === '--cwd') {
@@ -496,6 +654,10 @@ const parseArgs = (argv) => {
       opts.suite = argv[i + 1];
       if (opts.suite === undefined) throw usageFail('--suite needs a command');
       i += 1;
+    } else if (a === '--red') {
+      opts.red = argv[i + 1];
+      if (opts.red === undefined) throw usageFail('--red needs a testId ("<test-file>#<test-name-pattern>")');
+      i += 1;
     } else {
       throw usageFail(`unknown argument: ${a}`);
     }
@@ -509,7 +671,16 @@ export const main = (argv, ctx = {}) => {
   try {
     if (argv.includes('--help') || argv.includes('-h')) return { code: 0, stdout: HELP, stderr: '' };
     const opts = parseArgs(argv);
-    const { writtenPath, record } = runFoldCompleteness({ cwd: opts.cwd ?? cwd0, env, suiteCmd: opts.suite });
+    const cwd = opts.cwd ?? cwd0;
+    if (opts.red !== undefined) {
+      const { writtenPath, record } = runRedProbe({ cwd, env, testId: opts.red });
+      return {
+        code: 0,
+        stdout: `fold-completeness-run: minted a red-probe receipt for "${record.testId}" (loop "${record.loop}", ${record.reds}/${record.runs} observed red, hash ${record.fileHash.slice(0, 12)}…) → ${writtenPath}`,
+        stderr: '',
+      };
+    }
+    const { writtenPath, record } = runFoldCompleteness({ cwd, env, suiteCmd: opts.suite });
     const uncovered = record.coverage.uncoveredChanged.length;
     const unresolved = record.testIds.filter((t) => !t.resolvable || !t.baselineGreen).length;
     return {