taskplane 0.5.11 → 0.6.0

package/extensions/taskplane/merge.ts

@@ -2,18 +2,20 @@
  * Merge orchestration, merge agents, merge worktree
  * @module orch/merge
  */
-import { readFileSync, writeFileSync, existsSync, unlinkSync, copyFileSync, mkdirSync } from "fs";
-import { spawnSync } from "child_process";
-import { join, dirname } from "path";
+import { readFileSync, writeFileSync, existsSync, unlinkSync, copyFileSync, mkdirSync, rmSync } from "fs";
+import { execSync, spawnSync } from "child_process";
+import { join, dirname, resolve, relative } from "path";
 
 import { buildLaneEnvVars, buildTmuxSpawnArgs, execLog, tmuxHasSession, tmuxKillSession, toTmuxPath } from "./execution.ts";
 import { resolveOperatorId } from "./naming.ts";
 import { MERGE_POLL_INTERVAL_MS, MERGE_RESULT_GRACE_MS, MERGE_RESULT_READ_RETRIES, MERGE_RESULT_READ_RETRY_DELAY_MS, MERGE_SPAWN_RETRY_MAX, MERGE_TIMEOUT_MS, MergeError, VALID_MERGE_STATUSES } from "./types.ts";
-import type { AllocatedLane, LaneExecutionResult, MergeLaneResult, MergeResult, MergeResultStatus, MergeWaveResult, OrchestratorConfig, RepoMergeOutcome, WaveExecutionResult, WorkspaceConfig } from "./types.ts";
+import type { AllocatedLane, LaneExecutionResult, MergeLaneResult, MergeResult, MergeResultStatus, MergeWaveResult, OrchestratorConfig, RepoMergeOutcome, TaskRunnerConfig, TransactionRecord, TransactionStatus, VerificationBaselineResult, WaveExecutionResult, WorkspaceConfig } from "./types.ts";
 import { resolveBaseBranch, resolveRepoRoot } from "./waves.ts";
 import { generateMergeWorktreePath, sleepSync } from "./worktree.ts";
 import { getCurrentBranch, runGit } from "./git.ts";
 import { ORCH_MESSAGES } from "./messages.ts";
+import { captureBaseline, diffFingerprints, runVerificationCommands, parseTestOutput, deduplicateFingerprints } from "./verification.ts";
+import type { VerificationBaseline, FingerprintDiff, TestFingerprint } from "./verification.ts";
 
 // ── Merge Implementation ─────────────────────────────────────────────
 
@@ -473,6 +475,296 @@ export function waitForMergeResult(
 	}
 }
 
+/**
+ * Force-remove a merge worktree directory and prune stale git references.
+ *
+ * TP-029: Applies the same forceCleanupWorktree pattern used for lane
+ * worktrees. Tries `git worktree remove --force` first, then falls back
+ * to `rm -rf` + `git worktree prune` if the initial removal fails.
+ *
+ * Used in both stale-prep cleanup (before creating a fresh merge worktree)
+ * and end-of-wave cleanup (after merge completes).
+ *
+ * @param mergeWorkDir - Absolute path to the merge worktree directory
+ * @param repoRoot     - Main repository root for git operations
+ * @param context      - Logging context (e.g., "W1" for wave 1)
+ */
+function forceRemoveMergeWorktree(
+	mergeWorkDir: string,
+	repoRoot: string,
+	context: string,
+): void {
+	if (!existsSync(mergeWorkDir)) return;
+
+	// Try git worktree remove --force first
+	const removeResult = spawnSync("git", ["worktree", "remove", mergeWorkDir, "--force"], { cwd: repoRoot });
+	if (removeResult.status === 0) {
+		return;
+	}
+
+	// Fallback: force-remove the directory and prune git worktree state
+	const stderr = removeResult.stderr?.toString().trim() || "";
+	execLog("merge", context, `git worktree remove failed for merge worktree, applying force cleanup`, {
+		error: stderr.slice(0, 200),
+		path: mergeWorkDir,
+	});
+
+	try {
+		rmSync(mergeWorkDir, { recursive: true, force: true });
+		execLog("merge", context, `force-removed merge worktree directory`, { path: mergeWorkDir });
+	} catch (rmErr: unknown) {
+		// Node's rmSync may fail on Windows reserved-name files — try OS-level removal
+		const rmMsg = rmErr instanceof Error ? rmErr.message : String(rmErr);
+		execLog("merge", context, `rmSync failed for merge worktree, trying OS-level removal`, { error: rmMsg });
+		try {
+			if (process.platform === "win32") {
+				execSync(`rd /s /q "${mergeWorkDir}"`, { stdio: "pipe", timeout: 30_000 });
+			} else {
+				execSync(`rm -rf "${mergeWorkDir}"`, { stdio: "pipe", timeout: 30_000 });
+			}
+			execLog("merge", context, `OS-level removal of merge worktree succeeded`, { path: mergeWorkDir });
+		} catch (osErr: unknown) {
+			const osMsg = osErr instanceof Error ? osErr.message : String(osErr);
+			execLog("merge", context, `OS-level removal also failed — manual cleanup needed`, {
+				path: mergeWorkDir,
+				error: osMsg,
+			});
+		}
+	}
+
+	// Prune stale worktree references
+	runGit(["worktree", "prune"], repoRoot);
+}
+
+// ── Transaction Record Persistence (TP-033) ─────────────────────────
+
+/**
+ * Persist a transaction record to disk as JSON.
+ *
+ * Written to: `.pi/verification/{opId}/txn-b{batchId}-repo-{repoId}-wave-{n}-lane-{k}.json`
+ *
+ * When repoId is null/undefined (repo mode), uses "default" as the repo slug.
+ * Non-alphanumeric characters in repoId are sanitized to underscores.
+ *
+ * @param record - The transaction record to persist
+ * @param stateRoot - Root directory for .pi state files
+ */
+/**
+ * Persist a transaction record to disk. Returns null on success, or an error
+ * message string on failure. Persistence is best-effort — callers should
+ * accumulate errors and surface them in MergeWaveResult.persistenceErrors
+ * so operators know recovery guidance may reference missing files.
+ */
+function persistTransactionRecord(record: TransactionRecord, stateRoot: string): string | null {
+	try {
+		const repoSlug = record.repoId
+			? record.repoId.replace(/[^a-zA-Z0-9_-]/g, "_")
+			: "default";
+		const verifyDir = join(stateRoot, ".pi", "verification", record.opId);
+		mkdirSync(verifyDir, { recursive: true });
+		const fileName = `txn-b${record.batchId}-repo-${repoSlug}-wave-${record.waveIndex}-lane-${record.laneNumber}.json`;
+		writeFileSync(
+			join(verifyDir, fileName),
+			JSON.stringify(record, null, 2),
+			"utf-8",
+		);
+		execLog("merge", `W${record.waveIndex}`, `transaction record persisted`, {
+			file: fileName,
+			status: record.status,
+		});
+		return null;
+	} catch (err: unknown) {
+		// Transaction record persistence is best-effort — don't fail the merge
+		const errMsg = err instanceof Error ? err.message : String(err);
+		execLog("merge", `W${record.waveIndex}`, `failed to persist transaction record: ${errMsg}`);
+		return `lane ${record.laneNumber} (repo: ${record.repoId ?? "default"}): ${errMsg}`;
+	}
+}
+
+// ── Orchestrator-Side Verification (TP-032) ──────────────────────────
+
+/**
+ * Run post-merge verification and compare against baseline.
+ *
+ * Captures fingerprints from the merge worktree after a successful merge,
+ * diffs against the pre-merge baseline, and classifies the result:
+ * - "pass": no new failures (only pre-existing or fixed)
+ * - "verification_new_failure": genuinely new failures detected
+ * - "flaky_suspected": new failures disappeared on re-run (warning only)
+ *
+ * Flaky handling: when new failures are detected and flakyReruns > 0,
+ * only the commands that produced new failures are re-run up to
+ * flakyReruns times. If the failures disappear on any re-run attempt,
+ * the result is reclassified as "flaky_suspected". When flakyReruns is
+ * 0, no re-runs are attempted and new failures immediately block.
+ *
+ * @param testingCommands - Named verification commands (from testing.commands config)
+ * @param mergeWorkDir    - Merge worktree path (post-merge state)
+ * @param baseline        - Pre-merge baseline to compare against
+ * @param laneNumber      - Lane number (for logging/persistence)
+ * @param waveIndex       - Wave index (for persistence naming)
+ * @param batchId         - Batch ID (for persistence naming)
+ * @param opId            - Operator ID (for persistence naming)
+ * @param sessionName     - Session name for structured logging
+ * @param stateRoot       - State root for persistence (workspace root or repo root)
+ * @param repoId          - Repository ID for workspace-mode artifact naming (optional)
+ * @param flakyReruns     - Number of flaky re-runs (0 = disabled, default 1)
+ * @returns VerificationBaselineResult with classification and details
+ */
+function runPostMergeVerification(
+	testingCommands: Record<string, string>,
+	mergeWorkDir: string,
+	baseline: VerificationBaseline,
+	laneNumber: number,
+	waveIndex: number,
+	batchId: string,
+	opId: string,
+	sessionName: string,
+	stateRoot: string,
+	repoId?: string,
+	flakyReruns: number = 1,
+): VerificationBaselineResult {
+	execLog("merge", sessionName, "capturing post-merge verification fingerprints");
+
+	// Capture post-merge fingerprints
+	const postMerge = captureBaseline(testingCommands, mergeWorkDir);
+
+	// Persist post-merge snapshot for debugging
+	try {
+		const verifyDir = join(stateRoot, ".pi", "verification", opId);
+		mkdirSync(verifyDir, { recursive: true });
+		// TP-032 R006-1: Include repoId in filename to prevent overwrites
+		// when mergeWaveByRepo() calls mergeWave() once per repo group.
+		const repoSuffix = repoId ? `-repo-${repoId.replace(/[^a-zA-Z0-9_-]/g, "_")}` : "";
+		const postFileName = `post-b${batchId}-w${waveIndex}${repoSuffix}-lane${laneNumber}.json`;
+		writeFileSync(
+			join(verifyDir, postFileName),
+			JSON.stringify(postMerge, null, 2),
+			"utf-8",
+		);
+	} catch {
+		// Best effort — persistence failure doesn't block verification
+	}
+
+	// Diff fingerprints
+	const diff = diffFingerprints(baseline.fingerprints, postMerge.fingerprints);
+
+	execLog("merge", sessionName, "verification diff computed", {
+		newFailures: diff.newFailures.length,
+		preExisting: diff.preExisting.length,
+		fixed: diff.fixed.length,
+	});
+
+	// No new failures — pass
+	if (diff.newFailures.length === 0) {
+		return {
+			performed: true,
+			newFailureCount: 0,
+			preExistingCount: diff.preExisting.length,
+			fixedCount: diff.fixed.length,
+			classification: "pass",
+			newFailureSummary: "",
+			flakyRerunPerformed: false,
+		};
+	}
+
+	// ── Flaky re-run: re-run only the commands that produced new failures ──
+	// Only when flakyReruns > 0 (0 = disabled — any new failure immediately blocks)
+	if (flakyReruns > 0) {
+		// Identify which commandIds produced new failures
+		const failedCommandIds = new Set(diff.newFailures.map(fp => fp.commandId));
+		const rerunCommands: Record<string, string> = {};
+		for (const cmdId of failedCommandIds) {
+			if (testingCommands[cmdId]) {
+				rerunCommands[cmdId] = testingCommands[cmdId];
+			}
+		}
+
+		// Re-run up to flakyReruns times; break early if failures clear
+		let clearedOnRerun = false;
+		for (let attempt = 0; attempt < flakyReruns; attempt++) {
+			execLog("merge", sessionName, `new failures detected — running flaky re-run ${attempt + 1}/${flakyReruns}`, {
+				failedCommands: [...failedCommandIds].join(", "),
+				rerunCount: Object.keys(rerunCommands).length,
+			});
+
+			const rerunResults = runVerificationCommands(rerunCommands, mergeWorkDir);
+
+			// Parse re-run fingerprints
+			const rerunFingerprints: TestFingerprint[] = [];
+			for (const result of rerunResults) {
+				const fps = parseTestOutput(result);
+				rerunFingerprints.push(...fps);
+			}
+			const dedupedRerun = deduplicateFingerprints(rerunFingerprints);
+
+			// Re-diff: compare baseline against re-run results for the failed commands only
+			// Filter baseline fingerprints to only the commands we re-ran
+			const baselineForRerun = baseline.fingerprints.filter(fp => failedCommandIds.has(fp.commandId));
+			const rerunDiff = diffFingerprints(baselineForRerun, dedupedRerun);
+
+			if (rerunDiff.newFailures.length === 0) {
+				// Failures disappeared on re-run — flaky suspected
+				execLog("merge", sessionName, `flaky re-run ${attempt + 1} cleared all new failures — classifying as flaky_suspected`);
+				clearedOnRerun = true;
+				break;
+			}
+
+			// If this is the last attempt and failures persist, return failure
+			if (attempt === flakyReruns - 1) {
+				const summary = rerunDiff.newFailures
+					.slice(0, 5)
+					.map(fp => `${fp.commandId}:${fp.file}:${fp.case} (${fp.kind})`)
+					.join("; ");
+				const truncated = rerunDiff.newFailures.length > 5
+					? ` ... and ${rerunDiff.newFailures.length - 5} more`
+					: "";
+
+				return {
+					performed: true,
+					newFailureCount: rerunDiff.newFailures.length,
+					preExistingCount: diff.preExisting.length,
+					fixedCount: diff.fixed.length,
+					classification: "verification_new_failure",
+					newFailureSummary: summary + truncated,
+					flakyRerunPerformed: true,
+				};
+			}
+		}
+
+		if (clearedOnRerun) {
+			return {
+				performed: true,
+				newFailureCount: 0,
+				preExistingCount: diff.preExisting.length,
+				fixedCount: diff.fixed.length,
+				classification: "flaky_suspected",
+				newFailureSummary: `Flaky: ${diff.newFailures.length} failure(s) disappeared on re-run`,
+				flakyRerunPerformed: true,
+			};
+		}
+	}
+
+	// flakyReruns === 0 or fallthrough: new failures block immediately
+	const summary = diff.newFailures
+		.slice(0, 5)
+		.map(fp => `${fp.commandId}:${fp.file}:${fp.case} (${fp.kind})`)
+		.join("; ");
+	const truncated = diff.newFailures.length > 5
+		? ` ... and ${diff.newFailures.length - 5} more`
+		: "";
+
+	return {
+		performed: true,
+		newFailureCount: diff.newFailures.length,
+		preExistingCount: diff.preExisting.length,
+		fixedCount: diff.fixed.length,
+		classification: "verification_new_failure",
+		newFailureSummary: summary + truncated,
+		flakyRerunPerformed: flakyReruns > 0,
+	};
+}
+
 /**
  * Merge a completed wave's lane branches into the base branch.
  *
@@ -515,6 +807,8 @@ export function mergeWave(
 	baseBranch: string,
 	stateRoot?: string,
 	agentRoot?: string,
+	testingCommands?: Record<string, string>,
+	repoId?: string,
 ): MergeWaveResult {
 	const startTime = Date.now();
 	const tmuxPrefix = config.orchestrator.tmux_prefix;
@@ -574,13 +868,15 @@ export function mergeWave(
 	const tempBranch = `_merge-temp-${opId}-${batchId}`;
 	const mergeWorkDir = generateMergeWorktreePath(repoRoot, opId, batchId, config);
 
-	// Clean up stale merge worktree/branch from prior failed attempt
-	try {
-		if (existsSync(mergeWorkDir)) {
-			spawnSync("git", ["worktree", "remove", mergeWorkDir, "--force"], { cwd: repoRoot });
-			sleepSync(500);
-		}
-	} catch { /* best effort */ }
+	// Clean up stale merge worktree/branch from prior failed attempt.
+	// TP-029: Apply forceRemoveMergeWorktree fallback so stale merge worktrees
+	// from prior failed attempts don't block new merge creation.
+	forceRemoveMergeWorktree(mergeWorkDir, repoRoot, `W${waveIndex}`);
+	if (existsSync(mergeWorkDir)) {
+		// Force cleanup didn't fully remove — wait and retry once
+		sleepSync(500);
+		forceRemoveMergeWorktree(mergeWorkDir, repoRoot, `W${waveIndex}`);
+	}
 	try {
 		spawnSync("git", ["branch", "-D", tempBranch], { cwd: repoRoot });
 	} catch { /* branch may not exist */ }
@@ -614,12 +910,109 @@ export function mergeWave(
 		tempBranch,
 	});
 
+	// ── Orchestrator-side baseline capture (TP-032) ────────────────
+	// Capture verification fingerprints on the pre-merge state of the merge
+	// worktree. This baseline is compared against post-merge fingerprints
+	// for each lane to detect genuinely new failures vs pre-existing ones.
+	// Only runs when verification.enabled === true AND testing.commands present.
+	let baseline: VerificationBaseline | null = null;
+	const hasTestingCommands = testingCommands && Object.keys(testingCommands).length > 0;
+	const verificationEnabled = config.verification.enabled;
+	const verificationMode = config.verification.mode;
+	const flakyReruns = config.verification.flaky_reruns;
+
+	if (verificationEnabled && !hasTestingCommands) {
+		// Verification is enabled but no testing commands configured — treat as
+		// baseline-unavailable. Strict/permissive handling below.
+		if (verificationMode === "strict") {
+			execLog("merge", `W${waveIndex}`, "verification enabled but no testing commands configured — strict mode: failing merge");
+			// Clean up worktree and temp branch before returning failure
+			forceRemoveMergeWorktree(mergeWorkDir, repoRoot, `W${waveIndex}`);
+			try { spawnSync("git", ["branch", "-D", tempBranch], { cwd: repoRoot }); } catch { /* best effort */ }
+			return {
+				waveIndex, status: "failed", laneResults: [],
+				failedLane: null,
+				failureReason: "Verification enabled (strict mode) but no testing commands configured in taskRunner.testing.commands",
+				totalDurationMs: Date.now() - startTime,
+			};
+		} else {
+			execLog("merge", `W${waveIndex}`, "verification enabled but no testing commands configured — permissive mode: continuing without verification");
+		}
+	}
+
+	if (verificationEnabled && hasTestingCommands) {
+		execLog("merge", `W${waveIndex}`, "capturing verification baseline on pre-merge state", {
+			commandCount: Object.keys(testingCommands).length,
+			commands: Object.keys(testingCommands).join(", "),
+		});
+
+		try {
+			baseline = captureBaseline(testingCommands, mergeWorkDir);
+
+			// Persist baseline for debugging/auditability
+			const piDir = stateRoot ?? repoRoot;
+			const verifyDir = join(piDir, ".pi", "verification", opId);
+			mkdirSync(verifyDir, { recursive: true });
+			// TP-032 R006-1: Include repoId in filename to prevent overwrites
+			// when mergeWaveByRepo() calls mergeWave() once per repo group.
+			const repoSuffix = repoId ? `-repo-${repoId.replace(/[^a-zA-Z0-9_-]/g, "_")}` : "";
+			const baselineFileName = `baseline-b${batchId}-w${waveIndex}${repoSuffix}.json`;
+			writeFileSync(
+				join(verifyDir, baselineFileName),
+				JSON.stringify(baseline, null, 2),
+				"utf-8",
+			);
+
+			execLog("merge", `W${waveIndex}`, "verification baseline captured", {
+				fingerprints: baseline.fingerprints.length,
+				preExistingFailures: baseline.fingerprints.length,
+				storedAt: join(verifyDir, baselineFileName),
+			});
+		} catch (err: unknown) {
+			const errMsg = err instanceof Error ? err.message : String(err);
+			if (verificationMode === "strict") {
+				execLog("merge", `W${waveIndex}`, `baseline capture failed — strict mode: failing merge`, {
+					error: errMsg,
+				});
+				// Clean up worktree and temp branch before returning failure
+				forceRemoveMergeWorktree(mergeWorkDir, repoRoot, `W${waveIndex}`);
+				try { spawnSync("git", ["branch", "-D", tempBranch], { cwd: repoRoot }); } catch { /* best effort */ }
+				return {
+					waveIndex, status: "failed", laneResults: [],
+					failedLane: null,
+					failureReason: `Verification baseline capture failed (strict mode): ${errMsg}`,
+					totalDurationMs: Date.now() - startTime,
+				};
+			}
+			execLog("merge", `W${waveIndex}`, `baseline capture failed — permissive mode: continuing without baseline verification`, {
+				error: errMsg,
+			});
+			// Permissive: baseline capture failure is non-fatal — merge proceeds without
+			// orchestrator-side verification. Merge-agent verification (merge.verify)
+			// still applies independently.
+			baseline = null;
+		}
+	}
+
 	// Sequential merge loop
 	let failedLane: number | null = null;
 	let failureReason: string | null = null;
+	// TP-032 R006-2: When verification rollback fails, the temp branch still contains
+	// the bad merge commit. Branch advancement MUST be blocked entirely — not just for
+	// the verification-blocked lane, but for all lanes, because the temp branch HEAD
+	// includes the unverified commit and any prior successful merges built on top of it.
+	let blockAdvancement = false;
+
+	// TP-033: Collect transaction records for all lane merges in this wave
+	const transactionRecords: TransactionRecord[] = [];
+	// TP-033 R004-2: Track persistence errors for operator visibility
+	const persistenceErrors: string[] = [];
+	// TP-033: Track whether any rollback failure triggered safe-stop
+	let rollbackFailed = false;
 
 	for (const lane of orderedLanes) {
 		const laneStart = Date.now();
+		const txnStartedAt = new Date().toISOString();
 		const sessionName = `${tmuxPrefix}-${opId}-merge-${lane.laneNumber}`;
 		const resultFileName = `merge-result-w${waveIndex}-lane${lane.laneNumber}-${opId}-${batchId}.json`;
 		const piDir = stateRoot ?? repoRoot;
@@ -627,9 +1020,34 @@ export function mergeWave(
 		const requestFileName = `merge-request-w${waveIndex}-lane${lane.laneNumber}-${opId}-${batchId}.txt`;
 		const requestFilePath = join(piDir, ".pi", requestFileName);
 
+		// ── TP-033: Capture baseHEAD (temp branch HEAD before lane merge) ──
+		// Always captured for transaction record — not conditional on baseline.
+		// This is the rollback target if verification detects new failures.
+		let baseHEAD = "";
+		{
+			const headResult = spawnSync("git", ["rev-parse", "HEAD"], { cwd: mergeWorkDir, encoding: "utf-8" });
+			if (headResult.status === 0) {
+				baseHEAD = headResult.stdout.trim();
+			}
+		}
+
+		// ── TP-033: Capture laneHEAD (source branch tip being merged in) ──
+		let laneHEAD = "";
+		{
+			const laneRef = spawnSync("git", ["rev-parse", lane.branch], { cwd: repoRoot, encoding: "utf-8" });
+			if (laneRef.status === 0) {
+				laneHEAD = laneRef.stdout.trim();
+			}
+		}
+
+		// TP-032 compat: preLaneHead is baseHEAD (renamed for clarity in txn model)
+		const preLaneHead = baseHEAD;
+
 		execLog("merge", sessionName, `starting merge for lane ${lane.laneNumber}`, {
 			sourceBranch: lane.branch,
 			targetBranch,
+			baseHEAD: baseHEAD.slice(0, 8),
+			laneHEAD: laneHEAD.slice(0, 8),
 		});
 
 		try {
@@ -643,6 +1061,11 @@ export function mergeWave(
 			}
 
 			// Build merge request content
+			// TP-032 R006-3: Preserve merge.verify commands independently of baseline
+			// fingerprinting. The orchestrator-side baseline comparison (testing.commands)
+			// is additive — it does NOT replace the merge agent's own verification
+			// (merge.verify). Agents may run build checks or other non-fingerprintable
+			// commands via merge.verify that must not be silently suppressed.
 			const mergeRequestContent = buildMergeRequest(
 				lane,
 				targetBranch,
@@ -668,8 +1091,8 @@ export function mergeWave(
 				// Best effort
 			}
 
-			// Record lane result
-			laneResults.push({
+			// Record lane result (verificationBaseline populated below if applicable)
+			const laneResult: MergeLaneResult = {
 				laneNumber: lane.laneNumber,
 				laneId: lane.laneId,
 				sourceBranch: lane.branch,
@@ -678,7 +1101,8 @@ export function mergeWave(
 				error: null,
 				durationMs: Date.now() - laneStart,
 				repoId: lane.repoId,
-			});
+			};
+			laneResults.push(laneResult);
 
 			// Handle merge outcome
 			switch (mergeResult.status) {
@@ -708,8 +1132,14 @@ export function mergeWave(
 					break;
 
 				case "BUILD_FAILURE":
+					// TP-032: When baseline is active, BUILD_FAILURE from the merge agent
+					// should not normally occur (we suppress verify commands). But if it does
+					// (e.g., agent detected build failure independently), log and proceed as
+					// a regular failure — the orchestrator-side verification below will not
+					// run because the agent already reverted the merge commit.
 					execLog("merge", sessionName, "merge failed — verification failed", {
 						output: mergeResult.verification.output.slice(0, 200),
+						baselineActive: !!baseline,
 					});
 					failedLane = lane.laneNumber;
 					failureReason = `Post-merge verification failed in lane ${lane.laneNumber}: ` +
@@ -717,6 +1147,162 @@ export function mergeWave(
 					break;
 			}
 
+			// ── TP-033: Capture mergedHEAD after successful merge commit ──
+			let mergedHEAD: string | null = null;
+			if (mergeResult.status === "SUCCESS" || mergeResult.status === "CONFLICT_RESOLVED") {
+				const postMergeRef = spawnSync("git", ["rev-parse", "HEAD"], { cwd: mergeWorkDir, encoding: "utf-8" });
+				if (postMergeRef.status === 0) {
+					mergedHEAD = postMergeRef.stdout.trim();
+				}
+			}
+
+			// ── TP-033: Initialize transaction record for this lane ──
+			let txnStatus: TransactionStatus = failedLane !== null ? "merge_failed" : "committed";
+			let txnRollbackAttempted = false;
+			let txnRollbackResult: string | null = null;
+			let txnRecoveryCommands: string[] = [];
+
+			// ── Orchestrator-side post-merge verification (TP-032) ──────
+			// After a successful merge (SUCCESS/CONFLICT_RESOLVED), capture
+			// post-merge fingerprints and diff against baseline. New failures
+			// that weren't in the baseline block merge advancement.
+			if (
+				baseline !== null &&
+				hasTestingCommands &&
+				verificationEnabled &&
+				failedLane === null &&
+				(mergeResult.status === "SUCCESS" || mergeResult.status === "CONFLICT_RESOLVED")
+			) {
+				const verificationResult = runPostMergeVerification(
+					testingCommands!,
+					mergeWorkDir,
+					baseline,
+					lane.laneNumber,
+					waveIndex,
+					batchId,
+					opId,
+					sessionName,
+					stateRoot ?? repoRoot,
+					repoId,
+					flakyReruns,
+				);
+
+				// Attach verification result to the lane result
+				laneResult.verificationBaseline = verificationResult;
+
+				if (verificationResult.classification === "verification_new_failure") {
+					execLog("merge", sessionName, "orchestrator-side verification detected new failures", {
+						newFailures: verificationResult.newFailureCount,
+						preExisting: verificationResult.preExistingCount,
+						summary: verificationResult.newFailureSummary.slice(0, 200),
+					});
+
+					// ── TP-032: Rollback merge commit on verification_new_failure ──
+					// Reset the temp branch to pre-lane HEAD so the failed lane's
+					// merge commit doesn't get included in branch advancement.
+					// TP-032 R006-2: Mark lane as errored so it's excluded from success
+					// counters and branch advancement (R006-3).
+					laneResult.error = `verification_new_failure: ${verificationResult.newFailureCount} new failure(s)`;
+
+					if (preLaneHead) {
+						txnRollbackAttempted = true;
+						execLog("merge", sessionName, "rolling back temp branch to pre-lane HEAD", {
+							preLaneHead: preLaneHead.slice(0, 8),
+						});
+						const resetResult = spawnSync("git", ["reset", "--hard", preLaneHead], { cwd: mergeWorkDir });
+						if (resetResult.status === 0) {
+							execLog("merge", sessionName, "temp branch rolled back successfully");
+							txnStatus = "rolled_back";
+							txnRollbackResult = "success";
+						} else {
+							// TP-032 R006-2: Rollback failure is merge-fatal for this wave.
+							// The temp branch still contains the failing merge commit — target
+							// ref advancement MUST NOT proceed for ANY lane, because the temp
+							// branch HEAD includes the unverified commit.
+							const resetErr = resetResult.stderr?.toString().trim() || "unknown error";
+							laneResult.error = `verification_new_failure: rollback reset failed (${resetErr}) — ` +
+								`temp branch may contain failing merge commit, advancement blocked`;
+							blockAdvancement = true;
+							txnStatus = "rollback_failed";
+							txnRollbackResult = `reset failed: ${resetErr}`;
+
+							// ── TP-033: Safe-stop — emit recovery commands ──
+							txnRecoveryCommands = [
+								`# Recovery: manually reset merge worktree to pre-lane HEAD`,
+								`cd "${mergeWorkDir}"`,
+								`git reset --hard ${preLaneHead}`,
+								`# Then re-run merge or resume orchestration`,
+							];
+							rollbackFailed = true;
+
+							execLog("merge", sessionName, `CRITICAL: rollback reset failed: ${resetErr} — safe-stop triggered`, {
+								preLaneHead: preLaneHead.slice(0, 8),
+								recoveryCommands: txnRecoveryCommands,
+							});
+						}
+					} else {
+						// TP-032 R006-2: No pre-lane HEAD captured — cannot roll back.
+						// Block advancement since the bad commit cannot be removed.
+						laneResult.error = `verification_new_failure: no pre-lane HEAD available for rollback — ` +
+							`advancement blocked`;
+						blockAdvancement = true;
+						txnStatus = "rollback_failed";
+						txnRollbackAttempted = false;
+						txnRollbackResult = "no baseHEAD captured — rollback impossible";
+
+						// ── TP-033: Safe-stop — emit recovery commands ──
+						txnRecoveryCommands = [
+							`# Recovery: no baseHEAD was captured for rollback`,
+							`# Inspect merge worktree state manually:`,
+							`cd "${mergeWorkDir}"`,
+							`git log --oneline -5`,
+							`# Determine the correct pre-merge commit and reset:`,
+							`# git reset --hard <correct-commit>`,
+						];
+						rollbackFailed = true;
+
+						execLog("merge", sessionName, "CRITICAL: no baseHEAD — cannot roll back, safe-stop triggered");
+					}
+
+					failedLane = lane.laneNumber;
+					failureReason = `Verification baseline comparison detected ${verificationResult.newFailureCount} new failure(s) ` +
+						`in lane ${lane.laneNumber} (${verificationResult.preExistingCount} pre-existing). ` +
+						verificationResult.newFailureSummary.slice(0, 300);
+				} else if (verificationResult.classification === "flaky_suspected") {
+					execLog("merge", sessionName, "flaky test suspected — failures disappeared on re-run (warning only)", {
+						newFailures: verificationResult.newFailureCount,
+						flakyRerun: true,
+					});
+					// Warning only — does not block merge advancement
+				} else {
+					execLog("merge", sessionName, "orchestrator-side verification passed", {
+						preExisting: verificationResult.preExistingCount,
+						fixed: verificationResult.fixedCount,
+					});
+				}
+			}
+
+			// ── TP-033: Persist transaction record for this lane ──
+			const txnRecord: TransactionRecord = {
+				opId,
+				batchId,
+				waveIndex,
+				laneNumber: lane.laneNumber,
+				repoId: repoId ?? null,
+				baseHEAD,
+				laneHEAD,
+				mergedHEAD,
+				status: txnStatus,
+				rollbackAttempted: txnRollbackAttempted,
+				rollbackResult: txnRollbackResult,
+				recoveryCommands: txnRecoveryCommands,
+				startedAt: txnStartedAt,
+				completedAt: new Date().toISOString(),
+			};
+			transactionRecords.push(txnRecord);
+			const txnPersistError = persistTransactionRecord(txnRecord, stateRoot ?? repoRoot);
+			if (txnPersistError) persistenceErrors.push(txnPersistError);
+
 			// Stop merging if this lane failed
 			if (failedLane !== null) break;
 
@@ -749,6 +1335,27 @@ export function mergeWave(
 				repoId: lane.repoId,
 			});
 
+			// ── TP-033: Transaction record for merge error ──
+			const errorTxnRecord: TransactionRecord = {
+				opId,
+				batchId,
+				waveIndex,
+				laneNumber: lane.laneNumber,
+				repoId: repoId ?? null,
+				baseHEAD,
+				laneHEAD,
+				mergedHEAD: null,
+				status: "merge_failed",
+				rollbackAttempted: false,
+				rollbackResult: null,
+				recoveryCommands: [],
+				startedAt: txnStartedAt,
+				completedAt: new Date().toISOString(),
+			};
+			transactionRecords.push(errorTxnRecord);
+			const errorTxnPersistError = persistTransactionRecord(errorTxnRecord, stateRoot ?? repoRoot);
+			if (errorTxnPersistError) persistenceErrors.push(errorTxnPersistError);
+
 			failedLane = lane.laneNumber;
 			failureReason = `Merge error in lane ${lane.laneNumber}: ${errMsg}`;
 			break;
@@ -756,57 +1363,93 @@ export function mergeWave(
 	}
 
 	// ── Stage workspace task artifacts into merge worktree ──────────
-	// In workspace mode, workers write .DONE and STATUS.md to the canonical
-	// task folder (e.g., shared-libs/task-management/...) which is the repo's
-	// checked-out working tree (develop). These files need to be on the orch
-	// branch, not develop. Copy them into the merge worktree (which is on the
-	// orch branch's temp) and commit, so they're included in the update-ref.
+	// TP-035: Tightened artifact staging — only allowlisted task-owned files
+	// are staged. The allowlist is derived per-task-folder from completed lanes:
+	// exactly `.DONE`, `STATUS.md`, and `REVIEW_VERDICT.json` (when present).
+	// Files outside known task folders, worktree internals, and repo-escape
+	// paths are rejected. Uses resolve+relative path containment consistent
+	// with ensureTaskFilesCommitted() in execution.ts.
 	if (mergeWorkDir) {
-		const statusResult = spawnSync("git", ["status", "--porcelain"], { cwd: repoRoot, encoding: "utf-8" });
-		if (statusResult.status === 0 && statusResult.stdout) {
-			const lines = statusResult.stdout.split("\n").filter((l: string) => l.trim());
-			const artifactFiles = lines
-				.map((l: string) => l.slice(3).trim())
-				.filter((f: string) => f.endsWith(".DONE") || f.endsWith("STATUS.md"));
-
-			if (artifactFiles.length > 0) {
-				let staged = 0;
-				for (const file of artifactFiles) {
-					const srcPath = join(repoRoot, file);
-					const destPath = join(mergeWorkDir, file);
-					try {
-						if (existsSync(srcPath)) {
-							mkdirSync(dirname(destPath), { recursive: true });
-							copyFileSync(srcPath, destPath);
-							spawnSync("git", ["add", file], { cwd: mergeWorkDir });
-							staged++;
-						}
-					} catch { /* best effort */ }
+		// Build the set of allowed artifact paths (repo-root-relative) from
+		// the completed lanes' task folders.
+		const ALLOWED_ARTIFACT_NAMES = [".DONE", "STATUS.md", "REVIEW_VERDICT.json"];
+		const resolvedRepoRoot = resolve(repoRoot);
+		const allowedRelPaths = new Set<string>();
+
+		for (const lane of orderedLanes) {
+			for (const allocTask of lane.tasks) {
+				const absFolder = resolve(allocTask.task.taskFolder);
+				const relFolder = relative(resolvedRepoRoot, absFolder).replace(/\\/g, "/");
+
+				// Reject paths that escape the repo root
+				if (relFolder.startsWith("..") || relFolder.startsWith("/")) {
+					execLog("merge", `W${waveIndex}`, `skipping task folder outside repo root`, {
+						taskId: allocTask.taskId,
+						folder: relFolder,
+					});
+					continue;
 				}
-				if (staged > 0) {
-					spawnSync("git", ["commit", "-m", `checkpoint: wave ${waveIndex} task artifacts (.DONE, STATUS.md)`], { cwd: mergeWorkDir });
-					execLog("merge", `W${waveIndex}`, `committed ${staged} task artifact(s) to merge worktree`);
-
-					// Restore .DONE files only — these are untracked and would cause
-					// "dirty working tree" issues on /orch-integrate.
-					// Keep STATUS.md modifications in develop's working tree so the
-					// dashboard can read current progress from the canonical path.
-					for (const file of artifactFiles) {
-						if (file.endsWith(".DONE")) {
-							const srcPath = join(repoRoot, file);
-							try { if (existsSync(srcPath)) unlinkSync(srcPath); } catch { /* best effort */ }
-						}
-					}
+
+				for (const name of ALLOWED_ARTIFACT_NAMES) {
+					allowedRelPaths.add(`${relFolder}/${name}`);
 				}
 			}
 		}
+
+		if (allowedRelPaths.size > 0) {
+			let staged = 0;
+			let skipped = 0;
+
+			for (const relPath of allowedRelPaths) {
+				const srcPath = join(repoRoot, relPath);
+				if (!existsSync(srcPath)) continue; // File not present (e.g., no REVIEW_VERDICT.json) — skip silently
+
+				const destPath = join(mergeWorkDir, relPath);
+				try {
+					mkdirSync(dirname(destPath), { recursive: true });
+					copyFileSync(srcPath, destPath);
+					// Use pathspec-safe staging with -- separator
+					spawnSync("git", ["add", "--", relPath], { cwd: mergeWorkDir });
+					staged++;
+				} catch {
+					skipped++;
+					execLog("merge", `W${waveIndex}`, `failed to stage artifact`, { path: relPath });
+				}
+			}
+
+			if (staged > 0) {
+				spawnSync("git", ["commit", "-m", `checkpoint: wave ${waveIndex} task artifacts (.DONE, STATUS.md, REVIEW_VERDICT.json)`], { cwd: mergeWorkDir });
+				execLog("merge", `W${waveIndex}`, `committed ${staged} task artifact(s) to merge worktree`, {
+					skipped,
+					allowedCandidates: allowedRelPaths.size,
+				});
+			} else {
+				execLog("merge", `W${waveIndex}`, `no task artifacts to stage (0 of ${allowedRelPaths.size} candidates present/changed)`);
+			}
+
+			// Keep both .DONE and STATUS.md in develop's working tree:
+			// - STATUS.md: dashboard reads current progress from canonical path
+			// - .DONE: harmless untracked files, cleaned up by /orch-integrate stash
+			// Previous approach of deleting .DONE caused them to be missing
+			// after ff integration (git couldn't reliably restore them).
+		}
 	}
 
 	// ── Update target branch ref and clean up merge worktree ────────
-	const anySuccess = laneResults.some(
-		r => r.result?.status === "SUCCESS" || r.result?.status === "CONFLICT_RESOLVED",
+	// TP-032 R006-2: blockAdvancement overrides all success determination.
+	// When verification rollback fails, the temp branch contains a bad merge commit
+	// that would be included in branch advancement — so we block entirely.
+	// Also exclude verification_new_failure lanes (with successful rollback) from
+	// success accounting: they have laneResult.error set, so !r.error filters them.
+	const anySuccess = !blockAdvancement && laneResults.some(
+		r => !r.error && (r.result?.status === "SUCCESS" || r.result?.status === "CONFLICT_RESOLVED"),
 	);
 
+	if (blockAdvancement) {
+		execLog("merge", `W${waveIndex}`, "branch advancement BLOCKED due to verification rollback failure — " +
+			"temp branch may contain unverified merge commit");
+	}
+
 	if (anySuccess) {
 		// Get the temp branch HEAD commit — this is the merged result.
 		const revParseResult = spawnSync("git", ["rev-parse", tempBranch], { cwd: repoRoot });
@@ -886,15 +1529,25 @@ export function mergeWave(
 		}
 	}
 
-	// Clean up merge worktree and temp branch (always, regardless of outcome)
-	try {
-		spawnSync("git", ["worktree", "remove", mergeWorkDir, "--force"], { cwd: repoRoot });
-	} catch { /* best effort */ }
-	try {
-		// Small delay to ensure worktree lock is released
-		sleepSync(500);
-		spawnSync("git", ["branch", "-D", tempBranch], { cwd: repoRoot });
-	} catch { /* best effort */ }
+	// Clean up merge worktree and temp branch.
+	// TP-033: When rollback failed (safe-stop), preserve merge worktree and temp
+	// branch for manual recovery. The operator can use the recovery commands in
+	// the transaction record to restore consistency.
+	if (rollbackFailed) {
+		execLog("merge", `W${waveIndex}`, "SAFE-STOP: preserving merge worktree and temp branch for recovery", {
+			mergeWorkDir,
+			tempBranch,
+		});
+	} else {
+		// TP-029: Apply forceRemoveMergeWorktree fallback so locked/corrupted
+		// merge worktrees don't persist between attempts.
+		forceRemoveMergeWorktree(mergeWorkDir, repoRoot, `W${waveIndex}`);
+		try {
+			// Small delay to ensure worktree lock is released
+			sleepSync(500);
+			spawnSync("git", ["branch", "-D", tempBranch], { cwd: repoRoot });
+		} catch { /* best effort */ }
+	}
 
 	// Determine overall status
 	let status: MergeWaveResult["status"];
@@ -909,12 +1562,12 @@ export function mergeWave(
 	const totalDurationMs = Date.now() - startTime;
 
 	execLog("merge", `W${waveIndex}`, `wave merge complete: ${status}`, {
-		mergedLanes: laneResults.filter(r => r.result?.status === "SUCCESS" || r.result?.status === "CONFLICT_RESOLVED").length,
+		mergedLanes: laneResults.filter(r => !r.error && (r.result?.status === "SUCCESS" || r.result?.status === "CONFLICT_RESOLVED")).length,
 		failedLane: failedLane ?? 0,
 		duration: `${Math.round(totalDurationMs / 1000)}s`,
 	});
 
-	return {
+	const result: MergeWaveResult = {
 		waveIndex,
 		status,
 		laneResults,
@@ -922,6 +1575,21 @@ export function mergeWave(
 		failureReason,
 		totalDurationMs,
 	};
+
+	// TP-033: Attach transaction metadata
+	if (transactionRecords.length > 0) {
+		result.transactionRecords = transactionRecords;
+	}
+	if (rollbackFailed) {
+		result.rollbackFailed = true;
+	}
+	// TP-033 R004-2: Surface persistence failures so operator knows
+	// recovery guidance may reference missing transaction record files
+	if (persistenceErrors.length > 0) {
+		result.persistenceErrors = persistenceErrors;
+	}
+
+	return result;
 }
 
 
@@ -1000,6 +1668,7 @@ export function mergeWaveByRepo(
 	workspaceConfig?: WorkspaceConfig | null,
 	stateRoot?: string,
 	agentRoot?: string,
+	testingCommands?: Record<string, string>,
 ): MergeWaveResult {
 	const startTime = Date.now();
 
@@ -1054,6 +1723,7 @@ export function mergeWaveByRepo(
 			baseBranch,
 			stateRoot,
 			agentRoot,
+			testingCommands,
 		);
 		// Attach empty repoResults for consistent shape
 		return { ...result, repoResults: [] };
@@ -1062,6 +1732,9 @@ export function mergeWaveByRepo(
 	// ── Workspace mode: per-repo merge loops ─────────────────────
 	const allLaneResults: MergeLaneResult[] = [];
 	const repoOutcomes: RepoMergeOutcome[] = [];
+	const allTransactionRecords: TransactionRecord[] = [];
+	// TP-033 R004-2: Accumulate persistence errors across all repo groups
+	const allPersistenceErrors: string[] = [];
 	let firstFailedLane: number | null = null;
 	let firstFailureReason: string | null = null;
 	// Track repo-level failures independently of lane-level failures.
@@ -1069,6 +1742,8 @@ export function mergeWaveByRepo(
 	// pre-lane setup errors (temp branch creation, worktree creation).
 	// We must detect these to avoid misclassifying the aggregate as "succeeded".
 	let anyRepoFailed = false;
+	// TP-033: Track rollback failures across all repo groups
+	let anyRollbackFailed = false;
 
 	for (const group of repoGroups) {
 		const groupRepoRoot = resolveRepoRoot(group.repoId, repoRoot, workspaceConfig);
@@ -1103,11 +1778,25 @@ export function mergeWaveByRepo(
 			groupBaseBranch,
 			stateRoot,
 			agentRoot,
+			testingCommands,
+			group.repoId,
 		);
 
 		// Accumulate lane results
 		allLaneResults.push(...groupResult.laneResults);
 
+		// TP-033: Accumulate transaction records and rollback status
+		if (groupResult.transactionRecords) {
+			allTransactionRecords.push(...groupResult.transactionRecords);
+		}
+		// TP-033 R004-2: Accumulate persistence errors
+		if (groupResult.persistenceErrors) {
+			allPersistenceErrors.push(...groupResult.persistenceErrors);
+		}
+		if (groupResult.rollbackFailed) {
+			anyRollbackFailed = true;
+		}
+
 		// Build per-repo outcome
 		const repoOutcome: RepoMergeOutcome = {
 			repoId: group.repoId,
@@ -1132,6 +1821,20 @@ export function mergeWaveByRepo(
 					: `[repo:${group.repoId ?? "default"}] Merge failed (setup error)`;
 			}
 		}
+
+		// TP-033 R004-1: Safe-stop — halt all remaining repo merges immediately
+		// when a rollback failure is detected. Continuing would advance refs in
+		// other repos, making manual recovery harder.
+		if (anyRollbackFailed) {
+			const processedIndex = repoGroups.indexOf(group);
+			const remainingGroups = repoGroups.slice(processedIndex + 1);
+			if (remainingGroups.length > 0) {
+				execLog("merge", `W${waveIndex}`, `safe-stop: skipping ${remainingGroups.length} remaining repo group(s) after rollback failure`, {
+					skippedRepos: remainingGroups.map(g => g.repoId ?? "(default)").join(", "),
+				});
+			}
+			break;
+		}
 	}
 
 	// ── Aggregate status ─────────────────────────────────────────
@@ -1139,8 +1842,9 @@ export function mergeWaveByRepo(
 	// - anyLaneSucceeded: at least one lane merged successfully across all repos
 	// - anyRepoFailed: at least one repo had a non-succeeded status (includes
 	//   both lane-level failures AND repo setup failures with failedLane=null)
+	// TP-032 R006-3: Exclude verification_new_failure lanes from success determination
 	const anyLaneSucceeded = allLaneResults.some(
-		r => r.result?.status === "SUCCESS" || r.result?.status === "CONFLICT_RESOLVED",
+		r => !r.error && (r.result?.status === "SUCCESS" || r.result?.status === "CONFLICT_RESOLVED"),
 	);
 
 	let status: MergeWaveResult["status"];
@@ -1157,11 +1861,11 @@ export function mergeWaveByRepo(
 	execLog("merge", `W${waveIndex}`, `repo-scoped wave merge complete: ${status}`, {
 		repoCount: repoOutcomes.length,
 		repoStatuses: repoOutcomes.map(r => `${r.repoId ?? "default"}:${r.status}`).join(", "),
-		mergedLanes: allLaneResults.filter(r => r.result?.status === "SUCCESS" || r.result?.status === "CONFLICT_RESOLVED").length,
+		mergedLanes: allLaneResults.filter(r => !r.error && (r.result?.status === "SUCCESS" || r.result?.status === "CONFLICT_RESOLVED")).length,
 		duration: `${Math.round(totalDurationMs / 1000)}s`,
 	});
 
-	return {
+	const aggregateResult: MergeWaveResult = {
 		waveIndex,
 		status,
 		laneResults: allLaneResults,
@@ -1170,6 +1874,20 @@ export function mergeWaveByRepo(
 		totalDurationMs,
 		repoResults: repoOutcomes,
 	};
+
+	// TP-033: Attach transaction metadata from all repo groups
+	if (allTransactionRecords.length > 0) {
+		aggregateResult.transactionRecords = allTransactionRecords;
+	}
+	if (anyRollbackFailed) {
+		aggregateResult.rollbackFailed = true;
+	}
+	// TP-033 R004-2: Surface persistence errors from all repo groups
+	if (allPersistenceErrors.length > 0) {
+		aggregateResult.persistenceErrors = allPersistenceErrors;
+	}
+
+	return aggregateResult;
 }
 
 // ── Auto-Integration ─────────────────────────────────────────────────