taskplane 0.22.18 → 0.23.0

package/extensions/taskplane/engine.ts

@@ -6,7 +6,8 @@ import { existsSync, readdirSync, readFileSync, unlinkSync } from "fs";
 import { join, resolve } from "path";
 
 import { formatDiscoveryResults, runDiscovery } from "./discovery.ts";
-import { computeTransitiveDependents, execLog, executeLane, executeWave, tmuxKillSession } from "./execution.ts";
+import { computeTransitiveDependents, execLog, executeLane, executeLaneV2, executeWave, tmuxKillSession } from "./execution.ts";
+import type { RuntimeBackend } from "./execution.ts";
 import type { MonitorUpdateCallback } from "./execution.ts";
 // classifyExit no longer called directly — Tier 0 uses exitDiagnostic.classification
 // from the diagnostic-reports pipeline (populated by assembleDiagnosticInput).
@@ -87,6 +88,7 @@ async function attemptWorkerCrashRetry(
 	onNotify: (message: string, level: "info" | "warning" | "error") => void,
 	stateRoot: string,
 	runnerConfig?: TaskRunnerConfig,
+	runtimeBackend?: RuntimeBackend,
 ): Promise<{ retriedCount: number; succeededRetries: string[]; failedRetries: string[] }> {
 	if (!batchState.resilience) {
 		batchState.resilience = defaultResilienceState();
@@ -221,7 +223,8 @@ async function attemptWorkerCrashRetry(
 			// may be paused due to stop-wave policy, but Tier 0 retry should
 			// attempt recovery before the stop decision takes effect (R002-4).
 			const retryPauseSignal = { paused: false };
-			const retryResult = await executeLane(
+			const retryExecutor = (runtimeBackend === "v2") ? executeLaneV2 : executeLane;
+			const retryResult = await retryExecutor(
 				retryLane,
 				orchConfig,
 				repoRoot,
@@ -374,6 +377,7 @@ async function attemptModelFallbackRetry(
 	onNotify: (message: string, level: "info" | "warning" | "error") => void,
 	stateRoot: string,
 	runnerConfig?: TaskRunnerConfig,
+	runtimeBackend?: RuntimeBackend,
 ): Promise<{ retriedCount: number; succeededRetries: string[]; failedRetries: string[] }> {
 	// Short-circuit: if model fallback is disabled, skip entirely
 	const modelFallbackMode = runnerConfig?.model_fallback ?? "inherit";
@@ -487,7 +491,8 @@ async function attemptModelFallbackRetry(
 			// the task-runner to use the session model instead of configured model.
 			// TP-089: Also include ORCH_BATCH_ID so mailbox steering works for retries.
 			const modelFallbackEnv = { TASKPLANE_MODEL_FALLBACK: "1", ORCH_BATCH_ID: batchState.batchId };
-			const retryResult = await executeLane(
+			const retryExecutor = (runtimeBackend === "v2") ? executeLaneV2 : executeLane;
+			const retryResult = await retryExecutor(
 				retryLane,
 				orchConfig,
 				repoRoot,
@@ -623,6 +628,8 @@ async function attemptStaleWorktreeRecovery(
 	onMonitorUpdate: MonitorUpdateCallback | undefined,
 	onLanesAllocated: (lanes: AllocatedLane[]) => void,
 	stateRoot: string,
+	runtimeBackend?: RuntimeBackend,
+	onSupervisorAlert?: SupervisorAlertCallback,
 ): Promise<WaveExecutionResult | null> {
 	// Only attempt recovery for ALLOC_WORKTREE_FAILED
 	if (!waveResult.allocationError || waveResult.allocationError.code !== "ALLOC_WORKTREE_FAILED") {
@@ -722,12 +729,51 @@ async function attemptStaleWorktreeRecovery(
 		onMonitorUpdate,
 		onLanesAllocated,
 		workspaceConfig,
+		runtimeBackend,
+		onSupervisorAlert,
 	);
 
 	return retryResult;
 }
 
 
+export interface RuntimeBackendSelection {
+	backend: RuntimeBackend;
+	isSingleTask: boolean;
+	isRepoMode: boolean;
+	isDirectPromptTarget: boolean;
+}
+
+/**
+ * Select execution backend for a batch under the TP-105 scope guard.
+ *
+ * Runtime V2 is enabled only for a single-task batch in repo mode when
+ * the original target is exactly one direct PROMPT.md path.
+ */
+export function selectRuntimeBackend(
+	args: string,
+	rawWaves: string[][],
+	workspaceConfig?: WorkspaceConfig | null,
+): RuntimeBackendSelection {
+	const isSingleTask = rawWaves.length === 1 && rawWaves[0]?.length === 1;
+	const isRepoMode = !workspaceConfig;
+	const argTokens = args.trim().split(/\s+/).filter(Boolean);
+	const isDirectPromptTarget =
+		argTokens.length === 1 && /PROMPT\.md$/i.test(argTokens[0]);
+
+	// TP-108: Runtime V2 for all repo-mode batches.
+	// TP-109: Workspace mode also uses V2 now that packet-home paths are
+	// threaded through execution and resume (worktree-relative .DONE check).
+	const backend: RuntimeBackend = "v2";
+
+	return {
+		backend,
+		isSingleTask,
+		isRepoMode,
+		isDirectPromptTarget,
+	};
+}
+
 // ── /orch Execution Engine ───────────────────────────────────────────
 
 /**
@@ -1049,6 +1095,20 @@ export async function executeOrchBatch(
 	// ── TS-009: Persist state on batch start (after wave computation) ──
 	persistRuntimeState("batch-start", batchState, wavePlan, latestAllocatedLanes, allTaskOutcomes, discoveryRef, stateRoot);
 
+	// ── TP-105: Runtime V2 backend selection ────────────────────
+	// Use Runtime V2 (no-TMUX lane-runner) when ALL conditions are met:
+	//   1. Exactly one task in the batch
+	//   2. Repo mode (not workspace mode — workspace deferred to TP-109)
+	//   3. The user target is a single direct PROMPT.md path
+	// Otherwise, fall back to the legacy TMUX-backed path.
+	const backendSelection = selectRuntimeBackend(args, rawWaves, workspaceConfig);
+	const selectedBackend = backendSelection.backend;
+
+	if (selectedBackend === "v2") {
+		execLog("batch", batchState.batchId, "Runtime V2 backend selected");
+		onNotify("🚀 Using Runtime V2 backend (no-TMUX direct execution)", "info");
+	}
+
 	for (let waveIdx = 0; waveIdx < rawWaves.length; waveIdx++) {
 		// Check pause signal before starting each wave
 		if (batchState.pauseSignal.paused) {
@@ -1134,6 +1194,8 @@ export async function executeOrchBatch(
 			handleWaveMonitorUpdate,
 			onLanesAllocatedCb,
 			workspaceConfig,
+			selectedBackend,
+			emitAlert,
 		);
 
 		// ── TP-039: Tier 0 — Stale worktree recovery ────────────
@@ -1153,6 +1215,8 @@ export async function executeOrchBatch(
 				handleWaveMonitorUpdate,
 				onLanesAllocatedCb,
 				stateRoot,
+				selectedBackend,
+				emitAlert,
 			);
 			if (retryResult) {
 				const staleRecovered = !retryResult.allocationError;
@@ -1219,6 +1283,7 @@ export async function executeOrchBatch(
 				onNotify,
 				stateRoot,
 				runnerConfig,
+				selectedBackend,
 			);
 			if (modelFallbackOutcome.succeededRetries.length > 0) {
 				// Recompute blocked tasks after model fallback successes
@@ -1252,6 +1317,8 @@ export async function executeOrchBatch(
 				allTaskOutcomes,
 				onNotify,
 				stateRoot,
+				undefined,
+				selectedBackend,
 			);
 			if (retryOutcome.succeededRetries.length > 0) {
 				// Recompute blockedTaskIds from remaining failures (R002-2).
@@ -1468,6 +1535,8 @@ export async function executeOrchBatch(
 						agentRoot,
 						runnerConfig.testing_commands,
 						mergeHealthMonitor,
+						undefined, // forceMixedOutcome
+						selectedBackend,
 					);
 				} finally {
 					// TP-056: Always stop the health monitor when merge phase ends
@@ -1686,6 +1755,9 @@ export async function executeOrchBatch(
 							stateRoot,
 							agentRoot,
 							runnerConfig.testing_commands,
+							undefined, // healthMonitor
+							undefined, // forceMixedOutcome
+							selectedBackend,
 						);
 					},
 					persist: (trigger) => persistRuntimeState(trigger, batchState, wavePlan, latestAllocatedLanes, allTaskOutcomes, discoveryRef, stateRoot),

package/extensions/taskplane/execution.ts

@@ -9,7 +9,9 @@ import { join, dirname, basename, resolve, relative, delimiter as pathDelimiter
 import { userInfo } from "os";
 
 import { DONE_GRACE_MS, EXECUTION_POLL_INTERVAL_MS, ExecutionError, SESSION_SPAWN_RETRY_MAX } from "./types.ts";
-import type { AllocatedLane, AllocatedTask, DependencyGraph, LaneExecutionResult, LaneMonitorSnapshot, LaneTaskOutcome, LaneTaskStatus, MonitorState, MtimeTracker, OrchestratorConfig, ParsedTask, TaskMonitorSnapshot, WaveExecutionResult, WorkspaceConfig } from "./types.ts";
+import type { AllocatedLane, AllocatedTask, DependencyGraph, LaneExecutionResult, LaneMonitorSnapshot, LaneTaskOutcome, LaneTaskStatus, MonitorState, MtimeTracker, OrchestratorConfig, ParsedTask, TaskMonitorSnapshot, WaveExecutionResult, WorkspaceConfig, ExecutionUnit, PacketPaths, RuntimeAgentId, RuntimeAgentRole, SupervisorAlertCallback } from "./types.ts";
+import { resolvePacketPaths, buildRuntimeAgentId } from "./types.ts";
+import { readRegistrySnapshot, isTerminalStatus, isProcessAlive } from "./process-registry.ts";
 import { allocateLanes } from "./waves.ts";
 import { runGit } from "./git.ts";
 
@@ -266,6 +268,63 @@ export function killLaneAndChildren(sessionName: string): void {
 	tmuxKillSession(sessionName);
 }
 
+/**
+ * TP-112: Check if a V2 agent is alive via process registry.
+ * Returns true if the agent's PID is running and status is non-terminal.
+ * Returns false if no registry, no entry, terminal status, or dead PID.
+ *
+ * @param agentIdOrSessionName - Agent ID or session name to look up
+ * @param runtimeBackend - Must be "v2" (caller should guard)
+ * @returns true if agent is alive
+ * @since TP-112
+ */
+export function isV2AgentAlive(agentIdOrSessionName: string, _runtimeBackend?: RuntimeBackend): boolean {
+	// Read the registry from the global state root.
+	// Since this is a pure liveness check, we scan for matching agentId
+	// patterns: direct match, or lane-session + "-worker" suffix.
+	if (!_v2LivenessRegistryCache) return false;
+	const agents = _v2LivenessRegistryCache.agents;
+	// Direct match
+	const manifest = agents[agentIdOrSessionName];
+	if (manifest && !isTerminalStatus(manifest.status) && isProcessAlive(manifest.pid)) return true;
+	// Try worker suffix (monitor uses lane session name, registry uses agentId)
+	const workerManifest = agents[`${agentIdOrSessionName}-worker`];
+	if (workerManifest && !isTerminalStatus(workerManifest.status) && isProcessAlive(workerManifest.pid)) return true;
+	return false;
+}
+
+/** Cached registry for V2 liveness checks within a monitor cycle. @since TP-112 */
+let _v2LivenessRegistryCache: import("./process-registry.ts").RuntimeRegistry | null = null;
+
+/**
+ * Set the V2 liveness registry cache for the current monitor cycle.
+ * Called at the start of each monitor poll to avoid re-reading the file per-task.
+ * @since TP-112
+ */
+export function setV2LivenessRegistryCache(registry: import("./process-registry.ts").RuntimeRegistry | null): void {
+	_v2LivenessRegistryCache = registry;
+}
+
+/**
+ * TP-112: Kill V2 lane agents (worker + reviewer) by PID from the registry.
+ * Used for stall termination on the V2 path.
+ * @since TP-112
+ */
+export function killV2LaneAgents(sessionName: string): void {
+	if (!_v2LivenessRegistryCache) return;
+	const agents = _v2LivenessRegistryCache.agents;
+	for (const suffix of ["-worker", "-reviewer", ""]) {
+		const key = `${sessionName}${suffix}`;
+		const manifest = agents[key];
+		if (manifest && !isTerminalStatus(manifest.status) && isProcessAlive(manifest.pid)) {
+			try {
+				process.kill(manifest.pid, "SIGTERM");
+				execLog("monitor", key, `killed V2 agent (PID ${manifest.pid}) on stall`);
+			} catch { /* already dead */ }
+		}
+	}
+}
+
 // ── Async TMUX Helpers (TP-070) ──────────────────────────────────────
 
 /**
@@ -1692,8 +1751,16 @@ export async function resolveTaskMonitorState(
 	tracker: MtimeTracker,
 	stallTimeoutMs: number,
 	now: number,
+	runtimeBackend?: RuntimeBackend,
 ): Promise<TaskMonitorSnapshot> {
-	const sessionAlive = await tmuxHasSessionAsync(sessionName);
+	// TP-112: Backend-aware liveness check.
+	// V2: check process registry (PID liveness). Legacy: check TMUX session.
+	let sessionAlive: boolean;
+	if (runtimeBackend === "v2") {
+		sessionAlive = isV2AgentAlive(sessionName, runtimeBackend);
+	} else {
+		sessionAlive = await tmuxHasSessionAsync(sessionName);
+	}
 	const doneFileFound = await fileExistsAsync(donePath);
 
 	// Build base snapshot from parsed status
@@ -1784,12 +1851,17 @@ export async function resolveTaskMonitorState(
 		const stallMinutes = Math.round((now - tracker.stallTimerStart) / 60_000);
 		const stallReason = `STATUS.md unchanged for ${stallMinutes} minutes (threshold: ${Math.round(stallTimeoutMs / 60_000)} min)`;
 
-		// Kill the session and children
-		execLog("monitor", taskId, `stall detected — killing session`, {
+		// Kill the agent (backend-aware)
+		execLog("monitor", taskId, `stall detected — killing agent`, {
 			session: sessionName,
 			stallMinutes,
+			backend: runtimeBackend ?? "legacy",
 		});
-		killLaneAndChildren(sessionName);
+		if (runtimeBackend === "v2") {
+			killV2LaneAgents(sessionName);
+		} else {
+			killLaneAndChildren(sessionName);
+		}
 
 		return {
 			taskId,
@@ -1893,6 +1965,9 @@ export async function monitorLanes(
 	waveNumber: number = 1,
 	onUpdate?: MonitorUpdateCallback,
 	isWorkspaceMode?: boolean,
+	runtimeBackend?: RuntimeBackend,
+	batchId?: string,
+	stateRootForRegistry?: string,
 ): Promise<MonitorState> {
 	const pollIntervalMs = (config.monitoring.poll_interval || 5) * 1000;
 	const stallTimeoutMs = (config.failure.stall_timeout || 30) * 60_000;
@@ -1941,6 +2016,17 @@ export async function monitorLanes(
 		const now = Date.now();
 		pollCount++;
 
+		// TP-112: Refresh V2 liveness registry cache once per poll cycle
+		if (runtimeBackend === "v2" && batchId) {
+			try {
+				setV2LivenessRegistryCache(readRegistrySnapshot(stateRootForRegistry ?? repoRoot, batchId));
+			} catch {
+				setV2LivenessRegistryCache(null);
+			}
+		} else {
+			setV2LivenessRegistryCache(null);
+		}
+
 		// Check pause signal
 		if (pauseSignal.paused) {
 			execLog("monitor", "ALL", "pause signal detected — stopping monitoring");
@@ -1993,6 +2079,7 @@ export async function monitorLanes(
 						tracker,
 						stallTimeoutMs,
 						now,
+						runtimeBackend,
 					);
 
 					currentTaskSnapshot = snapshot;
@@ -2031,7 +2118,10 @@ export async function monitorLanes(
 				allTerminal = false;
 			}
 
-			const sessionAlive = await tmuxHasSessionAsync(lane.tmuxSessionName);
+			// TP-112: Backend-aware lane liveness for snapshot
+			const sessionAlive = runtimeBackend === "v2"
+				? isV2AgentAlive(lane.tmuxSessionName, runtimeBackend)
+				: await tmuxHasSessionAsync(lane.tmuxSessionName);
 
 			laneSnapshots.push({
 				laneId: lane.laneId,
@@ -2082,6 +2172,7 @@ export async function monitorLanes(
 				total: tasksTotal,
 				polls: pollCount,
 			});
+			setV2LivenessRegistryCache(null);
 			return monitorState;
 		}
 
@@ -2103,6 +2194,7 @@ export async function monitorLanes(
 		remainingTasks: lane.tasks.map(t => t.taskId),
 	}));
 
+	setV2LivenessRegistryCache(null);
 	return {
 		lanes: laneSnapshots,
 		tasksDone: 0,
@@ -2296,6 +2388,16 @@ export function ensureTaskFilesCommitted(
  * @param workspaceConfig   - Workspace configuration for repo routing (null/undefined = repo mode)
  * @returns WaveExecutionResult with outcomes and blocked task IDs
  */
+/**
+ * Runtime backend selector for lane execution.
+ *
+ * - `"legacy"`: TMUX-backed path (spawnLaneSession → task-runner TASK_AUTOSTART)
+ * - `"v2"`: Direct-child path (lane-runner → agent-host → pi --mode rpc)
+ *
+ * @since TP-105
+ */
+export type RuntimeBackend = "legacy" | "v2";
+
 export async function executeWave(
 	waveTasks: string[],
 	waveIndex: number,
@@ -2309,6 +2411,8 @@ export async function executeWave(
 	onMonitorUpdate?: MonitorUpdateCallback,
 	onLanesAllocated?: (lanes: AllocatedLane[]) => void,
 	workspaceConfig?: WorkspaceConfig | null,
+	runtimeBackend?: RuntimeBackend,
+	onSupervisorAlert?: SupervisorAlertCallback,
 ): Promise<WaveExecutionResult> {
 	const startedAt = Date.now();
 	const policy = config.failure.on_task_failure;
@@ -2391,14 +2495,20 @@ export async function executeWave(
 	// configPath is .pi/taskplane-workspace.yaml → parent of parent is workspace root.
 	const wsRoot = workspaceConfig ? dirname(dirname(workspaceConfig.configPath)) : undefined;
 	const isWsMode = !!workspaceConfig;
+	const backend = runtimeBackend ?? "legacy";
+	if (backend === "v2") {
+		execLog("wave", `W${waveIndex}`, "using Runtime V2 backend (executeLaneV2)");
+	}
+
 	const lanePromises = lanes.map(lane =>
-		executeLane(lane, config, repoRoot, wavePauseSignal, wsRoot, isWsMode, {
-			ORCH_BATCH_ID: batchId,
-		}),
+		backend === "v2"
+			? executeLaneV2(lane, config, repoRoot, wavePauseSignal, wsRoot, isWsMode, { ORCH_BATCH_ID: batchId }, onSupervisorAlert)
+			: executeLane(lane, config, repoRoot, wavePauseSignal, wsRoot, isWsMode, { ORCH_BATCH_ID: batchId }),
 	);
 
 	// Start monitoring as a sibling async loop
 	// Monitor runs concurrently and stops when all lanes are terminal or paused
+	const monitorStateRoot = resolveRuntimeStateRoot(repoRoot, wsRoot);
 	const monitorPromise = monitorLanes(
 		lanes,
 		config,
@@ -2407,6 +2517,9 @@ export async function executeWave(
 		waveIndex,
 		onMonitorUpdate,
 		isWsMode,
+		backend,
+		batchId,
+		monitorStateRoot,
 	);
 
 	// ── Stage 4: Wait for all lanes + apply policy ───────────────
@@ -2671,5 +2784,286 @@ export async function executeWithStopAll(
 	});
 }
 
+// ── Runtime V2 Bridge Helpers (TP-102) ─────────────────────────────────────
+//
+// These helpers bridge between existing legacy data structures
+// (AllocatedLane, AllocatedTask, resolveCanonicalTaskPaths) and
+// Runtime V2 contracts (ExecutionUnit, PacketPaths, RuntimeAgentId).
+//
+// They are additive — existing code paths continue to work.
+// Runtime V2 consumers can start using these to avoid coupling to
+// TMUX naming, cwd-derived paths, or extension lifecycle assumptions.
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Build a Runtime V2 ExecutionUnit from existing legacy structures.
+ *
+ * Translates the current AllocatedLane + AllocatedTask into the new
+ * ExecutionUnit contract with explicit packet-path authority.
+ *
+ * Uses `resolveCanonicalTaskPaths` to derive packet paths through
+ * the existing resolution logic (worktree-relative, cross-repo copy,
+ * archive fallback). This preserves current behavior while surfacing
+ * it through the Runtime V2 contract.
+ *
+ * **Cross-repo packet authority (TP-109):** In workspace mode, when the
+ * task packet home repo differs from the execution repo, the legacy path
+ * copies packet files into the worktree under `.taskplane-tasks/`. The
+ * resolved `packet` paths here point to that execution-local copy.
+ * This is by design: the worker reads/writes STATUS.md and creates .DONE
+ * in the worktree, and resume checks both the worktree-relative path and
+ * the original discovery path for .DONE detection.
+ *
+ * `packetHomeRepoId` identifies the source repo that *owns* the task
+ * (for discovery and routing), while `packet.taskFolder` is the
+ * authoritative *working* location where artifacts are read/written
+ * during execution. Resume reconciliation (TP-109) resolves both paths.
+ *
+ * @param lane - Allocated lane containing worktree and identity info
+ * @param task - Allocated task to build an execution unit for
+ * @param repoRoot - Main repository root
+ * @param isWorkspaceMode - Whether workspace mode is active
+ * @returns A fully-resolved ExecutionUnit
+ *
+ * @since TP-102
+ */
+export function buildExecutionUnit(
+	lane: AllocatedLane,
+	task: AllocatedTask,
+	repoRoot: string,
+	isWorkspaceMode?: boolean,
+): ExecutionUnit {
+	const resolved = resolveCanonicalTaskPaths(
+		task.task.taskFolder,
+		lane.worktreePath,
+		repoRoot,
+		isWorkspaceMode,
+	);
+
+	const executionRepoId = lane.repoId ?? "default";
+	const packetHomeRepoId = task.task.packetRepoId ?? executionRepoId;
+
+	// Build a segment-style ID if this is a segment execution,
+	// otherwise use the plain task ID.
+	const segmentId = task.task.activeSegmentId ?? null;
+	const id = segmentId ?? task.taskId;
+
+	return {
+		id,
+		taskId: task.taskId,
+		segmentId,
+		executionRepoId,
+		packetHomeRepoId,
+		worktreePath: lane.worktreePath,
+		packet: {
+			promptPath: resolved.taskFolderResolved + "/PROMPT.md",
+			statusPath: resolved.statusPath,
+			donePath: resolved.donePath,
+			reviewsDir: resolved.taskFolderResolved + "/.reviews",
+			taskFolder: resolved.taskFolderResolved,
+		},
+		task: task.task,
+	};
+}
+
+/**
+ * Build a RuntimeAgentId for a lane's agent from existing naming.
+ *
+ * Bridges the current TMUX session naming convention into a
+ * Runtime V2 stable agent ID. The output is compatible with
+ * existing supervisor tools and mailbox addressing.
+ *
+ * @param lane - Allocated lane with TMUX session name
+ * @param role - Agent role
+ * @param mergeIndex - Merge wave index (only for merge agents)
+ * @returns Canonical agent ID
+ *
+ * @since TP-102
+ */
+export function buildAgentIdFromLane(
+	lane: AllocatedLane,
+	role: RuntimeAgentRole,
+	mergeIndex?: number,
+): RuntimeAgentId {
+	// The current tmuxSessionName is already in the right format
+	// (e.g., "orch-henrylach-lane-1"). We derive agent IDs from it
+	// by appending the role suffix, matching the existing convention.
+	if (role === "merger" && mergeIndex != null) {
+		// Merge agents use a different naming pattern
+		const prefix = lane.tmuxSessionName.replace(/-lane-\d+$/, "");
+		return `${prefix}-merge-${mergeIndex}`;
+	}
+	if (role === "lane-runner") {
+		return lane.tmuxSessionName;
+	}
+	return `${lane.tmuxSessionName}-${role}`;
+}
+
+/**
+ * Resolve the Runtime V2 state root from available context.
+ *
+ * The state root is where `.pi/runtime/` artifacts live. In workspace
+ * mode this is the workspace root; in repo mode it's the repo root.
+ *
+ * This centralizes the resolution so Runtime V2 code doesn't need
+ * to repeat the workspace-vs-repo logic.
+ *
+ * @param repoRoot - Main repository root
+ * @param workspaceRoot - Workspace root (undefined in repo mode)
+ * @returns Absolute path to use as the state root for .pi/ artifacts
+ *
+ * @since TP-102
+ */
+export function resolveRuntimeStateRoot(
+	repoRoot: string,
+	workspaceRoot?: string,
+): string {
+	return workspaceRoot ?? repoRoot;
+}
+
+// ── Runtime V2 Lane Execution (TP-105) ────────────────────────────
+
+import { executeTaskV2, type LaneRunnerConfig, type LaneRunnerTaskResult } from "./lane-runner.ts";
+
+/**
+ * Execute a lane using the Runtime V2 headless backend.
+ *
+ * This replaces the legacy TMUX-backed `executeLane()` for lanes that
+ * should run on the new direct-child architecture. It uses the
+ * lane-runner module which spawns workers via agent-host.ts instead
+ * of TMUX sessions.
+ *
+ * The function signature is deliberately close to the legacy
+ * `executeLane()` to minimize integration churn in the engine.
+ * The key difference: no TMUX sessions are created.
+ *
+ * @since TP-105
+ */
+export async function executeLaneV2(
+	lane: AllocatedLane,
+	config: OrchestratorConfig,
+	repoRoot: string,
+	pauseSignal: { paused: boolean },
+	workspaceRoot?: string,
+	isWorkspaceMode?: boolean,
+	extraEnvVars?: Record<string, string>,
+	onSupervisorAlert?: SupervisorAlertCallback,
+): Promise<LaneExecutionResult> {
+	const laneId = lane.laneId;
+	const laneStartTime = Date.now();
+	const outcomes: LaneTaskOutcome[] = [];
+	let shouldSkipRemaining = false;
+
+	const stateRoot = resolveRuntimeStateRoot(repoRoot, workspaceRoot);
+	const batchId = config.orchestrator?.batchId || extraEnvVars?.ORCH_BATCH_ID || String(Date.now());
+
+	// Build agent ID prefix from orchestrator config
+	const tmuxPrefix = config.orchestrator?.tmux_prefix ?? "orch";
+	const opId = config.orchestrator?.operatorId || "op";
+	const agentIdPrefix = `${tmuxPrefix}-${opId}`;
+
+	// Load worker agent definition for system prompt
+	let workerSystemPrompt = "You are a task execution agent. Read STATUS.md first, find unchecked items, work on them, checkpoint after each.";
+	try {
+		const agentPath = join(stateRoot, ".pi", "agents", "task-worker.md");
+		if (existsSync(agentPath)) {
+			const raw = readFileSync(agentPath, "utf-8");
+			const fmEnd = raw.indexOf("---", 4);
+			if (fmEnd > 0) {
+				workerSystemPrompt = raw.slice(fmEnd + 3).trim();
+			}
+		}
+	} catch { /* use default */ }
+
+	execLog(laneId, "LANE", `starting Runtime V2 execution of ${lane.tasks.length} task(s)`, {
+		worktree: lane.worktreePath,
+		agentPrefix: agentIdPrefix,
+	});
+
+	for (const task of lane.tasks) {
+		if (shouldSkipRemaining || pauseSignal.paused) {
+			const reason = pauseSignal.paused ? "Skipped due to pause signal" : "Skipped due to prior task failure in lane";
+			outcomes.push({
+				taskId: task.taskId,
+				status: "skipped",
+				startTime: null,
+				endTime: null,
+				exitReason: reason,
+				sessionName: buildRuntimeAgentId(agentIdPrefix, lane.laneNumber, "worker"),
+				doneFileFound: false,
+			});
+			continue;
+		}
+
+		// Build execution unit
+		const unit = buildExecutionUnit(lane, task, repoRoot, isWorkspaceMode);
+
+		const laneRunnerConfig: LaneRunnerConfig = {
+			batchId,
+			agentIdPrefix,
+			laneNumber: lane.laneNumber,
+			worktreePath: lane.worktreePath,
+			branch: lane.branch,
+			repoId: lane.repoId ?? "default",
+			stateRoot,
+			workerModel: "",
+			workerTools: "read,write,edit,bash,grep,find,ls",
+			workerThinking: "",
+			workerSystemPrompt,
+			maxIterations: 20,
+			noProgressLimit: 3,
+			maxWorkerMinutes: config.failure?.maxWorkerMinutes || 30,
+			warnPercent: 85,
+			killPercent: 95,
+			onSupervisorAlert,
+		};
+
+		try {
+			const result = await executeTaskV2(unit, laneRunnerConfig, pauseSignal);
+			outcomes.push(result.outcome);
+
+			// Commit artifacts after success (same as legacy path)
+			if (result.outcome.status === "succeeded") {
+				commitTaskArtifacts(lane, task, laneId);
+				// Reset worktree for next task
+				if (lane.tasks.indexOf(task) < lane.tasks.length - 1) {
+					runGit(["checkout", "--", "."], lane.worktreePath);
+					runGit(["clean", "-fd"], lane.worktreePath);
+				}
+			}
+
+			if (result.outcome.status === "failed" || result.outcome.status === "stalled") {
+				shouldSkipRemaining = true;
+			}
+		} catch (err: unknown) {
+			const errMsg = err instanceof Error ? err.message : String(err);
+			execLog(laneId, task.taskId, `Runtime V2 execution error: ${errMsg}`);
+			outcomes.push({
+				taskId: task.taskId,
+				status: "failed",
+				startTime: Date.now(),
+				endTime: Date.now(),
+				exitReason: `Runtime V2 execution error: ${errMsg}`,
+				sessionName: buildRuntimeAgentId(agentIdPrefix, lane.laneNumber, "worker"),
+				doneFileFound: false,
+			});
+			shouldSkipRemaining = true;
+		}
+	}
+
+	const endTime = Date.now();
+	const succeeded = outcomes.every(o => o.status === "succeeded");
+	const failed = outcomes.some(o => o.status === "failed" || o.status === "stalled");
+
+	return {
+		laneNumber: lane.laneNumber,
+		laneId,
+		tasks: outcomes,
+		overallStatus: succeeded ? "succeeded" : failed ? "failed" : "partial",
+		startTime: laneStartTime,
+		endTime,
+	};
+}
+
 // ── /orch Command — Full Execution (Step 5) ─────────────────────────