taskplane 0.4.2 → 0.5.0

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

@@ -120,6 +120,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/persistence.ts

@@ -366,6 +366,18 @@ export function validatePersistedState(data: unknown): PersistedBatchState {
 		);
 	}
 
+	// ── Optional string fields: orchBranch ───────────────────────
+	// orchBranch was added after schema v2 shipped; default to "" if missing.
+	if (obj.orchBranch !== undefined && typeof obj.orchBranch !== "string") {
+		throw new StateFileError(
+			"STATE_SCHEMA_INVALID",
+			`Invalid "orchBranch" field (expected string, got ${typeof obj.orchBranch})`,
+		);
+	}
+	if (obj.orchBranch === undefined) {
+		obj.orchBranch = "";
+	}
+
 	// ── v2: mode field ───────────────────────────────────────────
 	// mode is required in v2, absent in v1 (defaults to "repo" via upconvert).
 	if (!isV1 && obj.mode === undefined) {
@@ -776,6 +788,7 @@ export function serializeBatchState(
 		phase: state.phase,
 		batchId: state.batchId,
 		baseBranch: state.baseBranch,
+		orchBranch: state.orchBranch ?? "",
 		mode: state.mode ?? "repo",
 		startedAt: state.startedAt,
 		updatedAt: now,

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,9 +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.mode = persistedState.mode;
 	batchState.startedAt = persistedState.startedAt;
 	batchState.pauseSignal = { paused: false };
@@ -901,7 +949,7 @@ export async function resumeOrchBatch(
 				orchConfig,
 				repoRoot,
 				batchState.batchId,
-				batchState.baseBranch,
+				batchState.orchBranch,
 				workspaceConfig,
 				stateRoot,
 				agentRoot,
@@ -1065,7 +1113,7 @@ export async function resumeOrchBatch(
 			batchState.batchId,
 			batchState.pauseSignal,
 			depGraph,
-			batchState.baseBranch,
+			batchState.orchBranch,
 			handleResumeMonitorUpdate,
 			(lanes) => {
 				latestAllocatedLanes = lanes;
@@ -1180,7 +1228,7 @@ export async function resumeOrchBatch(
 					orchConfig,
 					repoRoot,
 					batchState.batchId,
-					batchState.baseBranch,
+					batchState.orchBranch,
 					workspaceConfig,
 					stateRoot,
 					agentRoot,
@@ -1290,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) {
@@ -1313,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);
 		}
 	}
 
@@ -1334,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") {
@@ -1362,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/settings-tui.ts

@@ -98,9 +98,11 @@ export const SECTIONS: SectionDef[] = [
 			{ configPath: "orchestrator.orchestrator.worktreeLocation", label: "Worktree Location", control: "toggle", layer: "L1", fieldType: "enum", values: ["sibling", "subdirectory"], description: "Where lane worktree directories are created" },
 			{ configPath: "orchestrator.orchestrator.worktreePrefix", label: "Worktree Prefix", control: "input", layer: "L1", fieldType: "string", description: "Prefix for worktree directory names" },
 			{ configPath: "orchestrator.orchestrator.batchIdFormat", label: "Batch ID Format", control: "toggle", layer: "L1", fieldType: "enum", values: ["timestamp", "sequential"], description: "Batch ID format for logs/branch naming" },
-			{ configPath: "orchestrator.orchestrator.spawnMode", label: "Spawn Mode", control: "toggle", layer: "L1+L2", fieldType: "enum", values: ["tmux", "subprocess"], prefsKey: "spawnMode", description: "How lane sessions are spawned" },
+			// spawn_mode removed from Orchestrator section — /orch always requires tmux.
+			// The user-facing spawn mode setting is under Worker (controls /task behavior).
 			{ configPath: "orchestrator.orchestrator.tmuxPrefix", label: "Tmux Prefix", control: "input", layer: "L1+L2", fieldType: "string", prefsKey: "tmuxPrefix", description: "Prefix for orchestrator tmux sessions" },
 			{ configPath: "orchestrator.orchestrator.operatorId", label: "Operator ID", control: "input", layer: "L1+L2", fieldType: "string", prefsKey: "operatorId", description: "Operator identifier (empty = auto-detect)" },
+			{ configPath: "orchestrator.orchestrator.integration", label: "Integration", control: "toggle", layer: "L1", fieldType: "enum", values: ["manual", "auto"], description: "How completed batches are integrated. manual = user runs /orch-integrate. auto = fast-forward on completion." },
 		],
 	},
 	{
@@ -153,7 +155,7 @@ export const SECTIONS: SectionDef[] = [
 			{ configPath: "taskRunner.worker.model", label: "Worker Model", control: "input", layer: "L1+L2", fieldType: "string", prefsKey: "workerModel", description: "Worker model (empty = inherit session)" },
 			{ configPath: "taskRunner.worker.tools", label: "Worker Tools", control: "input", layer: "L1", fieldType: "string", description: "Worker tool allowlist" },
 			{ configPath: "taskRunner.worker.thinking", label: "Worker Thinking", control: "input", layer: "L1", fieldType: "string", description: "Worker thinking mode" },
-			{ configPath: "taskRunner.worker.spawnMode", label: "Worker Spawn Mode", control: "toggle", layer: "L1", fieldType: "enum", values: ["(inherit)", "subprocess", "tmux"], optional: true, description: "Worker spawn mode override (inherit = use orchestrator)" },
+			{ configPath: "taskRunner.worker.spawnMode", label: "Spawn Mode", control: "toggle", layer: "L1", fieldType: "enum", values: ["subprocess", "tmux"], description: "How /task spawns workers and reviewers. subprocess = child process (simpler), tmux = named sessions (attachable for debugging)" },
 		],
 	},
 	{

package/extensions/taskplane/types.ts

@@ -17,6 +17,8 @@ export interface OrchestratorConfig {
 		tmux_prefix: string;
 		/** Optional operator identifier. Auto-detected from OS username if empty. */
 		operator_id: string;
+		/** How completed batches are integrated. manual = user runs /orch-integrate. auto = fast-forward on completion. */
+		integration: "manual" | "auto";
 	};
 	dependencies: {
 		source: "prompt" | "agent";
@@ -151,6 +153,7 @@ export const DEFAULT_ORCHESTRATOR_CONFIG: OrchestratorConfig = {
 		spawn_mode: "subprocess",
 		tmux_prefix: "orch",
 		operator_id: "",
+		integration: "manual",
 	},
 	dependencies: {
 		source: "prompt",
@@ -829,6 +832,8 @@ export interface OrchBatchRuntimeState {
 	batchId: string;
 	/** Branch that was active when /orch started — used as base for worktrees and merge target */
 	baseBranch: string;
+	/** Orchestrator-managed branch name (e.g., 'orch/henry-20260318T140000'). Empty = legacy mode (merge into baseBranch directly). */
+	orchBranch: string;
 	/** Workspace execution mode (v2). Defaults to "repo" for backward compatibility. */
 	mode: WorkspaceMode;
 	/** Shared pause signal — set by /orch-pause, read by executeLane/executeWave */
@@ -908,6 +913,7 @@ export function freshOrchBatchState(): OrchBatchRuntimeState {
 		phase: "idle",
 		batchId: "",
 		baseBranch: "",
+		orchBranch: "",
 		mode: "repo",
 		pauseSignal: { paused: false },
 		waveResults: [],
@@ -1367,6 +1373,8 @@ export interface PersistedBatchState {
 	batchId: string;
 	/** Branch that was active when /orch started — used as base for worktrees and merge target */
 	baseBranch: string;
+	/** Orchestrator-managed branch name (e.g., 'orch/henry-20260318T140000'). Empty = legacy mode (merge into baseBranch directly). */
+	orchBranch: string;
 	/**
 	 * Workspace execution mode at batch start (v2).
 	 * - "repo": Single-repo mode (default, backward-compatible).

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,