forge-workflow 0.1.0-beta.4 → 0.1.0-beta.6

package/lib/pr-monitor/watch.js

@@ -15,29 +15,23 @@
  * and only pushed if the next tick did not recover/green it — the JOURNAL still
  * records everything (authority), so `events --since` replay stays complete.
  *
- * Every external effect is injectable (emit/sleep/rng/now/gather/watcherRunning/
- * writePid/removePid, plus `maxPasses`/`signal`) so tests exercise the loop with a
- * fake clock and fake gh, never touching live GitHub or waiting 60s.
+ * Every external effect is injectable (emit/sleep/rng/now/gather/owner authority,
+ * plus `maxPasses`/`signal`) so tests exercise the loop with a fake clock and fake
+ * provider, never touching live GitHub or waiting 60s.
  *
  * @module pr-monitor/watch
  */
 
 const { runMonitorPass } = require('./monitor');
 const journal = require('./journal');
+const watchOwner = require('./watch-owner');
 const { EVENT_TYPES: T } = require('./events');
 
 const DEFAULT_INTERVAL_MS = 60000;
+const DEFAULT_OWNER_HEARTBEAT_MS = 60000;
 const JITTER_RATIO = 0.2;
 const TERMINAL_TYPES = new Set([T.PR_MERGED, T.PR_CLOSED]);
 
-// In-process ownership of the watcher slot, keyed by journal dir. The journal
-// PID file serializes claims ACROSS processes, but it cannot make claims within
-// ONE process idempotent: after writePid, `watcherRunning(dir)` returns false
-// because the PID equals process.pid, so a second same-process watchLoop() would
-// also claim, run in parallel, and (on either exit) remove the shared PID while
-// the other is still active. This Set closes that gap for the loop lifetime.
-const ACTIVE_DIRS = new Set();
-
 /** Default push sink: one NDJSON line per event to stdout. */
 function defaultEmit(event) {
   process.stdout.write(`${JSON.stringify(event)}\n`);
@@ -78,30 +72,6 @@ function isAborted(signal) {
   return Boolean(signal && signal.aborted);
 }
 
-/**
- * Atomically claim the watcher slot for this PR. The `watcherRunning` check and
- * the `writePid` write run TOGETHER inside the cross-process journal lock (so two
- * starts in DIFFERENT processes can never both pass), AND the in-process
- * `ACTIVE_DIRS` guard rejects a SECOND concurrent `watchLoop()` in the SAME
- * process (which the PID file alone misses, since our own PID reads as "not
- * running"). Returns true only when the slot was newly claimed; the caller must
- * release with `releaseClaim(dir)` on loop exit. The (possibly injected)
- * `watcherRunning`/`writePid` primitives are honored, so test injection works.
- */
-function defaultClaim(dir, { watcherRunning, writePid, lockOpts }) {
-  return journal.withJournalLock(dir, () => {
-    if (ACTIVE_DIRS.has(dir) || watcherRunning(dir)) return false;
-    writePid(dir);
-    ACTIVE_DIRS.add(dir);
-    return true;
-  }, lockOpts);
-}
-
-/** Release the in-process watcher claim for `dir` (idempotent). */
-function releaseClaim(dir) {
-  ACTIVE_DIRS.delete(dir);
-}
-
 /**
  * Split a pass's events into: held-candidate failures (by check name), terminal
  * events (pr.merged/closed), and everything else (emitted immediately).
@@ -144,6 +114,20 @@ function confirmHeld(pending, contra, emit) {
   }
 }
 
+function emitTerminalPass(state, events, emit) {
+  const { failures, terminal, others } = partition(events);
+  const contra = contradictions(events);
+  const heldNames = new Set(state.pending.keys());
+  confirmHeld(state.pending, contra, emit);
+  state.pending = new Map();
+  for (const event of others) {
+    if (event.type === T.CHECK_RECOVERED && heldNames.has(checkName(event))) continue;
+    emit(event);
+  }
+  for (const failure of failures.values()) emit(failure);
+  for (const event of terminal) emit(event);
+}
+
 /**
  * Run ONE watch tick: a bounded monitor pass, then stream its events with the
  * 2-pass flap debounce applied. Mutates `state.pending` (the held failures).
@@ -151,10 +135,18 @@ function confirmHeld(pending, contra, emit) {
  * @returns {Promise<{ terminal: boolean }>} terminal=true → stop the loop.
  */
 async function runWatchPass(state, ctx, emit) {
-  const { events } = await runMonitorPass({
-    dir: ctx.dir, gather: ctx.gather, now: ctx.now, enrich: ctx.enrich, lockOpts: ctx.lockOpts,
+  const monitorPass = ctx.runMonitorPass || runMonitorPass;
+  const { events: rawEvents, terminalReceiptId, journalCursor } = await monitorPass({
+    ...ctx, dir: ctx.dir, gather: ctx.gather, now: ctx.now, enrich: ctx.enrich, lockOpts: ctx.lockOpts,
   });
+  const events = ctx.dir && Number.isSafeInteger(journalCursor)
+    ? journal.readEventsSince(ctx.dir, journalCursor)
+    : rawEvents;
   const { failures, terminal, others } = partition(events);
+  if (terminalReceiptId) {
+    emitTerminalPass(state, events, emit);
+    return { terminal: true, terminalReceiptId };
+  }
   const contra = contradictions(events);
   const heldNames = new Set(state.pending.keys());
 
@@ -168,7 +160,7 @@ async function runWatchPass(state, ctx, emit) {
   if (terminal.length) {
     for (const failure of failures.values()) emit(failure);
     for (const t of terminal) emit(t);
-    return { terminal: true };
+    return { terminal: false, receiptUnavailable: true };
   }
   state.pending = failures;
   return { terminal: false };
@@ -192,51 +184,130 @@ async function runWatchPass(state, ctx, emit) {
  * @returns {Promise<{ started: boolean, passes: number, stopped: boolean, reason?: string }>}
  */
 async function watchLoop(ctx) {
-  const { dir } = ctx;
   const emit = ctx.emit || defaultEmit;
   const sleep = ctx.sleep || defaultSleep;
   const rng = ctx.rng || Math.random;
   const intervalMs = ctx.intervalMs ?? DEFAULT_INTERVAL_MS;
+  const ownerHeartbeatMs = ctx.ownerHeartbeatMs ?? DEFAULT_OWNER_HEARTBEAT_MS;
   const maxPasses = ctx.maxPasses ?? Infinity;
-  const watcherRunning = ctx.watcherRunning || journal.watcherRunning;
-  const writePid = ctx.writePid || journal.writePid;
-  const removePid = ctx.removePid || journal.removePid;
-  const claim = ctx.claim || (() => defaultClaim(dir, { watcherRunning, writePid, lockOpts: ctx.lockOpts }));
-
-  // Atomic idempotent claim: a live OTHER watcher already owns this PR → no-op.
-  // The check+write are serialized under the journal lock so concurrent starts
-  // cannot both succeed (see defaultClaim).
-  const claimed = await claim(dir);
-  if (!claimed) {
-    return { started: false, passes: 0, stopped: false, reason: 'watcher-already-running' };
+  const owner = ctx.owner || watchOwner;
+  const ownerOptions = ctx.ownerOptions || {};
+  const identity = { repo: String(ctx.repo || '').toLowerCase(), pr: Number(ctx.pr) };
+  const generation = ctx.generation;
+  const controllerPid = Number(ctx.controllerPid);
+  const pid = Number(ctx.pid ?? process.pid);
+
+  // Exact generation binding makes a duplicate or stale child a clean no-op.
+  if (!Number.isSafeInteger(identity.pr) || identity.pr <= 0 || !identity.repo
+    || !generation || !Number.isSafeInteger(controllerPid) || controllerPid <= 0
+    || !Number.isSafeInteger(pid) || pid <= 0 || typeof owner.bindRunning !== 'function') {
+    return { started: false, passes: 0, stopped: false, reason: 'authority-unavailable' };
+  }
+  const bound = await owner.bindRunning(identity, { generation, controllerPid, pid }, ownerOptions);
+  if (!bound?.ok) {
+    return { started: false, passes: 0, stopped: false, reason: bound?.reason || 'bind-failed' };
   }
 
   const state = { pending: new Map() };
   let passes = 0;
   let stopped = false;
+  let terminalPending = false;
+  let reason;
+  let heartbeatFailure;
+  let heartbeatInFlight = null;
+  const checkpointOwner = () => {
+    if (heartbeatInFlight) return heartbeatInFlight;
+    heartbeatInFlight = (async () => {
+      try {
+        const checkpoint = await owner.heartbeat(identity, { generation, pid }, ownerOptions);
+        if (!checkpoint?.ok) heartbeatFailure = checkpoint?.reason || 'owner-lost';
+      } catch {
+        heartbeatFailure = 'owner-lost';
+      } finally {
+        heartbeatInFlight = null;
+      }
+    })();
+    return heartbeatInFlight;
+  };
+  const scheduleHeartbeat = ctx.setInterval || setInterval;
+  const cancelHeartbeat = ctx.clearInterval || clearInterval;
+  const heartbeatTimer = scheduleHeartbeat(() => { void checkpointOwner(); }, ownerHeartbeatMs);
+  heartbeatTimer?.unref?.();
   try {
     while (passes < maxPasses && !isAborted(ctx.signal)) {
+      if (heartbeatFailure) {
+        reason = heartbeatFailure;
+        break;
+      }
+      const current = await owner.readOwner(identity, ownerOptions);
+      if (!current?.ok || current.record?.generation !== generation || current.record?.watcherPid !== pid) {
+        reason = current?.reason || 'owner-lost';
+        break;
+      }
+      if (current.record.phase === 'stop_requested') {
+        stopped = true;
+        reason = 'stop-requested';
+        break;
+      }
+      if (current.record.phase === 'terminal_pending') {
+        stopped = true;
+        terminalPending = true;
+        reason = 'terminal-pending';
+        break;
+      }
+      if (current.record.phase !== 'running') {
+        reason = 'owner-not-running';
+        break;
+      }
       const result = await runWatchPass(state, ctx, emit);
       passes += 1;
-      if (result.terminal) { stopped = true; break; }
+      if (result.terminal) {
+        // Keep the exact running row for dead-owner receipt recovery if this write fails.
+        terminalPending = true;
+        const recorded = await owner.recordTerminal(identity, {
+          generation, pid, terminalReceiptId: result.terminalReceiptId,
+        }, ownerOptions);
+        if (recorded?.ok) {
+          stopped = true;
+          terminalPending = true;
+          reason = 'terminal-pending';
+          break;
+        }
+        reason = recorded?.reason || 'receipt-unavailable';
+      }
+      await checkpointOwner();
+      if (heartbeatFailure) {
+        reason = heartbeatFailure;
+        break;
+      }
       if (passes >= maxPasses || isAborted(ctx.signal)) break;
       await sleep(jitter(intervalMs, rng), ctx.signal);
     }
   } finally {
-    // Release BOTH claims: the in-process slot (for a same-process restart) and
-    // the cross-process PID file. Ordered so the in-process guard clears first.
-    releaseClaim(dir);
-    removePid(dir);
+    cancelHeartbeat(heartbeatTimer);
+    await heartbeatInFlight;
+    // Terminal ownership remains until a later dead-PID completion transaction;
+    // every other process exit releases its exact generation cooperatively.
+    if (!terminalPending) {
+      try {
+        const stopRequested = typeof owner.requestStop === 'function'
+          ? await owner.requestStop(identity, { generation, pid }, ownerOptions)
+          : { ok: true };
+        if (stopRequested?.ok) {
+          await owner.releaseNonterminal(identity, { generation, pid }, ownerOptions);
+        }
+      } catch {
+        // Preserve the owner row for a later dead-watcher recovery transaction.
+      }
+    }
   }
-  return { started: true, passes, stopped };
+  return { started: true, passes, stopped, ...(reason ? { reason } : {}) };
 }
 
 module.exports = {
   watchLoop,
   runWatchPass,
   defaultSleep,
-  defaultClaim,
-  releaseClaim,
   jitter,
   partition,
   contradictions,

package/lib/pr-pull.js

@@ -43,6 +43,11 @@ const LOG_FETCH_MULTIPLIER = 3;
 // re-review or a late reviewer comment inside the window means the PR is still
 // in flight. Mirrors the merge-rules `settle_min` idea (default 10 minutes).
 const DEFAULT_SETTLE_WINDOW_MS = 600000;
+const FULL_HEAD_SHA = /^[0-9a-f]{40}$/i;
+
+function normalizeHeadSha(value) {
+  return typeof value === 'string' && FULL_HEAD_SHA.test(value) ? value.toLowerCase() : null;
+}
 
 /**
  * Bot logins whose review threads ARE actionable fixes (their comments tell you
@@ -320,7 +325,7 @@ function isSkipped(check) {
 /** A check still in flight (not green, not failed) — e.g. IN_PROGRESS/QUEUED or
  * a status context with no conclusion yet. */
 function isPending(check) {
-  return !isGreen(check) && !isFailed(check);
+  return !isSkipped(check) && !isGreen(check) && !isFailed(check);
 }
 
 /**
@@ -865,12 +870,14 @@ function buildVerdictContext(input) {
 /** Rank 1: UNKNOWN (fail-closed) — unreadable input/required set, missing head
  * oid, or a torn read (head moved during the gather). */
 function rankUnknown(v) {
-  const torn = Boolean(v.headOidStart) && Boolean(v.headOidEnd) && v.headOidStart !== v.headOidEnd;
+  const startValid = normalizeHeadSha(v.headOidStart) !== null;
+  const endValid = normalizeHeadSha(v.headOidEnd) !== null;
+  const torn = startValid && endValid && v.headOidStart !== v.headOidEnd;
   v.evidence.tornRead = torn;
   if (v.requiredClass.unreadable && !v.evidence.unreadable.includes('requiredChecks')) {
     v.evidence.unreadable.push('requiredChecks');
   }
-  if (!v.headOidStart && !v.evidence.unreadable.includes('headOid')) {
+  if ((!startValid || !endValid) && !v.evidence.unreadable.includes('headOid')) {
     v.evidence.unreadable.push('headOid');
   }
   return (v.evidence.unreadable.length > 0 || torn) ? 'UNKNOWN' : null;
@@ -1139,10 +1146,13 @@ async function gatherPrSnapshot(ctx) {
 
   // readState is the one REQUIRED read — if it throws, the whole gather fails.
   const state = await adapter.readState(pr);
+  const headOidStart = normalizeHeadSha(state.headSha);
+  if (!headOidStart) unreadable.push('headOid');
+  if (state.providerEvidenceReadable === false) unreadable.push('providerEvidence');
+
   const requiredSet = await safeRead(
     'requiredChecks',
-    // `pr` lets the adapter fall back to the rollup `isRequired` set when branch
-    // protection is unreadable (the Actions token can't read protection).
+    // `pr` is included for diagnostic rollup evidence when protection is unreadable.
     () => adapter.readRequiredChecks({ owner, repo, base, pr }),
     { degraded, fallback: null },
   );
@@ -1169,16 +1179,26 @@ async function gatherPrSnapshot(ctx) {
   // Branch divergence (behind base → needs an update/rebase).
   const div = await safeRead(
     'divergence',
-    () => callIfPresent(adapter, 'readDivergence', { baseRef: ctx.baseRef, cwd }, { behind: 0 }),
-    { degraded, fallback: { behind: 0 } },
+    () => callIfPresent(
+      adapter,
+      'readDivergence',
+      { baseRef: ctx.baseRef, cwd, headRef: state.headSha },
+      { behind: 0 },
+    ),
+    { degraded, unreadable, fallback: { behind: 0 } },
   );
   const behind = div.behind || 0;
 
   // Predicted merge conflicts (which files) — optional adapter capability.
   const conflicts = await safeRead(
     'conflicts',
-    () => callIfPresent(adapter, 'detectConflicts', { baseRef: ctx.baseRef, cwd }, null),
-    { degraded, fallback: null },
+    () => callIfPresent(
+      adapter,
+      'detectConflicts',
+      { baseRef: ctx.baseRef, cwd, headRef: state.headSha },
+      null,
+    ),
+    { degraded, unreadable, fallback: null },
   );
 
   // Bot STATUS COMMENTS (Sonar/Vercel/Netlify/Codecov quality-gate + deployment
@@ -1214,7 +1234,8 @@ async function gatherPrSnapshot(ctx) {
   const headPushKnown = headPushTimeMs != null;
   // Torn-read guard: re-read the head oid at the END of the gather.
   const endState = await safeRead('headEnd', () => adapter.readState(pr), { degraded, unreadable });
-  const headOidEnd = endState ? endState.headSha : state.headSha;
+  const headOidEnd = normalizeHeadSha(endState && endState.headSha);
+  if (!headOidEnd && !unreadable.includes('headOid')) unreadable.push('headOid');
 
   // Actionable NON-HUMAN direct comments (mechanism-detected, suppression-list
   // filtered) and an AUTHOR-AGNOSTIC unresolved-thread count — both independent
@@ -1224,7 +1245,7 @@ async function gatherPrSnapshot(ctx) {
   const unresolvedThreadCount = countUnresolvedThreads(threads);
 
   const { verdict, evidence } = computeVerdict({
-    headOidStart: state.headSha,
+    headOidStart,
     headOidEnd,
     mergeStateStatus: state.mergeStateStatus,
     mergeable: state.mergeable,
@@ -1245,9 +1266,7 @@ async function gatherPrSnapshot(ctx) {
     unreadable,
   });
 
-  // Record which source answered the required-checks read (`protection` |
-  // `rollup` | null) so the source is visible in the verdict evidence — the
-  // rollup source is the CI path where branch protection is unreadable.
+  // Record the authoritative required-check source (`protection` or null).
   evidence.requiredSource = adapter.lastRequiredSource || null;
 
   return {

package/lib/pr-shepherd.js

@@ -32,6 +32,7 @@ const { fenceUntrusted } = require('./untrusted-content');
 
 /** Non-erroring terminal states a pass can settle into. */
 const TERMINAL_STATES = ['MERGE_READY', 'ESCALATE', 'PENDING', 'MERGED', 'CLOSED', 'NEEDS_REVIEW'];
+const MERGE_READY_PROVIDER_STATES = new Set(['CLEAN', 'HAS_HOOKS', 'UNSTABLE']);
 
 // Review threads are classified BY MECHANISM, not by a bot-name list: a GitHub
 // review THREAD is opened by a reviewer (a human OR any bot) and stays open until
@@ -72,9 +73,11 @@ function actionableComments(threads, _self) {
   );
 }
 
-const SUCCESS_CONCLUSIONS = new Set(['SUCCESS', 'NEUTRAL', 'SKIPPED']);
+const SUCCESS_CONCLUSIONS = new Set(['SUCCESS']);
 
 function isGreen(check) {
+  if (!Object.prototype.hasOwnProperty.call(check || {}, 'status')
+    || String(check.status || '').toUpperCase() !== 'COMPLETED') return false;
   const c = String(check.conclusion || '').toUpperCase();
   return SUCCESS_CONCLUSIONS.has(c);
 }
@@ -208,7 +211,7 @@ async function handleFailedRequired({
  * @returns {Promise<object>} decision envelope.
  */
 async function handleBehindBase({
-  behind, autoRebase, cleanTree, adapter, baseRef, headUnchanged, actions,
+  behind, autoRebase, cleanTree, adapter, baseRef, expectedHead, headUnchanged, actions,
 }) {
   if (!autoRebase) {
     return result('ESCALATE', {
@@ -237,10 +240,22 @@ async function handleBehindBase({
     });
   }
   try {
-    await adapter.rebaseOntoBase({ baseRef });
+    const rebaseResult = await adapter.rebaseOntoBase({ baseRef, expectedHead });
+    const verifiedHead = rebaseResult?.previousHead === expectedHead
+      && typeof rebaseResult?.headSha === 'string'
+      && /^[0-9a-f]{40}$/i.test(rebaseResult.headSha)
+      ? rebaseResult.headSha.toLowerCase()
+      : null;
+    if (!verifiedHead) {
+      return result('ESCALATE', {
+        actions,
+        reason: 'Rebase completed without a lease-bound post-action head; refusing convergence handoff.',
+      });
+    }
     actions.push({ type: 'rebase', baseRef });
     return result('PENDING', {
       actions,
+      expectedHead: verifiedHead,
       reason: 'Rebased onto base and force-pushed with lease. Awaiting CI on the next scheduled pass.',
     });
   } catch (error) {
@@ -388,13 +403,18 @@ async function runShepherdPass(ctx) {
 
   // Every read goes through the auth guard so 401/403-scope/rate-limit map to
   // the documented PENDING/HARD_STOP states instead of escaping as a generic
-  // failure. Non-auth errors still propagate.
+  // failure. Other read errors are surfaced below as ESCALATE results.
 
   // --- Read PR/CI state FIRST so a merged/closed PR is detected as terminal
   // even when the branch-protection (required-checks) read would fail with an
   // auth/scope error — the scheduler must always get the terminal signal for a
   // landed/closed PR. ---
-  const stateRead = await guardAuth(() => adapter.readState(pr), actions);
+  let stateRead;
+  try {
+    stateRead = await guardAuth(() => adapter.readState(pr), actions);
+  } catch (err) {
+    return result('ESCALATE', { actions, reason: `PR provider state is unreadable: ${err.message}` });
+  }
   if (stateRead.outcome) return stateRead.outcome;
   const startState = stateRead.value;
   const startSha = startState.headSha;
@@ -402,13 +422,24 @@ async function runShepherdPass(ctx) {
   // --- Lifecycle: a merged/closed PR is terminal. ---
   const lifecycle = lifecycleOutcome(startState.state, actions);
   if (lifecycle) return lifecycle;
+  if (startState.providerEvidenceReadable === false) {
+    return result('ESCALATE', {
+      actions,
+      reason: 'PR lifecycle, draft, head, or check-rollup evidence is malformed or incomplete.',
+    });
+  }
 
   // --- Required-checks set (only matters for non-terminal PRs); this is where
   // auth/scope fails fast. ---
-  const requiredRead = await guardAuth(
-    () => adapter.readRequiredChecks({ owner, repo, base }),
-    actions,
-  );
+  let requiredRead;
+  try {
+    requiredRead = await guardAuth(
+      () => adapter.readRequiredChecks({ owner, repo, base }),
+      actions,
+    );
+  } catch (err) {
+    return result('ESCALATE', { actions, reason: `Required-check policy is unreadable: ${err.message}` });
+  }
   if (requiredRead.outcome) return requiredRead.outcome;
   const required = requiredRead.value;
 
@@ -422,7 +453,7 @@ async function runShepherdPass(ctx) {
   }
 
   const divergenceRead = await guardAuth(
-    () => adapter.readDivergence({ baseRef, cwd }),
+    () => adapter.readDivergence({ baseRef, cwd, headRef: startSha }),
     actions,
   );
   if (divergenceRead.outcome) return divergenceRead.outcome;
@@ -459,7 +490,8 @@ async function runShepherdPass(ctx) {
   // never rebase — force autoRebase off so the branch-behind path only escalates. ---
   if (behind > 0) {
     return handleBehindBase({
-      behind, autoRebase: dryRun ? false : autoRebase, cleanTree, adapter, baseRef, headUnchanged, actions,
+      behind, autoRebase: dryRun ? false : autoRebase, cleanTree, adapter, baseRef,
+      expectedHead: startSha, headUnchanged, actions,
     });
   }
 
@@ -472,8 +504,16 @@ async function runShepherdPass(ctx) {
 
   // --- Terminal: all required green + not behind → merge-ready handoff. ---
   if (allRequiredGreen) {
+    const providerMergeState = String(startState.mergeStateStatus || '').toUpperCase();
+    if (!MERGE_READY_PROVIDER_STATES.has(providerMergeState)) {
+      return result('ESCALATE', {
+        actions,
+        reason: `Provider merge state ${providerMergeState || 'UNKNOWN'} does not authorize merge readiness.`,
+      });
+    }
     return result('MERGE_READY', {
       actions,
+      expectedHead: startSha,
       reason: 'All required checks are green and the branch is up to date. Handing off to the human to merge in the GitHub UI — the shepherd never merges.',
     });
   }

package/lib/preflight/gates.js

@@ -17,10 +17,11 @@
  */
 
 const path = require('node:path');
+const crypto = require('node:crypto');
 const { spawnSync } = require('node:child_process');
-const { execFileSync } = require('node:child_process');
 const nodeFs = require('node:fs');
-const { getAffectedTestFiles } = require('../commands/test');
+const { getTestCandidatesForChangedFile } = require('../commands/test');
+const { selectDocAssertingTests } = require('../doc-assertions');
 
 const IS_WINDOWS = process.platform === 'win32';
 
@@ -37,6 +38,36 @@ function statusSummary(result, okMsg, failMsg) {
     : { ok: false, summary: failMsg };
 }
 
+function compareStringsByCodePoint(left, right) {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+
+function normalizeChangedFiles(files) {
+  if (!Array.isArray(files)) return Object.freeze([]);
+  return Object.freeze([...new Set(
+    files.map((file) => String(file).replaceAll('\\', '/')).filter((file) => file !== ''),
+  )].sort(compareStringsByCodePoint));
+}
+
+function fingerprintChangedFiles(files) {
+  return crypto.createHash('sha256').update(JSON.stringify(files)).digest('hex');
+}
+
+function selectAffectedTests(projectRoot, changedFiles, fs = nodeFs) {
+  const tests = new Set();
+  for (const file of changedFiles) {
+    for (const candidate of getTestCandidatesForChangedFile(file)) {
+      if (fs.existsSync(path.join(projectRoot, candidate))) tests.add(candidate);
+    }
+  }
+  for (const candidate of selectDocAssertingTests(changedFiles, projectRoot, fs)) {
+    tests.add(candidate);
+  }
+  return [...tests].sort(compareStringsByCodePoint);
+}
+
 /**
  * Gate 1 — ESLint on the change blast radius (or the whole tree with --all).
  * `files === null` means "lint everything" (`eslint .`).
@@ -152,38 +183,50 @@ function runSonar(files, { projectRoot, spawn = spawnSync } = {}) {
  */
 function runAffectedTests({
   projectRoot,
-  changedFiles: _changedFiles,
+  changedFiles,
   spawn = spawnSync,
   resolveTests,
 } = {}) {
+  const inputs = Array.isArray(changedFiles) && Object.isFrozen(changedFiles)
+    ? changedFiles
+    : normalizeChangedFiles(changedFiles);
+  const inputFingerprint = fingerprintChangedFiles(inputs);
   const resolver = typeof resolveTests === 'function'
     ? resolveTests
-    // strict:true so a failed `git diff` THROWS here instead of returning [] —
-    // otherwise a git error would masquerade as "no affected tests" (fast-lane
-    // green), a fail-OPEN. The catch below turns that throw into a closed gate.
-    : () => getAffectedTestFiles(projectRoot, execFileSync, nodeFs, { strict: true });
+    : (files) => selectAffectedTests(projectRoot, files);
   let targets;
   try {
-    targets = resolver() || [];
+    targets = resolver(inputs) || [];
   } catch (err) {
     // A resolver ERROR must NOT masquerade as "no affected tests" (green).
     // We could not determine what to run, so fail closed — never a vacuous pass.
     const reason = err && err.message ? err.message : String(err);
-    return { ok: false, summary: `affected-test resolution failed — fail-closed (${reason})` };
+    return {
+      ok: false,
+      summary: `affected-test resolution failed — fail-closed (${reason})`,
+      inputFingerprint,
+    };
   }
   if (targets.length === 0) {
-    return { ok: true, summary: 'no affected tests resolved (fast lane)' };
+    return {
+      ok: true,
+      summary: 'no affected tests resolved (fast lane)',
+      inputFingerprint,
+    };
   }
   const result = spawn(
     'bun',
     ['test', '--timeout', '15000', ...targets],
     { cwd: projectRoot, stdio: 'inherit', shell: IS_WINDOWS },
   );
-  return statusSummary(
-    result,
-    `${targets.length} affected test file(s) passed`,
-    'affected tests failed',
-  );
+  return {
+    ...statusSummary(
+      result,
+      `${targets.length} affected test file(s) passed`,
+      'affected tests failed',
+    ),
+    inputFingerprint,
+  };
 }
 
 /**
@@ -198,15 +241,18 @@ function runAffectedTests({
  * @returns {{ name: string, run: () => Promise<{ok:boolean, summary?:string}> }[]}
  */
 function buildGates({ projectRoot, changedFiles = [], runAll = false, deps = {} }) {
+  const normalizedChangedFiles = normalizeChangedFiles(changedFiles);
+  const inputFingerprint = fingerprintChangedFiles(normalizedChangedFiles);
   const eslint = deps.eslint || ((files) => runEslint(files, { projectRoot }));
   const structural = deps.structural || (() => runStructural({ projectRoot }));
   const sonar = deps.sonar || ((files) => runSonar(files, { projectRoot }));
-  const affected = deps.affected || (() => runAffectedTests({ projectRoot, changedFiles }));
+  const affected = deps.affected
+    || ((files) => runAffectedTests({ projectRoot, changedFiles: files }));
 
   // Under --all, scope BOTH lint and sonar to the whole tree (null). Otherwise
   // sonar would receive changedFiles=[] and report a vacuous "no changed files"
   // pass while lint scanned everything — a fail-open hole on the remedy path.
-  const scanTargets = runAll ? null : changedFiles;
+  const scanTargets = runAll ? null : normalizedChangedFiles;
 
   // Affected-tests maps from the change set, which is empty under --all. Running
   // the WHOLE suite here defeats preflight's fast purpose (and hangs on Windows),
@@ -216,8 +262,9 @@ function buildGates({ projectRoot, changedFiles = [], runAll = false, deps = {}
       ok: true,
       skipped: true,
       summary: 'whole-tree mode (--all): affected-test mapping N/A — run the full suite (CI does)',
+      inputFingerprint,
     })
-    : async () => affected();
+    : async () => affected(normalizedChangedFiles);
 
   return [
     { name: 'lint', run: async () => eslint(scanTargets) },