taskplane 0.4.3 → 0.5.0

package/README.md

@@ -18,7 +18,7 @@ The taskplane dashboard runs on a local port on your system and gives you elegan
 
 ### Key Features
 
-- **Task Orchestrator** — Parallel multi-task execution using git worktrees for full filesystem isolation. Dependency-aware wave scheduling. Automated merges with conflict resolution.
+- **Task Orchestrator** — Parallel multi-task execution using git worktrees for full filesystem isolation. Dependency-aware wave scheduling. Automated merges into a dedicated orch branch — your working branch stays stable until you choose to integrate.
 - **Task Runner** — What the Orchestrator uses for autonomous single-task execution. Worker agents run in fresh-context loops with STATUS.md as persistent memory. Every checkbox gets a git checkpoint. Cross-model reviewer agents catch what the worker agents missed.
 - **Web Dashboard** — Live browser-based monitoring via `taskplane dashboard`. SSE streaming, lane/task progress, wave visualization, batch history.
 - **Structured Tasks** — PROMPT.md defines the mission, steps, and constraints. STATUS.md tracks progress. Agents follow the plan, not vibes.
@@ -128,7 +128,7 @@ The default scaffold includes two independent example tasks, so `/orch all` give
 Important distinction:
 
 - `/task` runs in your **current branch/worktree**.
-- `/orch` runs tasks in **isolated worktrees** and merges back.
+- `/orch` runs tasks in **isolated worktrees** on a dedicated orch branch — your working branch is never touched until you integrate.
 
 Because workers checkpoint with git commits, `/task` can capture unrelated local edits if you're changing files in parallel. For safer isolation (even with one task), prefer:
 
@@ -156,6 +156,7 @@ Orchestrator lanes execute tasks through task-runner under the hood, so `/task`
 | `/orch-abort [--hard]` | Abort batch (graceful or immediate) |
 | `/orch-deps <areas\|paths\|all>` | Show dependency graph |
 | `/orch-sessions` | List active worker sessions |
+| `/orch-integrate` | Integrate completed orch batch into your working branch |
 | `/taskplane-settings` | View and edit taskplane configuration interactively |
 
 ### CLI Commands
@@ -189,14 +190,18 @@ Orchestrator lanes execute tasks through task-runner under the hood, so `/task`
                  │
           ┌──────▼──────┐
           │ Merge Agent │    ← Conflict resolution
-          │ Integration │      & verification
-          │   Branch    │
+          │ Orch Branch │      & verification
+          └──────┬──────┘
+                 │
+          ┌──────▼──────┐
+          │ /orch-      │    ← User integrates into
+          │  integrate  │      working branch
           └─────────────┘
 ```
 
 **Single task** (`/task`): Worker iterates in fresh-context loops. STATUS.md is persistent memory. Each checkbox → git checkpoint. Reviewer validates on completion.
 
-**Parallel batch** (`/orch`): Tasks are sorted into dependency waves. Each wave runs in parallel across lanes (git worktrees). Completed lanes merge into the integration branch before the next wave starts.
+**Parallel batch** (`/orch`): Tasks are sorted into dependency waves. Each wave runs in parallel across lanes (git worktrees). Completed lanes merge into a dedicated orch branch. When the batch completes, use `/orch-integrate` to bring the results into your working branch (or configure auto-integration).
 
 ## Documentation
 

package/extensions/taskplane/engine.ts

@@ -9,7 +9,7 @@ import { formatDiscoveryResults, runDiscovery } from "./discovery.ts";
 import { execLog, executeWave, tmuxKillSession } from "./execution.ts";
 import type { MonitorUpdateCallback } from "./execution.ts";
 import { getCurrentBranch, runGit } from "./git.ts";
-import { mergeWaveByRepo } from "./merge.ts";
+import { attemptAutoIntegration, mergeWaveByRepo } from "./merge.ts";
 import { computeMergeFailurePolicy, formatRepoMergeSummary, ORCH_MESSAGES } from "./messages.ts";
 import { resolveOperatorId } from "./naming.ts";
 import { deleteBatchState, loadBatchHistory, persistRuntimeState, saveBatchHistory, seedPendingOutcomesForAllocatedLanes, syncTaskOutcomesFromMonitor, upsertTaskOutcome } from "./persistence.ts";
@@ -182,6 +182,26 @@ export async function executeOrchBatch(
 	wavePlan = rawWaves;
 	discoveryRef = discovery;
 
+	// ── Create orchestrator-managed branch ───────────────────────
+	// Created after all planning validations pass (preflight, discovery,
+	// graph validation, wave computation) to avoid orphan branches on
+	// planning-phase early exits.
+	// The orch branch isolates all batch work from the user's current branch.
+	// Worktrees branch from it; merges target it via update-ref.
+	const opId = resolveOperatorId(orchConfig);
+	const orchBranch = `orch/${opId}-${batchState.batchId}`;
+	const branchResult = runGit(["branch", orchBranch, batchState.baseBranch], repoRoot);
+	if (!branchResult.ok) {
+		batchState.phase = "failed";
+		batchState.endedAt = Date.now();
+		const errDetail = branchResult.stderr || branchResult.stdout || "unknown error";
+		batchState.errors.push(`Failed to create orch branch '${orchBranch}': ${errDetail}`);
+		onNotify(`❌ Failed to create orch branch '${orchBranch}': ${errDetail}`, "error");
+		return;
+	}
+	batchState.orchBranch = orchBranch;
+	execLog("batch", batchState.batchId, "created orch branch", { orchBranch, baseBranch: batchState.baseBranch });
+
 	onNotify(
 		ORCH_MESSAGES.orchStarting(batchState.batchId, rawWaves.length, batchState.totalTasks),
 		"info",
@@ -253,7 +273,7 @@ export async function executeOrchBatch(
 			batchState.batchId,
 			batchState.pauseSignal,
 			depGraph,
-			batchState.baseBranch,
+			batchState.orchBranch,
 			handleWaveMonitorUpdate,
 			(lanes) => {
 				latestAllocatedLanes = lanes;
@@ -361,7 +381,7 @@ export async function executeOrchBatch(
 					orchConfig,
 					repoRoot,
 					batchState.batchId,
-					batchState.baseBranch,
+					batchState.orchBranch,
 					workspaceConfig,
 					stateRoot,
 					agentRoot,
@@ -481,7 +501,7 @@ export async function executeOrchBatch(
 		if (waveIdx < rawWaves.length - 1 && !batchState.pauseSignal.paused) {
 			const prefix = orchConfig.orchestrator.worktree_prefix;
 			const resetOpId = resolveOperatorId(orchConfig);
-			const existingWorktrees = listWorktrees(prefix, repoRoot, resetOpId);
+			const existingWorktrees = listWorktrees(prefix, repoRoot, resetOpId, batchState.batchId);
 
 			if (existingWorktrees.length > 0) {
 				onNotify(
@@ -489,7 +509,7 @@ export async function executeOrchBatch(
 					"info",
 				);
 
-				const targetBranch = batchState.baseBranch;
+				const targetBranch = batchState.orchBranch;
 				for (const wt of existingWorktrees) {
 					const resetResult = safeResetWorktree(wt, targetBranch, repoRoot);
 					if (!resetResult.success) {
@@ -672,11 +692,13 @@ export async function executeOrchBatch(
 			}
 		} catch { /* .pi dir may not exist */ }
 
-		// Clean up worktrees — pass base branch to protect unmerged work
-		const targetBranch = batchState.baseBranch;
+		// Clean up worktrees — use orchBranch to protect unmerged work.
+		// Lane branches were merged into orchBranch (not baseBranch), so
+		// unmerged-branch detection must compare against orchBranch.
+		const targetBranch = batchState.orchBranch;
 		const cleanupOpId = resolveOperatorId(orchConfig);
 		execLog("batch", batchState.batchId, "cleaning up worktrees");
-		const removeResult = removeAllWorktrees(prefix, repoRoot, cleanupOpId, targetBranch);
+		const removeResult = removeAllWorktrees(prefix, repoRoot, cleanupOpId, targetBranch, batchState.batchId, orchConfig);
 
 		// Log preserved branches
 		for (const p of removeResult.preserved) {
@@ -750,6 +772,35 @@ export async function executeOrchBatch(
 		}
 	}
 
+	// ── Auto-Integration & Orch Branch Preservation (TP-022 Step 4) ──
+	// After all waves are done, optionally fast-forward baseBranch to orchBranch.
+	// Auto-integration never converts a successful batch into "failed" — failures
+	// are warnings that preserve the orch branch for manual integration.
+	// 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,
+				"batch",
+				onNotify,
+			);
+		}
+		// Manual mode (default) or auto-integration skipped: show integration guidance
+		if (!autoIntegrated) {
+			onNotify(
+				ORCH_MESSAGES.orchIntegrationManual(batchState.orchBranch, batchState.baseBranch, mergedTaskCount),
+				"info",
+			);
+		}
+	}
+
 	// ── TS-009: Persist terminal state ──
 	persistRuntimeState("batch-terminal", batchState, wavePlan, latestAllocatedLanes, allTaskOutcomes, discoveryRef, stateRoot);
 
@@ -783,5 +834,6 @@ export async function executeOrchBatch(
 	}
 }
 
+
 // ── Dashboard Widget (Step 6) ────────────────────────────────────────
 

package/extensions/taskplane/extension.ts

@@ -1,6 +1,6 @@
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 
-import { execSync } from "child_process";
+import { execSync, execFileSync } from "child_process";
 import { writeFileSync, unlinkSync, mkdirSync } from "fs";
 import { join } from "path";
 
@@ -9,6 +9,7 @@ import {
 	DEFAULT_TASK_RUNNER_CONFIG,
 	FATAL_DISCOVERY_CODES,
 	ORCH_MESSAGES,
+	StateFileError,
 	WorkspaceConfigError,
 	computeWaveAssignments,
 	createOrchWidget,
@@ -22,6 +23,7 @@ import {
 	formatPreflightResults,
 	formatWavePlan,
 	freshOrchBatchState,
+	getCurrentBranch,
 	listOrchSessions,
 	loadBatchState,
 	loadOrchestratorConfig,
@@ -29,6 +31,7 @@ import {
 	parseOrchSessionNames,
 	resumeOrchBatch,
 	runDiscovery,
+	runGit,
 	runPreflight,
 } from "./index.ts";
 import { buildExecutionContext } from "./workspace.ts";
@@ -42,6 +45,425 @@ import type {
 	TaskRunnerConfig,
 } from "./index.ts";
 
+// ── Integrate Args Parsing ────────────────────────────────────────────
+
+export type IntegrateMode = "ff" | "merge" | "pr";
+
+export interface IntegrateArgs {
+	mode: IntegrateMode;
+	force: boolean;
+	orchBranchArg?: string;
+}
+
+/**
+ * Parse `/orch-integrate` command arguments.
+ *
+ * Supported flags: --merge, --pr, --force
+ * Optional positional: orch branch name (e.g., orch/op-batchid)
+ *
+ * Returns parsed args or an error string if arguments are invalid.
+ */
+export function parseIntegrateArgs(raw: string | undefined): IntegrateArgs | { error: string } {
+	const input = raw?.trim() ?? "";
+	const tokens = input.split(/\s+/).filter(Boolean);
+
+	let mode: IntegrateMode = "ff";
+	let force = false;
+	const positionals: string[] = [];
+	let hasMerge = false;
+	let hasPr = false;
+
+	for (const token of tokens) {
+		if (token === "--merge") {
+			hasMerge = true;
+		} else if (token === "--pr") {
+			hasPr = true;
+		} else if (token === "--force") {
+			force = true;
+		} else if (token.startsWith("--")) {
+			return { error: `Unknown flag: ${token}` };
+		} else {
+			positionals.push(token);
+		}
+	}
+
+	// Mutual exclusion: --merge and --pr cannot be used together
+	if (hasMerge && hasPr) {
+		return { error: "Cannot use --merge and --pr together. Choose one integration mode." };
+	}
+
+	if (hasMerge) mode = "merge";
+	if (hasPr) mode = "pr";
+
+	if (positionals.length > 1) {
+		return { error: `Expected at most one branch argument, got ${positionals.length}: ${positionals.join(", ")}` };
+	}
+
+	return {
+		mode,
+		force,
+		orchBranchArg: positionals[0],
+	};
+}
+
+// ── Integration Context Resolution ────────────────────────────────────
+
+/**
+ * Successful result from resolveIntegrationContext.
+ */
+export interface IntegrationContext {
+	orchBranch: string;
+	baseBranch: string;
+	batchId: string;
+	currentBranch: string;
+	/** Informational messages generated during resolution (e.g., auto-detect notices) */
+	notices: string[];
+}
+
+/**
+ * Error result from resolveIntegrationContext.
+ */
+export interface IntegrationContextError {
+	error: string;
+	/** "info" for non-error states (legacy mode), "error" for real failures */
+	severity: "info" | "error";
+}
+
+/**
+ * Dependencies injected into resolveIntegrationContext for testability.
+ */
+export interface IntegrationDeps {
+	loadBatchState: () => PersistedBatchState | null;
+	getCurrentBranch: () => string | null;
+	listOrchBranches: () => string[];
+	orchBranchExists: (branch: string) => boolean;
+}
+
+/**
+ * Pure function to resolve all context needed for /orch-integrate.
+ *
+ * Resolution order:
+ * 1. Try loading persisted batch state → extract orchBranch/baseBranch
+ * 2. If state unavailable, use positional CLI arg
+ * 3. If neither, scan for orch/* branches
+ *
+ * Also performs: phase gating, legacy mode detection, branch existence check,
+ * detached HEAD check, and branch safety validation.
+ *
+ * Returns either a fully-resolved IntegrationContext or an IntegrationContextError.
+ */
+export function resolveIntegrationContext(
+	parsed: IntegrateArgs,
+	deps: IntegrationDeps,
+): IntegrationContext | IntegrationContextError {
+	let orchBranch = "";
+	let baseBranch = "";
+	let batchId = "";
+	const notices: string[] = [];
+
+	// Source 1: Try loading batch state
+	try {
+		const state = deps.loadBatchState();
+		if (state) {
+			orchBranch = state.orchBranch ?? "";
+			baseBranch = state.baseBranch ?? "";
+			batchId = state.batchId;
+
+			// Phase gate: batch must be completed before integration
+			if (state.phase !== "completed") {
+				return {
+					error:
+						`⏳ Batch ${batchId} is currently in "${state.phase}" phase.\n` +
+						`Integration requires a completed batch.\n` +
+						`Run /orch-status to check progress, or wait for the batch to finish.`,
+					severity: "info",
+				};
+			}
+
+			// Legacy merge mode check
+			if (!orchBranch) {
+				return {
+					error:
+						`ℹ️ Batch ${batchId} used legacy merge mode — work was already merged directly into ${baseBranch || "the base branch"}.\n` +
+						`There is no separate orch branch to integrate.`,
+					severity: "info",
+				};
+			}
+		}
+	} catch (err: unknown) {
+		// Capture the error but don't return yet — user may have provided a branch arg
+		const msg = err instanceof StateFileError
+			? (err.code === "STATE_FILE_IO_ERROR"
+				? `Could not read batch state file: ${err.message}`
+				: err.code === "STATE_FILE_PARSE_ERROR"
+					? `Batch state file contains invalid JSON: ${err.message}`
+					: `Batch state file has invalid schema: ${err.message}`)
+			: `Unexpected error loading batch state: ${(err as Error).message}`;
+		if (!parsed.orchBranchArg) {
+			return {
+				error: `⚠️ ${msg}\nYou can specify the orch branch directly: /orch-integrate <orch-branch>`,
+				severity: "error",
+			};
+		}
+		notices.push(`⚠️ ${msg} — using provided branch arg instead.`);
+	}
+
+	// Source 2: CLI positional branch arg overrides or fills in
+	if (parsed.orchBranchArg) {
+		orchBranch = parsed.orchBranchArg;
+	}
+
+	// Source 3: Neither state nor arg — scan for orch/* branches
+	if (!orchBranch) {
+		const candidates = deps.listOrchBranches();
+		if (candidates.length === 0) {
+			return {
+				error:
+					"❌ No completed batch found and no orch branches exist.\n" +
+					"Run /orch first to create a batch, or specify a branch: /orch-integrate <orch-branch>",
+				severity: "error",
+			};
+		}
+		if (candidates.length === 1) {
+			orchBranch = candidates[0];
+			notices.push(`ℹ️ No batch state found. Auto-detected orch branch: ${orchBranch}`);
+		} else {
+			return {
+				error:
+					`❌ No batch state found and multiple orch branches exist:\n` +
+					candidates.map(b => `  • ${b}`).join("\n") +
+					`\n\nSpecify which branch to integrate: /orch-integrate <orch-branch>`,
+				severity: "error",
+			};
+		}
+	}
+
+	// Verify orch branch exists
+	if (!deps.orchBranchExists(orchBranch)) {
+		return {
+			error: `❌ Branch "${orchBranch}" does not exist locally.\nCheck the branch name and try again.`,
+			severity: "error",
+		};
+	}
+
+	// Detached HEAD check
+	const currentBranch = deps.getCurrentBranch();
+	if (currentBranch === null) {
+		return {
+			error:
+				"❌ HEAD is detached — cannot integrate.\n" +
+				"Check out a branch first (e.g., `git checkout main`), then retry.",
+			severity: "error",
+		};
+	}
+
+	// Infer baseBranch from current branch when state is unavailable
+	if (!baseBranch) {
+		baseBranch = currentBranch;
+	}
+
+	// Branch safety: current branch must match baseBranch (unless --force)
+	if (currentBranch !== baseBranch && !parsed.force) {
+		return {
+			error:
+				`⚠️ Batch was started from ${baseBranch}, but you're on ${currentBranch}.\n` +
+				`Switch to ${baseBranch} first, or use /orch-integrate --force to skip this check.`,
+			severity: "error",
+		};
+	}
+
+	return {
+		orchBranch,
+		baseBranch,
+		batchId,
+		currentBranch,
+		notices,
+	};
+}
+
+// ── Integration Execution ─────────────────────────────────────────────
+
+/**
+ * Result of an integration attempt.
+ */
+export interface IntegrationResult {
+	/** Whether the integration succeeded overall */
+	success: boolean;
+	/** True if work was integrated locally (ff/merge) — controls cleanup eligibility */
+	integratedLocally: boolean;
+	/** Number of commits applied (informational) */
+	commitCount: string;
+	/** User-facing success message */
+	message: string;
+	/** User-facing error message (only when success=false) */
+	error?: string;
+}
+
+/**
+ * Dependencies injected into executeIntegration for testability.
+ */
+export interface IntegrationExecDeps {
+	runGit: (args: string[]) => { ok: boolean; stdout: string; stderr: string };
+	runCommand: (cmd: string, args: string[]) => { ok: boolean; stdout: string; stderr: string };
+	deleteBatchState: () => void;
+}
+
+/**
+ * Execute the integration operation for the resolved context.
+ *
+ * Mode-specific behavior:
+ * - ff: `git merge --ff-only {orchBranch}`. On failure → suggest --merge/--pr.
+ * - merge: `git merge {orchBranch} --no-edit`. On failure → show stderr.
+ * - pr: `git push origin {orchBranch}` then `gh pr create`. Never cleans up locally.
+ *
+ * Cleanup (local branch deletion + state file removal) is gated on integratedLocally === true.
+ * Cleanup failures are non-fatal (included as warnings in the message).
+ */
+export function executeIntegration(
+	mode: IntegrateMode,
+	context: IntegrationContext,
+	deps: IntegrationExecDeps,
+): IntegrationResult {
+	const { orchBranch, currentBranch, batchId } = context;
+
+	if (mode === "ff") {
+		// Fast-forward merge
+		const result = deps.runGit(["merge", "--ff-only", orchBranch]);
+		if (!result.ok) {
+			return {
+				success: false,
+				integratedLocally: false,
+				commitCount: "0",
+				message: "",
+				error:
+					`❌ Fast-forward failed — branches have diverged.\n` +
+					`${result.stderr}\n\n` +
+					`Try:\n` +
+					`  /orch-integrate --merge    Create a merge commit\n` +
+					`  /orch-integrate --pr       Create a pull request instead`,
+			};
+		}
+		// Count commits that were applied
+		const countResult = deps.runGit(["rev-list", "--count", `${orchBranch}..HEAD`]);
+		// After ff, HEAD === orchBranch tip so we use a different measurement
+		// The rev-list before the merge was computed in the handler; pass commitCount through context
+		// Actually, for ff: commits applied = what was ahead before merge.
+		// After ff merge HEAD moved forward, so we measure from the merge-base.
+		// Simplest: use "merge was successful" and the pre-computed count from the handler.
+		return performCleanup(deps, orchBranch, {
+			success: true,
+			integratedLocally: true,
+			commitCount: "?", // Overridden by caller with pre-computed count
+			message: `✅ Fast-forwarded ${currentBranch} to ${orchBranch}.`,
+		});
+	}
+
+	if (mode === "merge") {
+		const result = deps.runGit(["merge", orchBranch, "--no-edit"]);
+		if (!result.ok) {
+			return {
+				success: false,
+				integratedLocally: false,
+				commitCount: "0",
+				message: "",
+				error:
+					`❌ Merge failed — there may be conflicts.\n` +
+					`${result.stderr}\n\n` +
+					`Resolve conflicts manually, or try:\n` +
+					`  /orch-integrate --pr       Create a pull request instead`,
+			};
+		}
+		return performCleanup(deps, orchBranch, {
+			success: true,
+			integratedLocally: true,
+			commitCount: "?",
+			message: `✅ Merged ${orchBranch} into ${currentBranch} (merge commit created).`,
+		});
+	}
+
+	// PR mode
+	// Step 1: Push the orch branch to origin
+	const pushResult = deps.runGit(["push", "origin", orchBranch]);
+	if (!pushResult.ok) {
+		return {
+			success: false,
+			integratedLocally: false,
+			commitCount: "0",
+			message: "",
+			error:
+				`❌ Failed to push ${orchBranch} to origin.\n` +
+				`${pushResult.stderr}\n\n` +
+				`Check your remote configuration and try again.`,
+		};
+	}
+
+	// Step 2: Create pull request via gh CLI
+	const prTitle = batchId
+		? `Integrate orch batch ${batchId}`
+		: `Integrate ${orchBranch}`;
+	const ghResult = deps.runCommand("gh", [
+		"pr", "create",
+		"--base", currentBranch,
+		"--head", orchBranch,
+		"--title", prTitle,
+		"--fill",
+	]);
+	if (!ghResult.ok) {
+		return {
+			success: false,
+			integratedLocally: false,
+			commitCount: "0",
+			message: "",
+			error:
+				`❌ Branch pushed but PR creation failed.\n` +
+				`${ghResult.stderr}\n\n` +
+				`The branch ${orchBranch} is on origin — create the PR manually.`,
+		};
+	}
+
+	const prUrl = ghResult.stdout.trim();
+	return {
+		success: true,
+		integratedLocally: false, // PR mode: branch must survive
+		commitCount: "0",
+		message:
+			`✅ Pull request created for ${orchBranch} → ${currentBranch}.\n` +
+			(prUrl ? `   ${prUrl}\n` : "") +
+			`\nThe orch branch has been kept (needed for the PR).`,
+	};
+}
+
+/**
+ * Perform post-integration cleanup: delete local orch branch and batch state.
+ * Cleanup failures are non-fatal — warnings are appended to the result message.
+ */
+function performCleanup(
+	deps: IntegrationExecDeps,
+	orchBranch: string,
+	result: IntegrationResult,
+): IntegrationResult {
+	const warnings: string[] = [];
+
+	// Delete local orch branch
+	const branchDelete = deps.runGit(["branch", "-D", orchBranch]);
+	if (!branchDelete.ok) {
+		warnings.push(`⚠️ Could not delete local branch ${orchBranch}: ${branchDelete.stderr}`);
+	}
+
+	// Delete batch state file
+	try {
+		deps.deleteBatchState();
+	} catch (err: unknown) {
+		warnings.push(`⚠️ Could not clean up batch state: ${(err as Error).message}`);
+	}
+
+	if (warnings.length > 0) {
+		result.message += "\n" + warnings.join("\n");
+	}
+
+	return result;
+}
+
 // ── Extension ────────────────────────────────────────────────────────
 
 export default function (pi: ExtensionAPI) {
@@ -647,6 +1069,143 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	pi.registerCommand("orch-integrate", {
+		description: "Integrate completed orch batch into your working branch",
+		handler: async (args, ctx) => {
+			// Show usage if no args and no active batch state to infer from
+			if (args?.trim() === "--help" || args?.trim() === "-h") {
+				ctx.ui.notify(
+					"Usage: /orch-integrate [<orch-branch>] [--merge] [--pr] [--force]\n\n" +
+					"Integrate a completed orch batch into your working branch.\n\n" +
+					"Modes:\n" +
+					"  (default)   Fast-forward merge (cleanest history)\n" +
+					"  --merge     Create a real merge commit\n" +
+					"  --pr        Push orch branch and create a pull request\n\n" +
+					"Options:\n" +
+					"  --force     Skip branch safety check\n" +
+					"  <branch>    Orch branch name (auto-detected from batch state if omitted)\n\n" +
+					"Examples:\n" +
+					"  /orch-integrate                          Auto-detect and fast-forward\n" +
+					"  /orch-integrate --merge                  Auto-detect with merge commit\n" +
+					"  /orch-integrate orch/op-abc123 --pr      Specific branch, create PR\n" +
+					"  /orch-integrate --force                  Skip branch safety check",
+					"info",
+				);
+				return;
+			}
+
+			if (!requireExecCtx(ctx)) return;
+
+			// Parse arguments
+			const parsed = parseIntegrateArgs(args);
+			if ("error" in parsed) {
+				ctx.ui.notify(`❌ ${parsed.error}\n\nRun /orch-integrate --help for usage.`, "error");
+				return;
+			}
+
+			// ── Step 2: Resolve integration context ──────────────────
+			const { repoRoot } = execCtx!;
+			const resolution = resolveIntegrationContext(parsed, {
+				loadBatchState: () => loadBatchState(repoRoot),
+				getCurrentBranch: () => getCurrentBranch(repoRoot),
+				listOrchBranches: () => {
+					const result = runGit(["branch", "--list", "orch/*"], repoRoot);
+					return result.ok
+						? result.stdout.split("\n").map(b => b.replace(/^\*?\s+/, "").trim()).filter(Boolean)
+						: [];
+				},
+				orchBranchExists: (branch: string) => {
+					return runGit(["rev-parse", "--verify", `refs/heads/${branch}`], repoRoot).ok;
+				},
+			});
+
+			if ("error" in resolution) {
+				const severity = (resolution as IntegrationContextError).severity;
+				ctx.ui.notify(resolution.error, severity === "info" ? "info" : "error");
+				return;
+			}
+
+			const { orchBranch, baseBranch, batchId, currentBranch, notices } = resolution as IntegrationContext;
+
+			// Show any notices from resolution (auto-detection messages, warnings)
+			for (const notice of notices) {
+				ctx.ui.notify(notice, "info");
+			}
+
+			// ── Step 2: Pre-integration summary ──────────────────────
+			// Count commits ahead
+			const revListResult = runGit(
+				["rev-list", "--count", `${currentBranch}..${orchBranch}`],
+				repoRoot,
+			);
+			const commitsAhead = revListResult.ok ? revListResult.stdout.trim() : "?";
+
+			// Get diff summary
+			const diffStatResult = runGit(
+				["diff", "--stat", `${currentBranch}...${orchBranch}`],
+				repoRoot,
+			);
+			const diffSummary = diffStatResult.ok ? diffStatResult.stdout.trim() : "(unable to compute diff)";
+
+			ctx.ui.notify(
+				`🔀 Integration Summary\n` +
+				`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n` +
+				`  Orch branch:  ${orchBranch}\n` +
+				`  Target:       ${currentBranch}\n` +
+				`  Commits:      ${commitsAhead} ahead\n` +
+				`  Mode:         ${parsed.mode === "ff" ? "fast-forward" : parsed.mode === "merge" ? "merge commit" : "pull request"}\n` +
+				(batchId ? `  Batch:        ${batchId}\n` : "") +
+				(parsed.force ? `  ⚠ Force:      branch safety check skipped\n` : "") +
+				`\n` +
+				(diffSummary ? `${diffSummary}\n` : "") +
+				`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`,
+				"info",
+			);
+
+			// ── Step 3: Execute integration mode ─────────────────
+			const integrationResult = executeIntegration(parsed.mode, resolution as IntegrationContext, {
+				runGit: (gitArgs: string[]) => runGit(gitArgs, repoRoot),
+				runCommand: (cmd: string, cmdArgs: string[]) => {
+					try {
+						const stdout = execFileSync(cmd, cmdArgs, {
+							encoding: "utf-8",
+							timeout: 60_000,
+							cwd: repoRoot,
+							stdio: ["pipe", "pipe", "pipe"],
+						}).trim();
+						return { ok: true, stdout, stderr: "" };
+					} catch (err: unknown) {
+						const e = err as { stdout?: string; stderr?: string; message?: string };
+						return {
+							ok: false,
+							stdout: (e.stdout ?? "").toString().trim(),
+							stderr: (e.stderr ?? e.message ?? "unknown error").toString().trim(),
+						};
+					}
+				},
+				deleteBatchState: () => deleteBatchState(repoRoot),
+			});
+
+			if (!integrationResult.success) {
+				ctx.ui.notify(integrationResult.error!, "error");
+				return;
+			}
+
+			// Override commit count with pre-computed value for local integrations
+			if (integrationResult.integratedLocally) {
+				integrationResult.commitCount = commitsAhead;
+			}
+
+			ctx.ui.notify(
+				integrationResult.message +
+				(integrationResult.integratedLocally
+					? `\n${integrationResult.commitCount} commit(s) applied.`
+					: ""),
+				"info",
+			);
+		},
+	});
+
 	// ── Settings TUI ─────────────────────────────────────────────────
 
 	pi.registerCommand("taskplane-settings", {
@@ -719,7 +1278,8 @@ export default function (pi: ExtensionAPI) {
 			"/orch <areas|all>        Start batch execution\n" +
 			"/orch-plan <areas|all>   Preview execution plan\n" +
 			"/orch-deps <areas|all>   Show dependency graph\n" +
-			"/orch-sessions           List TMUX sessions",
+			"/orch-sessions           List TMUX sessions\n" +
+			"/orch-integrate          Integrate orch branch into working branch",
 			"info",
 		);
 

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/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.0",
   "description": "AI agent orchestration for pi — parallel task execution with checkpoint discipline",
   "keywords": [
     "pi-package",