taskplane 0.4.3 → 0.5.1

package/extensions/taskplane/merge.ts

@@ -11,7 +11,9 @@ import { resolveOperatorId } from "./naming.ts";
 import { MERGE_POLL_INTERVAL_MS, MERGE_RESULT_GRACE_MS, MERGE_RESULT_READ_RETRIES, MERGE_RESULT_READ_RETRY_DELAY_MS, MERGE_SPAWN_RETRY_MAX, MERGE_TIMEOUT_MS, MergeError, VALID_MERGE_STATUSES } from "./types.ts";
 import type { AllocatedLane, LaneExecutionResult, MergeLaneResult, MergeResult, MergeResultStatus, MergeWaveResult, OrchestratorConfig, RepoMergeOutcome, WaveExecutionResult, WorkspaceConfig } from "./types.ts";
 import { resolveBaseBranch, resolveRepoRoot } from "./waves.ts";
-import { sleepSync } from "./worktree.ts";
+import { generateMergeWorktreePath, sleepSync } from "./worktree.ts";
+import { getCurrentBranch, runGit } from "./git.ts";
+import { ORCH_MESSAGES } from "./messages.ts";
 
 // ── Merge Implementation ─────────────────────────────────────────────
 
@@ -567,9 +569,10 @@ export function mergeWave(
 	// ── 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.
-	// Include opId to prevent collisions between concurrent operators.
+	// The merge worktree lives inside the batch container alongside lane worktrees:
+	// {basePath}/{opId}-{batchId}/merge
 	const tempBranch = `_merge-temp-${opId}-${batchId}`;
-	const mergeWorkDir = join(repoRoot, ".worktrees", `merge-workspace-${opId}`);
+	const mergeWorkDir = generateMergeWorktreePath(repoRoot, opId, batchId, config);
 
 	// Clean up stale merge worktree/branch from prior failed attempt
 	try {
@@ -752,37 +755,87 @@ export function mergeWave(
 		}
 	}
 
-	// ── Fast-forward develop and clean up merge worktree ────────────
+	// ── Update target branch ref and clean up merge worktree ────────
 	const anySuccess = laneResults.some(
 		r => r.result?.status === "SUCCESS" || r.result?.status === "CONFLICT_RESOLVED",
 	);
 
 	if (anySuccess) {
-		// Fast-forward the real target branch to the temp merge branch.
-		// The main repo may have dirty files (user edits) — 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}`;
+		// 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 {
-				execLog("merge", `W${waveIndex}`, "fast-forward succeeded after stash/pop");
+				// 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),
+					});
+				}
 			}
-		} else {
-			execLog("merge", `W${waveIndex}`, `fast-forwarded ${targetBranch} to merge result`);
 		}
 	}
 
@@ -1068,3 +1121,105 @@ export function mergeWaveByRepo(
 	};
 }
 
+// ── 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;
+}
+

package/extensions/taskplane/messages.ts

@@ -36,7 +36,7 @@ export const ORCH_MESSAGES = {
 		`🔀 [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) => {
+	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("");
@@ -48,6 +48,17 @@ export const ORCH_MESSAGES = {
 			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(`   ℹ Orch branch: ${orchBranch}`);
+			if (baseBranch) {
+				lines.push(`   Review changes: git log ${baseBranch}..${orchBranch}`);
+			}
+			lines.push("   Next steps:");
+			lines.push("   • /orch-integrate          — fast-forward into your branch");
+			lines.push("   • /orch-integrate --merge   — merge (if branches diverged)");
+			lines.push("   • /orch-integrate --pr      — push and open a PR");
+		}
 		return lines.join("\n");
 	},
 	orchBatchFailed: (batchId: string, reason: string) =>
@@ -120,6 +131,24 @@ export const ORCH_MESSAGES = {
 	// /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;
 
 

package/extensions/taskplane/resume.ts

@@ -9,14 +9,14 @@ import { runDiscovery } from "./discovery.ts";
 import { executeOrchBatch } from "./engine.ts";
 import { computeTransitiveDependents, execLog, executeWave, pollUntilTaskComplete, spawnLaneSession, tmuxHasSession } from "./execution.ts";
 import type { MonitorUpdateCallback } from "./execution.ts";
-import { runGit } from "./git.ts";
-import { mergeWaveByRepo } from "./merge.ts";
+import { getCurrentBranch, runGit } from "./git.ts";
+import { attemptAutoIntegration, mergeWaveByRepo } from "./merge.ts";
 import { computeMergeFailurePolicy, formatRepoMergeSummary, ORCH_MESSAGES } from "./messages.ts";
 import { resolveOperatorId } from "./naming.ts";
 import { deleteBatchState, hasTaskDoneMarker, loadBatchState, persistRuntimeState, seedPendingOutcomesForAllocatedLanes, syncTaskOutcomesFromMonitor, upsertTaskOutcome } from "./persistence.ts";
 import { StateFileError } from "./types.ts";
 import type { AllocatedLane, AllocatedTask, LaneExecutionResult, LaneTaskOutcome, LaneTaskStatus, MergeWaveResult, OrchBatchPhase, OrchBatchRuntimeState, OrchestratorConfig, ParsedTask, PersistedBatchState, PersistedLaneRecord, ReconciledTaskState, ResumeEligibility, ResumePoint, TaskRunnerConfig, WaveExecutionResult, WorkspaceConfig } from "./types.ts";
-import { buildDependencyGraph, resolveRepoRoot } from "./waves.ts";
+import { buildDependencyGraph, resolveBaseBranch, resolveRepoRoot } from "./waves.ts";
 import { deleteBranchBestEffort, forceCleanupWorktree, listWorktrees, removeAllWorktrees, removeWorktree, safeResetWorktree } from "./worktree.ts";
 
 // ── Resume Repo Helpers ──────────────────────────────────────────────
@@ -56,6 +56,37 @@ export function collectRepoRoots(
 	return [...roots];
 }
 
+/**
+ * Resolve a repoId from a resolved repo root path.
+ *
+ * In workspace mode, workspace config maps repoId → path. This performs
+ * the reverse lookup: given a resolved absolute path, find the repoId.
+ * Returns `undefined` if no workspace config or no matching repo is found
+ * (which is correct for repo mode or the primary/default repo).
+ *
+ * Used during cleanup to call `resolveBaseBranch()` per-repo with the
+ * correct repoId, ensuring unmerged-branch protection checks against
+ * the right target branch in workspace mode.
+ *
+ * @param repoRoot        - Resolved absolute path of the repo
+ * @param workspaceConfig - Workspace configuration (null in repo mode)
+ * @returns The repoId or undefined if not found / not in workspace mode
+ */
+export function resolveRepoIdFromRoot(
+	repoRoot: string,
+	workspaceConfig?: WorkspaceConfig | null,
+): string | undefined {
+	if (!workspaceConfig) return undefined;
+
+	for (const [repoId, repoConfig] of workspaceConfig.repos) {
+		if (repoConfig.path === repoRoot) {
+			return repoId;
+		}
+	}
+
+	return undefined;
+}
+
 /**
  * Reconstruct AllocatedLane[] from persisted lane records.
  *
@@ -609,10 +640,26 @@ export async function resumeOrchBatch(
 	}
 
 	// ── 6. Reconstruct runtime state ─────────────────────────────
+
+	// Guard: orchBranch must be present for routing. Persisted states from
+	// pre-TP-022 runs may have orchBranch="" (TP-020 defaults).
+	// Check BEFORE mutating batchState so phase/batchId remain idle on rejection,
+	// allowing future /orch-resume or /orch-abort to proceed.
+	if (!persistedState.orchBranch) {
+		onNotify(
+			`❌ Cannot resume batch ${persistedState.batchId}: persisted state has no orch branch. ` +
+			`This batch was created before orch-branch routing was implemented. ` +
+			`Use /orch-abort to clean up, then start a new batch.`,
+			"error",
+		);
+		return;
+	}
+
 	batchState.phase = "executing";
 	batchState.batchId = persistedState.batchId;
 	batchState.baseBranch = persistedState.baseBranch || "";
-	batchState.orchBranch = persistedState.orchBranch || "";
+	batchState.orchBranch = persistedState.orchBranch;
+
 	batchState.mode = persistedState.mode;
 	batchState.startedAt = persistedState.startedAt;
 	batchState.pauseSignal = { paused: false };
@@ -902,7 +949,7 @@ export async function resumeOrchBatch(
 				orchConfig,
 				repoRoot,
 				batchState.batchId,
-				batchState.baseBranch,
+				batchState.orchBranch,
 				workspaceConfig,
 				stateRoot,
 				agentRoot,
@@ -1066,7 +1113,7 @@ export async function resumeOrchBatch(
 			batchState.batchId,
 			batchState.pauseSignal,
 			depGraph,
-			batchState.baseBranch,
+			batchState.orchBranch,
 			handleResumeMonitorUpdate,
 			(lanes) => {
 				latestAllocatedLanes = lanes;
@@ -1181,7 +1228,7 @@ export async function resumeOrchBatch(
 					orchConfig,
 					repoRoot,
 					batchState.batchId,
-					batchState.baseBranch,
+					batchState.orchBranch,
 					workspaceConfig,
 					stateRoot,
 					agentRoot,
@@ -1291,10 +1338,24 @@ export async function resumeOrchBatch(
 			// Use encounteredRepoRoots which includes both persisted lanes
 			// AND newly allocated lanes from resumed waves, ensuring repos
 			// introduced after resume starts are covered.
+			// Per-repo target branch: primary repo uses orchBranch, secondary
+			// repos resolve their own branch (same as cleanup — see section 11).
 			for (const perRepoRoot of encounteredRepoRoots) {
-				const existingWorktrees = listWorktrees(wtPrefix, perRepoRoot, resetOpId);
+				const existingWorktrees = listWorktrees(wtPrefix, perRepoRoot, resetOpId, batchState.batchId);
 				if (existingWorktrees.length > 0) {
-					const targetBranch = batchState.baseBranch;
+					let targetBranch: string;
+					if (perRepoRoot === repoRoot) {
+						targetBranch = batchState.orchBranch;
+					} else {
+						const repoId = resolveRepoIdFromRoot(perRepoRoot, workspaceConfig);
+						try {
+							targetBranch = resolveBaseBranch(repoId, perRepoRoot, batchState.orchBranch, workspaceConfig);
+						} catch {
+							// If resolution fails, fall back to orchBranch (reset will
+							// fail gracefully and trigger worktree removal)
+							targetBranch = batchState.orchBranch;
+						}
+					}
 					for (const wt of existingWorktrees) {
 						const resetResult = safeResetWorktree(wt, targetBranch, perRepoRoot);
 						if (!resetResult.success) {
@@ -1314,13 +1375,39 @@ export async function resumeOrchBatch(
 	if (!preserveWorktreesForResume) {
 		const wtPrefix = orchConfig.orchestrator.worktree_prefix;
 		const cleanupOpId = resolveOperatorId(orchConfig);
-		const targetBranch = batchState.baseBranch;
 
 		// Use encounteredRepoRoots which includes both persisted lanes
 		// AND newly allocated lanes from resumed waves, ensuring repos
 		// introduced after resume starts are cleaned up.
+		//
+		// Per-repo target branch resolution (workspace-mode correctness):
+		// In repo mode, orchBranch is the correct target for all worktrees.
+		// In workspace mode, the orchBranch only exists in the primary repo.
+		// Secondary repos were merged against their own resolved base branch
+		// (via resolveBaseBranch in mergeWaveByRepo), so unmerged-branch
+		// protection must compare against that same per-repo branch.
 		for (const perRepoRoot of encounteredRepoRoots) {
-			removeAllWorktrees(wtPrefix, perRepoRoot, cleanupOpId, targetBranch);
+			let targetBranch: string | undefined;
+			if (perRepoRoot === repoRoot) {
+				// Primary repo: lane branches were merged into orchBranch
+				targetBranch = batchState.orchBranch;
+			} else {
+				// Secondary repo (workspace mode): resolve the repo's own branch
+				// using the same logic as mergeWaveByRepo. Find repoId by matching
+				// the resolved path back to workspace config.
+				const repoId = resolveRepoIdFromRoot(perRepoRoot, workspaceConfig);
+				try {
+					targetBranch = resolveBaseBranch(repoId, perRepoRoot, batchState.orchBranch, workspaceConfig);
+				} catch {
+					// resolveBaseBranch may throw if HEAD is detached and no
+					// defaultBranch is configured. Fall back to undefined which
+					// skips branch protection (branches are deleted without
+					// merge-status check — safe because successfully merged
+					// branches were already cleaned up in post-merge steps).
+					targetBranch = undefined;
+				}
+			}
+			removeAllWorktrees(wtPrefix, perRepoRoot, cleanupOpId, targetBranch, batchState.batchId, orchConfig);
 		}
 	}
 
@@ -1335,6 +1422,32 @@ export async function resumeOrchBatch(
 		}
 	}
 
+	// ── Auto-Integration & Orch Branch Preservation (TP-022 Step 4) ──
+	// Parity with engine.ts: auto-integrate if configured, else show manual guidance.
+	// Gate: only run for terminal phases (completed/failed). Paused/stopped batches
+	// are not yet done — integration would mutate refs prematurely.
+	let autoIntegrated = false;
+	const mergedTaskCount = batchState.succeededTasks;
+	const isTerminalPhase = batchState.phase === "completed" || batchState.phase === "failed";
+	if (isTerminalPhase && !preserveWorktreesForResume && batchState.orchBranch && mergedTaskCount > 0) {
+		if (orchConfig.orchestrator.integration === "auto") {
+			autoIntegrated = attemptAutoIntegration(
+				batchState.orchBranch,
+				batchState.baseBranch,
+				repoRoot,
+				batchState.batchId,
+				"resume",
+				onNotify,
+			);
+		}
+		if (!autoIntegrated) {
+			onNotify(
+				ORCH_MESSAGES.orchIntegrationManual(batchState.orchBranch, batchState.baseBranch, mergedTaskCount),
+				"info",
+			);
+		}
+	}
+
 	persistRuntimeState("batch-terminal", batchState, wavePlan, latestAllocatedLanes, allTaskOutcomes, discovery, stateRoot);
 
 	if (batchState.phase === "paused" || batchState.phase === "stopped") {
@@ -1363,3 +1476,7 @@ export async function resumeOrchBatch(
 	}
 }
 
+
+// attemptAutoIntegration is now a shared helper in merge.ts (TP-022 Step 4).
+// Both engine.ts and resume.ts import it from there to eliminate parity drift.
+

package/extensions/taskplane/waves.ts

@@ -588,7 +588,20 @@ export function resolveBaseBranch(
 		}
 	}
 
-	// Step 3: Ultimate fallback — batch-level base branch
+	// Step 3: Ultimate fallback — batch-level base branch.
+	// In workspace mode the batch base branch is the orch branch (e.g.
+	// "orch/op-batch123"), which only exists in the primary repo. Using it
+	// for a secondary repo would cause worktree creation failure because the
+	// ref doesn't exist there. Fail fast with an actionable message instead.
+	if (repoId && batchBaseBranch.startsWith("orch/")) {
+		throw new Error(
+			`Cannot resolve base branch for repo "${repoId}" at ${repoRoot}: ` +
+			`HEAD is detached and no defaultBranch is configured. ` +
+			`The batch base branch "${batchBaseBranch}" is an orch branch that does not exist in this repo. ` +
+			`Configure a defaultBranch for this repo in task-orchestrator.yaml workspace settings.`,
+		);
+	}
+
 	return batchBaseBranch;
 }
 
@@ -1070,10 +1083,11 @@ export function allocateLanes(
 			// This should never happen if ensureLaneWorktrees and assignTasksToLanes
 			// agree on lane numbers, but handle defensively.
 			// Roll back all worktrees across all repos on this unexpected failure.
+			// Pass batchId + config for batch-scoped cleanup (only remove this batch's worktrees).
 			for (const groupKey of createdGroupKeys) {
 				const groupRepoId = repoIdForGroup.get(groupKey);
 				const groupRepoRoot = resolveRepoRoot(groupRepoId, repoRoot, workspaceConfig);
-				removeAllWorktrees(config.orchestrator.worktree_prefix, groupRepoRoot, opId);
+				removeAllWorktrees(config.orchestrator.worktree_prefix, groupRepoRoot, opId, undefined, batchId, config);
 			}
 			return {
 				success: false,

package/extensions/taskplane/worktree.ts

@@ -2,7 +2,7 @@
  * Worktree CRUD, bulk ops, branch protection, preflight
  * @module orch/worktree
  */
-import { existsSync, mkdirSync, readdirSync, realpathSync, rmSync } from "fs";
+import { existsSync, mkdirSync, readdirSync, realpathSync, rmdirSync, rmSync } from "fs";
 import { execSync } from "child_process";
 import { join, basename, resolve } from "path";
 
@@ -202,7 +202,7 @@ export function removeBatchContainerIfEmpty(containerPath: string): boolean {
 		if (entries.length > 0) {
 			return false; // Non-empty — do not remove (partial failure safety)
 		}
-		rmSync(containerPath, { recursive: false });
+		rmdirSync(containerPath);
 		return true;
 	} catch {
 		// If we can't read or remove — leave it alone (safe default)
@@ -1390,7 +1390,7 @@ export function ensureLaneWorktrees(
 	const prefix = config.orchestrator.worktree_prefix;
 	const opId = resolveOperatorId(config);
 
-	const existing = listWorktrees(prefix, repoRoot, opId);
+	const existing = listWorktrees(prefix, repoRoot, opId, batchId);
 	const existingByLane = new Map<number, WorktreeInfo>();
 	for (const wt of existing) {
 		existingByLane.set(wt.laneNumber, wt);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskplane",
-  "version": "0.4.3",
+  "version": "0.5.1",
   "description": "AI agent orchestration for pi — parallel task execution with checkpoint discipline",
   "keywords": [
     "pi-package",