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

package/scripts/protected-state-check.js

@@ -1,10 +1,20 @@
 #!/usr/bin/env node
 
 const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
 const {
 	assertProtectedWriteAllowed,
 	recordProtectedStateAuditEvent,
 } = require('../lib/protected-state-surfaces');
+const {
+	authorizeAndConsumeProtectedStateWrites,
+	isValidGitObjectId,
+} = require('../lib/protected-state-authority');
+const { verifyBunLockfileRegeneration } = require('../lib/bun-lockfile-proof');
+const { resolveBaseRemote, resolveBaseBranch } = require('../lib/base-remote');
+const realStagedFiles = new Set();
+const deletedFiles = new Set();
 
 function parseNameStatus(output) {
 	const files = [];
@@ -14,8 +24,10 @@ function parseNameStatus(output) {
 		const parts = trimmed.split('\t').filter(Boolean);
 		const status = parts[0] || '';
 		if (/^[RC]/.test(status)) {
+			if (parts[1]) deletedFiles.add(parts[1]);
 			files.push(...parts.slice(1, 3));
 		} else {
+			if (status.startsWith('D') && parts[1]) deletedFiles.add(parts[1]);
 			files.push(parts[1]);
 		}
 	}
@@ -23,55 +35,484 @@ function parseNameStatus(output) {
 }
 
 function getStagedFiles() {
+	let stagedFiles;
 	if (process.env.FORGE_PROTECTED_STATE_STAGED_NAME_STATUS !== undefined) {
-		return parseNameStatus(process.env.FORGE_PROTECTED_STATE_STAGED_NAME_STATUS);
-	}
-
-	if (process.env.FORGE_PROTECTED_STATE_STAGED_FILES !== undefined) {
-		return process.env.FORGE_PROTECTED_STATE_STAGED_FILES
+		stagedFiles = parseNameStatus(process.env.FORGE_PROTECTED_STATE_STAGED_NAME_STATUS);
+	} else if (process.env.FORGE_PROTECTED_STATE_STAGED_FILES !== undefined) {
+		stagedFiles = process.env.FORGE_PROTECTED_STATE_STAGED_FILES
 			.split(/\r?\n/)
 			.map(line => line.trim())
 			.filter(Boolean);
+	} else {
+		const output = execFileSync('git', ['diff', '--cached', '--name-status', '--diff-filter=ACMRDT'], {
+			encoding: 'utf8',
+			stdio: ['ignore', 'pipe', 'pipe'],
+		});
+		stagedFiles = parseNameStatus(output);
+		for (const file of stagedFiles) realStagedFiles.add(file);
+	}
+
+	if (process.env.FORGE_PROTECTED_STATE_STAGED_NAME_STATUS !== undefined || process.env.FORGE_PROTECTED_STATE_STAGED_FILES !== undefined) {
+		try {
+			execFileSync('git', ['rev-parse', '--is-inside-work-tree'], {
+				encoding: 'utf8',
+				stdio: ['ignore', 'pipe', 'pipe'],
+			});
+		} catch (_error) {
+			return [...new Set(stagedFiles)];
+		}
+		const realOutput = execFileSync('git', ['diff', '--cached', '--name-status', '--diff-filter=ACMRDT'], {
+			encoding: 'utf8',
+			stdio: ['ignore', 'pipe', 'pipe'],
+		});
+		const indexedFiles = parseNameStatus(realOutput);
+		for (const file of indexedFiles) realStagedFiles.add(file);
+		stagedFiles.push(...indexedFiles);
+	}
+	return [...new Set(stagedFiles)];
+}
+
+function getStagedContent(file) {
+	if (!realStagedFiles.has(file) && process.env.FORGE_PROTECTED_STATE_STAGED_CONTENTS_JSON) {
+		const contents = JSON.parse(process.env.FORGE_PROTECTED_STATE_STAGED_CONTENTS_JSON);
+		return Object.prototype.hasOwnProperty.call(contents, file) ? contents[file] : null;
+	}
+
+	try {
+		return execFileSync('git', ['show', `:${file}`], {
+			encoding: null,
+			stdio: ['ignore', 'pipe', 'pipe'],
+		});
+	} catch (_error) {
+		if (!deletedFiles.has(file)) return null;
+		try {
+			return execFileSync('git', ['show', `HEAD:${file}`], {
+				encoding: null,
+				stdio: ['ignore', 'pipe', 'pipe'],
+			});
+		} catch {
+			return null;
+		}
+	}
+}
+
+
+function getCurrentHead(execGit = execFileSync) {
+	let output;
+	try {
+		output = execGit('git', ['rev-parse', '--verify', 'HEAD^{commit}'], {
+			encoding: 'utf8',
+			stdio: ['ignore', 'pipe', 'pipe'],
+		});
+	} catch (headError) {
+		let symbolicRef;
+		try {
+			symbolicRef = execGit('git', ['symbolic-ref', '-q', 'HEAD'], {
+				encoding: 'utf8',
+				stdio: ['ignore', 'pipe', 'pipe'],
+			}).trim();
+		} catch {
+			throw headError;
+		}
+		if (!/^refs\/heads\/[^\0\r\n]+$/.test(symbolicRef)) throw headError;
+		try {
+			execGit('git', ['show-ref', '--verify', '--quiet', symbolicRef], {
+				encoding: 'utf8',
+				stdio: ['ignore', 'pipe', 'pipe'],
+			});
+		} catch (refError) {
+			if (refError.status === 1) return null;
+			throw headError;
+		}
+		throw headError;
 	}
+	const head = output.trim();
+	if (!isValidGitObjectId(head)) throw new Error('Current HEAD did not resolve to one full Git object id.');
+	return head;
+}
+
+const ABSENT_ENTRY = 'absent';
+const LINE_SPLIT = /\r?\n/;
 
-	const output = execFileSync('git', ['diff', '--cached', '--name-status', '--diff-filter=ACMRDT'], {
+// Pathspec magic is only honoured when Git is not already in a forced pathspec
+// mode. If the hook inherits GIT_LITERAL_PATHSPECS=1, `:(literal)<file>` is read
+// as a filename spelled `:(literal)<file>`, every probe matches nothing, and the
+// exemption predicate would compare absent against absent. The sibling GLOB /
+// NOGLOB / ICASE switches distort matching the same way, so strip all four and
+// keep the explicit `:(literal)` magic (paths with glob or colon characters stay
+// safe). Keys are compared case-insensitively because Windows environment names
+// are case-insensitive.
+const PATHSPEC_ENV_KEYS = new Set([
+	'GIT_LITERAL_PATHSPECS',
+	'GIT_GLOB_PATHSPECS',
+	'GIT_NOGLOB_PATHSPECS',
+	'GIT_ICASE_PATHSPECS',
+]);
+
+function pathspecSafeEnv() {
+	const env = { ...process.env };
+	for (const key of Object.keys(env)) {
+		if (PATHSPEC_ENV_KEYS.has(key.toUpperCase())) delete env[key];
+	}
+	return env;
+}
+
+const GIT_PROBE_ENV = pathspecSafeEnv();
+const REMOTE_PROBE_TIMEOUT_MS = 15_000;
+
+function gitCapture(args) {
+	return execFileSync('git', args, {
 		encoding: 'utf8',
 		stdio: ['ignore', 'pipe', 'pipe'],
-	});
-	return parseNameStatus(output);
+		env: GIT_PROBE_ENV,
+	}).trim();
 }
 
-function getAllowedSurfaces() {
-	return new Set(
-		String(process.env.FORGE_PROTECTED_STATE_ALLOWED_SURFACES || '')
-			.split(',')
-			.map(surface => surface.trim())
-			.filter(Boolean),
-	);
+// Resolve a commit-ish to a full object id, or null when it does not exist.
+// Worktree-safe: plain `git rev-parse` already resolves per-worktree state.
+function resolveCommit(revision) {
+	try {
+		const id = gitCapture(['rev-parse', '--verify', '--quiet', `${revision}^{commit}`]);
+		return isValidGitObjectId(id) ? id : null;
+	} catch {
+		return null;
+	}
+}
+
+// Best common ancestor of two commits, or null when there is none (unrelated
+// histories) or the query fails. Used to tell "the merge side deleted this path"
+// apart from "this path never existed on the merge side".
+function resolveMergeBase(left, right) {
+	let base;
+	try {
+		base = gitCapture(['merge-base', left, right]).split(LINE_SPLIT)[0].trim();
+	} catch {
+		return null;
+	}
+	return isValidGitObjectId(base) ? base : null;
+}
+
+// Git prints the mode but not the type for index entries; derive it so index and
+// tree entries normalise to the same shape.
+function objectTypeForMode(mode) {
+	if (mode === '160000') return 'commit';
+	if (mode === '040000' || mode === '40000') return 'tree';
+	return 'blob';
+}
+
+// Normalised `<mode> <type> <oid>` for the staged index entry, ABSENT_ENTRY when
+// the path is not in the index, or null when the answer is unknown. A conflicted
+// path yields several stage lines and therefore null — fail closed.
+// The mode matters: blob equality alone would exempt a real 100644 -> 100755
+// index change on a protected path.
+function stagedEntry(file) {
+	let output;
+	try {
+		output = gitCapture(['ls-files', '--stage', '--', `:(literal)${file}`]);
+	} catch {
+		return null;
+	}
+	if (output === '') return ABSENT_ENTRY;
+	const lines = output.split(LINE_SPLIT).filter(Boolean);
+	if (lines.length !== 1) return null;
+	const match = /^([0-7]{6}) ([0-9a-f]{40}|[0-9a-f]{64}) [0-3]\t/.exec(lines[0]);
+	if (!match) return null;
+	return `${match[1]} ${objectTypeForMode(match[1])} ${match[2]}`;
+}
+
+// Same normalised shape for `<revision>:<file>`, so the comparison covers mode
+// and object type as well as content.
+function revisionEntry(revision, file) {
+	let output;
+	try {
+		output = gitCapture(['ls-tree', revision, '--', `:(literal)${file}`]);
+	} catch {
+		return null;
+	}
+	if (output === '') return ABSENT_ENTRY;
+	const lines = output.split(LINE_SPLIT).filter(Boolean);
+	if (lines.length !== 1) return null;
+	const match = /^([0-7]{6}) (blob|tree|commit) ([0-9a-f]{40}|[0-9a-f]{64})\t/.exec(lines[0]);
+	if (!match) return null;
+	return `${match[1]} ${match[2]} ${match[3]}`;
 }
 
-function main() {
+// Adapter so the shared base-remote resolver runs through this script's
+// pathspec-scrubbed git probe. The resolver ignores the options object it is
+// handed here; the env scrub and quiet stdio come from `gitCapture`.
+function baseRemoteProbe(_command, args) {
+	return gitCapture(args);
+}
+
+// Resolve the repository's single canonical upstream ref, deterministically:
+// the *base* remote (`upstream` preferred over `origin`, the same resolution
+// `/ship` uses to pick a PR base), then that remote's default branch
+// (`refs/remotes/<remote>/HEAD`, falling back to the conventional default
+// names). Deliberately NOT the current branch's tracking remote: in a
+// fork-style checkout the feature branch tracks the contributor-owned fork, and
+// trusting it would let a change merged from the fork's default branch pass as
+// "already published on the base" when it never reached the official repo.
+// Fail closed when the official `upstream` remote is configured but has no
+// fetched tracking refs: falling through to `origin` would change trust domains
+// and let fork-only content pass as already published upstream.
+// Fail closed when the base branch is ambiguous: with no authoritative HEAD
+// and both conventional defaults present, candidate order would trust main
+// even when master is the real integration branch, letting content published
+// only to the wrong branch pass as already published on the base.
+// Returns the fully-qualified local ref plus its remote/branch identity, or null
+// when the canonical upstream cannot be established.
+function canonicalUpstream() {
+	const cwd = process.cwd();
+	const remote = resolveBaseRemote(baseRemoteProbe, cwd);
+	if (remote === 'origin') {
+		try {
+			gitCapture(['remote', 'get-url', 'upstream']);
+			return null;
+		} catch {
+			// No upstream configured; origin fallback is legitimate.
+		}
+	}
+	try {
+		const remotes = gitCapture(['remote']).split(/\r?\n/).map(line => line.trim());
+		if (!remotes.includes(remote)) return null;
+	} catch {
+		return null;
+	}
+
+	const candidates = [];
+	let head = null;
+	try {
+		const resolved = gitCapture(['symbolic-ref', '--quiet', `refs/remotes/${remote}/HEAD`]);
+		if (resolved) head = resolved;
+	} catch {
+		// no remote HEAD recorded; fall through to the resolved default branch
+	}
+	if (head) {
+		candidates.push(head);
+	} else {
+		const hasMain = Boolean(resolveCommit(`refs/remotes/${remote}/main`));
+		const hasMaster = Boolean(resolveCommit(`refs/remotes/${remote}/master`));
+		if (hasMain && hasMaster) return null;
+	}
+	candidates.push(`refs/remotes/${remote}/${resolveBaseBranch(baseRemoteProbe, process.cwd(), remote)}`);
+	candidates.push(`refs/remotes/${remote}/main`, `refs/remotes/${remote}/master`);
+
+	const prefix = `refs/remotes/${remote}/`;
+	for (const ref of candidates) {
+		if (resolveCommit(ref) && ref.startsWith(prefix) && ref.length > prefix.length) {
+			return { ref, remote, branch: ref.slice(prefix.length) };
+		}
+	}
+	return null;
+}
+
+// A local remote-tracking ref is only cached evidence. Confirm that the remote
+// still advertises both the selected default branch and its frozen commit
+// without mutating refs; unavailable or malformed remote evidence fails closed.
+function isCurrentCanonicalCommit(canonical, expectedCommit) {
+	if (!canonical || !expectedCommit) return false;
+	const expectedRef = `refs/heads/${canonical.branch}`;
+	let output;
+	try {
+		output = execFileSync('git', ['ls-remote', '--symref', '--exit-code', canonical.remote, 'HEAD'], {
+			encoding: 'utf8',
+			stdio: ['ignore', 'pipe', 'pipe'],
+			env: { ...GIT_PROBE_ENV, GIT_TERMINAL_PROMPT: '0', GCM_INTERACTIVE: 'Never' },
+			timeout: REMOTE_PROBE_TIMEOUT_MS,
+		}).trim();
+	} catch {
+		return false;
+	}
+	const lines = output.split(LINE_SPLIT).filter(Boolean);
+	if (lines.length !== 2) return false;
+	const symref = lines.map(line => /^ref: ([^\0\r\n\t]+)\tHEAD$/.exec(line)).find(Boolean);
+	const head = lines.map(line => /^([0-9a-f]{40}|[0-9a-f]{64})\tHEAD$/.exec(line)).find(Boolean);
+	return Boolean(symref && head && symref[1] === expectedRef && head[1] === expectedCommit);
+}
+
+// True when `commit` is contained in the canonical upstream line — not merely
+// "some ref points at it". `--contains` over refs/remotes would accept an
+// untrusted contributor remote or a hand-written `git update-ref
+// refs/remotes/<anything>`; ancestry in the canonical ref is the property we
+// actually want (these bytes are already published on the branch this repo
+// integrates into, where the same gate ran).
+//
+// Honest limitation: refs under .git are locally writable, and anyone who can
+// write .git can disable this hook outright. This gate defends against
+// accidental and agent-authored protected edits and against merges from
+// untrusted contributor remotes. It is NOT a security boundary against a local
+// adversary — do not treat it as one.
+function isCanonicalUpstreamAncestor(commit, canonicalCommit) {
+	if (!canonicalCommit) return false;
+	try {
+		execFileSync('git', ['merge-base', '--is-ancestor', commit, canonicalCommit], {
+			stdio: ['ignore', 'ignore', 'ignore'],
+		});
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+// A merge is in progress when the per-worktree MERGE_HEAD exists. `--git-path`
+// resolves the correct (possibly linked-worktree) git dir. Returns null unless a
+// merge is genuinely in progress and every recorded id resolves; `trustedSides`
+// holds only those MERGE_HEAD commits contained in the canonical upstream commit.
+function readMergeProvenance() {
+	let mergeHeadPath;
+	try {
+		mergeHeadPath = gitCapture(['rev-parse', '--git-path', 'MERGE_HEAD']);
+	} catch {
+		return null;
+	}
+	if (!mergeHeadPath) return null;
+	let raw;
+	try {
+		raw = fs.readFileSync(path.resolve(process.cwd(), mergeHeadPath), 'utf8');
+	} catch {
+		return null;
+	}
+	const ids = raw
+		.split(/\r?\n/)
+		.map(line => line.trim())
+		.filter(Boolean);
+	if (ids.length === 0 || !ids.every(isValidGitObjectId)) return null;
+	const resolved = ids.map(id => resolveCommit(id));
+	if (resolved.some(commit => commit === null)) return null;
+	// HEAD anchors the "no net change" half of the predicate. If it cannot be
+	// resolved we know nothing about the commit being built, so there is no
+	// exemption context at all — fail closed rather than fall back to the sides.
+	const head = resolveCommit('HEAD');
+	if (!head) return null;
+	const canonical = canonicalUpstream();
+	const canonicalCommit = canonical ? resolveCommit(canonical.ref) : null;
+	return {
+		head,
+		canonical,
+		canonicalCommit,
+		trustedSides: resolved.filter(commit => isCanonicalUpstreamAncestor(commit, canonicalCommit)),
+	};
+}
+
+// Exemption predicate. While a merge is in progress, a staged protected path is
+// exempt only when the committer introduced no net change AND the content has
+// trusted provenance:
+//   - staged entry (mode + object) === the entry at HEAD: no net change versus the branch being
+//     committed onto, so there is no provenance question at all; or
+//   - staged entry === both a MERGE_HEAD contained in the canonical upstream
+//     commit and that current canonical commit: the bytes are still published
+//     on the line this repo integrates into, where the same gate ran.
+// A purely local merge side earns no exemption — otherwise anyone could smuggle a
+// protected edit in on a local branch and merge it. The merge base is likewise not
+// a permitted side: matching only the base means both sides were reverted, an edit.
+// Anything else stays blocked, and any failed git query fails closed.
+function createMergeExemption() {
+	const merge = readMergeProvenance();
+	if (!merge) return () => false;
+	let canonicalIsCurrent;
+	const hasCurrentCanonicalCommit = () => {
+		if (canonicalIsCurrent === undefined) {
+			canonicalIsCurrent = isCurrentCanonicalCommit(merge.canonical, merge.canonicalCommit);
+		}
+		return canonicalIsCurrent;
+	};
+	return file => {
+		const staged = stagedEntry(file);
+		if (staged === null) return false;
+		if (staged !== ABSENT_ENTRY && staged === revisionEntry(merge.head, file)) return true;
+		if (!merge.canonicalCommit || staged !== revisionEntry(merge.canonicalCommit, file)) return false;
+		if (staged === ABSENT_ENTRY) {
+			// Git just reported this path as staged, so an absent index entry is only
+			// honest for a staged deletion; otherwise the probe contradicts git and
+			// the answer is unknown.
+			if (!deletedFiles.has(file)) return false;
+			// Absent on a trusted side is not proof that side deleted anything — a
+			// path that only ever existed on HEAD is absent upstream too, so a manual
+			// `git rm` during a merge would otherwise exempt itself. Demand that the
+			// merge side actually removed it: present at the merge base, gone at the
+			// side. Fail closed when the base or either probe is unavailable.
+			const trustedDeletion = merge.trustedSides.some(side => {
+				if (revisionEntry(side, file) !== ABSENT_ENTRY) return false;
+				const base = resolveMergeBase(merge.head, side);
+				if (!base) return false;
+				const baseEntry = revisionEntry(base, file);
+				return baseEntry !== null && baseEntry !== ABSENT_ENTRY;
+			});
+			return trustedDeletion && hasCurrentCanonicalCommit();
+		}
+		const trustedCarryOver = merge.trustedSides.some(revision => {
+			const entry = revisionEntry(revision, file);
+			return entry !== null && entry === staged;
+		});
+		return trustedCarryOver && hasCurrentCanonicalCommit();
+	};
+}
+
+async function main() {
 	const actor =
 		process.env.FORGE_PROTECTED_STATE_ACTOR ||
 		process.env.FORGE_ACTOR ||
 		process.env.USER ||
 		process.env.USERNAME ||
 		'unknown';
-	const allowedSurfaces = getAllowedSurfaces();
-	const decisions = getStagedFiles()
+	const sourceHead = getCurrentHead();
+	const isMergeCarryOver = createMergeExemption();
+	const mergeExempt = [];
+	const probes = getStagedFiles()
 		.map(file => {
 			const probe = assertProtectedWriteAllowed(file, { actor, operation: 'staged_edit' });
-			if (probe.requiredSurface && allowedSurfaces.has(probe.requiredSurface)) {
-				return assertProtectedWriteAllowed(file, {
+			if (!probe.requiredSurface) return { probe };
+			// Deliberately after the lockfile branch: bun.lock keeps its own
+			// regeneration proof, which a merge must never skip.
+			if (probe.path !== 'bun.lock' && isMergeCarryOver(probe.path)) {
+				mergeExempt.push(probe.path);
+				return { probe: { ...probe, allowed: true, decision: 'allowed_merge_carry_over' } };
+			}
+			if (probe.path === 'bun.lock' && probe.requiredSurface === 'lockfiles') {
+				return {
+					probe,
+					directDecision: {
+						...probe,
+						...verifyBunLockfileRegeneration(process.cwd()),
+					},
+				};
+			}
+
+			const content = getStagedContent(probe.path);
+			if (content === null) return { probe };
+			return {
+				probe,
+				request: {
 					actor,
-					operation: 'staged_edit',
-					viaForgeApi: true,
 					surface: probe.requiredSurface,
-				});
-			}
-			return probe;
+					path: probe.path,
+					content,
+					operation: deletedFiles.has(probe.path) ? 'staged_delete' : 'staged_edit',
+					sourceHead,
+				},
+			};
+		});
+	const protectedProbes = probes.filter(entry => entry.request);
+	const authorization = await authorizeAndConsumeProtectedStateWrites(
+		process.cwd(),
+		protectedProbes.map(entry => entry.request),
+		{ sourceHead },
+	);
+	let authorizationIndex = 0;
+	const decisions = probes
+		.map(entry => {
+			if (entry.directDecision) return entry.directDecision;
+			if (!entry.request) return entry.probe;
+			const trustedDecision = authorization.decisions[authorizationIndex++];
+			if (!trustedDecision && authorization.batchDecision) return { ...entry.probe, allowed: true };
+			return trustedDecision.allowed
+				? trustedDecision
+				: { ...entry.probe, ...trustedDecision, repairHint: entry.probe.repairHint };
 		})
 		.filter(decision => !decision.allowed);
+	if (authorization.batchDecision && !authorization.batchDecision.allowed) {
+		decisions.push(authorization.batchDecision);
+	}
 
 	for (const decision of decisions) {
 		const audit = recordProtectedStateAuditEvent(decision, { cwd: process.cwd() });
@@ -80,6 +521,10 @@ function main() {
 		}
 	}
 
+	for (const file of mergeExempt) {
+		console.log(`OK: ${file} matches a merge side unchanged (merge in progress); no net edit introduced.`);
+	}
+
 	if (decisions.length === 0) {
 		console.log('OK: No protected state edits detected.');
 		process.exit(0);
@@ -89,16 +534,19 @@ function main() {
 	for (const decision of decisions) {
 		console.error(`  - ${decision.path} [${decision.requiredSurface}]`);
 		console.error(`    Decision: ${decision.decision}`);
+		console.error(`    Reason: ${decision.reason}`);
 		console.error(`    Repair: ${decision.repairHint}`);
 	}
 	console.error('');
-	console.error('Use the owning Forge or Beads API surface, then stage the generated result if that command explicitly owns it.');
+	console.error('Use the owning Forge API surface, then stage the generated result if that command explicitly owns it.');
 	process.exit(1);
 }
 
-try {
-	main();
-} catch (error) {
-	console.error(`Protected state check failed: ${error.message}`);
-	process.exit(1);
+if (require.main === module) {
+	main().catch(error => {
+		console.error(`Protected state check failed: ${error.message}`);
+		process.exit(1);
+	});
 }
+
+module.exports = { getCurrentHead };

package/scripts/run-command-eval.js

@@ -20,6 +20,7 @@ const {
 } = require('./lib/eval-runner');
 const { gradeTranscript } = require('./lib/grading');
 const { saveEvalResult } = require('./lib/eval-storage');
+const { verifyEvalReplay } = require('./lib/eval-evidence');
 
 // ---------------------------------------------------------------------------
 // parseArgs
@@ -89,6 +90,7 @@ function runShellCommand(command, worktreePath) {
  * @param {string} [options._basePath] — eval-logs base path for testing
  * @param {boolean} [options._skipWorktree=false] — skip worktree creation for unit tests
  * @param {Function} [options._executeOverride] — injectable command executor for testing
+ * @param {{envelope: object, inputs: {skill: string, tool: string}}} [options.replay] — exact-SHA replay binding
  * @returns {Promise<{ command: string, results: Array, overall_score: number, passed: boolean, duration_ms: number }>}
  */
 async function runEvalPipeline(evalSetPath, options = {}) {
@@ -98,6 +100,8 @@ async function runEvalPipeline(evalSetPath, options = {}) {
   const execOverride = options._executeOverride || null;
   const invokeGrader = options._invokeGrader || null;
   const basePath = options._basePath || undefined;
+  const hasReplay = Object.hasOwn(options, 'replay');
+  const replay = options.replay;
 
   const startTime = Date.now();
 
@@ -105,10 +109,34 @@ async function runEvalPipeline(evalSetPath, options = {}) {
   const evalSet = loadEvalSet(evalSetPath);
   const { command, queries } = evalSet;
 
+  let replayEvidence = null;
+  if (hasReplay) {
+    if (!replay || typeof replay !== 'object' || Array.isArray(replay)) throw new Error('replay must be an object');
+    for (const field of Object.keys(replay)) {
+      if (!['envelope', 'inputs'].includes(field)) throw new Error(`Unknown field 'replay.${field}'`);
+    }
+    if (!Object.hasOwn(replay, 'envelope')) throw new Error('replay.envelope is required');
+    if (!replay.inputs || typeof replay.inputs !== 'object' || Array.isArray(replay.inputs)) {
+      throw new Error('replay.inputs must be an object');
+    }
+    for (const field of Object.keys(replay.inputs)) {
+      if (!['skill', 'tool'].includes(field)) throw new Error(`Unknown field 'replay.inputs.${field}'`);
+    }
+    for (const field of ['skill', 'tool']) {
+      if (!Object.hasOwn(replay.inputs, field)) throw new Error(`replay.inputs.${field} is required`);
+    }
+    replayEvidence = verifyEvalReplay(replay.envelope, {
+      evalSet,
+      skill: replay.inputs.skill,
+      tool: replay.inputs.tool,
+    });
+    if (skipWorktree) throw new Error('Replay worktree verification cannot be skipped');
+  }
+
   // 2. Create eval worktree (unless skipped for testing)
   let worktreePath = null;
   if (!skipWorktree) {
-    const wt = await createEvalWorktree();
+    const wt = await createEvalWorktree(replayEvidence ? replayEvidence.head_sha : undefined);
     worktreePath = wt.path;
   }