@pi-agents/orchid 0.1.0-beta.0

package/src/orchestrator/messages.ts

@@ -0,0 +1,1062 @@
+/**
+ * User-facing message templates (ORCH_MESSAGES)
+ * @module orch/messages
+ */
+import type {
+	AbortMode,
+	MergeFailureClassification,
+	MergeRetryCallbacks,
+	MergeRetryDecision,
+	MergeRetryLoopOutcome,
+	MergeRetryPolicy,
+	MergeWaveResult,
+	OrchestratorConfig,
+	RepoMergeOutcome,
+} from "./types.ts";
+import { MERGE_RETRY_POLICY_MATRIX } from "./types.ts";
+
+// ── Message Templates ────────────────────────────────────────────────
+
+/**
+ * Deterministic message templates for user-facing /orch commands.
+ * Ensures consistent UX across invocations.
+ */
+export const ORCH_MESSAGES = {
+	// /orch
+	orchStarting: (batchId: string, waves: number, tasks: number) =>
+		`🚀 Starting batch ${batchId}: ${waves} wave(s), ${tasks} task(s)`,
+	orchWaveStart: (waveNum: number, totalWaves: number, tasks: number, lanes: number) =>
+		`\n🌊 Wave ${waveNum}/${totalWaves}: ${tasks} task(s) across ${lanes} lane(s)`,
+	orchWaveComplete: (
+		waveNum: number,
+		succeeded: number,
+		failed: number,
+		skipped: number,
+		elapsedSec: number,
+	) =>
+		`✅ Wave ${waveNum} complete: ${succeeded} succeeded, ${failed} failed, ${skipped} skipped (${elapsedSec}s)`,
+	orchMergeStart: (waveNum: number, laneCount: number) =>
+		`🔀 [Wave ${waveNum}] Merging ${laneCount} lane(s) into target branch...`,
+	orchMergeLaneSuccess: (laneNum: number, commit: string, durationSec: number) =>
+		`  ✅ Lane ${laneNum} merged (${commit.slice(0, 8)}, ${durationSec}s)`,
+	orchMergeLaneConflictResolved: (laneNum: number, conflictCount: number, durationSec: number) =>
+		`  ⚡ Lane ${laneNum} merged with ${conflictCount} auto-resolved conflict(s) (${durationSec}s)`,
+	orchMergeLaneFailed: (laneNum: number, reason: string) =>
+		`  ❌ Lane ${laneNum} merge failed: ${reason}`,
+	orchMergeComplete: (waveNum: number, mergedCount: number, totalSec: number) =>
+		`🔀 [Wave ${waveNum}] Merge complete: ${mergedCount} lane(s) merged (${totalSec}s)`,
+	orchMergeFailed: (waveNum: number, laneNum: number, reason: string) =>
+		`❌ [Wave ${waveNum}] Merge failed at lane ${laneNum}: ${reason}`,
+	orchMergeSkipped: (waveNum: number) => `📝 [Wave ${waveNum}] No successful lanes to merge`,
+	orchMergePlaceholder: (waveNum: number) =>
+		`🔀 [Wave ${waveNum}] Merge: placeholder — Step 3 (TS-008) will replace with mergeWave()`,
+	orchWorktreeReset: (waveNum: number, lanes: number) =>
+		`🔄 Resetting ${lanes} worktree(s) to target branch HEAD after wave ${waveNum}`,
+	orchBatchComplete: (
+		batchId: string,
+		succeeded: number,
+		failed: number,
+		skipped: number,
+		blocked: number,
+		elapsedSec: number,
+		orchBranch?: string,
+		baseBranch?: string,
+	) => {
+		const lines = [
+			`\n🏁 Batch ${batchId} complete: ${succeeded} succeeded, ${failed} failed, ${skipped} skipped, ${blocked} blocked (${elapsedSec}s)`,
+		];
+		if (failed > 0 || blocked > 0) {
+			lines.push("");
+			if (blocked > 0) {
+				lines.push(`   ${blocked} task(s) were blocked because upstream tasks failed.`);
+			}
+			lines.push("   Next steps:");
+			lines.push("   • /orch-status     — review what failed and why");
+			lines.push("   • /orch-resume     — retry from the failed wave");
+			lines.push("   • /orch-abort      — clean up and start fresh");
+		}
+		if (orchBranch && succeeded > 0) {
+			lines.push("");
+			lines.push("   ┌─────────────────────────────────────────────────┐");
+			lines.push(`   │  Your changes are on branch: ${orchBranch}`);
+			lines.push(`   │  Your ${baseBranch || "working"} branch was not modified.`);
+			if (baseBranch) {
+				lines.push(`   │  Preview: git log ${baseBranch}..${orchBranch}`);
+			}
+			lines.push("   │");
+			lines.push("   │  👉 To bring changes into your working branch:");
+			lines.push("   │");
+			lines.push("   │    /orch-integrate        — merge directly (recommended)");
+			lines.push("   │    /orch-integrate --pr   — create a pull request");
+			lines.push("   └─────────────────────────────────────────────────┘");
+		}
+		return lines.join("\n");
+	},
+	orchBatchFailed: (batchId: string, reason: string) => `\n❌ Batch ${batchId} failed: ${reason}`,
+	orchBatchStopped: (batchId: string, policy: string) =>
+		`\n⛔ Batch ${batchId} stopped by ${policy} policy`,
+
+	// /orch-pause
+	pauseNoBatch: () => "No active batch is running. Use /orch <areas|all> to start.",
+	pauseAlreadyPaused: (batchId: string) => `Batch ${batchId} is already paused.`,
+	pauseActivated: (batchId: string) =>
+		`⏸️  Pausing batch ${batchId}... lanes will stop after their current tasks complete.`,
+
+	// /orch-sessions
+	sessionsNone: () => "No active orchestrator sessions found.",
+	sessionsHeader: (count: number) => `🖥️  ${count} orchestrator session(s):`,
+
+	// /orch orphan detection
+	orphanDetectionResume: (batchId: string, sessionCount: number) =>
+		`🔄 Found ${sessionCount} running orchestrator session(s) from batch ${batchId}.\n` +
+		`   Use /orch-resume to continue, or /orch-abort to clean up.`,
+	orphanDetectionAbort: (sessionCount: number) =>
+		`⚠️ Found ${sessionCount} orphan orchestrator session(s) without usable state.\n` +
+		`   Use /orch-abort to clean up before starting a new batch.`,
+	orphanDetectionCleanup: () => `🧹 Cleaned up stale batch state file. Starting fresh.`,
+
+	// /orch-resume
+	resumeStarting: (batchId: string, phase: string) =>
+		`🔄 Resuming batch ${batchId} (was: ${phase})...`,
+	resumeReconciled: (
+		batchId: string,
+		completed: number,
+		pending: number,
+		failed: number,
+		reconnecting: number,
+		reExecuting: number = 0,
+	) =>
+		`📊 Batch ${batchId} reconciliation: ${completed} completed, ${pending} pending, ${failed} failed, ${reconnecting} reconnecting` +
+		(reExecuting > 0 ? `, ${reExecuting} re-executing` : ""),
+	resumeSkippedWaves: (skippedCount: number) => `⏭️  Skipping ${skippedCount} completed wave(s)`,
+	resumeReconnecting: (sessionCount: number) =>
+		`🔗 Reconnecting to ${sessionCount} alive session(s)...`,
+	resumeNoState: () =>
+		`❌ No batch to resume. No batch-state.json file found.\n` +
+		`   Use /orch <areas|all> to start a new batch.`,
+
+	/**
+	 * TP-187 (#539): Successful reconstruction from .pi/runtime/<batchId>/
+	 * runtime artifacts during force-resume after `orch_abort()`.
+	 */
+	resumeReconstructed: (batchId: string, selectionNote: string) =>
+		`🔨 Reconstructed batch ${batchId} from .pi/runtime/ artifacts (${selectionNote}).\n` +
+		`   Force-resume will proceed with a fresh wave-zero pass; the existing\n` +
+		`   reconciliation logic will re-detect succeeded tasks via .DONE markers.`,
+
+	/**
+	 * TP-187 (#539): Fail-loud message when force-resume can't reconstruct
+	 * after `orch_abort()` because required runtime artifacts are missing.
+	 */
+	resumeNoStateAfterAbort: (missingArtifact: string, batchId: string | null) =>
+		`❌ Cannot resume after abort: ${missingArtifact}.\n` +
+		(batchId ? `   Last known batch: ${batchId}.\n` : "") +
+		`   To start fresh from the preserved worktree state, run\n` +
+		`   \`orch_start <PROMPT.md>\` (or \`/orch <areas|all>\`).`,
+	resumeInvalidState: (error: string) =>
+		`❌ Cannot resume: batch state file is invalid.\n` +
+		`   Error: ${error}\n` +
+		`   Delete .pi/batch-state.json and start a new batch.`,
+	resumePhaseNotResumable: (batchId: string, phase: string, reason: string) =>
+		`❌ Cannot resume batch ${batchId} (phase: ${phase}).\n` + `   ${reason}`,
+	resumeComplete: (
+		batchId: string,
+		succeeded: number,
+		failed: number,
+		skipped: number,
+		blocked: number,
+		elapsedSec: number,
+	) =>
+		`\n🏁 Resumed batch ${batchId} complete: ${succeeded} succeeded, ${failed} failed, ${skipped} skipped, ${blocked} blocked (${elapsedSec}s total)`,
+
+	// /orch-resume --force
+	forceResumeStarting: (batchId: string, phase: string) =>
+		`⚠️ Force-resuming batch ${batchId} from ${phase} state. Running pre-resume diagnostics...`,
+	forceResumeDiagnosticsFailed: (batchId: string) =>
+		`❌ Cannot force-resume batch ${batchId}: pre-resume diagnostics failed.\n` +
+		`   Fix the issues above, then retry /orch-resume --force.`,
+
+	// /orch-abort
+	abortGracefulStarting: (batchId: string, sessionCount: number) =>
+		`⏳ Graceful abort of batch ${batchId}: signaling ${sessionCount} session(s) to checkpoint and exit...`,
+	abortGracefulWaiting: (batchId: string, graceSec: number) =>
+		`⏳ Waiting up to ${graceSec}s for sessions to checkpoint and exit...`,
+	abortGracefulForceKill: (count: number) =>
+		`⚠️ Force-killing ${count} session(s) that did not exit within timeout`,
+	abortGracefulComplete: (
+		batchId: string,
+		graceful: number,
+		forceKilled: number,
+		durationSec: number,
+	) =>
+		`✅ Graceful abort complete for batch ${batchId}: ${graceful} exited gracefully, ${forceKilled} force-killed (${durationSec}s)`,
+	abortHardStarting: (batchId: string, sessionCount: number) =>
+		`⚡ Hard abort of batch ${batchId}: killing ${sessionCount} session(s) immediately...`,
+	abortHardComplete: (batchId: string, killed: number, durationSec: number) =>
+		`✅ Hard abort complete for batch ${batchId}: ${killed} session(s) killed (${durationSec}s)`,
+	abortPartialFailure: (failureCount: number) =>
+		`⚠️ ${failureCount} error(s) during abort (see details above)`,
+	abortNoBatch: () => `No active batch to abort. Use /orch <areas|all> to start a batch.`,
+	abortComplete: (mode: AbortMode, sessionsKilled: number) =>
+		`🏁 Abort (${mode}) complete: ${sessionsKilled} session(s) terminated. Worktrees and branches preserved.`,
+	// /orch merge — repo-scoped partial summary (TP-005 Step 1)
+	orchMergePartialRepoSummary: (waveNum: number, repoLines: string[]) =>
+		`⚠️ [Wave ${waveNum}] Merge partially succeeded — repo outcomes diverged:\n${repoLines.join("\n")}`,
+
+	// /orch integration — post-batch integration guidance (TP-022 Step 4)
+	orchIntegrationAutoSuccess: (orchBranch: string, baseBranch: string) =>
+		`✅ Auto-integrated: ${baseBranch} fast-forwarded to ${orchBranch}.`,
+	orchIntegrationAutoFailed: (orchBranch: string, baseBranch: string, reason: string) =>
+		`⚠️ Auto-integration skipped: ${reason}\n` +
+		`   Orch branch ${orchBranch} preserved. Integrate manually:\n` +
+		`   git log ${baseBranch}..${orchBranch}\n` +
+		`   git merge ${orchBranch}`,
+	orchIntegrationManual: (orchBranch: string, baseBranch: string, mergedTaskCount: number) => {
+		const lines = [
+			`ℹ️ Batch complete. Orch branch ${orchBranch} has ${mergedTaskCount} merged task(s).`,
+			`   Review and integrate:`,
+			`   git log ${baseBranch}..${orchBranch}`,
+			`   git merge ${orchBranch}`,
+		];
+		return lines.join("\n");
+	},
+} as const;
+
+// ── Repo-Scoped Merge Summary (TP-005) ──────────────────────────────
+
+/**
+ * Status emoji for repo merge outcome.
+ */
+function repoStatusIcon(status: RepoMergeOutcome["status"]): string {
+	switch (status) {
+		case "succeeded":
+			return "✅";
+		case "partial":
+			return "⚠️";
+		case "failed":
+			return "❌";
+		default:
+			return "❓";
+	}
+}
+
+/**
+ * Format a repo-divergence summary for a partial merge wave result.
+ *
+ * Returns null if:
+ * - repoResults is empty or undefined (mono-repo mode)
+ * - all repos have the same status (no divergence)
+ * - there is only one repo group (divergence is meaningless)
+ *
+ * When the partial result is caused by mixed-outcome lanes within
+ * a single repo (not repo divergence), this returns null to avoid
+ * misleading "cross-repo divergence" messaging.
+ *
+ * The returned string is a complete, ready-to-emit message.
+ *
+ * @param mergeResult - The MergeWaveResult with status "partial"
+ * @returns Formatted summary string, or null if no repo-divergence summary applies
+ */
+export function formatRepoMergeSummary(mergeResult: MergeWaveResult): string | null {
+	const repoResults = mergeResult.repoResults;
+
+	// No repo attribution → mono-repo mode, no summary
+	if (!repoResults || repoResults.length === 0) {
+		return null;
+	}
+
+	// Single repo group → divergence is meaningless (partial is lane-level)
+	if (repoResults.length < 2) {
+		return null;
+	}
+
+	// Check for actual divergence: are there different statuses across repos?
+	const statuses = new Set(repoResults.map((r) => r.status));
+	if (statuses.size < 2) {
+		// All repos have the same status (e.g., all "partial") —
+		// the partial is from within-repo lane failures, not cross-repo divergence
+		return null;
+	}
+
+	// Build per-repo summary lines (sorted by repoId, which repoResults already is)
+	const repoLines = repoResults.map((r) => {
+		const repoLabel = r.repoId ?? "(default)";
+		const icon = repoStatusIcon(r.status);
+		// TP-032 R006-3: Exclude verification_new_failure lanes from success count
+		const mergedCount = r.laneResults.filter(
+			(lr) =>
+				!lr.error && (lr.result?.status === "SUCCESS" || lr.result?.status === "CONFLICT_RESOLVED"),
+		).length;
+		const totalCount = r.laneResults.length;
+		let detail = `${mergedCount}/${totalCount} lane(s) merged`;
+		if (r.failureReason) {
+			detail += ` — ${r.failureReason.slice(0, 150)}`;
+		}
+		return `   ${icon} ${repoLabel}: ${detail}`;
+	});
+
+	return ORCH_MESSAGES.orchMergePartialRepoSummary(mergeResult.waveIndex, repoLines);
+}
+
+// ── Merge Failure Policy Application (TP-005 Step 2) ─────────────────
+
+/**
+ * Result of applying the merge failure policy.
+ *
+ * Pure function output — callers use this to perform state mutations
+ * and notifications consistently. Ensures engine.ts and resume.ts
+ * apply identical pause/abort transitions.
+ */
+export interface MergeFailurePolicyResult {
+	/** The applied policy: "pause" or "abort". */
+	policy: "pause" | "abort";
+	/** Target phase for batchState.phase. */
+	targetPhase: "paused" | "stopped";
+	/** Error message to push to batchState.errors. */
+	errorMessage: string;
+	/** Persistence trigger label. */
+	persistTrigger: "merge-failure-pause" | "merge-failure-abort";
+	/** User-facing notification message. */
+	notifyMessage: string;
+	/** Notification level for onNotify. */
+	notifyLevel: "error";
+	/** Comma-separated failed lane identifiers for logging. */
+	failedLaneIds: string;
+	/** Structured log details for execLog. */
+	logDetails: {
+		failedLane: number;
+		failedLaneIds: string;
+		reason: string;
+	};
+}
+
+/**
+ * Compute the merge failure policy application result.
+ *
+ * This is a **pure function** — it computes all outputs deterministically
+ * from the merge result and config, without performing any side effects.
+ *
+ * Both engine.ts and resume.ts MUST use this function to guarantee
+ * identical failure attribution, phase transitions, error messages,
+ * and notifications on repo-scoped merge failures.
+ *
+ * Failure attribution rules (priority chain):
+ * 1. Lane-level: lanes with CONFLICT_UNRESOLVED, BUILD_FAILURE, or error
+ *    → formatted as `lane-<N>` (comma-separated).
+ * 2. Fallback: if no lane-level failures but `mergeResult.failedLane`
+ *    is non-null, uses `lane-<N>` as the identifier.
+ * 3. Repo-level: if no lane-level failures and failedLane is null
+ *    (repo setup failure), uses `repo:<repoId>` from repoResults
+ *    entries with non-succeeded status. Sorted deterministically.
+ * - The failure reason is truncated to 200 chars for notifications and
+ *   logged in full in batchState.errors.
+ *
+ * @param mergeResult  - The merge wave result with status "failed" or "partial"
+ * @param waveIndex    - 0-based wave index (displayed as 1-indexed)
+ * @param config       - Orchestrator configuration (for on_merge_failure policy)
+ * @returns Policy result object for callers to apply
+ */
+export function computeMergeFailurePolicy(
+	mergeResult: MergeWaveResult,
+	waveIndex: number,
+	config: OrchestratorConfig,
+): MergeFailurePolicyResult {
+	const waveNum = waveIndex + 1;
+	const mergeFailurePolicy = config.failure.on_merge_failure;
+
+	// Build failed lane identifiers from lane results.
+	// Priority chain:
+	//   1. Lane-level: lanes with CONFLICT_UNRESOLVED, BUILD_FAILURE, or error
+	//   2. Fallback: failedLane from mergeResult (single lane ID)
+	//   3. Repo-level: repos with non-succeeded status from repoResults
+	//      (catches setup failures where failedLane=null and no lane results)
+	let failedLaneIds = mergeResult.laneResults
+		.filter(
+			(r) =>
+				r.result?.status === "CONFLICT_UNRESOLVED" || r.result?.status === "BUILD_FAILURE" || r.error,
+		)
+		.map((r) => `lane-${r.laneNumber}`)
+		.join(", ");
+	if (!failedLaneIds && mergeResult.failedLane !== null) {
+		failedLaneIds = `lane-${mergeResult.failedLane}`;
+	}
+	if (!failedLaneIds && mergeResult.repoResults && mergeResult.repoResults.length > 0) {
+		// Repo-level fallback for setup failures (no lane results, failedLane=null).
+		// Uses sorted repoResults order for determinism.
+		failedLaneIds = mergeResult.repoResults
+			.filter((r) => r.status !== "succeeded")
+			.map((r) => `repo:${r.repoId ?? "default"}`)
+			.join(", ");
+	}
+
+	const reason = mergeResult.failureReason || "unknown";
+	const reasonTruncated = reason.slice(0, 200);
+
+	const logDetails = {
+		failedLane: mergeResult.failedLane ?? 0,
+		failedLaneIds,
+		reason: reasonTruncated,
+	};
+
+	const errorMessage =
+		`Merge failed at wave ${waveNum}: ${reason}. ` +
+		(mergeFailurePolicy === "pause"
+			? `Batch paused. Resolve conflicts and use /orch-resume to continue.`
+			: `Batch aborted by on_merge_failure policy.`);
+
+	const laneDetail = failedLaneIds ? ` (${failedLaneIds})` : "";
+
+	let notifyMessage: string;
+	if (mergeFailurePolicy === "pause") {
+		notifyMessage =
+			`⏸️  Batch paused due to merge failure at wave ${waveNum}${laneDetail}. ` +
+			`Reason: ${reasonTruncated}. ` +
+			`Resolve conflicts and resume.`;
+	} else {
+		notifyMessage =
+			`⛔ Batch aborted due to merge failure at wave ${waveNum}${laneDetail}. ` +
+			`Reason: ${reasonTruncated}.`;
+	}
+
+	return {
+		policy: mergeFailurePolicy,
+		targetPhase: mergeFailurePolicy === "pause" ? "paused" : "stopped",
+		errorMessage,
+		persistTrigger: mergeFailurePolicy === "pause" ? "merge-failure-pause" : "merge-failure-abort",
+		notifyMessage,
+		notifyLevel: "error",
+		failedLaneIds,
+		logDetails,
+	};
+}
+
+// ── Cleanup Gate Policy (TP-029 Step 2) ──────────────────────────────
+
+/**
+ * Per-repo cleanup failure detail.
+ * Collected during post-merge inter-wave verification.
+ */
+export interface CleanupGateRepoFailure {
+	/** Repo root path that has stale worktrees */
+	repoRoot: string;
+	/** Repo ID (undefined for primary/repo-mode) */
+	repoId: string | undefined;
+	/** Paths of stale worktrees still registered after cleanup */
+	staleWorktrees: string[];
+}
+
+/**
+ * Result of applying the cleanup gate policy.
+ *
+ * Pure function output — callers use this to perform state mutations
+ * and notifications consistently. Ensures engine.ts and resume.ts
+ * apply identical pause transitions on cleanup failure.
+ */
+export interface CleanupGatePolicyResult {
+	/** Always "pause" — cleanup failures block next wave but preserve merged work */
+	policy: "pause";
+	/** Target phase for batchState.phase */
+	targetPhase: "paused";
+	/** Error message to push to batchState.errors */
+	errorMessage: string;
+	/** Persistence trigger label — matches spec classification naming */
+	persistTrigger: "cleanup_post_merge_failed";
+	/** User-facing notification message */
+	notifyMessage: string;
+	/** Notification level for onNotify */
+	notifyLevel: "error";
+	/** Structured log details for execLog */
+	logDetails: {
+		waveNumber: number;
+		failedRepoCount: number;
+		totalStaleWorktrees: number;
+		repos: Array<{ repoId: string; staleCount: number }>;
+	};
+}
+
+/**
+ * Compute the cleanup gate policy result for post-merge verification failure.
+ *
+ * This is a **pure function** — it computes all outputs deterministically
+ * from the wave index and per-repo failure details, without performing any
+ * side effects.
+ *
+ * Both engine.ts and resume.ts MUST use this function to guarantee
+ * identical failure attribution, phase transitions, error messages,
+ * and notifications when post-merge cleanup leaves stale worktrees.
+ *
+ * The cleanup gate always pauses (never aborts) because:
+ * - Merged commits are already on the orch branch and must not be lost
+ * - The operator can manually remove stale worktrees and `/orch-resume`
+ *
+ * @param waveIndex  - 0-based wave index (displayed as 1-indexed)
+ * @param failures   - Per-repo cleanup failure details
+ * @returns Policy result object for callers to apply
+ */
+export function computeCleanupGatePolicy(
+	waveIndex: number,
+	failures: CleanupGateRepoFailure[],
+): CleanupGatePolicyResult {
+	const waveNum = waveIndex + 1;
+	const failedRepoCount = failures.length;
+	const totalStaleWorktrees = failures.reduce((sum, f) => sum + f.staleWorktrees.length, 0);
+
+	const repos = failures.map((f) => ({
+		repoId: f.repoId ?? "(default)",
+		staleCount: f.staleWorktrees.length,
+	}));
+
+	const repoDetail = repos.map((r) => `${r.repoId} (${r.staleCount} stale)`).join(", ");
+
+	const errorMessage =
+		`Post-merge cleanup failed at wave ${waveNum}: ${totalStaleWorktrees} stale worktree(s) ` +
+		`in ${failedRepoCount} repo(s) [${repoDetail}]. ` +
+		`Batch paused. Remove stale worktrees manually and use /orch-resume to continue.`;
+
+	// Build recovery commands for each failed repo
+	const recoveryLines: string[] = [];
+	for (const f of failures) {
+		const label = f.repoId ?? "default";
+		for (const wt of f.staleWorktrees) {
+			recoveryLines.push(`     git worktree remove --force "${wt}"  # repo: ${label}`);
+		}
+	}
+
+	const notifyMessage =
+		`⏸️  Batch paused: post-merge cleanup failed at wave ${waveNum}.\n` +
+		`   ${totalStaleWorktrees} stale worktree(s) in ${failedRepoCount} repo(s): ${repoDetail}\n` +
+		`   Manual recovery:\n` +
+		recoveryLines.join("\n") +
+		"\n" +
+		`   Then: /orch-resume`;
+
+	return {
+		policy: "pause",
+		targetPhase: "paused",
+		errorMessage,
+		persistTrigger: "cleanup_post_merge_failed",
+		notifyMessage,
+		notifyLevel: "error",
+		logDetails: {
+			waveNumber: waveNum,
+			failedRepoCount,
+			totalStaleWorktrees,
+			repos,
+		},
+	};
+}
+
+// ── Merge Retry Policy (TP-033 Step 2) ───────────────────────────────
+
+/**
+ * Classify a merge failure into a MergeFailureClassification.
+ *
+ * Inspects the MergeWaveResult — lane errors, failure reasons, and merge
+ * result statuses — to determine which retry policy class applies.
+ *
+ * Classification priority (first match wins):
+ * 1. `verification_new_failure` — any lane error starts with "verification_new_failure"
+ * 2. `merge_conflict_unresolved` — any lane result has CONFLICT_UNRESOLVED status
+ * 3. `cleanup_post_merge_failed` — failure reason contains "cleanup" or "stale worktree"
+ * 4. `git_lock_file` — failure reason contains "lock" or ".lock"
+ * 5. `git_worktree_dirty` — failure reason contains "dirty" or "worktree"
+ * 6. `null` — unclassifiable (treated as non-retriable by callers)
+ *
+ * This is a **pure function** — no side effects.
+ *
+ * @param mergeResult - The failed MergeWaveResult to classify
+ * @returns Classification or null if no merge-retry class matches
+ * @since TP-033
+ */
+export function classifyMergeFailure(
+	mergeResult: MergeWaveResult,
+): MergeFailureClassification | null {
+	// Check lane-level errors first (most specific)
+	for (const lr of mergeResult.laneResults) {
+		if (lr.error && lr.error.startsWith("verification_new_failure")) {
+			return "verification_new_failure";
+		}
+	}
+
+	// Check lane result statuses
+	for (const lr of mergeResult.laneResults) {
+		if (lr.result?.status === "CONFLICT_UNRESOLVED") {
+			return "merge_conflict_unresolved";
+		}
+	}
+
+	// Check failure reason string patterns
+	const reason = (mergeResult.failureReason || "").toLowerCase();
+
+	// Lock file detection: git operations fail with "Unable to create '.../.git/index.lock': File exists"
+	if (reason.includes("lock") || reason.includes(".lock")) {
+		return "git_lock_file";
+	}
+
+	// Cleanup failures: stale worktrees or cleanup errors
+	if (reason.includes("cleanup") || reason.includes("stale worktree")) {
+		return "cleanup_post_merge_failed";
+	}
+
+	// Dirty worktree: git operations fail due to uncommitted changes
+	if (reason.includes("dirty") || reason.includes("worktree")) {
+		return "git_worktree_dirty";
+	}
+
+	return null;
+}
+
+/**
+ * Compute the retry decision for a merge failure.
+ *
+ * Given the failure classification and the current retry count for the
+ * relevant scope, returns a decision indicating whether to retry, the
+ * cooldown to wait, or the exhaustion action to take.
+ *
+ * This is a **pure function** — both engine.ts and resume.ts MUST use
+ * this function to guarantee identical retry behavior.
+ *
+ * @param classification - The classified merge failure (null = unclassifiable)
+ * @param currentRetryCount - Current retry attempts for this scope (0 = first failure)
+ * @returns Retry decision with all fields populated
+ * @since TP-033
+ */
+export function computeMergeRetryDecision(
+	classification: MergeFailureClassification | null,
+	currentRetryCount: number,
+): MergeRetryDecision {
+	// Unclassifiable failures are never retried
+	if (classification === null) {
+		return {
+			shouldRetry: false,
+			cooldownMs: 0,
+			reason: "Unclassifiable merge failure — no retry policy available",
+			currentAttempt: currentRetryCount,
+			maxAttempts: 0,
+			classification: "merge_conflict_unresolved", // placeholder for type safety
+			exhaustionAction: "pause",
+		};
+	}
+
+	const policy: MergeRetryPolicy = MERGE_RETRY_POLICY_MATRIX[classification];
+
+	if (!policy.retriable) {
+		return {
+			shouldRetry: false,
+			cooldownMs: 0,
+			reason: `${classification} is not retriable — immediate ${policy.exhaustionAction}`,
+			currentAttempt: currentRetryCount,
+			maxAttempts: 0,
+			classification,
+			exhaustionAction: policy.exhaustionAction,
+		};
+	}
+
+	if (currentRetryCount >= policy.maxAttempts) {
+		return {
+			shouldRetry: false,
+			cooldownMs: 0,
+			reason: `${classification} retry exhausted (${currentRetryCount}/${policy.maxAttempts}) — ${policy.exhaustionAction}`,
+			currentAttempt: currentRetryCount,
+			maxAttempts: policy.maxAttempts,
+			classification,
+			exhaustionAction: policy.exhaustionAction,
+		};
+	}
+
+	return {
+		shouldRetry: true,
+		cooldownMs: policy.cooldownMs,
+		reason:
+			`${classification} retry ${currentRetryCount + 1}/${policy.maxAttempts}` +
+			(policy.cooldownMs > 0 ? ` (cooldown: ${policy.cooldownMs}ms)` : ""),
+		currentAttempt: currentRetryCount + 1,
+		maxAttempts: policy.maxAttempts,
+		classification,
+		exhaustionAction: policy.exhaustionAction,
+	};
+}
+
+/**
+ * Build the merge retry scope key for persisted retry counters.
+ *
+ * Format: `{repoId}:w{waveIndex}:l{laneNumber}`
+ * - In workspace mode: uses the repo ID (e.g., "api:w0:l1")
+ * - In repo mode (repoId undefined/null): uses "default" (e.g., "default:w0:l1")
+ *
+ * NOTE: This is a different key format from the task-scoped format in v3 types
+ * (`{taskId}:w{waveIndex}:l{laneNumber}`). The merge retry scope is intentionally
+ * repo-scoped because merge failures are per-repo, not per-task. Both formats
+ * coexist in `resilience.retryCountByScope` — the prefix disambiguates them.
+ *
+ * @param repoId - Repo ID (undefined/null in repo mode)
+ * @param waveIndex - 0-based wave index
+ * @param laneNumber - Lane number
+ * @returns Scope key string
+ * @since TP-033
+ */
+export function buildMergeRetryScopeKey(
+	repoId: string | undefined | null,
+	waveIndex: number,
+	laneNumber: number,
+): string {
+	const repo = repoId ?? "default";
+	return `${repo}:w${waveIndex}:l${laneNumber}`;
+}
+
+/**
+ * Extract the repo ID for a failed merge from the MergeWaveResult.
+ *
+ * Priority:
+ * 1. Lane-level: find the failed lane result and use its repoId
+ * 2. Repo-level: when failedLane is null (setup failure), check repoResults
+ *    for the first failed repo group
+ * 3. Fallback: undefined (will become "default" in scope key)
+ *
+ * This ensures workspace-mode setup failures (e.g., worktree dirty before
+ * any lane starts) still get repo-scoped counters rather than all collapsing
+ * into "default:w{N}:l0".
+ *
+ * @param mergeResult - The failed MergeWaveResult
+ * @returns Repo ID or undefined if not determinable
+ * @since TP-033 R006
+ */
+export function extractFailedRepoId(mergeResult: MergeWaveResult): string | undefined {
+	const failedLaneNum = mergeResult.failedLane;
+
+	// 1. Try lane-level extraction
+	if (failedLaneNum !== null && failedLaneNum !== undefined) {
+		const failedLaneResult = mergeResult.laneResults.find(
+			(lr) =>
+				lr.laneNumber === failedLaneNum &&
+				(lr.error ||
+					lr.result?.status === "CONFLICT_UNRESOLVED" ||
+					lr.result?.status === "BUILD_FAILURE"),
+		);
+		if (failedLaneResult?.repoId) return failedLaneResult.repoId;
+	}
+
+	// 2. Repo-level fallback for setup failures (failedLane === null)
+	if (mergeResult.repoResults && mergeResult.repoResults.length > 0) {
+		const failedRepo = mergeResult.repoResults.find(
+			(rr) => rr.status === "failed" || rr.status === "partial",
+		);
+		if (failedRepo?.repoId) return failedRepo.repoId;
+	}
+
+	// 3. If failureReason mentions a specific repo path, we could parse it,
+	//    but that's fragile. Return undefined → "default" in scope key.
+	return undefined;
+}
+
+/**
+ * Shared merge retry loop used by both engine.ts and resume.ts.
+ *
+ * Wraps the retry cycle in a loop: after each failed retry, re-classifies
+ * the latest mergeResult, recomputes the retry decision using the persisted
+ * counter, and continues until success, safe-stop, or exhaustion/non-retriable.
+ *
+ * This is the **single implementation** of retry loop semantics.
+ * Engine.ts and resume.ts provide callbacks for their specific side effects
+ * (persistence, merge invocation, notification) to guarantee parity.
+ *
+ * **Important:** On retry exhaustion, this returns `kind: "exhausted"` which
+ * the caller MUST handle by forcing `paused` phase regardless of
+ * `on_merge_failure` config. The exhaustion action from the matrix takes
+ * precedence over config policy.
+ *
+ * @param mergeResult - The initial failed merge result
+ * @param waveIdx - 0-based wave index (for logging)
+ * @param retryCountByScope - Mutable reference to persisted retry counters
+ * @param callbacks - Side-effect callbacks for persistence/merge/logging
+ * @returns Outcome describing what happened during the retry cycle
+ * @since TP-033 R006
+ */
+export async function applyMergeRetryLoop(
+	mergeResult: MergeWaveResult,
+	waveIdx: number,
+	retryCountByScope: Record<string, number>,
+	callbacks: MergeRetryCallbacks,
+): Promise<MergeRetryLoopOutcome> {
+	let currentResult = mergeResult;
+
+	// Classify the initial failure
+	let classification = classifyMergeFailure(currentResult);
+	const failedRepoId = extractFailedRepoId(currentResult);
+	const failedLaneNum = currentResult.failedLane ?? 0;
+	const scopeKey = buildMergeRetryScopeKey(failedRepoId, waveIdx, failedLaneNum);
+	const currentRetryCount = retryCountByScope[scopeKey] ?? 0;
+
+	// Check if any retry is possible at all
+	const initialDecision = computeMergeRetryDecision(classification, currentRetryCount);
+
+	if (!initialDecision.shouldRetry) {
+		// Non-retriable or already exhausted before we start
+		if (classification !== null && initialDecision.currentAttempt > 0) {
+			// Previously had retries — this is exhaustion
+			return {
+				kind: "exhausted",
+				mergeResult: currentResult,
+				classification,
+				scopeKey,
+				lastDecision: initialDecision,
+				errorMessage: `Merge retry exhausted at wave ${waveIdx + 1}: ${initialDecision.reason}`,
+				notifyMessage: `⏸️ Merge retry exhausted at wave ${waveIdx + 1}. ${initialDecision.reason}`,
+			};
+		}
+		// No retry was ever possible
+		return {
+			kind: "no_retry",
+			mergeResult: currentResult,
+			classification,
+			scopeKey,
+		};
+	}
+
+	// Enter retry loop
+	let lastDecision = initialDecision;
+
+	while (lastDecision.shouldRetry) {
+		// Increment counter in persisted state
+		retryCountByScope[scopeKey] = lastDecision.currentAttempt;
+
+		callbacks.log(`merge retry: ${lastDecision.reason}`, {
+			classification,
+			scopeKey,
+			attempt: lastDecision.currentAttempt,
+			maxAttempts: lastDecision.maxAttempts,
+			cooldownMs: lastDecision.cooldownMs,
+		});
+
+		callbacks.persist("merge-retry-increment");
+
+		// Emit Tier 0 attempt event via callback (TP-039 R004: emit only when retry is scheduled)
+		callbacks.onRetryAttempt?.(lastDecision);
+
+		callbacks.notify(
+			`🔄 Merge retry (${lastDecision.reason}) at wave ${waveIdx + 1}. ` +
+				(lastDecision.cooldownMs > 0
+					? `Waiting ${lastDecision.cooldownMs}ms before retry...`
+					: "Retrying immediately..."),
+			"warning",
+		);
+
+		if (lastDecision.cooldownMs > 0) {
+			await callbacks.sleep(lastDecision.cooldownMs);
+		}
+
+		// Re-invoke merge
+		callbacks.persist("merge-retry-start");
+		currentResult = await callbacks.performMerge();
+		callbacks.updateMergeResult(currentResult);
+		callbacks.persist("merge-retry-complete");
+
+		// Check outcome
+		if (currentResult.status === "succeeded") {
+			callbacks.notify(`✅ Merge retry succeeded at wave ${waveIdx + 1}.`, "info");
+			return {
+				kind: "retry_succeeded",
+				mergeResult: currentResult,
+				classification,
+				scopeKey,
+				lastDecision,
+			};
+		}
+
+		if (currentResult.rollbackFailed) {
+			// Safe-stop takes priority
+			const hasPersistErrors =
+				currentResult.persistenceErrors && currentResult.persistenceErrors.length > 0;
+			const persistWarning = hasPersistErrors
+				? ` WARNING: ${currentResult.persistenceErrors!.length} transaction record(s) failed to persist.`
+				: "";
+
+			return {
+				kind: "safe_stop",
+				mergeResult: currentResult,
+				classification,
+				scopeKey,
+				lastDecision,
+				errorMessage:
+					`Safe-stop at wave ${waveIdx + 1}: verification rollback failed after retry. ` +
+					`Merge worktree and temp branch preserved for recovery.` +
+					persistWarning,
+				notifyMessage:
+					`🛑 Safe-stop: verification rollback failed at wave ${waveIdx + 1} after retry. ` +
+					`Batch force-paused.` +
+					persistWarning,
+			};
+		}
+
+		// Retry failed — re-classify and check if we can retry again
+		classification = classifyMergeFailure(currentResult);
+		const updatedCount = retryCountByScope[scopeKey] ?? 0;
+		lastDecision = computeMergeRetryDecision(classification, updatedCount);
+	}
+
+	// Loop ended: exhaustion
+	return {
+		kind: "exhausted",
+		mergeResult: currentResult,
+		classification,
+		scopeKey,
+		lastDecision,
+		errorMessage: `Merge retry exhausted at wave ${waveIdx + 1}: ${lastDecision.reason}`,
+		notifyMessage: `⏸️ Merge retry exhausted at wave ${waveIdx + 1}. ${lastDecision.reason}`,
+	};
+}
+
+// ── Integrate Cleanup Acceptance (TP-029 Step 3) ─────────────────────
+
+/**
+ * Per-repo acceptance check findings after /orch-integrate.
+ * Collected by scanning all workspace repos (not just repos that had the orch branch).
+ */
+export interface IntegrateCleanupRepoFindings {
+	/** Repo root path */
+	repoRoot: string;
+	/** Repo ID (undefined for repo-mode / primary) */
+	repoId: string | undefined;
+	/** Stale lane worktrees still registered (git worktree list matches) */
+	staleWorktrees: string[];
+	/** Stale lane branches (task/{opId}-lane-*) */
+	staleLaneBranches: string[];
+	/** Stale orch branches (orch/{opId}-{batchId}) */
+	staleOrchBranches: string[];
+	/** Batch-scoped autostash entries still present */
+	staleAutostashEntries: string[];
+	/** Non-empty .worktrees/ containers */
+	nonEmptyWorktreeContainers: string[];
+}
+
+/**
+ * Result of the /orch-integrate cleanup acceptance check.
+ * Pure function output — callers use this to format the summary notification.
+ */
+export interface IntegrateCleanupResult {
+	/** True if all repos pass all acceptance criteria */
+	clean: boolean;
+	/** Notification severity level: "info" when clean, "warning" when dirty */
+	notifyLevel: "info" | "warning";
+	/** Per-repo findings (only repos with at least one finding) */
+	dirtyRepos: IntegrateCleanupRepoFindings[];
+	/** User-facing cleanup report (appended to integrate summary) */
+	report: string;
+}
+
+/**
+ * Compute the integrate cleanup result from per-repo acceptance findings.
+ *
+ * This is a **pure function** — computes all outputs deterministically
+ * from the per-repo findings without side effects.
+ *
+ * The acceptance criteria (roadmap 2d) are:
+ * 1. No registered lane worktrees remain in any workspace repo
+ * 2. No lane branches remain (task/{opId}-lane-*)
+ * 3. No orch branches remain (orch/{opId}-{batchId})
+ * 4. No stale autostash from current batch remains
+ * 5. No non-empty .worktrees/ containers remain
+ *
+ * @param repoFindings  - Per-repo findings from scanning all workspace repos
+ * @returns Cleanup result with pass/fail verdict and human-readable report
+ */
+export function computeIntegrateCleanupResult(
+	repoFindings: IntegrateCleanupRepoFindings[],
+): IntegrateCleanupResult {
+	// Filter to repos that have at least one issue
+	const dirtyRepos = repoFindings.filter(
+		(r) =>
+			r.staleWorktrees.length > 0 ||
+			r.staleLaneBranches.length > 0 ||
+			r.staleOrchBranches.length > 0 ||
+			r.staleAutostashEntries.length > 0 ||
+			r.nonEmptyWorktreeContainers.length > 0,
+	);
+
+	if (dirtyRepos.length === 0) {
+		return {
+			clean: true,
+			notifyLevel: "info",
+			dirtyRepos: [],
+			report: "🧹 Cleanup verified: no stale worktrees, branches, or autostash entries remain.",
+		};
+	}
+
+	// Build per-repo detail lines
+	const details: string[] = [];
+	for (const repo of dirtyRepos) {
+		const label = repo.repoId ?? "(default)";
+		const issues: string[] = [];
+		if (repo.staleWorktrees.length > 0) {
+			issues.push(`${repo.staleWorktrees.length} stale worktree(s)`);
+		}
+		if (repo.staleLaneBranches.length > 0) {
+			issues.push(`${repo.staleLaneBranches.length} lane branch(es)`);
+		}
+		if (repo.staleOrchBranches.length > 0) {
+			issues.push(`${repo.staleOrchBranches.length} orch branch(es)`);
+		}
+		if (repo.staleAutostashEntries.length > 0) {
+			issues.push(`${repo.staleAutostashEntries.length} autostash entr(ies)`);
+		}
+		if (repo.nonEmptyWorktreeContainers.length > 0) {
+			issues.push(`${repo.nonEmptyWorktreeContainers.length} non-empty .worktrees/ container(s)`);
+		}
+		details.push(`  ${label}: ${issues.join(", ")}`);
+	}
+
+	// Build recovery commands
+	const recovery: string[] = [];
+	for (const repo of dirtyRepos) {
+		const label = repo.repoId ?? "default";
+		for (const wt of repo.staleWorktrees) {
+			recovery.push(`  git worktree remove --force "${wt}"  # repo: ${label}`);
+		}
+		for (const br of repo.staleLaneBranches) {
+			recovery.push(`  git branch -D "${br}"  # repo: ${label}`);
+		}
+		for (const br of repo.staleOrchBranches) {
+			recovery.push(`  git branch -D "${br}"  # repo: ${label}`);
+		}
+		for (const entry of repo.staleAutostashEntries) {
+			recovery.push(`  git stash drop "${entry}"  # repo: ${label}`);
+		}
+	}
+
+	const report =
+		`⚠️ Cleanup incomplete — residual artifacts found:\n` +
+		details.join("\n") +
+		(recovery.length > 0 ? `\n  Manual cleanup:\n${recovery.join("\n")}` : "");
+
+	return {
+		clean: false,
+		notifyLevel: "warning",
+		dirtyRepos,
+		report,
+	};
+}
+
+// ── Resume ORCH_MESSAGES ─────────────────────────────────────────────
+
+// Note: These are added via extension to the ORCH_MESSAGES object below.
+
+// ── Resume Orchestration ─────────────────────────────────────────────
+
+/**
+ * Resume an interrupted batch from persisted state.
+ *
+ * Flow:
+ * 1. Load and validate batch-state.json
+ * 2. Check phase eligibility (paused/executing/merging only)
+ * 3. Check for alive TMUX sessions and .DONE files
+ * 4. Reconcile persisted state against live signals
+ * 5. Compute resume point (which wave to start from)
+ * 6. Reconstruct runtime state and continue execution
+ *
+ * @param orchConfig     - Orchestrator configuration
+ * @param runnerConfig   - Task runner configuration
+ * @param cwd            - Repository root
+ * @param batchState     - Mutable batch state (will be populated from persisted state)
+ * @param onNotify       - Callback for user-facing messages
+ * @param onMonitorUpdate - Optional callback for dashboard updates
+ */