@pi-agents/orchid 0.1.0-beta.0

package/src/orchestrator/merge.ts

@@ -0,0 +1,3414 @@
+/**
+ * Merge orchestration, merge agents, merge worktree
+ * @module orch/merge
+ */
+import {
+	readFileSync,
+	writeFileSync,
+	existsSync,
+	unlinkSync,
+	copyFileSync,
+	mkdirSync,
+	rmSync,
+	readdirSync,
+	type Dirent,
+} from "fs";
+import { readFile as fsReadFile } from "fs/promises";
+import { execSync, spawnSync } from "child_process";
+import { join, dirname, resolve, relative } from "path";
+
+import { execLog, isV2AgentAlive, setV2LivenessRegistryCache } 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_MAX_RETRIES,
+	MERGE_TIMEOUT_MS,
+	MERGE_HEALTH_POLL_INTERVAL_MS,
+	MERGE_HEALTH_WARNING_THRESHOLD_MS,
+	MERGE_HEALTH_STUCK_THRESHOLD_MS,
+	MergeError,
+	VALID_MERGE_STATUSES,
+	buildEngineEventBase,
+} from "./types.ts";
+import type {
+	AllocatedLane,
+	LaneExecutionResult,
+	MergeLaneResult,
+	MergeResult,
+	MergeResultStatus,
+	MergeWaveResult,
+	OrchestratorConfig,
+	RepoMergeOutcome,
+	TaskRunnerConfig,
+	TransactionRecord,
+	TransactionStatus,
+	VerificationBaselineResult,
+	WaveExecutionResult,
+	WorkspaceConfig,
+	MergeHealthStatus,
+	MergeHealthEventType,
+	MergeSessionSnapshot,
+	MergeSessionHealthState,
+	EngineEvent,
+	OrchBatchPhase,
+	RuntimeMergeSnapshot,
+	RuntimeAgentTelemetrySnapshot,
+} from "./types.ts";
+import { resolveBaseBranch, resolveRepoRoot } from "./waves.ts";
+import {
+	readManifest,
+	writeManifest,
+	buildRegistrySnapshot,
+	writeRegistrySnapshot,
+	readRegistrySnapshot,
+	writeMergeSnapshot,
+} from "./process-registry.ts";
+import { generateMergeWorktreePath, sleepAsync, sleepSync } from "./worktree.ts";
+import { getCurrentBranch, runGit } from "./git.ts";
+import { ORCH_MESSAGES } from "./messages.ts";
+import { emitEngineEvent } from "./persistence.ts";
+import { loadOrchestratorConfig } from "./config.ts";
+import {
+	captureBaseline,
+	diffFingerprints,
+	runVerificationCommands,
+	parseTestOutput,
+	deduplicateFingerprints,
+} from "./verification.ts";
+import { spawnAgent } from "./agent-host.ts";
+import type { AgentHostOptions, AgentHostResult, AgentTelemetryCallback } from "./agent-host.ts";
+import { loadPiSettingsPackages, filterExcludedExtensions } from "./settings-loader.ts";
+import type { RuntimeBackend } from "./execution.ts";
+import type { VerificationBaseline, FingerprintDiff, TestFingerprint } from "./verification.ts";
+
+// ── Merge Implementation ─────────────────────────────────────────────
+
+/**
+ * Parse and validate a merge result JSON file.
+ *
+ * Strict validation:
+ * - Must be valid JSON
+ * - Must have required fields: status, source_branch, verification
+ * - status must be a known MergeResultStatus
+ * - Unknown status values are mapped to BUILD_FAILURE (fail-safe)
+ *
+ * Retry-read strategy: if initial parse fails, waits and retries up to
+ * MERGE_RESULT_READ_RETRIES times to handle partially-written files.
+ *
+ * @param resultPath - Absolute path to the merge result JSON file
+ * @returns Validated MergeResult
+ * @throws MergeError with appropriate code on validation failure
+ */
+export function parseMergeResult(resultPath: string): MergeResult {
+	if (!existsSync(resultPath)) {
+		throw new MergeError("MERGE_RESULT_INVALID", `Merge result file not found: ${resultPath}`);
+	}
+
+	const pickString = (obj: Record<string, unknown>, ...keys: string[]): string | null => {
+		for (const key of keys) {
+			const value = obj[key];
+			if (typeof value === "string" && value.trim().length > 0) {
+				return value;
+			}
+		}
+		return null;
+	};
+
+	const hasFlatVerification = (obj: Record<string, unknown>): boolean =>
+		typeof obj.verification_passed === "boolean" ||
+		Array.isArray(obj.verification_commands) ||
+		typeof obj.verification_output === "string" ||
+		typeof obj.verification_exit_code === "number";
+
+	const normalizeVerification = (
+		obj: Record<string, unknown>,
+	): MergeResult["verification"] | null => {
+		const nested =
+			obj.verification && typeof obj.verification === "object"
+				? (obj.verification as Record<string, unknown>)
+				: null;
+
+		if (!nested && !hasFlatVerification(obj)) {
+			return null;
+		}
+
+		const passedFromBool =
+			(nested && typeof nested.passed === "boolean" ? nested.passed : undefined) ??
+			(nested && typeof nested.all_passed === "boolean" ? nested.all_passed : undefined) ??
+			(typeof obj.verification_passed === "boolean" ? obj.verification_passed : undefined);
+
+		const exitCode =
+			(nested && typeof nested.exitCode === "number" ? nested.exitCode : undefined) ??
+			(nested && typeof nested.exit_code === "number" ? nested.exit_code : undefined) ??
+			(typeof obj.verification_exit_code === "number" ? obj.verification_exit_code : undefined);
+
+		const passed =
+			typeof passedFromBool === "boolean"
+				? passedFromBool
+				: typeof exitCode === "number"
+					? exitCode === 0
+					: false;
+
+		const ran =
+			nested && typeof nested.ran === "boolean"
+				? nested.ran
+				: typeof passedFromBool === "boolean" ||
+					typeof exitCode === "number" ||
+					(nested && typeof nested.command === "string") ||
+					(nested && typeof nested.summary === "string") ||
+					typeof obj.verification_output === "string" ||
+					Array.isArray(obj.verification_commands);
+
+		const output = (
+			(nested && typeof nested.output === "string" ? nested.output : undefined) ??
+			(nested && typeof nested.summary === "string" ? nested.summary : undefined) ??
+			(nested && typeof nested.notes === "string" ? nested.notes : undefined) ??
+			(typeof obj.verification_output === "string" ? obj.verification_output : "")
+		).slice(0, 2000);
+
+		return { ran, passed, output };
+	};
+
+	// Retry-read loop for partially-written files
+	let lastParseError = "";
+	for (let attempt = 1; attempt <= MERGE_RESULT_READ_RETRIES; attempt++) {
+		try {
+			const raw = readFileSync(resultPath, "utf-8").trim();
+			if (!raw) {
+				lastParseError = "File is empty";
+				if (attempt < MERGE_RESULT_READ_RETRIES) {
+					sleepSync(MERGE_RESULT_READ_RETRY_DELAY_MS);
+					continue;
+				}
+				throw new MergeError(
+					"MERGE_RESULT_INVALID",
+					`Merge result file is empty after ${MERGE_RESULT_READ_RETRIES} attempts: ${resultPath}`,
+				);
+			}
+
+			const parsed = JSON.parse(raw) as Record<string, unknown>;
+
+			// Validate required fields
+			if (typeof parsed.status !== "string") {
+				throw new MergeError(
+					"MERGE_RESULT_MISSING_FIELDS",
+					`Merge result missing required field "status": ${resultPath}`,
+				);
+			}
+
+			// Accept known source-field variants written by different merge agents.
+			// Canonical field remains source_branch.
+			const sourceBranch = pickString(parsed, "source_branch", "sourceBranch", "source");
+			if (!sourceBranch) {
+				throw new MergeError(
+					"MERGE_RESULT_MISSING_FIELDS",
+					`Merge result missing required field "source_branch" (accepted aliases: sourceBranch, source): ${resultPath}`,
+				);
+			}
+
+			const verification = normalizeVerification(parsed);
+			if (!verification) {
+				throw new MergeError(
+					"MERGE_RESULT_MISSING_FIELDS",
+					`Merge result missing required field "verification": ${resultPath}`,
+				);
+			}
+
+			// Normalize status to uppercase (merge agents may write lowercase)
+			// TP-195: hoist normalized value to a local string so the
+			// `VALID_MERGE_STATUSES.has()` call typechecks. `parsed.status`
+			// is `unknown` after JSON parse; assigning `String(...)` to a
+			// property of an `any` doesn't propagate `string` type back
+			// through `parsed.status`. Runtime evaluation order is
+			// unchanged.
+			const normalizedStatus = String(parsed.status).toUpperCase();
+			parsed.status = normalizedStatus;
+
+			// Validate status value
+			if (!VALID_MERGE_STATUSES.has(normalizedStatus)) {
+				execLog(
+					"merge",
+					"parse",
+					`unknown merge status "${normalizedStatus}" — treating as BUILD_FAILURE`,
+					{
+						resultPath,
+					},
+				);
+				parsed.status = "BUILD_FAILURE";
+			}
+
+			const targetBranch = pickString(parsed, "target_branch", "targetBranch", "target") ?? "";
+			const mergeCommit = pickString(parsed, "merge_commit", "mergeCommit") ?? "";
+			const conflicts = Array.isArray(parsed.conflicts)
+				? parsed.conflicts
+						.filter(
+							(c): c is { file: string; type: string; resolved: boolean; resolution?: string } =>
+								typeof c === "object" &&
+								c !== null &&
+								typeof (c as { file?: unknown }).file === "string" &&
+								typeof (c as { type?: unknown }).type === "string" &&
+								typeof (c as { resolved?: unknown }).resolved === "boolean",
+						)
+						.map((c) => ({
+							file: c.file,
+							type: c.type,
+							resolved: c.resolved,
+							...(typeof c.resolution === "string" ? { resolution: c.resolution } : {}),
+						}))
+				: [];
+
+			// Normalize optional fields with defaults
+			return {
+				status: parsed.status as MergeResultStatus,
+				source_branch: sourceBranch,
+				target_branch: targetBranch,
+				merge_commit: mergeCommit,
+				conflicts,
+				verification,
+			};
+		} catch (err: unknown) {
+			if (err instanceof MergeError) throw err;
+
+			// JSON parse error — possibly partially written
+			lastParseError = err instanceof Error ? err.message : String(err);
+			if (attempt < MERGE_RESULT_READ_RETRIES) {
+				sleepSync(MERGE_RESULT_READ_RETRY_DELAY_MS);
+				continue;
+			}
+		}
+	}
+
+	throw new MergeError(
+		"MERGE_RESULT_INVALID",
+		`Failed to parse merge result JSON after ${MERGE_RESULT_READ_RETRIES} attempts. ` +
+			`Last error: ${lastParseError}. File: ${resultPath}`,
+	);
+}
+
+/**
+ * Async version of parseMergeResult — reads and validates a merge result
+ * JSON file without blocking the event loop.
+ *
+ * Uses `fs/promises.readFile` instead of `readFileSync` and `sleepAsync`
+ * instead of `sleepSync` for retry delays. Validation semantics and error
+ * codes are identical to the sync version.
+ *
+ * @param resultPath - Path to the merge result JSON file
+ * @returns Promise resolving to a validated MergeResult
+ * @throws MergeError on missing/invalid/unparseable result
+ *
+ * @since TP-070
+ */
+export async function parseMergeResultAsync(resultPath: string): Promise<MergeResult> {
+	if (!existsSync(resultPath)) {
+		throw new MergeError("MERGE_RESULT_INVALID", `Merge result file not found: ${resultPath}`);
+	}
+
+	const pickString = (obj: Record<string, unknown>, ...keys: string[]): string | null => {
+		for (const key of keys) {
+			const value = obj[key];
+			if (typeof value === "string" && value.trim().length > 0) {
+				return value;
+			}
+		}
+		return null;
+	};
+
+	const hasFlatVerification = (obj: Record<string, unknown>): boolean =>
+		typeof obj.verification_passed === "boolean" ||
+		Array.isArray(obj.verification_commands) ||
+		typeof obj.verification_output === "string" ||
+		typeof obj.verification_exit_code === "number";
+
+	const normalizeVerification = (
+		obj: Record<string, unknown>,
+	): MergeResult["verification"] | null => {
+		const nested =
+			obj.verification && typeof obj.verification === "object"
+				? (obj.verification as Record<string, unknown>)
+				: null;
+
+		if (!nested && !hasFlatVerification(obj)) {
+			return null;
+		}
+
+		const passedFromBool =
+			(nested && typeof nested.passed === "boolean" ? nested.passed : undefined) ??
+			(nested && typeof nested.all_passed === "boolean" ? nested.all_passed : undefined) ??
+			(typeof obj.verification_passed === "boolean" ? obj.verification_passed : undefined);
+
+		const exitCode =
+			(nested && typeof nested.exitCode === "number" ? nested.exitCode : undefined) ??
+			(nested && typeof nested.exit_code === "number" ? nested.exit_code : undefined) ??
+			(typeof obj.verification_exit_code === "number" ? obj.verification_exit_code : undefined);
+
+		const passed =
+			typeof passedFromBool === "boolean"
+				? passedFromBool
+				: typeof exitCode === "number"
+					? exitCode === 0
+					: false;
+
+		const ran =
+			nested && typeof nested.ran === "boolean"
+				? nested.ran
+				: typeof passedFromBool === "boolean" ||
+					typeof exitCode === "number" ||
+					(nested && typeof nested.command === "string") ||
+					(nested && typeof nested.summary === "string") ||
+					typeof obj.verification_output === "string" ||
+					Array.isArray(obj.verification_commands);
+
+		const output = (
+			(nested && typeof nested.output === "string" ? nested.output : undefined) ??
+			(nested && typeof nested.summary === "string" ? nested.summary : undefined) ??
+			(nested && typeof nested.notes === "string" ? nested.notes : undefined) ??
+			(typeof obj.verification_output === "string" ? obj.verification_output : "")
+		).slice(0, 2000);
+
+		return { ran, passed, output };
+	};
+
+	// Retry-read loop for partially-written files — async version
+	let lastParseError = "";
+	for (let attempt = 1; attempt <= MERGE_RESULT_READ_RETRIES; attempt++) {
+		try {
+			const raw = (await fsReadFile(resultPath, "utf-8")).trim();
+			if (!raw) {
+				lastParseError = "File is empty";
+				if (attempt < MERGE_RESULT_READ_RETRIES) {
+					await sleepAsync(MERGE_RESULT_READ_RETRY_DELAY_MS);
+					continue;
+				}
+				throw new MergeError(
+					"MERGE_RESULT_INVALID",
+					`Merge result file is empty after ${MERGE_RESULT_READ_RETRIES} attempts: ${resultPath}`,
+				);
+			}
+
+			const parsed = JSON.parse(raw) as Record<string, unknown>;
+
+			// Validate required fields
+			if (typeof parsed.status !== "string") {
+				throw new MergeError(
+					"MERGE_RESULT_MISSING_FIELDS",
+					`Merge result missing required field "status": ${resultPath}`,
+				);
+			}
+
+			const sourceBranch = pickString(parsed, "source_branch", "sourceBranch", "source");
+			if (!sourceBranch) {
+				throw new MergeError(
+					"MERGE_RESULT_MISSING_FIELDS",
+					`Merge result missing required field "source_branch" (accepted aliases: sourceBranch, source): ${resultPath}`,
+				);
+			}
+
+			const verification = normalizeVerification(parsed);
+			if (!verification) {
+				throw new MergeError(
+					"MERGE_RESULT_MISSING_FIELDS",
+					`Merge result missing required field "verification": ${resultPath}`,
+				);
+			}
+
+			// Normalize status to uppercase
+			// TP-195: hoist normalized value to a local string (same rationale
+			// as the parallel block at line ~225 above).
+			const normalizedStatus = String(parsed.status).toUpperCase();
+			parsed.status = normalizedStatus;
+
+			if (!VALID_MERGE_STATUSES.has(normalizedStatus)) {
+				execLog(
+					"merge",
+					"parse",
+					`unknown merge status "${normalizedStatus}" — treating as BUILD_FAILURE`,
+					{
+						resultPath,
+					},
+				);
+				parsed.status = "BUILD_FAILURE";
+			}
+
+			const targetBranch = pickString(parsed, "target_branch", "targetBranch", "target") ?? "";
+			const mergeCommit = pickString(parsed, "merge_commit", "mergeCommit") ?? "";
+			const conflicts = Array.isArray(parsed.conflicts)
+				? parsed.conflicts
+						.filter(
+							(c): c is { file: string; type: string; resolved: boolean; resolution?: string } =>
+								typeof c === "object" &&
+								c !== null &&
+								typeof (c as { file?: unknown }).file === "string" &&
+								typeof (c as { type?: unknown }).type === "string" &&
+								typeof (c as { resolved?: unknown }).resolved === "boolean",
+						)
+						.map((c) => ({
+							file: c.file,
+							type: c.type,
+							resolved: c.resolved,
+							...(typeof c.resolution === "string" ? { resolution: c.resolution } : {}),
+						}))
+				: [];
+
+			return {
+				status: parsed.status as MergeResultStatus,
+				source_branch: sourceBranch,
+				target_branch: targetBranch,
+				merge_commit: mergeCommit,
+				conflicts,
+				verification,
+			};
+		} catch (err: unknown) {
+			if (err instanceof MergeError) throw err;
+
+			lastParseError = err instanceof Error ? err.message : String(err);
+			if (attempt < MERGE_RESULT_READ_RETRIES) {
+				await sleepAsync(MERGE_RESULT_READ_RETRY_DELAY_MS);
+				continue;
+			}
+		}
+	}
+
+	throw new MergeError(
+		"MERGE_RESULT_INVALID",
+		`Failed to parse merge result JSON after ${MERGE_RESULT_READ_RETRIES} attempts. ` +
+			`Last error: ${lastParseError}. File: ${resultPath}`,
+	);
+}
+
+/**
+ * TP-171: Stage task artifacts from skipped-only lanes onto the target branch
+ * using an isolated temporary worktree.
+ *
+ * When no mergeable lanes exist (e.g., all tasks skipped), there is no merge worktree.
+ * This function creates a lightweight temporary worktree on `targetBranch`, copies
+ * STATUS.md, .DONE, REVIEW_VERDICT.json, and .reviews/** from skipped-lane worktrees
+ * into it, commits, advances `targetBranch`, then cleans up the temporary worktree.
+ * This ensures partial worker progress (STATUS.md updates) survives integration.
+ */
+function stageSkippedArtifactsToTargetBranch(
+	lanes: AllocatedLane[],
+	waveIndex: number,
+	repoRoot: string,
+	targetBranch: string,
+): void {
+	// TP-171: Do NOT include .DONE — skipped tasks' code was not merged,
+	// so staging .DONE would create false completion markers.
+	const ALLOWED_NAMES = ["STATUS.md", "REVIEW_VERDICT.json"];
+	const ALLOWED_DIRS = [".reviews"];
+	const resolvedRepoRoot = resolve(repoRoot);
+
+	// Create a temporary worktree on the target branch for isolated artifact staging.
+	// This avoids writing to whatever branch repoRoot has checked out.
+	const tmpWorktreePath = join(repoRoot, "..", `skip-artifacts-w${waveIndex}-${Date.now()}`);
+	const resolvedTmpPath = resolve(tmpWorktreePath);
+
+	try {
+		const addResult = spawnSync("git", ["worktree", "add", resolvedTmpPath, targetBranch], {
+			cwd: repoRoot,
+		});
+		if (addResult.status !== 0) {
+			execLog("merge", `W${waveIndex}`, `failed to create temp worktree for skipped artifacts`, {
+				stderr: addResult.stderr?.toString().trim(),
+			});
+			return;
+		}
+
+		let staged = 0;
+
+		for (const lane of lanes) {
+			if (!lane.worktreePath || !existsSync(lane.worktreePath)) continue;
+			for (const allocTask of lane.tasks) {
+				if (!allocTask.task?.taskFolder?.trim()) continue;
+				// Resolve taskFolder against the lane worktree first (workspace mode:
+				// taskFolder may be relative to the packet repo, not the execution repo).
+				// Fall back to repoRoot if worktreePath is unavailable.
+				const resolveBase = lane.worktreePath ? resolve(lane.worktreePath) : resolvedRepoRoot;
+				const absFolder = resolve(resolveBase, allocTask.task.taskFolder);
+				const relFolder = relative(resolvedRepoRoot, absFolder).replace(/\\/g, "/");
+				if (relFolder.startsWith("..") || relFolder.startsWith("/")) continue;
+
+				for (const name of ALLOWED_NAMES) {
+					const relPath = `${relFolder}/${name}`;
+					const srcPath = join(lane.worktreePath, relPath);
+					if (!existsSync(srcPath)) continue;
+					try {
+						const destPath = join(resolvedTmpPath, relPath);
+						mkdirSync(dirname(destPath), { recursive: true });
+						copyFileSync(srcPath, destPath);
+						spawnSync("git", ["add", "--", relPath], { cwd: resolvedTmpPath });
+						staged++;
+					} catch {
+						/* best effort */
+					}
+				}
+
+				for (const dirName of ALLOWED_DIRS) {
+					const laneDir = join(lane.worktreePath, relFolder, dirName);
+					if (!existsSync(laneDir)) continue;
+					try {
+						const entries = readdirSync(laneDir, { recursive: true, withFileTypes: true });
+						for (const entry of entries) {
+							if (!entry.isFile()) continue;
+							const entryPath = entry.parentPath ? join(entry.parentPath, entry.name) : entry.name;
+							const fileRel = relative(laneDir, entryPath).replace(/\\/g, "/");
+							if (fileRel.startsWith("..")) continue;
+							const relPath = `${relFolder}/${dirName}/${fileRel}`;
+							const srcPath = join(laneDir, fileRel);
+							const destPath = join(resolvedTmpPath, relPath);
+							mkdirSync(dirname(destPath), { recursive: true });
+							copyFileSync(srcPath, destPath);
+							spawnSync("git", ["add", "--", relPath], { cwd: resolvedTmpPath });
+							staged++;
+						}
+					} catch {
+						/* best effort */
+					}
+				}
+			}
+		}
+
+		if (staged > 0) {
+			const commitResult = spawnSync(
+				"git",
+				["commit", "-m", `checkpoint: wave ${waveIndex} skipped-task artifacts (STATUS.md, .reviews)`],
+				{ cwd: resolvedTmpPath },
+			);
+			if (commitResult.status === 0) {
+				execLog("merge", `W${waveIndex}`, `staged ${staged} artifact(s) from skipped-only lanes`, {
+					lanes: lanes.map((l) => l.laneNumber).join(","),
+				});
+			} else {
+				execLog("merge", `W${waveIndex}`, `failed to commit skipped-task artifacts`, {
+					stderr: commitResult.stderr?.toString().trim(),
+				});
+			}
+		}
+	} catch (err: any) {
+		execLog("merge", `W${waveIndex}`, `unexpected error staging skipped artifacts`, {
+			error: err?.message,
+		});
+	} finally {
+		// Clean up the temporary worktree
+		try {
+			spawnSync("git", ["worktree", "remove", "--force", resolvedTmpPath], { cwd: repoRoot });
+		} catch {
+			/* best effort cleanup */
+		}
+		try {
+			if (existsSync(resolvedTmpPath)) {
+				rmSync(resolvedTmpPath, { recursive: true, force: true });
+			}
+		} catch {
+			/* best effort cleanup */
+		}
+	}
+}
+
+/**
+ * Determine merge order for completed lanes.
+ *
+ * Default heuristic: fewest-files-first.
+ * - Lanes with fewer files in their file scope merge first
+ * - Smaller changes are less likely to conflict, establishing a clean base
+ * - Tie-breaker: branch name alphabetically (deterministic)
+ *
+ * Alternative: sequential (lane number order).
+ *
+ * @param lanes  - Completed lanes to order
+ * @param order  - Ordering strategy from config
+ * @returns Lanes sorted in merge order
+ */
+export function determineMergeOrder(
+	lanes: AllocatedLane[],
+	order: "fewest-files-first" | "sequential",
+): AllocatedLane[] {
+	const sorted = [...lanes];
+
+	if (order === "sequential") {
+		sorted.sort((a, b) => a.laneNumber - b.laneNumber);
+		return sorted;
+	}
+
+	// fewest-files-first: count total file scope across all tasks in the lane
+	sorted.sort((a, b) => {
+		const aFiles = a.tasks.reduce((sum, t) => sum + (t.task?.fileScope?.length || 0), 0);
+		const bFiles = b.tasks.reduce((sum, t) => sum + (t.task?.fileScope?.length || 0), 0);
+
+		if (aFiles !== bFiles) return aFiles - bFiles;
+
+		// Tie-breaker: branch name alphabetically
+		return a.branch.localeCompare(b.branch);
+	});
+
+	return sorted;
+}
+
+/**
+ * Build merge request content for the merge agent.
+ *
+ * The merge request is a structured text document that tells the merge agent:
+ * - Which branch to merge (source)
+ * - Which branch to merge into (target)
+ * - What tasks were completed in this lane
+ * - File scope of those tasks
+ * - Verification commands to run
+ * - Where to write the result file
+ *
+ * @param lane           - The lane to merge
+ * @param targetBranch   - Target branch (typically "develop")
+ * @param waveIndex      - Wave number (1-indexed)
+ * @param verifyCommands - Verification commands from config
+ * @param resultFilePath - Path where the merge agent should write results
+ * @returns Formatted merge request text
+ */
+export function buildMergeRequest(
+	lane: AllocatedLane,
+	targetBranch: string,
+	waveIndex: number,
+	verifyCommands: string[],
+	resultFilePath: string,
+): string {
+	const taskIds = lane.tasks.map((t) => t.taskId).join(", ");
+	// TP-169: Guard against null task stubs from reconstructAllocatedLanes
+	const fileScopes = lane.tasks
+		.flatMap((t) => t.task?.fileScope || [])
+		.filter((f, i, arr) => arr.indexOf(f) === i); // deduplicate
+
+	const mergeMessage = `merge: wave ${waveIndex} lane ${lane.laneNumber} — ${taskIds}`;
+
+	const lines: string[] = [
+		"# Merge Request",
+		"",
+		`## Source Branch`,
+		`${lane.branch}`,
+		"",
+		`## Target Branch`,
+		`${targetBranch}`,
+		"",
+		`## Merge Message`,
+		`${mergeMessage}`,
+		"",
+		`## Tasks Completed`,
+		...lane.tasks.map((t) => `- ${t.taskId}: ${t.task?.taskName ?? "(unknown)"}`),
+		"",
+		`## File Scope`,
+		...(fileScopes.length > 0 ? fileScopes.map((f) => `- ${f}`) : ["- (no file scope declared)"]),
+		"",
+		`## Verification Commands`,
+		...verifyCommands.map((cmd) => `\`\`\`bash\n${cmd}\n\`\`\``),
+		"",
+		`## Result File`,
+		`result_file: ${resultFilePath.split("\\").join("/")}`,
+		`Write your JSON result to EXACTLY this path (do NOT modify or convert it): ${resultFilePath.split("\\").join("/")}`,
+		"",
+		"## Result JSON Schema (required)",
+		"Use EXACT snake_case keys shown below. Do not use camelCase or shortened keys.",
+		"",
+		"```json",
+		"{",
+		'  "status": "SUCCESS" | "CONFLICT_RESOLVED" | "CONFLICT_UNRESOLVED" | "BUILD_FAILURE",',
+		'  "source_branch": "<source branch name>",',
+		'  "target_branch": "<target branch name>",',
+		'  "merge_commit": "<merge commit sha or empty string>",',
+		'  "conflicts": [{ "file": "...", "type": "...", "resolved": true|false }],',
+		'  "verification": { "ran": true|false, "passed": true|false, "output": "..." }',
+		"}",
+		"```",
+		"",
+		"Do NOT use keys like source/sourceBranch/target/mergeCommit.",
+		"Write valid JSON only (no markdown around the final file).",
+		"",
+		"## Important",
+		"- You are working in an ISOLATED MERGE WORKTREE (not the user's main repo)",
+		"- The correct branch is ALREADY checked out — do NOT checkout any other branch",
+		"- Simply merge the source branch into the current HEAD",
+		"- Run ALL verification commands after a successful merge",
+		"- If verification fails, revert the merge commit before writing the result",
+		"- Write the result file LAST, after all git operations are complete",
+	];
+
+	return lines.join("\n");
+}
+
+/**
+ * Spawn a merge agent via Runtime V2 direct agent-host (no terminal multiplexer).
+ *
+ * Per Runtime V2 spec (02-runtime-process-model.md §8.3):
+ * "engine spawns merge host directly" — the merge agent runs as a direct
+ * child process via agent-host, with process registry tracking, normalized
+ * events, and deterministic exit classification.
+ *
+ * The merge agent receives the merge request as its prompt and writes
+ * a result JSON file. The caller polls for that result file (same contract
+ * as the legacy session-backed path via waitForMergeResult).
+ *
+ * @param sessionName     - Stable agent ID (e.g., "orch-merge-1")
+ * @param repoRoot        - Main repository root (merge happens here)
+ * @param mergeWorkDir    - Working directory for the merge
+ * @param mergeRequestPath - Path to the merge request file
+ * @param config          - Orchestrator config
+ * @param stateRoot       - Root for state files / registry
+ * @param agentRoot       - Root for agent prompts
+ * @param batchId         - Current batch ID
+ * @returns Promise that resolves when the agent exits
+ *
+ * @since TP-108
+ */
+// TP-195: return type changed from `Promise<AgentHostResult>` to
+// `Promise<void>` to match actual semantics. The function never returns a
+// value — it spawns the merge agent, attaches `.then`/`.catch` handlers
+// for fire-and-forget exit logging (line ~912 marker: "Fire-and-forget"),
+// and exits. Both call sites (lines ~1929, ~1942) `await` the returned
+// promise but do not consume its value.
+export async function spawnMergeAgentV2(
+	sessionName: string,
+	repoRoot: string,
+	mergeWorkDir: string,
+	mergeRequestPath: string,
+	config: OrchestratorConfig,
+	stateRoot?: string,
+	agentRoot?: string,
+	batchId?: string,
+	waveIndex?: number,
+): Promise<void> {
+	execLog("merge", sessionName, "spawning merge agent via Runtime V2 (direct agent-host)", {
+		mergeWorkDir,
+		mergeRequestPath,
+	});
+
+	// Read the merge request as the agent prompt
+	const prompt = readFileSync(mergeRequestPath, "utf-8");
+
+	// Resolve merger system prompt
+	const systemPromptCandidates = [
+		agentRoot ? join(agentRoot, "task-merger.md") : "",
+		join(stateRoot ?? repoRoot, ".pi", "agents", "task-merger.md"),
+	].filter(Boolean);
+	const systemPromptPath = systemPromptCandidates.find((p) => existsSync(p)) || "";
+	let systemPrompt: string | undefined;
+	if (systemPromptPath) {
+		try {
+			systemPrompt = readFileSync(systemPromptPath, "utf-8");
+		} catch {
+			/* use default */
+		}
+	}
+
+	// Resolve event/exit paths
+	const sidecarRoot = join(stateRoot ?? repoRoot, ".pi");
+	const bid = batchId || "unknown";
+	const eventsPath = join(sidecarRoot, "runtime", bid, "agents", sessionName, "events.jsonl");
+	const exitSummaryPath = join(
+		sidecarRoot,
+		"runtime",
+		bid,
+		"agents",
+		sessionName,
+		"exit-summary.json",
+	);
+
+	// Mailbox directory
+	let mailboxDir: string | null = null;
+	if (batchId) {
+		mailboxDir = join(sidecarRoot, "mailbox", batchId, sessionName);
+		mkdirSync(join(mailboxDir, "inbox"), { recursive: true });
+	}
+
+	// TP-180: Forward user-installed extensions to merge agent
+	const mergeStateRoot = stateRoot ?? repoRoot;
+	const allMergePackages = loadPiSettingsPackages(mergeStateRoot);
+	const mergeExclusions = config.merge.exclude_extensions ?? [];
+	const mergePackages = filterExcludedExtensions(allMergePackages, mergeExclusions);
+
+	const opts: AgentHostOptions = {
+		agentId: sessionName,
+		role: "merger",
+		batchId: bid,
+		laneNumber: null,
+		taskId: null,
+		repoId: "default",
+		cwd: mergeWorkDir,
+		prompt,
+		systemPrompt,
+		model: config.merge.model || undefined,
+		tools: config.merge.tools || undefined,
+		thinking: config.merge.thinking || undefined,
+		mailboxDir,
+		eventsPath,
+		exitSummaryPath,
+		timeoutMs: (config.merge.timeout_minutes ?? 10) * 60 * 1000,
+		stateRoot: mergeStateRoot,
+		packet: null,
+		...(mergePackages.length > 0 ? { extensions: mergePackages } : {}),
+		env: {
+			ORCH_BATCH_ID: bid,
+		},
+	};
+
+	// Derive the 1-indexed merge number from the session name
+	// (e.g. "orch-henry-merge-1" → 1, "orch-henry-merge-2" → 2).
+	const mergeNumberMatch = sessionName.match(/-merge-(\d+)$/);
+	if (!mergeNumberMatch) {
+		execLog(
+			"merge",
+			sessionName,
+			"warning: could not parse merge number from session name — defaulting to 1",
+			{ sessionName },
+		);
+	}
+	const mergeNumber = mergeNumberMatch ? parseInt(mergeNumberMatch[1], 10) : 1;
+	const mergeStartedAt = Date.now();
+
+	// Helper: build a RuntimeAgentTelemetrySnapshot from a partial AgentHostResult.
+	const buildAgentSnap = (
+		tel: Partial<AgentHostResult>,
+		status: RuntimeAgentTelemetrySnapshot["status"],
+	): RuntimeAgentTelemetrySnapshot => ({
+		agentId: sessionName,
+		status,
+		elapsedMs: tel.durationMs ?? Date.now() - mergeStartedAt,
+		toolCalls: tel.toolCalls ?? 0,
+		contextPct: tel.contextUsage?.percent ?? 0,
+		costUsd: tel.costUsd ?? 0,
+		lastTool: tel.lastTool ?? "",
+		inputTokens: tel.inputTokens ?? 0,
+		outputTokens: tel.outputTokens ?? 0,
+		cacheReadTokens: tel.cacheReadTokens ?? 0,
+		cacheWriteTokens: tel.cacheWriteTokens ?? 0,
+	});
+
+	// Telemetry callback: write a merge snapshot on every telemetry update.
+	// Non-fatal — snapshot writes must never interfere with merge execution.
+	const onMergeTelemetry: AgentTelemetryCallback = (tel) => {
+		try {
+			const snap: RuntimeMergeSnapshot = {
+				batchId: bid,
+				mergeNumber,
+				sessionName,
+				waveIndex: waveIndex ?? 0,
+				status: "running",
+				agent: buildAgentSnap(tel, "running"),
+				updatedAt: Date.now(),
+			};
+			writeMergeSnapshot(mergeStateRoot, bid, waveIndex ?? 0, mergeNumber, snap);
+		} catch {
+			/* non-fatal */
+		}
+	};
+
+	const { promise, kill } = spawnAgent(opts, undefined, onMergeTelemetry);
+
+	// Write an initial "running" snapshot immediately so the dashboard row
+	// appears even when the first telemetry event is delayed.
+	try {
+		const initialSnap: RuntimeMergeSnapshot = {
+			batchId: bid,
+			mergeNumber,
+			sessionName,
+			waveIndex: waveIndex ?? 0,
+			status: "running",
+			agent: buildAgentSnap({}, "running"),
+			updatedAt: Date.now(),
+		};
+		writeMergeSnapshot(mergeStateRoot, bid, waveIndex ?? 0, mergeNumber, initialSnap);
+	} catch {
+		/* non-fatal */
+	}
+
+	// Store the kill handle for external cleanup (pause/abort).
+	// The promise runs in background — caller uses waitForMergeResult()
+	// to poll for the result file, same contract as the legacy session path.
+	activeMergeAgents.set(sessionName, { promise, kill, stateRoot: mergeStateRoot, batchId: bid });
+
+	// Fire-and-forget: the background promise handles exit logging and
+	// writes a terminal snapshot ("complete" or "failed") when the agent exits.
+	promise
+		.then((result) => {
+			activeMergeAgents.delete(sessionName);
+			execLog("merge", sessionName, "merge agent exited (V2)", {
+				exitCode: result.exitCode,
+				durationMs: result.durationMs,
+				costUsd: result.costUsd,
+				killed: result.killed,
+			});
+			// Write terminal snapshot. Promise resolves for both successful and
+			// failed exits, so derive status from result fields rather than
+			// relying on .catch to handle failures.
+			// Determine terminal status. A clean post-success kill sets registry
+			// manifest to "exited" via killMergeAgentV2(name, true=cleanExit).
+			// Check the registry first so a successful-then-killed agent is shown
+			// as "complete" rather than "failed".
+			let terminalStatus: RuntimeMergeSnapshot["status"] = "complete";
+			try {
+				const manifest = readManifest(mergeStateRoot, bid, sessionName as any);
+				if (manifest?.status === "exited") {
+					terminalStatus = "complete";
+				} else if (result.exitCode !== 0 || !result.agentEnded) {
+					terminalStatus = "failed";
+				}
+			} catch {
+				if (result.exitCode !== 0 || !result.agentEnded) terminalStatus = "failed";
+			}
+			try {
+				const snap: RuntimeMergeSnapshot = {
+					batchId: bid,
+					mergeNumber,
+					sessionName,
+					waveIndex: waveIndex ?? 0,
+					status: terminalStatus,
+					agent: buildAgentSnap(result, terminalStatus === "complete" ? "exited" : "crashed"),
+					updatedAt: Date.now(),
+				};
+				writeMergeSnapshot(mergeStateRoot, bid, waveIndex ?? 0, mergeNumber, snap);
+			} catch {
+				/* non-fatal */
+			}
+		})
+		.catch((err) => {
+			activeMergeAgents.delete(sessionName);
+			execLog(
+				"merge",
+				sessionName,
+				`merge agent error (V2): ${err instanceof Error ? err.message : String(err)}`,
+			);
+			// Write a failed terminal snapshot on unexpected rejection.
+			try {
+				const snap: RuntimeMergeSnapshot = {
+					batchId: bid,
+					mergeNumber,
+					sessionName,
+					waveIndex: waveIndex ?? 0,
+					status: "failed",
+					agent: buildAgentSnap({}, "crashed"),
+					updatedAt: Date.now(),
+				};
+				writeMergeSnapshot(mergeStateRoot, bid, waveIndex ?? 0, mergeNumber, snap);
+			} catch {
+				/* non-fatal */
+			}
+		});
+}
+
+/** Active V2 merge agent handles for cleanup/abort. @since TP-108 */
+const activeMergeAgents = new Map<
+	string,
+	{ promise: Promise<AgentHostResult>; kill: () => void; stateRoot?: string; batchId?: string }
+>();
+
+/**
+ * Kill a V2 merge agent if it's still running.
+ * Used by pause/abort/cleanup flows.
+ * @since TP-108
+ */
+export function killMergeAgentV2(sessionName: string, cleanExit?: boolean): boolean {
+	const handle = activeMergeAgents.get(sessionName);
+	if (handle) {
+		handle.kill();
+		// TP-115: On clean post-result cleanup, update manifest to "exited"
+		// so dashboard shows correct status instead of "killed".
+		if (cleanExit && handle.stateRoot && handle.batchId) {
+			try {
+				const manifest = readManifest(handle.stateRoot, handle.batchId, sessionName as any);
+				if (manifest) {
+					manifest.status = "exited";
+					writeManifest(handle.stateRoot, manifest);
+					const snapshot = buildRegistrySnapshot(handle.stateRoot, handle.batchId);
+					writeRegistrySnapshot(handle.stateRoot, snapshot);
+				}
+			} catch {
+				/* best effort */
+			}
+		}
+		activeMergeAgents.delete(sessionName);
+		return true;
+	}
+	return false;
+}
+
+/**
+ * Kill ALL active V2 merge agents. Used by abort flow to ensure
+ * no merge agents survive even when the legacy session list is empty.
+ * @returns Number of agents killed
+ * @since TP-108
+ */
+export function killAllMergeAgentsV2(): number {
+	let killed = 0;
+	for (const [name, handle] of activeMergeAgents) {
+		handle.kill();
+		execLog("merge", name, "V2 merge agent killed by bulk abort");
+		killed++;
+	}
+	activeMergeAgents.clear();
+	return killed;
+}
+
+/**
+ * Re-read merge timeout from config on disk.
+ *
+ * TP-038: Allows the operator to increase `merge.timeoutMinutes` without
+ * restarting the pi session. Called before each retry attempt so the
+ * retry loop picks up any config changes made while the batch was running.
+ *
+ * @param configRoot - The directory containing `.pi/orchid-config.json`
+ * @param pointerConfigRoot - Optional pointer config root (workspace mode)
+ * @returns Fresh timeout in milliseconds
+ */
+export function reloadMergeTimeoutMs(configRoot: string, pointerConfigRoot?: string): number {
+	try {
+		const freshConfig = loadOrchestratorConfig(configRoot, pointerConfigRoot);
+		const minutes = freshConfig.merge.timeout_minutes ?? 90;
+		return minutes * 60 * 1000;
+	} catch (err: unknown) {
+		// Config re-read is best-effort — fall back to default on failure
+		const errMsg = err instanceof Error ? err.message : String(err);
+		execLog(
+			"merge",
+			"config-reload",
+			`failed to re-read merge timeout from config: ${errMsg} — using default`,
+		);
+		return MERGE_TIMEOUT_MS;
+	}
+}
+
+/** Merge result statuses that indicate the merge agent completed successfully. */
+const SUCCESSFUL_MERGE_STATUSES = new Set<string>(["SUCCESS", "CONFLICT_RESOLVED"]);
+
+/**
+ * Wait for merge agent to produce a result file.
+ *
+ * Polling loop with timeout and session liveness detection:
+ * 1. Check if result file exists → parse and return
+ * 2. Check if the merge agent session is still alive
+ * 3. If session died without result → grace period → check again → fail
+ * 4. If timeout exceeded → check result before killing:
+ *    a. If result exists with SUCCESS/CONFLICT_RESOLVED: accept it
+ *       (merge agent slow but succeeded)
+ *    b. If result missing or non-success: kill session → fail
+ *
+ * @param resultPath   - Path to the expected result JSON file
+ * @param sessionName  - Merge session name for liveness checking
+ * @param timeoutMs    - Maximum wait time (default: MERGE_TIMEOUT_MS)
+ * @returns Validated MergeResult
+ * @throws MergeError on timeout, session death, or invalid result
+ */
+export async function waitForMergeResult(
+	resultPath: string,
+	sessionName: string,
+	timeoutMs: number = MERGE_TIMEOUT_MS,
+	runtimeBackend?: RuntimeBackend,
+): Promise<MergeResult> {
+	const startTime = Date.now();
+	let sessionDiedAt: number | null = null;
+	const isV2 = runtimeBackend === "v2";
+
+	execLog("merge", sessionName, "waiting for merge result", {
+		resultPath,
+		timeoutMs,
+		backend: isV2 ? "v2" : "legacy",
+	});
+
+	while (true) {
+		const elapsed = Date.now() - startTime;
+
+		// Check timeout
+		if (elapsed >= timeoutMs) {
+			// TP-038: Check result file BEFORE killing the session.
+			if (existsSync(resultPath)) {
+				try {
+					const lateResult = await parseMergeResultAsync(resultPath);
+					if (SUCCESSFUL_MERGE_STATUSES.has(lateResult.status)) {
+						execLog(
+							"merge",
+							sessionName,
+							"merge agent slow but succeeded — accepting result at timeout",
+							{
+								status: lateResult.status,
+								elapsed,
+								timeoutMs,
+							},
+						);
+						// Clean up agent (may still be running post-write)
+						killMergeAgentV2(sessionName, true);
+						return lateResult;
+					}
+					execLog("merge", sessionName, "merge result exists at timeout but non-success — killing", {
+						status: lateResult.status,
+					});
+				} catch {
+					// Result file unreadable — fall through to kill
+				}
+			}
+
+			execLog("merge", sessionName, "merge timeout — killing agent", { elapsed, timeoutMs });
+			killMergeAgentV2(sessionName);
+
+			throw new MergeError(
+				"MERGE_TIMEOUT",
+				`Merge agent '${sessionName}' did not produce a result within ` +
+					`${Math.round(timeoutMs / 1000)}s. The agent has been killed. ` +
+					`Check the merge request and agent logs.`,
+			);
+		}
+
+		// Check if result file exists
+		if (existsSync(resultPath)) {
+			try {
+				const result = await parseMergeResultAsync(resultPath);
+				execLog("merge", sessionName, "merge result received", {
+					status: result.status,
+					elapsed,
+				});
+				// Clean up agent if still alive
+				killMergeAgentV2(sessionName, true);
+				return result;
+			} catch (err: unknown) {
+				if (err instanceof MergeError && err.code === "MERGE_RESULT_INVALID") {
+					await sleepAsync(MERGE_RESULT_READ_RETRY_DELAY_MS);
+					if (existsSync(resultPath)) {
+						try {
+							return await parseMergeResultAsync(resultPath);
+						} catch {
+							/* give up */
+						}
+					}
+				}
+			}
+		}
+
+		// Check agent liveness — backend-aware
+		// Runtime V2: check active merge agent handle map (process-owned).
+		const agentAlive = activeMergeAgents.has(sessionName);
+
+		if (!agentAlive) {
+			if (sessionDiedAt === null) {
+				sessionDiedAt = Date.now();
+				execLog("merge", sessionName, "agent exited — starting grace period", {
+					graceMs: MERGE_RESULT_GRACE_MS,
+				});
+			} else if (Date.now() - sessionDiedAt >= MERGE_RESULT_GRACE_MS) {
+				// Grace period expired — one final check
+				if (existsSync(resultPath)) {
+					try {
+						return await parseMergeResultAsync(resultPath);
+					} catch {
+						/* fall through */
+					}
+				}
+
+				throw new MergeError(
+					"MERGE_SESSION_DIED",
+					`Merge agent '${sessionName}' exited without writing ` +
+						`a result file to '${resultPath}'. The merge may have crashed. ` +
+						`Check agent logs for diagnostics.`,
+				);
+			}
+		}
+
+		await sleepAsync(MERGE_POLL_INTERVAL_MS);
+	}
+}
+
+/**
+ * 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.
+ *
+ * Orchestration flow:
+ * 1. Filter to only succeeded lanes (failed lanes are not merged)
+ * 2. Determine merge order (fewest-files-first or sequential)
+ * 3. For each lane, sequentially:
+ *    a. Build merge request content
+ *    b. Write merge request to temp file
+ *    c. Spawn merge agent session (in main repo)
+ *    d. Wait for merge result
+ *    e. Handle result (continue, log, or pause)
+ * 4. Return MergeWaveResult
+ *
+ * Sequential execution is mandatory — the base branch is a shared
+ * resource, and each merge must see the prior merge's result.
+ *
+ * On CONFLICT_UNRESOLVED or BUILD_FAILURE: stops merging remaining lanes
+ * and returns with failure status.
+ *
+ * Temp file cleanup: merge request files are cleaned up after each lane,
+ * regardless of outcome. Result files are left for debugging.
+ *
+ * @param completedLanes   - Lanes that completed execution (from wave result)
+ * @param waveResult       - The wave execution result (for lane status filtering)
+ * @param waveIndex        - Wave number (1-indexed)
+ * @param config           - Orchestrator configuration
+ * @param repoRoot         - Main repository root
+ * @param batchId          - Batch ID for session naming
+ * @param baseBranch       - Branch to merge into (captured at batch start)
+ * @returns MergeWaveResult with per-lane outcomes
+ */
+export async function mergeWave(
+	completedLanes: AllocatedLane[],
+	waveResult: WaveExecutionResult,
+	waveIndex: number,
+	config: OrchestratorConfig,
+	repoRoot: string,
+	batchId: string,
+	baseBranch: string,
+	stateRoot?: string,
+	agentRoot?: string,
+	testingCommands?: Record<string, string>,
+	repoId?: string,
+	healthMonitor?: MergeHealthMonitor | null,
+	forceMixedOutcome?: boolean,
+	runtimeBackend?: RuntimeBackend,
+): Promise<MergeWaveResult> {
+	const startTime = Date.now();
+	const sessionPrefix = config.orchestrator.sessionPrefix;
+	const opId = resolveOperatorId(config);
+	const targetBranch = baseBranch;
+	const laneResults: MergeLaneResult[] = [];
+
+	// Build lane outcome lookup for merge eligibility checks.
+	const laneOutcomeByNumber = new Map<number, LaneExecutionResult>();
+	for (const laneOutcome of waveResult.laneResults) {
+		laneOutcomeByNumber.set(laneOutcome.laneNumber, laneOutcome);
+	}
+
+	// A lane is mergeable if:
+	// - It has at least one succeeded task, AND
+	// - It has no hard failures (failed/stalled).
+	//
+	// This allows succeeded+skipped lanes (e.g., stop-wave skip of remaining tasks)
+	// to merge their committed work, while excluding mixed succeeded+failed lanes.
+	//
+	// TP-078: When forceMixedOutcome is true, lanes with both succeeded and
+	// failed/stalled tasks are also considered mergeable. This allows the
+	// orch_force_merge tool to merge succeeded commits from mixed-outcome lanes.
+	const mergeableLanes = completedLanes.filter((lane) => {
+		const outcome = laneOutcomeByNumber.get(lane.laneNumber);
+		if (!outcome) return false;
+
+		const hasSucceeded = outcome.tasks.some((t) => t.status === "succeeded");
+		const hasHardFailure = outcome.tasks.some((t) => t.status === "failed" || t.status === "stalled");
+
+		if (forceMixedOutcome) {
+			// In force mode, merge any lane with at least one succeeded task
+			return hasSucceeded;
+		}
+
+		return hasSucceeded && !hasHardFailure;
+	});
+
+	if (mergeableLanes.length === 0) {
+		// TP-171: Even when no lanes are mergeable, skipped-task lanes may have
+		// partial progress (STATUS.md updates) that should be staged on the target
+		// branch so it survives integration. Stage artifacts directly without
+		// creating a full merge worktree.
+		const skippedOnlyLanes = completedLanes.filter((lane) => {
+			if (!lane.worktreePath) return false;
+			const outcome = laneOutcomeByNumber.get(lane.laneNumber);
+			if (!outcome) return false;
+			return outcome.tasks.some((t) => t.status === "skipped");
+		});
+		if (skippedOnlyLanes.length > 0) {
+			stageSkippedArtifactsToTargetBranch(skippedOnlyLanes, waveIndex, repoRoot, targetBranch);
+		}
+
+		execLog("merge", `W${waveIndex}`, "no mergeable lanes (all failed or empty)");
+		return {
+			waveIndex,
+			status: "succeeded", // vacuous success — nothing to merge
+			laneResults: [],
+			failedLane: null,
+			failureReason: null,
+			totalDurationMs: Date.now() - startTime,
+		};
+	}
+
+	// Determine merge order
+	const orderedLanes = determineMergeOrder(mergeableLanes, config.merge.order);
+
+	// TP-171: Identify lanes with skipped tasks that are NOT in the mergeable set.
+	// These lanes won't have their branches merged, but their task artifacts
+	// (STATUS.md, .reviews) should still be staged so partial progress is preserved
+	// through integration. Only lanes with worktree paths can contribute artifacts.
+	const mergeableLaneNumbers = new Set(mergeableLanes.map((l) => l.laneNumber));
+	const skippedArtifactLanes = completedLanes.filter((lane) => {
+		if (mergeableLaneNumbers.has(lane.laneNumber)) return false;
+		if (!lane.worktreePath) return false;
+		const outcome = laneOutcomeByNumber.get(lane.laneNumber);
+		if (!outcome) return false;
+		return outcome.tasks.some((t) => t.status === "skipped");
+	});
+
+	execLog("merge", `W${waveIndex}`, `merging ${orderedLanes.length} lane(s)`, {
+		order: config.merge.order,
+		lanes: orderedLanes.map((l) => l.laneNumber).join(","),
+		skippedArtifactLanes:
+			skippedArtifactLanes.length > 0
+				? skippedArtifactLanes.map((l) => l.laneNumber).join(",")
+				: undefined,
+	});
+
+	// ── Create isolated merge worktree ──────────────────────────────
+	// Merging in a dedicated worktree prevents dirty-worktree failures
+	// caused by user edits or orchestrator-generated files in the main repo.
+	// The merge worktree lives inside the batch container alongside lane worktrees:
+	// {basePath}/{opId}-{batchId}/merge
+	const tempBranch = `_merge-temp-${opId}-${batchId}`;
+	const mergeWorkDir = generateMergeWorktreePath(repoRoot, opId, batchId, config);
+
+	// 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
+		await sleepAsync(500);
+		forceRemoveMergeWorktree(mergeWorkDir, repoRoot, `W${waveIndex}`);
+	}
+	try {
+		spawnSync("git", ["branch", "-D", tempBranch], { cwd: repoRoot });
+	} catch {
+		/* branch may not exist */
+	}
+
+	// Create temp branch at target branch HEAD, then worktree
+	const branchResult = spawnSync("git", ["branch", tempBranch, targetBranch], { cwd: repoRoot });
+	if (branchResult.status !== 0) {
+		const err = branchResult.stderr?.toString().trim() || "unknown error";
+		execLog("merge", `W${waveIndex}`, `failed to create temp branch: ${err}`);
+		return {
+			waveIndex,
+			status: "failed",
+			laneResults: [],
+			failedLane: null,
+			failureReason: `Failed to create merge temp branch: ${err}`,
+			totalDurationMs: Date.now() - startTime,
+		};
+	}
+
+	const wtResult = spawnSync("git", ["worktree", "add", mergeWorkDir, tempBranch], {
+		cwd: repoRoot,
+	});
+	if (wtResult.status !== 0) {
+		const err = wtResult.stderr?.toString().trim() || "unknown error";
+		execLog("merge", `W${waveIndex}`, `failed to create merge worktree: ${err}`);
+		spawnSync("git", ["branch", "-D", tempBranch], { cwd: repoRoot });
+		return {
+			waveIndex,
+			status: "failed",
+			laneResults: [],
+			failedLane: null,
+			failureReason: `Failed to create merge worktree: ${err}`,
+			totalDurationMs: Date.now() - startTime,
+		};
+	}
+
+	execLog("merge", `W${waveIndex}`, `merge worktree created`, {
+		worktree: mergeWorkDir,
+		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 = `${sessionPrefix}-${opId}-merge-${lane.laneNumber}`;
+		const resultFileName = `merge-result-w${waveIndex}-lane${lane.laneNumber}-${opId}-${batchId}.json`;
+		const piDir = stateRoot ?? repoRoot;
+		const resultFilePath = join(piDir, ".pi", resultFileName);
+		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 {
+			// Clean up any stale result file from prior attempt
+			if (existsSync(resultFilePath)) {
+				try {
+					unlinkSync(resultFilePath);
+				} catch {
+					// Best effort
+				}
+			}
+
+			// 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,
+				waveIndex,
+				config.merge.verify,
+				resultFilePath,
+			);
+
+			// Write merge request to temp file
+			writeFileSync(requestFilePath, mergeRequestContent, "utf-8");
+
+			// ── TP-038: Spawn + wait with retry-on-timeout ──────────────
+			// On MERGE_TIMEOUT, retry with 2× the previous timeout (up to
+			// MERGE_TIMEOUT_MAX_RETRIES). Before each retry, re-read config
+			// from disk so operators can increase merge.timeoutMinutes without
+			// restarting the session.
+			let mergeResult: MergeResult;
+			{
+				const configRoot = stateRoot ?? repoRoot;
+				let currentTimeoutMs = (config.merge.timeout_minutes ?? 10) * 60 * 1000;
+				let lastTimeoutError: MergeError | null = null;
+
+				for (let attempt = 0; attempt <= MERGE_TIMEOUT_MAX_RETRIES; attempt++) {
+					// On retry: clean up stale result, re-read config, apply backoff
+					if (attempt > 0) {
+						// Re-read config from disk (TP-038: allows operator to adjust timeout)
+						const freshTimeoutMs = reloadMergeTimeoutMs(configRoot);
+						// Apply 2× backoff: double the timeout for each retry attempt
+						currentTimeoutMs = freshTimeoutMs * Math.pow(2, attempt);
+
+						execLog(
+							"merge",
+							sessionName,
+							`retry ${attempt}/${MERGE_TIMEOUT_MAX_RETRIES} after timeout — respawning merge agent`,
+							{
+								newTimeoutMs: currentTimeoutMs,
+								newTimeoutMin: Math.round(currentTimeoutMs / 60_000),
+								attempt,
+							},
+						);
+
+						// Clean up stale result file from prior attempt
+						if (existsSync(resultFilePath)) {
+							try {
+								unlinkSync(resultFilePath);
+							} catch {
+								/* best effort */
+							}
+						}
+
+						// Re-spawn merge agent for the retry.
+						// Kill previous V2 agent handle to prevent orphan/duplicate.
+						killMergeAgentV2(sessionName);
+						await spawnMergeAgentV2(
+							sessionName,
+							repoRoot,
+							mergeWorkDir,
+							requestFilePath,
+							config,
+							stateRoot,
+							agentRoot,
+							batchId,
+							waveIndex,
+						);
+					} else {
+						// First attempt: spawn merge agent (Runtime V2)
+						await spawnMergeAgentV2(
+							sessionName,
+							repoRoot,
+							mergeWorkDir,
+							requestFilePath,
+							config,
+							stateRoot,
+							agentRoot,
+							batchId,
+							waveIndex,
+						);
+					}
+
+					try {
+						mergeResult = await waitForMergeResult(
+							resultFilePath,
+							sessionName,
+							currentTimeoutMs,
+							runtimeBackend,
+						);
+						// TP-056: Deregister session from health monitor on completion
+						if (healthMonitor) healthMonitor.removeSession(sessionName);
+						lastTimeoutError = null;
+						break; // Success — exit retry loop
+					} catch (waitErr: unknown) {
+						if (
+							waitErr instanceof MergeError &&
+							waitErr.code === "MERGE_TIMEOUT" &&
+							attempt < MERGE_TIMEOUT_MAX_RETRIES
+						) {
+							// Timeout — will retry on next loop iteration
+							lastTimeoutError = waitErr;
+							// TP-056: Deregister before retry (will re-register on respawn)
+							if (healthMonitor) healthMonitor.removeSession(sessionName);
+							continue;
+						}
+						// Non-timeout error or final retry exhausted — propagate
+						// TP-056: Deregister session from health monitor on error
+						if (healthMonitor) healthMonitor.removeSession(sessionName);
+						throw waitErr;
+					}
+				}
+
+				// TypeScript: mergeResult is guaranteed to be assigned here
+				// (either break from loop or throw propagated the error)
+				mergeResult = mergeResult!;
+			}
+
+			// Clean up request file (leave result file for debugging)
+			try {
+				unlinkSync(requestFilePath);
+			} catch {
+				// Best effort
+			}
+
+			// Record lane result (verificationBaseline populated below if applicable)
+			const laneResult: MergeLaneResult = {
+				laneNumber: lane.laneNumber,
+				laneId: lane.laneId,
+				sourceBranch: lane.branch,
+				targetBranch,
+				result: mergeResult,
+				error: null,
+				durationMs: Date.now() - laneStart,
+				repoId: lane.repoId,
+			};
+			laneResults.push(laneResult);
+
+			// Handle merge outcome
+			switch (mergeResult.status) {
+				case "SUCCESS":
+					execLog("merge", sessionName, "merge succeeded", {
+						mergeCommit: mergeResult.merge_commit.slice(0, 8),
+						duration: `${Math.round((Date.now() - laneStart) / 1000)}s`,
+					});
+					break;
+
+				case "CONFLICT_RESOLVED":
+					execLog("merge", sessionName, "merge succeeded with resolved conflicts", {
+						mergeCommit: mergeResult.merge_commit.slice(0, 8),
+						conflictCount: mergeResult.conflicts.length,
+						duration: `${Math.round((Date.now() - laneStart) / 1000)}s`,
+					});
+					break;
+
+				case "CONFLICT_UNRESOLVED":
+					execLog("merge", sessionName, "merge failed — unresolved conflicts", {
+						conflictCount: mergeResult.conflicts.length,
+						files: mergeResult.conflicts.map((c) => c.file).join(", "),
+					});
+					failedLane = lane.laneNumber;
+					failureReason =
+						`Unresolved merge conflicts in lane ${lane.laneNumber}: ` +
+						mergeResult.conflicts.map((c) => c.file).join(", ");
+					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}: ` +
+						mergeResult.verification.output.slice(0, 500);
+					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;
+		} catch (err: unknown) {
+			// Clean up request file on error
+			try {
+				if (existsSync(requestFilePath)) unlinkSync(requestFilePath);
+			} catch {
+				// Best effort
+			}
+
+			// Kill merge agent if still alive.
+			killMergeAgentV2(sessionName);
+
+			const errMsg = err instanceof Error ? err.message : String(err);
+			const errCode = err instanceof MergeError ? err.code : "UNKNOWN";
+
+			execLog("merge", sessionName, `merge error: ${errMsg}`, { code: errCode });
+
+			laneResults.push({
+				laneNumber: lane.laneNumber,
+				laneId: lane.laneId,
+				sourceBranch: lane.branch,
+				targetBranch,
+				result: null,
+				error: errMsg,
+				durationMs: Date.now() - laneStart,
+				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;
+		}
+	}
+
+	// ── Stage workspace task artifacts into merge worktree ──────────
+	// TP-035: Tightened artifact staging — only allowlisted task-owned files
+	// are staged. The allowlist is derived per-task-folder from completed lanes:
+	// `.DONE`, `STATUS.md`, `REVIEW_VERDICT.json`, and `.reviews/**` files.
+	// 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) {
+		// Build the set of allowed artifact paths (repo-root-relative) from
+		// the completed lanes' task folders.
+		//
+		// Allowlist policy:
+		// - task marker files: .DONE, STATUS.md, REVIEW_VERDICT.json
+		// - review outputs under task-local .reviews/**
+		const ALLOWED_ARTIFACT_NAMES = [".DONE", "STATUS.md", "REVIEW_VERDICT.json"];
+		const ALLOWED_ARTIFACT_DIRS = [".reviews"];
+		const resolvedRepoRoot = resolve(repoRoot);
+		const allowedRelPaths = new Set<string>();
+		const relPathToWorktree = new Map<string, string>();
+
+		const listFilesRecursively = (rootDir: string): string[] => {
+			if (!existsSync(rootDir)) return [];
+			const files: string[] = [];
+			const walk = (dir: string): void => {
+				let entries: Dirent[];
+				try {
+					entries = readdirSync(dir, { withFileTypes: true });
+				} catch {
+					return;
+				}
+				for (const entry of entries) {
+					const absPath = join(dir, entry.name);
+					if (entry.isDirectory()) {
+						walk(absPath);
+						continue;
+					}
+					if (!entry.isFile()) continue;
+					const relPath = relative(rootDir, absPath).replace(/\\/g, "/");
+					if (!relPath || relPath.startsWith("..") || relPath.startsWith("/")) continue;
+					files.push(relPath);
+				}
+			};
+			walk(rootDir);
+			return files;
+		};
+
+		// TP-171: Skipped-artifact lanes get a restricted allowlist — no .DONE
+		// because their code was not merged; staging .DONE would create false
+		// completion markers on the orch branch.
+		const SKIPPED_ARTIFACT_NAMES = ["STATUS.md", "REVIEW_VERDICT.json"];
+		const skippedArtifactLaneNumbers = new Set(skippedArtifactLanes.map((l) => l.laneNumber));
+
+		// Include both merged lanes and skipped-artifact lanes in staging.
+		const artifactStagingLanes = [...orderedLanes, ...skippedArtifactLanes];
+		for (const lane of artifactStagingLanes) {
+			// Select allowlist based on lane type
+			const isSkippedOnly = skippedArtifactLaneNumbers.has(lane.laneNumber);
+			const nameAllowlist = isSkippedOnly ? SKIPPED_ARTIFACT_NAMES : ALLOWED_ARTIFACT_NAMES;
+
+			for (const allocTask of lane.tasks) {
+				if (!allocTask.task?.taskFolder?.trim()) {
+					execLog(
+						"merge",
+						`W${waveIndex}`,
+						`skipping task with missing taskFolder (possibly dynamically expanded)`,
+						{
+							taskId: allocTask.taskId,
+						},
+					);
+					continue;
+				}
+				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;
+				}
+
+				for (const name of nameAllowlist) {
+					const rp = `${relFolder}/${name}`;
+					allowedRelPaths.add(rp);
+					relPathToWorktree.set(rp, join(lane.worktreePath, rp));
+				}
+
+				for (const dirName of ALLOWED_ARTIFACT_DIRS) {
+					const laneDir = join(lane.worktreePath, relFolder, dirName);
+					for (const relFile of listFilesRecursively(laneDir)) {
+						const rp = `${relFolder}/${dirName}/${relFile}`;
+						allowedRelPaths.add(rp);
+						relPathToWorktree.set(rp, join(lane.worktreePath, rp));
+					}
+
+					const repoDir = join(repoRoot, relFolder, dirName);
+					for (const relFile of listFilesRecursively(repoDir)) {
+						const rp = `${relFolder}/${dirName}/${relFile}`;
+						allowedRelPaths.add(rp);
+					}
+				}
+			}
+		}
+
+		if (allowedRelPaths.size > 0) {
+			let staged = 0;
+			let skipped = 0;
+			let preserved = 0;
+
+			for (const relPath of allowedRelPaths) {
+				const destPath = join(mergeWorkDir, relPath);
+
+				// TP-099: If the file already exists in mergeWorkDir (from lane merge),
+				// do NOT overwrite it — the lane merge brought the correct worker-updated
+				// version (e.g., STATUS.md with checked items, execution log, discoveries).
+				// Overwriting from repoRoot would revert to the pre-execution template.
+				if (existsSync(destPath)) {
+					preserved++;
+					continue;
+				}
+
+				// File missing from mergeWorkDir — backfill from best available source.
+				// Primary: lane worktree (has worker-generated .DONE/STATUS/.reviews content).
+				// Fallback: repoRoot (original task folder, with path containment check).
+				const worktreeSrc = relPathToWorktree.get(relPath);
+				let srcPath: string | null = null;
+
+				// Try lane worktree first (trusted engine-allocated path)
+				if (worktreeSrc && existsSync(worktreeSrc)) {
+					srcPath = worktreeSrc;
+				} else {
+					// Fallback to repoRoot with path containment check (TP-035 hardening)
+					const repoRootSrc = join(repoRoot, relPath);
+					if (existsSync(repoRootSrc)) {
+						const resolvedSrc = resolve(repoRootSrc);
+						const srcRelToRepo = relative(resolvedRepoRoot, resolvedSrc).replace(/\\/g, "/");
+						if (srcRelToRepo.startsWith("..") || srcRelToRepo.startsWith("/")) {
+							execLog("merge", `W${waveIndex}`, `skipping artifact source outside repo root`, {
+								path: relPath,
+								src: repoRootSrc,
+							});
+							continue;
+						}
+						srcPath = repoRootSrc;
+					}
+				}
+				if (!srcPath) continue; // File not present anywhere — skip silently
+
+				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, .reviews/*)`,
+					],
+					{ cwd: mergeWorkDir },
+				);
+				execLog("merge", `W${waveIndex}`, `committed ${staged} task artifact(s) to merge worktree`, {
+					skipped,
+					preserved,
+					allowedCandidates: allowedRelPaths.size,
+				});
+			} else {
+				execLog(
+					"merge",
+					`W${waveIndex}`,
+					`no task artifacts to stage (0 of ${allowedRelPaths.size} candidates present/changed, ${preserved} preserved from lane merge)`,
+				);
+			}
+
+			// 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 ────────
+	// 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 });
+
+		if (revParseResult.status !== 0) {
+			const err = revParseResult.stderr?.toString().trim() || "unknown error";
+			execLog("merge", `W${waveIndex}`, `failed to resolve temp branch HEAD: ${err}`, { tempBranch });
+			failedLane = failedLane ?? -1;
+			failureReason = `Failed to resolve merge temp branch HEAD (${tempBranch}): ${err}`;
+		} else {
+			const tempBranchHead = revParseResult.stdout.toString().trim();
+
+			// Gate advancement strategy:
+			// - If targetBranch is NOT checked out in repoRoot, use update-ref
+			//   (safe, does not touch the working tree). This is the common case
+			//   for the orch branch in repo mode.
+			// - If targetBranch IS checked out in repoRoot (workspace mode, where
+			//   resolveBaseBranch returns the repo's current branch), use
+			//   git merge --ff-only to advance HEAD+index+worktree together.
+			const checkedOutBranch = getCurrentBranch(repoRoot);
+			const targetIsCheckedOut = checkedOutBranch === targetBranch;
+
+			if (targetIsCheckedOut) {
+				// Checked-out branch — must use ff-only to keep HEAD/index/worktree in sync.
+				// Dirty working tree may block ff — stash if needed.
+				const ffResult = spawnSync("git", ["merge", "--ff-only", tempBranch], { cwd: repoRoot });
+
+				if (ffResult.status !== 0) {
+					// Dirty working tree may block ff — try stash + ff + pop
+					execLog("merge", `W${waveIndex}`, "fast-forward blocked — stashing user changes");
+					const stashMsg = `merge-agent-autostash-w${waveIndex}-${batchId}`;
+					spawnSync("git", ["stash", "push", "--include-untracked", "-m", stashMsg], { cwd: repoRoot });
+
+					const ffRetry = spawnSync("git", ["merge", "--ff-only", tempBranch], { cwd: repoRoot });
+
+					// Always pop stash, regardless of ff result
+					spawnSync("git", ["stash", "pop"], { cwd: repoRoot });
+
+					if (ffRetry.status !== 0) {
+						const err = ffRetry.stderr?.toString().trim() || "unknown error";
+						execLog("merge", `W${waveIndex}`, `fast-forward failed even after stash: ${err}`);
+						failedLane = failedLane ?? -1;
+						failureReason = `Fast-forward of ${targetBranch} failed: ${err}`;
+					} else {
+						execLog("merge", `W${waveIndex}`, "fast-forward succeeded after stash/pop");
+					}
+				} else {
+					execLog("merge", `W${waveIndex}`, `fast-forwarded ${targetBranch} to merge result`);
+				}
+			} else {
+				// Not checked out — safe to use update-ref without touching the worktree.
+				// Use compare-and-swap (3-arg form) to guard against concurrent branch movement.
+				const oldRefResult = spawnSync("git", ["rev-parse", `refs/heads/${targetBranch}`], {
+					cwd: repoRoot,
+				});
+				const oldRef = oldRefResult.status === 0 ? oldRefResult.stdout.toString().trim() : "";
+
+				const updateRefArgs = oldRef
+					? ["update-ref", `refs/heads/${targetBranch}`, tempBranchHead, oldRef]
+					: ["update-ref", `refs/heads/${targetBranch}`, tempBranchHead];
+
+				const updateRefResult = spawnSync("git", updateRefArgs, { cwd: repoRoot });
+
+				if (updateRefResult.status !== 0) {
+					const err = updateRefResult.stderr?.toString().trim() || "unknown error";
+					execLog("merge", `W${waveIndex}`, `update-ref failed for ${targetBranch}: ${err}`, {
+						targetBranch,
+						tempBranchHead: tempBranchHead.slice(0, 8),
+					});
+					failedLane = failedLane ?? -1;
+					failureReason = `update-ref of ${targetBranch} to ${tempBranchHead.slice(0, 8)} failed: ${err}`;
+				} else {
+					execLog("merge", `W${waveIndex}`, `updated ${targetBranch} ref to merge result`, {
+						targetBranch,
+						commit: tempBranchHead.slice(0, 8),
+					});
+				}
+			}
+		}
+	}
+
+	// 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
+			await sleepAsync(500);
+			spawnSync("git", ["branch", "-D", tempBranch], { cwd: repoRoot });
+		} catch {
+			/* best effort */
+		}
+	}
+
+	// Determine overall status
+	let status: MergeWaveResult["status"];
+	if (failedLane === null) {
+		status = "succeeded";
+	} else if (anySuccess) {
+		status = "partial";
+	} else {
+		status = "failed";
+	}
+
+	const totalDurationMs = Date.now() - startTime;
+
+	execLog("merge", `W${waveIndex}`, `wave merge complete: ${status}`, {
+		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`,
+	});
+
+	const result: MergeWaveResult = {
+		waveIndex,
+		status,
+		laneResults,
+		failedLane,
+		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;
+}
+
+// ── Repo-Scoped Merge ────────────────────────────────────────────────
+
+/**
+ * Group mergeable lanes by their `repoId`.
+ *
+ * Returns groups sorted deterministically by repoId (undefined/repo-mode
+ * group sorts first as empty string). Lanes within each group preserve
+ * the input order.
+ *
+ * @param lanes - Lanes to group (already filtered for mergeability)
+ * @returns Array of { repoId, lanes } groups in deterministic order
+ */
+export function groupLanesByRepo(
+	lanes: AllocatedLane[],
+): Array<{ repoId: string | undefined; lanes: AllocatedLane[] }> {
+	const groupMap = new Map<string, AllocatedLane[]>();
+
+	for (const lane of lanes) {
+		const key = lane.repoId ?? "";
+		const existing = groupMap.get(key) || [];
+		existing.push(lane);
+		groupMap.set(key, existing);
+	}
+
+	const sortedKeys = [...groupMap.keys()].sort();
+	return sortedKeys.map((key) => ({
+		repoId: key || undefined,
+		lanes: groupMap.get(key)!,
+	}));
+}
+
+/**
+ * Merge a wave's lanes partitioned by repository.
+ *
+ * In repo mode (all lanes have repoId=undefined), this produces a single
+ * repo group and delegates to `mergeWave()` exactly once — a no-op
+ * regression case that preserves existing behavior.
+ *
+ * In workspace mode, lanes are grouped by `repoId`. Each repo group gets:
+ * - Its own repo root (via `resolveRepoRoot()`)
+ * - Its own base branch (via `resolveBaseBranch()`)
+ * - An independent `mergeWave()` call with those repo-scoped parameters
+ *
+ * Repo groups are processed in deterministic order (sorted by repoId).
+ * Per-repo results are aggregated into a single `MergeWaveResult` for
+ * the existing wave-level failure policy handling in `engine.ts`.
+ *
+ * Failure semantics:
+ * - A failure in one repo does NOT stop merging in other repos.
+ * - The aggregate status is "succeeded" only if all repos succeeded.
+ * - If any repo failed and any succeeded, status is "partial".
+ * - `repoResults` field carries per-repo attribution for downstream
+ *   reporting (Step 1 will use this for explicit partial-success summaries).
+ *
+ * @param completedLanes   - Lanes that completed execution (from wave result)
+ * @param waveResult       - The wave execution result (for lane status filtering)
+ * @param waveIndex        - Wave number (1-indexed)
+ * @param config           - Orchestrator configuration
+ * @param repoRoot         - Default repository root (used in repo mode)
+ * @param batchId          - Batch ID for session naming
+ * @param baseBranch       - Default branch to merge into (captured at batch start)
+ * @param workspaceConfig  - Workspace configuration (null in repo mode)
+ * @returns MergeWaveResult with per-lane and per-repo outcomes
+ */
+export async function mergeWaveByRepo(
+	completedLanes: AllocatedLane[],
+	waveResult: WaveExecutionResult,
+	waveIndex: number,
+	config: OrchestratorConfig,
+	repoRoot: string,
+	batchId: string,
+	baseBranch: string,
+	workspaceConfig?: WorkspaceConfig | null,
+	stateRoot?: string,
+	agentRoot?: string,
+	testingCommands?: Record<string, string>,
+	healthMonitor?: MergeHealthMonitor | null,
+	forceMixedOutcome?: boolean,
+	runtimeBackend?: RuntimeBackend,
+): Promise<MergeWaveResult> {
+	const startTime = Date.now();
+
+	// Build lane outcome lookup for merge eligibility (same logic as mergeWave).
+	const laneOutcomeByNumber = new Map<number, LaneExecutionResult>();
+	for (const laneOutcome of waveResult.laneResults) {
+		laneOutcomeByNumber.set(laneOutcome.laneNumber, laneOutcome);
+	}
+
+	// Filter to mergeable lanes (same criteria as mergeWave).
+	// TP-078: When forceMixedOutcome is true, lanes with mixed outcomes are also included.
+	const mergeableLanes = completedLanes.filter((lane) => {
+		const outcome = laneOutcomeByNumber.get(lane.laneNumber);
+		if (!outcome) return false;
+		const hasSucceeded = outcome.tasks.some((t) => t.status === "succeeded");
+		const hasHardFailure = outcome.tasks.some((t) => t.status === "failed" || t.status === "stalled");
+		if (forceMixedOutcome) return hasSucceeded;
+		return hasSucceeded && !hasHardFailure;
+	});
+
+	if (mergeableLanes.length === 0) {
+		// TP-171: Even when no lanes are mergeable, skipped-task lanes may have
+		// partial progress that should be staged on the target branch.
+		const skippedOnlyLanes = completedLanes.filter((lane) => {
+			if (!lane.worktreePath) return false;
+			const outcome = laneOutcomeByNumber.get(lane.laneNumber);
+			if (!outcome) return false;
+			return outcome.tasks.some((t) => t.status === "skipped");
+		});
+		if (skippedOnlyLanes.length > 0) {
+			// In workspace mode, group skipped lanes by repo and stage per-repo.
+			const skippedByRepo = groupLanesByRepo(skippedOnlyLanes);
+			for (const group of skippedByRepo) {
+				const groupRepoRoot = resolveRepoRoot(group.repoId, repoRoot, workspaceConfig);
+				stageSkippedArtifactsToTargetBranch(group.lanes, waveIndex, groupRepoRoot, baseBranch);
+			}
+		}
+
+		execLog("merge", `W${waveIndex}`, "no mergeable lanes (all failed or empty)");
+		return {
+			waveIndex,
+			status: "succeeded",
+			laneResults: [],
+			failedLane: null,
+			failureReason: null,
+			totalDurationMs: Date.now() - startTime,
+			repoResults: [],
+		};
+	}
+
+	// Group lanes by repo
+	const repoGroups = groupLanesByRepo(mergeableLanes);
+
+	execLog("merge", `W${waveIndex}`, `merging across ${repoGroups.length} repo group(s)`, {
+		repos: repoGroups.map((g) => g.repoId ?? "(default)").join(", "),
+		totalLanes: mergeableLanes.length,
+	});
+
+	// In repo mode (single group with repoId=undefined), delegate directly
+	// to mergeWave() for zero-overhead backward compatibility.
+	if (repoGroups.length === 1 && repoGroups[0].repoId === undefined) {
+		const result = await mergeWave(
+			completedLanes,
+			waveResult,
+			waveIndex,
+			config,
+			repoRoot,
+			batchId,
+			baseBranch,
+			stateRoot,
+			agentRoot,
+			testingCommands,
+			undefined, // repoId
+			healthMonitor,
+			forceMixedOutcome,
+			runtimeBackend,
+		);
+		// Attach empty repoResults for consistent shape
+		return { ...result, repoResults: [] };
+	}
+
+	// ── 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.
+	// mergeWave() can return status="failed" with failedLane=null for
+	// 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);
+		// In workspace mode with orch branch, always merge into the orch branch
+		// (passed as baseBranch from engine.ts). Do NOT use resolveBaseBranch()
+		// which returns the repo's current branch (e.g., develop), bypassing
+		// the orch branch model entirely.
+		const groupBaseBranch = baseBranch;
+
+		execLog("merge", `W${waveIndex}`, `merging repo group: ${group.repoId ?? "(default)"}`, {
+			repoRoot: groupRepoRoot,
+			baseBranch: groupBaseBranch,
+			laneCount: group.lanes.length,
+			lanes: group.lanes.map((l) => l.laneNumber).join(","),
+		});
+
+		// TP-171: Build allGroupLanes from all completed lanes for this repo
+		// (not just mergeable) so mergeWave() can compute skippedArtifactLanes.
+		const groupRepoId = group.repoId;
+		const allGroupLanes = completedLanes.filter((l) => (l.repoId ?? undefined) === groupRepoId);
+		const allGroupLaneNumbers = new Set(allGroupLanes.map((l) => l.laneNumber));
+
+		// Build a filtered WaveExecutionResult containing all lanes for this repo
+		// (including skipped-only lanes that aren't in the mergeable group).
+		const filteredWaveResult: WaveExecutionResult = {
+			...waveResult,
+			laneResults: waveResult.laneResults.filter((lr) => allGroupLaneNumbers.has(lr.laneNumber)),
+			allocatedLanes: waveResult.allocatedLanes.filter((l) => allGroupLaneNumbers.has(l.laneNumber)),
+		};
+
+		const groupResult = await mergeWave(
+			allGroupLanes,
+			filteredWaveResult,
+			waveIndex,
+			config,
+			groupRepoRoot,
+			batchId,
+			groupBaseBranch,
+			stateRoot,
+			agentRoot,
+			testingCommands,
+			group.repoId,
+			healthMonitor,
+			forceMixedOutcome,
+			runtimeBackend,
+		);
+
+		// 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,
+			status: groupResult.status,
+			laneResults: groupResult.laneResults,
+			failedLane: groupResult.failedLane,
+			failureReason: groupResult.failureReason,
+		};
+		repoOutcomes.push(repoOutcome);
+
+		// Track failures across repos (but continue to merge other repos).
+		// Check groupResult.status (not just failedLane) to catch setup failures
+		// where mergeWave() returns status="failed" with failedLane=null
+		// (e.g., temp branch creation or worktree creation failure).
+		if (groupResult.status !== "succeeded") {
+			anyRepoFailed = true;
+
+			if (firstFailureReason === null) {
+				firstFailedLane = groupResult.failedLane;
+				firstFailureReason = groupResult.failureReason
+					? `[repo:${group.repoId ?? "default"}] ${groupResult.failureReason}`
+					: `[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;
+		}
+	}
+
+	// TP-171: Stage artifacts for repos that have only skipped lanes but were
+	// not included in the mergeable repoGroups.
+	const processedRepoIds = new Set(repoGroups.map((g) => g.repoId));
+	const skippedOnlyRepoLanes = completedLanes.filter((lane) => {
+		if (!lane.worktreePath) return false;
+		const laneRepoId = lane.repoId ?? undefined;
+		if (processedRepoIds.has(laneRepoId)) return false; // already handled by mergeWave
+		const outcome = laneOutcomeByNumber.get(lane.laneNumber);
+		if (!outcome) return false;
+		return outcome.tasks.some((t) => t.status === "skipped");
+	});
+	// TP-171 R004: Gate artifact staging behind safe-stop — do not advance
+	// any branch refs when a rollback failure has been detected.
+	if (skippedOnlyRepoLanes.length > 0 && !anyRollbackFailed) {
+		const skippedRepoGroups = groupLanesByRepo(skippedOnlyRepoLanes);
+		for (const group of skippedRepoGroups) {
+			const groupRepoRoot = resolveRepoRoot(group.repoId, repoRoot, workspaceConfig);
+			stageSkippedArtifactsToTargetBranch(group.lanes, waveIndex, groupRepoRoot, baseBranch);
+		}
+	}
+
+	// ── Aggregate status ─────────────────────────────────────────
+	// Use both lane-level and repo-level evidence for correct classification:
+	// - 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.error && (r.result?.status === "SUCCESS" || r.result?.status === "CONFLICT_RESOLVED"),
+	);
+
+	let status: MergeWaveResult["status"];
+	if (!anyRepoFailed) {
+		status = "succeeded";
+	} else if (anyLaneSucceeded) {
+		status = "partial";
+	} else {
+		status = "failed";
+	}
+
+	const totalDurationMs = Date.now() - startTime;
+
+	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.error && (r.result?.status === "SUCCESS" || r.result?.status === "CONFLICT_RESOLVED"),
+		).length,
+		duration: `${Math.round(totalDurationMs / 1000)}s`,
+	});
+
+	const aggregateResult: MergeWaveResult = {
+		waveIndex,
+		status,
+		laneResults: allLaneResults,
+		failedLane: firstFailedLane,
+		failureReason: firstFailureReason,
+		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 ─────────────────────────────────────────────────
+
+/**
+ * Attempt to fast-forward baseBranch to orchBranch in the main repo.
+ *
+ * Shared by engine.ts (fresh batch) and resume.ts (resumed batch).
+ * The `logCategory` parameter distinguishes the calling context in execLog.
+ *
+ * Failure matrix — all failures are warnings, never batch-fatal:
+ * - **Diverged**: baseBranch has commits not in orchBranch (not fast-forwardable)
+ * - **Detached HEAD / missing base**: baseBranch not resolvable
+ * - **Dirty worktree**: baseBranch is checked out with uncommitted changes
+ * - **Branch not checked out**: baseBranch is not the current branch;
+ *   use update-ref (no worktree impact) with compare-and-swap
+ *
+ * @param orchBranch  - The orch branch to integrate from
+ * @param baseBranch  - The user's branch to advance
+ * @param repoRoot    - Absolute path to the primary repo root
+ * @param batchId     - Batch identifier for logging
+ * @param logCategory - execLog category ("batch" for engine, "resume" for resume)
+ * @param onNotify    - Notification callback
+ * @returns true if integration succeeded, false otherwise
+ */
+export function attemptAutoIntegration(
+	orchBranch: string,
+	baseBranch: string,
+	repoRoot: string,
+	batchId: string,
+	logCategory: string,
+	onNotify: (message: string, level: "info" | "warning" | "error") => void,
+): boolean {
+	// 1. Verify orchBranch exists
+	const orchExists = runGit(["rev-parse", "--verify", `refs/heads/${orchBranch}`], repoRoot);
+	if (!orchExists.ok) {
+		const reason = `orch branch '${orchBranch}' not found`;
+		execLog(logCategory, batchId, `auto-integration skipped: ${reason}`);
+		onNotify(ORCH_MESSAGES.orchIntegrationAutoFailed(orchBranch, baseBranch, reason), "warning");
+		return false;
+	}
+
+	// 2. Verify baseBranch exists
+	const baseExists = runGit(["rev-parse", "--verify", `refs/heads/${baseBranch}`], repoRoot);
+	if (!baseExists.ok) {
+		const reason = `base branch '${baseBranch}' not found`;
+		execLog(logCategory, batchId, `auto-integration skipped: ${reason}`);
+		onNotify(ORCH_MESSAGES.orchIntegrationAutoFailed(orchBranch, baseBranch, reason), "warning");
+		return false;
+	}
+
+	// 3. Check fast-forwardability: baseBranch must be an ancestor of orchBranch
+	const isAncestor = runGit(["merge-base", "--is-ancestor", baseBranch, orchBranch], repoRoot);
+	if (!isAncestor.ok) {
+		const reason = `branches have diverged (${baseBranch} is not an ancestor of ${orchBranch})`;
+		execLog(logCategory, batchId, `auto-integration skipped: ${reason}`);
+		onNotify(ORCH_MESSAGES.orchIntegrationAutoFailed(orchBranch, baseBranch, reason), "warning");
+		return false;
+	}
+
+	// 4. Gate on whether baseBranch is checked out (same pattern as merge advancement)
+	const checkedOutBranch = getCurrentBranch(repoRoot);
+	const baseIsCheckedOut = checkedOutBranch === baseBranch;
+
+	const orchHead = runGit(["rev-parse", orchBranch], repoRoot).stdout.trim();
+
+	if (baseIsCheckedOut) {
+		// baseBranch is checked out — use merge --ff-only (updates worktree)
+		// Check for dirty worktree first
+		const statusCheck = runGit(["status", "--porcelain"], repoRoot);
+		if (statusCheck.ok && statusCheck.stdout.trim()) {
+			const reason = `working tree is dirty (${baseBranch} is checked out with uncommitted changes)`;
+			execLog(logCategory, batchId, `auto-integration skipped: ${reason}`);
+			onNotify(ORCH_MESSAGES.orchIntegrationAutoFailed(orchBranch, baseBranch, reason), "warning");
+			return false;
+		}
+
+		const ffResult = runGit(["merge", "--ff-only", orchBranch], repoRoot);
+		if (!ffResult.ok) {
+			const reason = `fast-forward failed: ${ffResult.stderr || ffResult.stdout || "unknown"}`;
+			execLog(logCategory, batchId, `auto-integration failed: ${reason}`);
+			onNotify(ORCH_MESSAGES.orchIntegrationAutoFailed(orchBranch, baseBranch, reason), "warning");
+			return false;
+		}
+	} else {
+		// baseBranch is NOT checked out — use update-ref with compare-and-swap
+		const baseOldRef = runGit(["rev-parse", baseBranch], repoRoot).stdout.trim();
+		const updateResult = runGit(
+			["update-ref", `refs/heads/${baseBranch}`, orchHead, baseOldRef],
+			repoRoot,
+		);
+		if (!updateResult.ok) {
+			const reason = `update-ref failed: ${updateResult.stderr || updateResult.stdout || "unknown"}`;
+			execLog(logCategory, batchId, `auto-integration failed: ${reason}`);
+			onNotify(ORCH_MESSAGES.orchIntegrationAutoFailed(orchBranch, baseBranch, reason), "warning");
+			return false;
+		}
+	}
+
+	execLog(logCategory, batchId, `auto-integrated: ${baseBranch} advanced to ${orchBranch}`, {
+		orchHead,
+	});
+	onNotify(ORCH_MESSAGES.orchIntegrationAutoSuccess(orchBranch, baseBranch), "info");
+	return true;
+}
+
+// ── Merge Health Monitor (TP-056) ────────────────────────────────────
+
+/**
+ * Classify merge-session health from Runtime V2 liveness and result-file state.
+ *
+ * Without legacy pane capture, warning/stuck are time-based heuristics from
+ * the session registration timestamp (`lastActivityAt`).
+ *
+ * @param sessionAlive   - Whether the Runtime V2 merge agent is alive
+ * @param hasResultFile  - Whether the merge result file exists
+ * @param healthState    - Tracked health state for this session
+ * @param now            - Current epoch ms
+ * @returns Updated health status
+ *
+ * @since TP-056
+ */
+export function classifyMergeHealth(
+	sessionAlive: boolean,
+	hasResultFile: boolean,
+	healthState: MergeSessionHealthState,
+	now: number,
+): MergeHealthStatus {
+	if (!sessionAlive && !hasResultFile) {
+		return "dead";
+	}
+
+	if (!sessionAlive && hasResultFile) {
+		return "healthy";
+	}
+
+	const elapsedMs = now - healthState.lastActivityAt;
+	if (elapsedMs >= MERGE_HEALTH_STUCK_THRESHOLD_MS) {
+		return "stuck";
+	}
+	if (elapsedMs >= MERGE_HEALTH_WARNING_THRESHOLD_MS) {
+		return "warning";
+	}
+	return "healthy";
+}
+
+/**
+ * Active merge session health monitor.
+ *
+ * Runs on its own polling interval during the merge phase, checking each
+ * active merge session for liveness and activity. Emits structured events
+ * for the supervisor to consume.
+ *
+ * Design principles (from PROMPT.md):
+ * - Does NOT kill sessions autonomously — emits events for operator decision
+ * - Runs independently of the merge result poll
+ * - Stores session snapshots in memory (ephemeral, not persisted)
+ * - Emits structured events to the unified events.jsonl
+ *
+ * @since TP-056
+ */
+export class MergeHealthMonitor {
+	/** Per-session health state, keyed by session name */
+	private sessions: Map<string, MergeSessionHealthState> = new Map();
+
+	/** Timer handle for the polling loop */
+	private pollTimer: ReturnType<typeof setInterval> | null = null;
+
+	/** Whether the monitor is currently running */
+	private _running = false;
+
+	/** Callback invoked when a dead session is detected (for early exit signaling) */
+	private _onDeadSession: ((sessionName: string, laneNumber: number) => void) | null = null;
+
+	/** Event emission context */
+	private stateRoot: string;
+	private batchId: string;
+	private waveIndex: number;
+	private phase: OrchBatchPhase;
+
+	/** Polling interval override (for testing) */
+	private pollIntervalMs: number;
+
+	constructor(opts: {
+		stateRoot: string;
+		batchId: string;
+		waveIndex: number;
+		phase: OrchBatchPhase;
+		pollIntervalMs?: number;
+		onDeadSession?: (sessionName: string, laneNumber: number) => void;
+	}) {
+		this.stateRoot = opts.stateRoot;
+		this.batchId = opts.batchId;
+		this.waveIndex = opts.waveIndex;
+		this.phase = opts.phase;
+		this.pollIntervalMs = opts.pollIntervalMs ?? MERGE_HEALTH_POLL_INTERVAL_MS;
+		this._onDeadSession = opts.onDeadSession ?? null;
+	}
+
+	/** Whether the monitor is currently running */
+	get running(): boolean {
+		return this._running;
+	}
+
+	/**
+	 * Register a merge session for monitoring.
+	 *
+	 * @param sessionName - Merge session name
+	 * @param laneNumber  - Lane number the session belongs to
+	 * @param resultPath  - Path to the expected merge result file
+	 */
+	addSession(sessionName: string, laneNumber: number, resultPath: string): void {
+		const now = Date.now();
+		this.sessions.set(sessionName, {
+			sessionName,
+			laneNumber,
+			lastSnapshot: null,
+			lastActivityAt: now,
+			status: "healthy",
+			warningEmitted: false,
+			stuckEmitted: false,
+			deadEmitted: false,
+		});
+		// Store resultPath for later lookup
+		this._resultPaths.set(sessionName, resultPath);
+	}
+
+	/** Result file paths for each session (for dead-session detection) */
+	private _resultPaths: Map<string, string> = new Map();
+
+	/**
+	 * Remove a session from monitoring (e.g., merge completed for this lane).
+	 */
+	removeSession(sessionName: string): void {
+		this.sessions.delete(sessionName);
+		this._resultPaths.delete(sessionName);
+	}
+
+	/** Overlap guard for async poll (TP-070) */
+	private _polling = false;
+
+	/**
+	 * Start the health monitoring polling loop.
+	 */
+	start(): void {
+		if (this._running) return;
+		this._running = true;
+
+		execLog("merge-health", "monitor", "merge health monitor started", {
+			sessionCount: this.sessions.size,
+			pollIntervalMs: this.pollIntervalMs,
+		});
+
+		this.pollTimer = setInterval(async () => {
+			if (this._polling) return; // Overlap guard (TP-070)
+			this._polling = true;
+			try {
+				await this.poll();
+			} finally {
+				this._polling = false;
+			}
+		}, this.pollIntervalMs);
+	}
+
+	/**
+	 * Stop the health monitoring polling loop.
+	 */
+	stop(): void {
+		if (!this._running) return;
+		this._running = false;
+
+		if (this.pollTimer !== null) {
+			clearInterval(this.pollTimer);
+			this.pollTimer = null;
+		}
+
+		execLog("merge-health", "monitor", "merge health monitor stopped", {
+			sessionCount: this.sessions.size,
+		});
+
+		this.sessions.clear();
+		this._resultPaths.clear();
+	}
+
+	/**
+	 * Run a single poll cycle across all monitored sessions.
+	 *
+	 * Exposed as public for testing — normally called by the interval timer.
+	 */
+	async poll(): Promise<void> {
+		const now = Date.now();
+
+		try {
+			setV2LivenessRegistryCache(readRegistrySnapshot(this.stateRoot, this.batchId));
+		} catch {
+			setV2LivenessRegistryCache(null);
+		}
+
+		try {
+			for (const [sessionName, state] of this.sessions) {
+				const sessionAlive = isV2AgentAlive(sessionName, "v2");
+				const resultPath = this._resultPaths.get(sessionName) ?? "";
+				const hasResultFile = resultPath ? existsSync(resultPath) : false;
+
+				const newStatus = classifyMergeHealth(sessionAlive, hasResultFile, state, now);
+
+				state.status = newStatus;
+
+				// Emit events based on status transitions
+				this._emitHealthEvents(state, now);
+
+				// Signal dead session for early exit
+				if (newStatus === "dead" && !state.deadEmitted) {
+					state.deadEmitted = true;
+					if (this._onDeadSession) {
+						this._onDeadSession(sessionName, state.laneNumber);
+					}
+				}
+			}
+		} finally {
+			setV2LivenessRegistryCache(null);
+		}
+	}
+
+	/**
+	 * Emit health events based on current state.
+	 * De-duplicates: each event type emitted at most once per session.
+	 */
+	private _emitHealthEvents(state: MergeSessionHealthState, now: number): void {
+		const stalledMinutes = Math.round((now - state.lastActivityAt) / 60_000);
+
+		if (state.status === "warning" && !state.warningEmitted) {
+			state.warningEmitted = true;
+			const event: EngineEvent = {
+				...buildEngineEventBase("merge_health_warning", this.batchId, this.waveIndex, this.phase),
+				laneNumber: state.laneNumber,
+				sessionName: state.sessionName,
+				healthStatus: "warning",
+				stalledMinutes,
+				reason: `Merge agent on lane ${state.laneNumber} may be stalled (${stalledMinutes} min without completion)`,
+			};
+			emitEngineEvent(this.stateRoot, event);
+			execLog("merge-health", state.sessionName, `⚠️ merge session possibly stalled`, {
+				stalledMinutes,
+				laneNumber: state.laneNumber,
+			});
+		}
+
+		if (state.status === "dead" && !state.deadEmitted) {
+			// deadEmitted is set in poll() after onDeadSession callback
+			const event: EngineEvent = {
+				...buildEngineEventBase("merge_health_dead", this.batchId, this.waveIndex, this.phase),
+				laneNumber: state.laneNumber,
+				sessionName: state.sessionName,
+				healthStatus: "dead",
+				reason: `Merge agent on lane ${state.laneNumber} session died without producing a result`,
+			};
+			emitEngineEvent(this.stateRoot, event);
+			execLog("merge-health", state.sessionName, `💀 merge session dead — no result file`, {
+				laneNumber: state.laneNumber,
+			});
+		}
+
+		if (state.status === "stuck" && !state.stuckEmitted) {
+			state.stuckEmitted = true;
+			const event: EngineEvent = {
+				...buildEngineEventBase("merge_health_stuck", this.batchId, this.waveIndex, this.phase),
+				laneNumber: state.laneNumber,
+				sessionName: state.sessionName,
+				healthStatus: "stuck",
+				stalledMinutes,
+				reason: `Merge agent on lane ${state.laneNumber} appears stuck (${stalledMinutes} min without completion). Consider killing and retrying.`,
+			};
+			emitEngineEvent(this.stateRoot, event);
+			execLog("merge-health", state.sessionName, `🔒 merge session stuck`, {
+				stalledMinutes,
+				laneNumber: state.laneNumber,
+			});
+		}
+	}
+
+	/**
+	 * Get the current health states for all monitored sessions.
+	 * Used for testing and inspection.
+	 */
+	getSessionStates(): Map<string, MergeSessionHealthState> {
+		return new Map(this.sessions);
+	}
+}