taskplane 0.4.3 → 0.5.1

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);
 
@@ -766,22 +817,35 @@ export async function executeOrchBatch(
 				batchState.skippedTasks,
 				batchState.blockedTasks,
 				totalElapsedSec,
+				batchState.orchBranch,
+				batchState.baseBranch,
 			),
 			batchState.failedTasks > 0 ? "warning" : "info",
 		);
 
-		// ── TS-009: Delete state file on clean completion (no failures) ──
+		// ── Preserve state for /orch-integrate when orch branch exists ──
+		// If integration is "manual" and we have an orch branch, keep the
+		// state file so /orch-integrate can find orchBranch and baseBranch.
+		// Only delete state if there's no orch branch to integrate.
 		if (batchState.phase === "completed") {
-			try {
-				deleteBatchState(stateRoot);
-				execLog("state", batchState.batchId, "state file deleted on clean completion");
-			} catch (err: unknown) {
-				const msg = err instanceof Error ? err.message : String(err);
-				execLog("state", batchState.batchId, `failed to delete state file: ${msg}`);
+			if (batchState.orchBranch) {
+				execLog("state", batchState.batchId, "state file preserved for /orch-integrate", {
+					orchBranch: batchState.orchBranch,
+				});
+			} else {
+				// Legacy mode (no orch branch) — clean up state
+				try {
+					deleteBatchState(stateRoot);
+					execLog("state", batchState.batchId, "state file deleted on clean completion");
+				} catch (err: unknown) {
+					const msg = err instanceof Error ? err.message : String(err);
+					execLog("state", batchState.batchId, `failed to delete state file: ${msg}`);
+				}
 			}
 		}
 	}
 }
 
+
 // ── Dashboard Widget (Step 6) ────────────────────────────────────────
 

package/extensions/taskplane/execution.ts

@@ -11,6 +11,53 @@ import type { AllocatedLane, AllocatedTask, DependencyGraph, LaneExecutionResult
 import { allocateLanes } from "./waves.ts";
 import { runGit } from "./git.ts";
 
+// ── Task Runner Extension Path Resolution ────────────────────────────
+
+/**
+ * Find the task-runner extension path for lane sessions.
+ *
+ * Resolution order:
+ *   1. Local project: {repoRoot}/extensions/task-runner.ts (for taskplane dev)
+ *   2. Global npm (Windows): {APPDATA}/npm/node_modules/taskplane/extensions/task-runner.ts
+ *   3. Global npm (Unix): /usr/local/lib/node_modules/taskplane/extensions/task-runner.ts
+ *   4. npm peer: resolve from pi's location
+ *
+ * @throws ExecutionError if task-runner.ts cannot be found anywhere
+ */
+function resolveTaskRunnerExtensionPath(repoRoot: string): string {
+	const extFile = join("extensions", "task-runner.ts");
+
+	// 1. Local project (taskplane development)
+	const localPath = join(resolve(repoRoot), extFile);
+	if (existsSync(localPath)) return localPath;
+
+	// 2. Global npm install paths
+	const home = process.env.HOME || process.env.USERPROFILE || "";
+	const candidates: string[] = [];
+	if (process.env.APPDATA) {
+		candidates.push(join(process.env.APPDATA, "npm", "node_modules", "taskplane", extFile));
+	}
+	if (home) {
+		candidates.push(join(home, "AppData", "Roaming", "npm", "node_modules", "taskplane", extFile));
+		candidates.push(join(home, ".npm-global", "lib", "node_modules", "taskplane", extFile));
+	}
+	candidates.push(join("/usr", "local", "lib", "node_modules", "taskplane", extFile));
+
+	// 3. Peer of pi's package
+	try {
+		const piPath = process.argv[1] || "";
+		const piPkgDir = resolve(piPath, "..", "..");
+		candidates.push(join(piPkgDir, "..", "taskplane", extFile));
+	} catch { /* ignore */ }
+
+	for (const candidate of candidates) {
+		if (existsSync(candidate)) return candidate;
+	}
+
+	// Fallback: return the local path (will fail at spawn time with a clear error)
+	return localPath;
+}
+
 // ── Execution Helpers ────────────────────────────────────────────────
 
 /**
@@ -206,7 +253,7 @@ export function buildTmuxSpawnArgs(
 		.map(([key, val]) => `${key}=${shellQuote(val)}`)
 		.join(" ");
 
-	const taskRunnerExtPath = join(resolve(repoRoot), "extensions", "task-runner.ts");
+	const taskRunnerExtPath = resolveTaskRunnerExtensionPath(repoRoot);
 	const basePiCommand = `${envParts} pi --no-session -e ${shellQuote(taskRunnerExtPath)}`;
 
 	// NOTE: Do not redirect lane output here. Shell redirection has proven