taskplane 0.25.8 → 0.27.0

package/extensions/taskplane/execution.ts

@@ -13,22 +13,13 @@ import { resolvePacketPaths, buildRuntimeAgentId } from "./types.ts";
 import { readRegistrySnapshot, readLaneSnapshot, isTerminalStatus, isProcessAlive, detectOrphans, markOrphansCrashed, buildRegistrySnapshot, writeRegistrySnapshot } from "./process-registry.ts";
 import { allocateLanes } from "./waves.ts";
 import { resolveOperatorId } from "./naming.ts";
-import { runGit } from "./git.ts";
+import { runGit, runGitWithEnv } from "./git.ts";
 import { resolveTaskplanePackageFile, resolveTaskplaneAgentTemplate } from "./path-resolver.ts";
+import { resolvePointer, loadWorkspaceConfig } from "./workspace.ts";
 
 // ── Taskplane Package File Resolution ────────────────────────────────
 // getNpmGlobalRoot() and resolveTaskplanePackageFile() consolidated in path-resolver.ts (TP-157)
 
-// ── Task Runner Extension Path Resolution ────────────────────────────
-
-/**
- * Find the task-runner extension path for lane sessions.
- * @see resolveTaskplanePackageFile for resolution order
- */
-function resolveTaskRunnerExtensionPath(repoRoot: string): string {
-	return resolveTaskplanePackageFile(repoRoot, join("extensions", "task-runner.ts"));
-}
-
 // ── RPC Wrapper Path Resolution ──────────────────────────────────────
 
 /**
@@ -50,7 +41,7 @@ function resolveTaskRunnerExtensionPath(repoRoot: string): string {
 /**
  * Structured log helper for lane execution.
  *
- * All execution logs go to stderr (same pattern as task-runner.ts).
+ * All execution logs go to stderr.
  * Format: [orch] {laneId}/{taskId}: {message}
  * Correlation fields: batchId, laneId, taskId, sessionName.
  * No PII — only IDs and paths.
@@ -378,9 +369,8 @@ export function resolveCanonicalTaskPaths(
 
 	if (isWorkspaceMode) {
 		// Workspace mode: use worktree-relative path when the task folder is
-		// inside the lane's repo (same logic as TASK_AUTOSTART resolution).
-		// The worker writes .DONE and STATUS.md in the worktree, so the engine
-		// must look there too.
+		// inside the lane's repo. The worker writes .DONE and STATUS.md in
+		// the worktree, so the engine must look there too.
 		if (folderNorm.startsWith(repoRootNorm + "/")) {
 			const relPath = folderNorm.slice(repoRootNorm.length + 1);
 			resolvedFolder = join(worktreePath, relPath);
@@ -1392,7 +1382,7 @@ export function computeTransitiveDependents(
  *
  * Git worktrees only contain tracked (committed) files. If a user creates
  * task folders (PROMPT.md, STATUS.md) but doesn't commit them, the worktree
- * won't have those files and TASK_AUTOSTART will fail with "file not found".
+ * won't have those files and the worker will fail with "file not found".
  *
  * This function checks each wave task's folder for untracked or modified files,
  * stages them, and creates a commit on the current branch. This must run BEFORE
@@ -1446,6 +1436,124 @@ export function ensureTaskFilesCommitted(
 
 	if (foldersToStage.length === 0) return;
 
+	// TP-169: When an orch branch is provided, commit task files directly on
+	// the orch branch using a temporary git index file. This avoids polluting
+	// the repo's current branch (e.g. main) with orchestrator-internal staging
+	// commits, maintaining proper branch isolation in workspace mode.
+	//
+	// Approach:
+	// 1. Read the orch branch's tree into a temporary index
+	// 2. Add new/modified task files to the temporary index
+	// 3. Write the combined tree
+	// 4. Create a commit on the orch branch
+	// 5. Update the orch branch ref
+	// 6. Clean up the temporary index
+	//
+	// Fallback: if orch branch plumbing fails or orchBranch is not provided,
+	// fall back to the legacy path of committing on HEAD.
+	if (orchBranch) {
+		const orchTipRes = runGit(["rev-parse", `refs/heads/${orchBranch}`], repoRoot);
+		if (orchTipRes.ok) {
+			const orchTip = orchTipRes.stdout.trim();
+			const tmpIdx = join(repoRoot, ".git", `tmp-staging-idx-wave-${waveIndex}`);
+
+			try {
+				// Read orch branch tree into temporary index
+				const readTreeRes = runGitWithEnv(
+					["read-tree", orchTip],
+					repoRoot,
+					{ GIT_INDEX_FILE: tmpIdx },
+				);
+				if (!readTreeRes.ok) {
+					execLog("wave", `W${waveIndex}`, `orch branch staging: read-tree failed, falling back to HEAD commit`, {
+						error: readTreeRes.stderr,
+					});
+					// Fall through to legacy path
+				} else {
+					// Add task files to temporary index
+					let addFailed = false;
+					for (const folder of foldersToStage) {
+						const addRes = runGitWithEnv(
+							["add", "--", folder],
+							repoRoot,
+							{ GIT_INDEX_FILE: tmpIdx },
+						);
+						if (!addRes.ok) {
+							execLog("wave", `W${waveIndex}`, `orch branch staging: git add failed for ${folder}, falling back`, {
+								error: addRes.stderr,
+							});
+							addFailed = true;
+							break;
+						}
+					}
+
+					if (!addFailed) {
+						// Write tree from temporary index
+						const writeTreeRes = runGitWithEnv(
+							["write-tree"],
+							repoRoot,
+							{ GIT_INDEX_FILE: tmpIdx },
+						);
+
+						if (writeTreeRes.ok) {
+							const tree = writeTreeRes.stdout.trim();
+							const taskIds = foldersToStage.map(f => f.split("/").pop() || f).join(", ");
+							const commitMsg = `chore: stage task files for orchestrator wave ${waveIndex} (${taskIds})`;
+
+							// Create commit directly on orch branch
+							const commitTreeRes = runGit(
+								["commit-tree", tree, "-p", orchTip, "-m", commitMsg],
+								repoRoot,
+							);
+
+							if (commitTreeRes.ok) {
+								const newCommit = commitTreeRes.stdout.trim();
+								const refUpdateRes = runGit(
+									["update-ref", `refs/heads/${orchBranch}`, newCommit, orchTip],
+									repoRoot,
+								);
+
+								if (refUpdateRes.ok) {
+									execLog("wave", `W${waveIndex}`, `committed ${foldersToStage.length} task folder(s) directly on orch branch`, {
+										orchBranch,
+										folders: foldersToStage,
+										from: orchTip.slice(0, 8),
+										to: newCommit.slice(0, 8),
+									});
+									// Clean up temp index and return — no need for legacy path
+									try { unlinkSync(tmpIdx); } catch { /* best effort */ }
+									return;
+								}
+								execLog("wave", `W${waveIndex}`, `orch branch staging: ref update failed, falling back`, {
+									error: refUpdateRes.stderr,
+								});
+							} else {
+								execLog("wave", `W${waveIndex}`, `orch branch staging: commit-tree failed, falling back`, {
+									error: commitTreeRes.stderr,
+								});
+							}
+						} else {
+							execLog("wave", `W${waveIndex}`, `orch branch staging: write-tree failed, falling back`, {
+								error: writeTreeRes.stderr,
+							});
+						}
+					}
+				}
+			} catch (err: unknown) {
+				execLog("wave", `W${waveIndex}`, `orch branch staging: unexpected error, falling back to HEAD commit`, {
+					error: err instanceof Error ? err.message : String(err),
+				});
+			} finally {
+				// Always clean up temp index
+				try { unlinkSync(tmpIdx); } catch { /* best effort */ }
+			}
+		}
+	}
+
+	// Legacy fallback: commit on HEAD and sync orch branch.
+	// This path is used when orchBranch is not provided, or when the
+	// plumbing-based approach above failed.
+
 	// Stage only the task folders
 	for (const folder of foldersToStage) {
 		const addResult = runGit(["add", "--", folder], repoRoot);
@@ -1482,15 +1590,6 @@ export function ensureTaskFilesCommitted(
 	// Fast-forward (or merge) the orch branch to include the staging commit so
 	// that worktrees—which branch from orchBranch—see the new task files and
 	// workers can find their PROMPT.md / STATUS.md without an ENOENT crash.
-	//
-	// The orch branch was created from baseBranch before executeWave runs, so in
-	// wave 1 it is always an ancestor of HEAD and a plain fast-forward applies.
-	// In wave 2+ the orch branch may have advanced due to prior wave merges
-	// (commits from worker worktrees merged back). In that case we create a merge
-	// commit so the task files become visible without rewinding any wave history.
-	//
-	// Failure here is non-fatal: the commit already succeeded; if the ref update
-	// fails the subsequent worktree allocation will produce a clear error.
 	if (orchBranch) {
 		try {
 			const headRes = runGit(["rev-parse", "HEAD"], repoRoot);
@@ -1500,16 +1599,12 @@ export function ensureTaskFilesCommitted(
 				const newHead = headRes.stdout.trim();
 				const orchTip = orchTipRes.stdout.trim();
 
-				// Check whether the orch branch tip is an ancestor of the new HEAD
-				// (i.e., a fast-forward is safe and sufficient).
 				const ancestorCheck = runGit(
 					["merge-base", "--is-ancestor", orchTip, newHead],
 					repoRoot,
 				);
 
 				if (ancestorCheck.ok) {
-					// FF case: orch branch is behind HEAD — move it forward.
-					// Expected-old-sha semantics guard against concurrent ref moves.
 					const ffResult = runGit(
 						["update-ref", `refs/heads/${orchBranch}`, newHead, orchTip],
 						repoRoot,
@@ -1527,29 +1622,16 @@ export function ensureTaskFilesCommitted(
 						});
 					}
 				} else {
-					// Non-FF case: orch branch has advanced due to prior wave merges.
-					// Create a merge commit so the new task files become visible in
-					// worktrees without discarding any accumulated wave history.
-					// Requires git ≥ 2.38 for `merge-tree --write-tree`.
 					const mergeTreeRes = runGit(
 						["merge-tree", "--write-tree", orchTip, newHead],
 						repoRoot,
 					);
 					if (mergeTreeRes.ok) {
-						// First line of stdout is the merged tree SHA.
-						// git merge-tree --write-tree exits 0 on clean merge, non-zero on conflicts.
-						// Since it exited 0, the tree should be conflict-free, but validate
-						// the SHA looks like a valid 40-hex OID before using it.
 						const mergedTree = mergeTreeRes.stdout.trim().split("\n")[0];
-						if (!/^[0-9a-f]{40}$/i.test(mergedTree)) {
-							execLog("wave", `W${waveIndex}`, `warning: merge-tree returned unexpected output (non-fatal)`, {
-								orchBranch,
-								output: mergedTree.slice(0, 60),
-							});
-						} else {
-							const mergeCommitMsg = `merge: include staged task files for wave ${waveIndex} into orch branch`;
+						if (/^[0-9a-f]{40}$/i.test(mergedTree)) {
+							const mergeMsg = `merge: include staged task files for wave ${waveIndex} into orch branch`;
 							const commitTreeRes = runGit(
-								["commit-tree", mergedTree, "-p", orchTip, "-p", newHead, "-m", mergeCommitMsg],
+								["commit-tree", mergedTree, "-p", orchTip, "-p", newHead, "-m", mergeMsg],
 								repoRoot,
 							);
 							if (commitTreeRes.ok) {
@@ -1561,28 +1643,11 @@ export function ensureTaskFilesCommitted(
 								if (refUpdateRes.ok) {
 									execLog("wave", `W${waveIndex}`, `merged staging commit into orch branch (non-FF wave)`, {
 										orchBranch,
-										orchTip: orchTip.slice(0, 8),
-										newHead: newHead.slice(0, 8),
 										mergeCommit: mergeCommitSha.slice(0, 8),
 									});
-								} else {
-									execLog("wave", `W${waveIndex}`, `warning: failed to update orch branch ref after merge-tree (non-fatal)`, {
-										orchBranch,
-										error: refUpdateRes.stderr,
-									});
 								}
-							} else {
-								execLog("wave", `W${waveIndex}`, `warning: failed to create merge commit for orch branch (non-fatal)`, {
-									orchBranch,
-									error: commitTreeRes.stderr,
-								});
 							}
-						} // end valid tree SHA
-					} else {
-						execLog("wave", `W${waveIndex}`, `warning: failed to compute merge-tree for orch branch (non-fatal; requires git ≥ 2.38)`, {
-							orchBranch,
-							error: mergeTreeRes.stderr,
-						});
+						}
 					}
 				}
 			}
@@ -1640,7 +1705,7 @@ export function ensureTaskFilesCommitted(
 /**
  * Runtime backend selector for lane execution.
  *
- * - `"legacy"`: Session-backed path (spawnLaneSession → task-runner TASK_AUTOSTART)
+ * - `"legacy"`: Session-backed path (spawnLaneSession, deprecated)
  * - `"v2"`: Direct-child path (lane-runner → agent-host → pi --mode rpc)
  *
  * @since TP-105
@@ -1677,7 +1742,7 @@ export async function executeWave(
 	// ── Stage 0: Ensure task files are committed ────────────────
 	// Task folders may contain untracked files (PROMPT.md, STATUS.md) that
 	// won't appear in worktrees unless committed. Stage and commit them now,
-	// before worktree creation, so workers can find their TASK_AUTOSTART paths.
+	// before worktree creation, so workers can find their task files.
 	// Pass orchBranch so the staging commit is reflected in the orch branch
 	// before worktrees are allocated from it.
 	try {
@@ -2103,8 +2168,23 @@ export function buildExecutionUnit(
 	repoRoot: string,
 	isWorkspaceMode?: boolean,
 ): ExecutionUnit {
+	// TP-169: Guard against missing taskFolder. This can happen when
+	// reconstructAllocatedLanes creates task stubs from persisted state
+	// where taskFolder enrichment failed (e.g., dynamically-expanded
+	// segments whose persisted records had empty taskFolder).
+	const taskFolder = task.task?.taskFolder;
+	if (!taskFolder) {
+		throw new ExecutionError(
+			"EXEC_MISSING_TASK_FOLDER",
+			`Cannot build execution unit for task ${task.taskId}: taskFolder is ${taskFolder === "" ? "empty" : "undefined"}. ` +
+			`This typically means the task's persisted record was not enriched with discovery data. ` +
+			`Re-run discovery or check that the task exists in the task area.`,
+			"execution",
+			task.taskId,
+		);
+	}
 	const resolved = resolveCanonicalTaskPaths(
-		task.task.taskFolder,
+		taskFolder,
 		lane.worktreePath,
 		repoRoot,
 		isWorkspaceMode,
@@ -2257,6 +2337,110 @@ function loadLocalAgentPrompt(stateRoot: string, agentName: string): string {
 	return "";
 }
 
+// ── Agent Definition Loading ─────────────────────────────────────────
+
+/** Track whether an agent pointer warning has been logged this session (log once). */
+let _execPointerWarningLogged = false;
+
+/**
+ * Reset agent pointer warning state for testing.
+ * @since TP-161
+ */
+export function resetPointerWarning(): void {
+	_execPointerWarningLogged = false;
+}
+
+/**
+ * Resolve agent files using the workspace pointer (workspace mode only).
+ * Returns the agentRoot from the pointer, or null in repo mode / on failure.
+ */
+function resolveAgentPointerRoot(): string | null {
+	const wsRoot = process.env.TASKPLANE_WORKSPACE_ROOT;
+	if (!wsRoot) return null;
+	try {
+		const wsConfig = loadWorkspaceConfig(wsRoot);
+		const result = resolvePointer(wsRoot, wsConfig);
+		if (result?.warning && !_execPointerWarningLogged) {
+			_execPointerWarningLogged = true;
+			console.error(`[execution] pointer: ${result.warning}`);
+		}
+		return result?.agentRoot ?? null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Load a complete agent definition (systemPrompt + tools + model) by name.
+ *
+ * Resolution order:
+ *   1. cwd/.pi/agents/<name>.md
+ *   2. cwd/agents/<name>.md
+ *   3. pointer.agentRoot/<name>.md (workspace mode only)
+ *   4. Base package templates/agents/<name>.md
+ *
+ * If a local file has `standalone: true` in frontmatter, it is used as-is
+ * (no base composition). Otherwise, base + local are composed.
+ *
+ * @param cwd - Working directory (project root) to search for local agent files
+ * @param name - Agent name (e.g., "task-worker", "task-reviewer")
+ * @returns Composed agent definition, or null if no base and no local file found
+ * @since TP-161
+ */
+export function loadAgentDef(cwd: string, name: string): { systemPrompt: string; tools: string; model: string } | null {
+	const localPaths = [
+		join(cwd, ".pi", "agents", `${name}.md`),
+		join(cwd, "agents", `${name}.md`),
+	];
+
+	// In workspace mode, add pointer-resolved agent root as fallback
+	const agentRoot = resolveAgentPointerRoot();
+	if (agentRoot) {
+		localPaths.push(join(agentRoot, `${name}.md`));
+	}
+
+	// Load base from package
+	let baseDef: { fm: Record<string, string>; body: string } | null = null;
+	try {
+		const basePath = resolveTaskplaneAgentTemplate(name);
+		if (existsSync(basePath)) {
+			baseDef = parseAgentFile(basePath);
+		}
+	} catch { /* fall through */ }
+
+	// Load local override (first found wins)
+	let localDef: { fm: Record<string, string>; body: string } | null = null;
+	for (const p of localPaths) {
+		localDef = parseAgentFile(p);
+		if (localDef) break;
+	}
+
+	// No base and no local → null
+	if (!baseDef && !localDef) return null;
+
+	// Local with standalone: true → use local as-is, ignore base
+	if (localDef?.fm.standalone === "true") {
+		return {
+			systemPrompt: localDef.body,
+			tools: localDef.fm.tools || "read,grep,find,ls",
+			model: localDef.fm.model || "",
+		};
+	}
+
+	// Compose base + local
+	const basePrompt = baseDef?.body || "";
+	const localPrompt = localDef?.body || "";
+	const composedPrompt = localPrompt
+		? basePrompt + "\n\n---\n\n## Project-Specific Guidance\n\n" + localPrompt
+		: basePrompt;
+
+	// Local frontmatter overrides base (tools, model)
+	const tools = localDef?.fm.tools || baseDef?.fm.tools || "read,grep,find,ls";
+	const model = localDef?.fm.model || baseDef?.fm.model || "";
+
+	return { systemPrompt: composedPrompt.trim(), tools, model };
+}
+
 export function resolveRuntimeStateRoot(
 	repoRoot: string,
 	workspaceRoot?: string,