taskplane 0.28.8 → 0.29.1

package/extensions/taskplane/persistence.ts

@@ -2,12 +2,12 @@
  * State persistence, serialization, orphan detection
  * @module orch/persistence
  */
-import { readFileSync, writeFileSync, existsSync, unlinkSync, renameSync, mkdirSync, appendFileSync } from "fs";
+import { readFileSync, writeFileSync, existsSync, unlinkSync, renameSync, mkdirSync, appendFileSync, readdirSync, statSync } from "fs";
 import { join, dirname, basename } from "path";
 
 import { execLog } from "./execution.ts";
-import { BATCH_STATE_SCHEMA_VERSION, StateFileError, batchStatePath, BATCH_HISTORY_MAX_ENTRIES, defaultResilienceState, defaultBatchDiagnostics } from "./types.ts";
-import type { BatchHistorySummary } from "./types.ts";
+import { BATCH_STATE_SCHEMA_VERSION, StateFileError, batchStatePath, BATCH_HISTORY_MAX_ENTRIES, defaultResilienceState, defaultBatchDiagnostics, runtimeRoot, runtimeManifestPath } from "./types.ts";
+import type { BatchHistorySummary, RuntimeAgentManifest } from "./types.ts";
 import type { AllocatedLane, DiscoveryResult, EngineEvent, EscalationContext, LaneTaskOutcome, LaneTaskStatus, MonitorState, OrchBatchPhase, OrchBatchRuntimeState, PersistedBatchState, PersistedLaneRecord, PersistedMergeResult, PersistedSegmentRecord, PersistedTaskRecord, TaskMonitorSnapshot, Tier0RecoveryPattern, WorkspaceMode } from "./types.ts";
 import { sleepSync } from "./worktree.ts";
 import type { PreserveFailedLaneProgressResult } from "./worktree.ts";
@@ -2085,3 +2085,378 @@ export function emitEngineEvent(
 	}
 }
 
+
+// ── TP-187 (#539): Batch-Meta Runtime Artifact ─────────────────────
+//
+// Small JSON file written at batch-start to `.pi/runtime/<batchId>/batch-meta.json`.
+// Captures the wave plan and the few non-recoverable scalars (baseBranch,
+// orchBranch, mode, startedAt, totalWaves) so that `orch_resume(force=true)`
+// can deterministically reconstruct a validator-compliant PersistedBatchState
+// after `orch_abort()` deletes `.pi/batch-state.json`.
+//
+// Without this artifact the wave topology is unrecoverable from the surviving
+// runtime registry alone (manifests don't carry wave info) and a flattened
+// "single wave with all surviving tasks" reconstruction can violate DAG
+// dependency ordering. See R003 plan review.
+
+/**
+ * Schema-tagged batch metadata persisted alongside per-batch runtime state.
+ *
+ * @since TP-187 (#539)
+ */
+export interface BatchMetaArtifact {
+	schemaVersion: 1;
+	batchId: string;
+	wavePlan: string[][];
+	baseBranch: string;
+	orchBranch: string;
+	mode: WorkspaceMode;
+	startedAt: number;
+	totalWaves: number;
+}
+
+/** Path to the batch-meta artifact for a given batch. */
+function batchMetaPath(stateRoot: string, batchId: string): string {
+	return join(runtimeRoot(stateRoot, batchId), "batch-meta.json");
+}
+
+/**
+ * Persist the wave plan and core batch metadata to the runtime artifact
+ * directory. Best-effort: failures are logged but do NOT crash the batch.
+ *
+ * Called once at batch-start (after wavePlan is finalized) and re-written
+ * whenever the wave plan mutates (segment expansion).
+ *
+ * @since TP-187 (#539)
+ */
+export function saveBatchMetaRuntimeArtifact(
+	stateRoot: string,
+	artifact: BatchMetaArtifact,
+): void {
+	try {
+		const path = batchMetaPath(stateRoot, artifact.batchId);
+		mkdirSync(dirname(path), { recursive: true });
+		const tmp = path + ".tmp";
+		writeFileSync(tmp, JSON.stringify(artifact, null, 2) + "\n", "utf-8");
+		renameSync(tmp, path);
+		execLog("state", artifact.batchId, "persisted batch-meta runtime artifact", {
+			waves: artifact.wavePlan.length,
+			tasks: artifact.wavePlan.reduce((sum, w) => sum + w.length, 0),
+		});
+	} catch (err) {
+		execLog("state", artifact.batchId, `batch-meta write failed: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+
+/**
+ * Load the batch-meta artifact for a given batch, or null if missing/invalid.
+ *
+ * @since TP-187 (#539)
+ */
+export function loadBatchMetaRuntimeArtifact(
+	stateRoot: string,
+	batchId: string,
+): BatchMetaArtifact | null {
+	const path = batchMetaPath(stateRoot, batchId);
+	if (!existsSync(path)) return null;
+	try {
+		const raw = readFileSync(path, "utf-8");
+		const parsed = JSON.parse(raw);
+		if (!parsed || typeof parsed !== "object") return null;
+		const obj = parsed as Record<string, unknown>;
+		if (obj.schemaVersion !== 1) return null;
+		if (typeof obj.batchId !== "string" || obj.batchId !== batchId) return null;
+		if (!Array.isArray(obj.wavePlan)) return null;
+		for (const wave of obj.wavePlan) {
+			if (!Array.isArray(wave)) return null;
+			for (const taskId of wave) {
+				if (typeof taskId !== "string") return null;
+			}
+		}
+		if (typeof obj.baseBranch !== "string") return null;
+		if (typeof obj.orchBranch !== "string") return null;
+		if (obj.mode !== "repo" && obj.mode !== "workspace") return null;
+		if (typeof obj.startedAt !== "number") return null;
+		if (typeof obj.totalWaves !== "number") return null;
+		return obj as unknown as BatchMetaArtifact;
+	} catch {
+		return null;
+	}
+}
+
+
+// ── TP-187 (#539): Reconstruct PersistedBatchState from runtime artifacts ──
+
+/**
+ * Result of `reconstructBatchStateFromRuntime`. On success, contains the
+ * validator-compliant state, the selected batchId, and a human-readable note
+ * about how the selection was made (used by resume's onNotify output). On
+ * failure, names the missing or corrupt artifact for fail-loud reporting.
+ *
+ * @since TP-187 (#539)
+ */
+export type ReconstructResult =
+	| { ok: true; state: PersistedBatchState; batchId: string; selectionNote: string }
+	| { ok: false; error: string };
+
+/**
+ * List candidate `.pi/runtime/<batchId>/` directories newest-first by mtime,
+ * with lex-largest tie-break for determinism.
+ */
+function listRuntimeBatchDirs(stateRoot: string): { batchId: string; mtimeMs: number }[] {
+	const root = join(stateRoot, ".pi", "runtime");
+	if (!existsSync(root)) return [];
+	let entries: string[] = [];
+	try {
+		entries = readdirSync(root);
+	} catch {
+		return [];
+	}
+	const candidates: { batchId: string; mtimeMs: number }[] = [];
+	for (const name of entries) {
+		const dir = join(root, name);
+		try {
+			const st = statSync(dir);
+			if (!st.isDirectory()) continue;
+			candidates.push({ batchId: name, mtimeMs: st.mtimeMs });
+		} catch {
+			continue;
+		}
+	}
+	candidates.sort((a, b) => {
+		if (b.mtimeMs !== a.mtimeMs) return b.mtimeMs - a.mtimeMs;
+		return b.batchId.localeCompare(a.batchId);
+	});
+	return candidates;
+}
+
+/**
+ * Read all worker manifests under `.pi/runtime/<batchId>/agents/`.
+ *
+ * Returns an empty array if the agents directory is missing.
+ */
+function readWorkerManifests(stateRoot: string, batchId: string): RuntimeAgentManifest[] {
+	const agentsDir = join(runtimeRoot(stateRoot, batchId), "agents");
+	if (!existsSync(agentsDir)) return [];
+	let entries: string[] = [];
+	try {
+		entries = readdirSync(agentsDir);
+	} catch {
+		return [];
+	}
+	const manifests: RuntimeAgentManifest[] = [];
+	for (const agentId of entries) {
+		const manifestPath = runtimeManifestPath(stateRoot, batchId, agentId);
+		if (!existsSync(manifestPath)) continue;
+		try {
+			const raw = readFileSync(manifestPath, "utf-8");
+			const parsed = JSON.parse(raw) as RuntimeAgentManifest;
+			if (parsed && typeof parsed === "object" && parsed.role === "worker") {
+				manifests.push(parsed);
+			}
+		} catch {
+			continue;
+		}
+	}
+	return manifests;
+}
+
+/**
+ * Deterministically reconstruct a validator-compliant `PersistedBatchState`
+ * from the surviving runtime artifacts after `.pi/batch-state.json` has been
+ * deleted (typically by `orch_abort()`).
+ *
+ * Required artifacts: at least one `.pi/runtime/<batchId>/` directory whose
+ * `batch-meta.json` parses cleanly AND has at least one worker manifest with
+ * an existing worktree on disk. Anything else returns a fail-loud error so
+ * the caller can surface a clear "no resumable state" message instead of
+ * silently producing an invalid state.
+ *
+ * @since TP-187 (#539)
+ */
+export function reconstructBatchStateFromRuntime(stateRoot: string): ReconstructResult {
+	const candidates = listRuntimeBatchDirs(stateRoot);
+	if (candidates.length === 0) {
+		return { ok: false, error: "no .pi/runtime/ directory or no batch subdirectories" };
+	}
+
+	// Try the newest batch first; if its required artifacts are missing, fall
+	// through to the next candidate. We stop at the first batch with a parseable
+	// batch-meta + at least one viable worker manifest.
+	const failures: string[] = [];
+	for (let idx = 0; idx < candidates.length; idx++) {
+		const cand = candidates[idx];
+		const meta = loadBatchMetaRuntimeArtifact(stateRoot, cand.batchId);
+		if (!meta) {
+			failures.push(`${cand.batchId}: batch-meta.json missing or invalid`);
+			continue;
+		}
+		const manifests = readWorkerManifests(stateRoot, cand.batchId);
+		if (manifests.length === 0) {
+			failures.push(`${cand.batchId}: no worker manifests`);
+			continue;
+		}
+		const workerManifestsWithWorktree = manifests.filter(m => typeof m.cwd === "string" && m.cwd.length > 0 && existsSync(m.cwd));
+		if (workerManifestsWithWorktree.length === 0) {
+			failures.push(`${cand.batchId}: worktree paths from manifests no longer exist on disk`);
+			continue;
+		}
+
+		// TP-187 (#539) — sage post-integration follow-up: refuse reconstruction
+		// when the runtime artifacts indicate this batch was multi-repo (segment
+		// expansion). Reconstruction hardcodes `segments: []` and cannot recover
+		// the per-segment topology that lives only in the deleted batch-state.
+		// Resuming with `segments: []` for a multi-repo batch would silently lose
+		// the expansion state and could re-execute already-done segments OR fail
+		// dependency checks for cross-repo waves. Detection heuristic: if worker
+		// manifests carry more than one distinct repoId, segment expansion was
+		// active. Single-repo batches (the common case, including Taskplane's
+		// own self-orchestration) are unaffected.
+		{
+			const distinctRepoIds = new Set<string>();
+			for (const m of workerManifestsWithWorktree) {
+				if (typeof m.repoId === "string" && m.repoId.length > 0) {
+					distinctRepoIds.add(m.repoId);
+				}
+			}
+			if (distinctRepoIds.size > 1) {
+				failures.push(
+					`${cand.batchId}: multi-repo batch detected (${distinctRepoIds.size} distinct repoIds: ` +
+					`${[...distinctRepoIds].slice(0, 4).join(", ")}` +
+					`${distinctRepoIds.size > 4 ? ", ..." : ""}); reconstruction would lose segment ` +
+					`expansion state and is refused. Restore .pi/batch-state.json from backup or start a new batch.`
+				);
+				continue;
+			}
+		}
+
+		// Build per-lane aggregation from worker manifests.
+		const laneMap = new Map<number, { laneNumber: number; agentId: string; worktreePath: string; repoId: string; taskIds: string[] }>();
+		for (const m of workerManifestsWithWorktree) {
+			if (typeof m.laneNumber !== "number") continue;
+			const lane = laneMap.get(m.laneNumber) ?? {
+				laneNumber: m.laneNumber,
+				agentId: m.agentId,
+				worktreePath: m.cwd,
+				repoId: m.repoId ?? "default",
+				taskIds: [] as string[],
+			};
+			if (typeof m.taskId === "string" && m.taskId && !lane.taskIds.includes(m.taskId)) {
+				lane.taskIds.push(m.taskId);
+			}
+			laneMap.set(m.laneNumber, lane);
+		}
+		if (laneMap.size === 0) {
+			failures.push(`${cand.batchId}: no lane numbers in manifests`);
+			continue;
+		}
+
+		// Tasks: union of taskIds across all lanes, plus any wavePlan tasks that
+		// are not represented (they are pending, not yet executed).
+		const knownTaskIds = new Set<string>();
+		for (const lane of laneMap.values()) {
+			for (const tid of lane.taskIds) knownTaskIds.add(tid);
+		}
+		for (const wave of meta.wavePlan) {
+			for (const tid of wave) knownTaskIds.add(tid);
+		}
+
+		// Build task records with conservative defaults; resume's reconciliation
+		// pass will re-detect succeeded tasks via `.DONE` markers and STATUS.md.
+		const tasks: PersistedTaskRecord[] = [];
+		const manifestByTaskId = new Map<string, RuntimeAgentManifest>();
+		for (const m of workerManifestsWithWorktree) {
+			if (typeof m.taskId === "string" && m.taskId) {
+				manifestByTaskId.set(m.taskId, m);
+			}
+		}
+		for (const taskId of knownTaskIds) {
+			const m = manifestByTaskId.get(taskId);
+			const lane = m ? laneMap.get(m.laneNumber) : undefined;
+			const taskRecord: PersistedTaskRecord = {
+				taskId,
+				taskName: taskId,
+				taskFolder: m?.packet?.taskFolder ?? "",
+				status: "pending",
+				sessionName: m?.agentId ?? "",
+				laneNumber: lane?.laneNumber ?? 0,
+				startedAt: typeof m?.startedAt === "number" ? m.startedAt : null,
+				endedAt: null,
+				exitReason: "",
+				doneFileFound: false,
+			};
+			if (m?.repoId) taskRecord.repoId = m.repoId;
+			if (m?.packet?.packetRepoId) (taskRecord as Record<string, unknown>).packetRepoId = m.packet.packetRepoId;
+			if (m?.packet?.packetTaskPath) (taskRecord as Record<string, unknown>).packetTaskPath = m.packet.packetTaskPath;
+			tasks.push(taskRecord);
+		}
+
+		// Build lane records.
+		const lanes: PersistedLaneRecord[] = Array.from(laneMap.values())
+			.sort((a, b) => a.laneNumber - b.laneNumber)
+			.map(l => {
+				const sessionId = l.agentId.replace(/-(worker|reviewer)$/, "");
+				const rec: PersistedLaneRecord = {
+					laneId: `lane-${l.laneNumber}`,
+					laneNumber: l.laneNumber,
+					laneSessionId: sessionId,
+					worktreePath: l.worktreePath,
+					branch: meta.orchBranch ? `${meta.orchBranch}-lane-${l.laneNumber}` : `lane-${l.laneNumber}`,
+					taskIds: [...l.taskIds],
+				};
+				if (l.repoId && l.repoId !== "default") rec.repoId = l.repoId;
+				return rec;
+			});
+
+		const now = Date.now();
+		const reconstructed: PersistedBatchState = {
+			schemaVersion: BATCH_STATE_SCHEMA_VERSION,
+			batchId: meta.batchId,
+			phase: "stopped",
+			baseBranch: meta.baseBranch,
+			orchBranch: meta.orchBranch,
+			mode: meta.mode,
+			startedAt: meta.startedAt,
+			endedAt: null,
+			updatedAt: now,
+			currentWaveIndex: 0,
+			totalWaves: meta.totalWaves,
+			totalTasks: tasks.length,
+			succeededTasks: 0,
+			failedTasks: 0,
+			skippedTasks: 0,
+			blockedTasks: 0,
+			wavePlan: meta.wavePlan.map(wave => [...wave]),
+			lanes,
+			tasks,
+			mergeResults: [],
+			blockedTaskIds: [],
+			errors: [],
+			segments: [],
+			lastError: null,
+			resilience: { ...defaultResilienceState(), resumeForced: true },
+			diagnostics: defaultBatchDiagnostics(),
+		} as PersistedBatchState;
+
+		// Validate the reconstructed shape against the on-disk schema gate.
+		try {
+			const json = JSON.stringify(reconstructed);
+			validatePersistedState(JSON.parse(json));
+		} catch (err) {
+			failures.push(`${cand.batchId}: reconstructed state failed validation: ${err instanceof Error ? err.message : String(err)}`);
+			continue;
+		}
+
+		const totalCandidates = candidates.length;
+		const selectionNote = totalCandidates === 1
+			? `single batch in .pi/runtime/`
+			: `selected from ${totalCandidates} candidate(s) by mtime newest-first (skipped ${idx} earlier candidate(s))`;
+		return { ok: true, state: reconstructed, batchId: meta.batchId, selectionNote };
+	}
+
+	return {
+		ok: false,
+		error: `no reconstructable batch found in .pi/runtime/ (${failures.length} candidate(s) inspected: ${failures.slice(0, 3).join("; ")}${failures.length > 3 ? "; ..." : ""})`,
+	};
+}
+

package/extensions/taskplane/resume.ts

@@ -7,7 +7,7 @@ import { join } from "path";
 
 import { assembleDiagnosticInput, emitDiagnosticReports } from "./diagnostic-reports.ts";
 import { runDiscovery } from "./discovery.ts";
-import { executeOrchBatch, resolveDisplayWaveNumber } from "./engine.ts";
+import { executeOrchBatch, resolveDisplayWaveNumber, buildSpawnFailureAlertExtras } from "./engine.ts";
 import { buildReviewerEnv, buildWorkerEnv, buildWorkerExcludeEnv, computeTransitiveDependents, execLog, executeLaneV2, executeWave, resolveCanonicalTaskPaths } from "./execution.ts";
 import type { MonitorUpdateCallback, RuntimeBackend } from "./execution.ts";
 import { selectRuntimeBackend } from "./engine.ts";
@@ -37,7 +37,7 @@ import { mergeWaveByRepo } from "./merge.ts";
 import { applyMergeRetryLoop, computeCleanupGatePolicy, computeMergeFailurePolicy, extractFailedRepoId, formatRepoMergeSummary, ORCH_MESSAGES } from "./messages.ts";
 import type { CleanupGateRepoFailure } from "./messages.ts";
 import { resolveOperatorId } from "./naming.ts";
-import { applyPartialProgressToOutcomes, deleteBatchState, hasTaskDoneMarker, loadBatchState, persistRuntimeState, seedPendingOutcomesForAllocatedLanes, syncTaskOutcomesFromMonitor, upsertTaskOutcome } from "./persistence.ts";
+import { applyPartialProgressToOutcomes, deleteBatchState, hasTaskDoneMarker, loadBatchState, persistRuntimeState, reconstructBatchStateFromRuntime, saveBatchState, seedPendingOutcomesForAllocatedLanes, syncTaskOutcomesFromMonitor, upsertTaskOutcome } from "./persistence.ts";
 import { buildBatchProgressSnapshot, buildSupervisorSegmentFrontierSnapshot, defaultResilienceState, StateFileError } from "./types.ts";
 import type { AllocatedLane, AllocatedTask, LaneExecutionResult, LaneTaskOutcome, LaneTaskStatus, MergeWaveResult, OrchBatchPhase, OrchBatchRuntimeState, OrchestratorConfig, ParsedTask, PersistedBatchState, PersistedLaneRecord, PersistedSegmentRecord, ReconciledTaskState, ResumeEligibility, ResumePoint, TaskRunnerConfig, WaveExecutionResult, WorkspaceConfig } from "./types.ts";
 import { buildDependencyGraph, resolveBaseBranch, resolveRepoRoot } from "./waves.ts";
@@ -1070,6 +1070,18 @@ export async function resumeOrchBatch(
 	force: boolean = false,
 	onSupervisorAlert?: import("./types.ts").SupervisorAlertCallback | null,
 	supervisorAutonomy: "interactive" | "supervised" | "autonomous" = "autonomous",
+	/**
+	 * TP-187 (#538): Optional callback fired when a lane reaches a terminal
+	 * state during a resumed batch. Threaded through to executeWave so the
+	 * supervisor process keeps suppressing zombie alerts after resume too.
+	 */
+	onLaneTerminated?: import("./types.ts").LaneTerminatedCallback | null,
+	/**
+	 * TP-187 (#538): Optional callback fired when a lane is freshly
+	 * (re-)allocated during resume. The supervisor uses it to lift any
+	 * carried-over zombie-alert suppression.
+	 */
+	onLaneRespawned?: ((laneNumber: number, agentId: string, batchId: string) => void) | null,
 ): Promise<void> {
 	const repoRoot = cwd;
 	// State files (.pi/batch-state.json, lane-state, etc.) belong in the workspace root,
@@ -1111,13 +1123,49 @@ export async function resumeOrchBatch(
 	}
 
 	if (!persistedState) {
+		if (!force) {
+			onNotify(
+				ORCH_MESSAGES.resumeNoState(),
+				"error",
+			);
+			// TP-040 R006: Reset phase on pre-execution early return
+			batchState.phase = "idle";
+			return;
+		}
+		// TP-187 (#539): On force-resume, attempt deterministic reconstruction
+		// from .pi/runtime/<batchId>/ runtime artifacts (typically left intact
+		// by `orch_abort()` even though `.pi/batch-state.json` is deleted).
+		const reconstruction = reconstructBatchStateFromRuntime(stateRoot);
+		if (!reconstruction.ok) {
+			onNotify(
+				ORCH_MESSAGES.resumeNoStateAfterAbort(reconstruction.error, null),
+				"error",
+			);
+			// TP-040 R006: Reset phase on pre-execution early return
+			batchState.phase = "idle";
+			return;
+		}
+		// Successful reconstruction: persist so the rest of resumeOrchBatch
+		// proceeds with a normal on-disk batch-state.json picture.
 		onNotify(
-			ORCH_MESSAGES.resumeNoState(),
-			"error",
+			ORCH_MESSAGES.resumeReconstructed(reconstruction.batchId, reconstruction.selectionNote),
+			"warning",
 		);
-		// TP-040 R006: Reset phase on pre-execution early return
-		batchState.phase = "idle";
-		return;
+		try {
+			saveBatchState(JSON.stringify(reconstruction.state, null, 2), stateRoot);
+		} catch (err) {
+			onNotify(
+				ORCH_MESSAGES.resumeNoStateAfterAbort(
+					`reconstructed state could not be persisted: ${err instanceof Error ? err.message : String(err)}`,
+					reconstruction.batchId,
+				),
+				"error",
+			);
+			// TP-040 R006: Reset phase on pre-execution early return
+			batchState.phase = "idle";
+			return;
+		}
+		persistedState = reconstruction.state;
 	}
 
 	// ── 2. Check eligibility ─────────────────────────────────────
@@ -2050,6 +2098,8 @@ export async function resumeOrchBatch(
 			runnerConfig.reviewer,
 			runnerConfig.worker,
 			runnerConfig.workerExcludeExtensions ?? [],
+			onLaneTerminated ?? undefined,
+			onLaneRespawned ?? undefined,
 		);
 
 		batchState.waveResults.push(waveResult);
@@ -2110,11 +2160,17 @@ export async function resumeOrchBatch(
 			const frontierSummary = segmentFrontier
 				? `  Segment frontier: ${segmentFrontier.terminalSegments}/${segmentFrontier.totalSegments} terminal\n`
 				: "";
+			// TP-190 (#561): Mirror engine.ts emission — propagate the structured
+			// exit category so /orch-resume task-failure alerts route through the
+			// same supervisor playbook branches as /orch. Shared helper enforces
+			// payload parity between the two emission sites.
+			const { exitCategory, summaryLine: spawnFailureLine } = buildSpawnFailureAlertExtras(outcome);
 			emitAlert({
 				category: "task-failure",
 				summary:
 					`⚠️ Task failure: ${taskId}\n` +
 					`  Exit reason: ${exitReason}\n` +
+					spawnFailureLine +
 					segmentSummary +
 					frontierSummary +
 					`  Lane: ${laneForTask?.laneId ?? "unknown"} (lane ${laneForTask?.laneNumber ?? "?"})\n` +
@@ -2134,6 +2190,7 @@ export async function resumeOrchBatch(
 					laneNumber: laneForTask?.laneNumber,
 					waveIndex: waveIdx,
 					exitReason,
+					exitCategory,
 					partialProgress: hasPartialProgress,
 					batchProgress: buildBatchProgressSnapshot(batchState),
 				},

package/extensions/taskplane/tool-allowlist-constants.ts

@@ -0,0 +1,37 @@
+/**
+ * Lightweight, import-free constants module for the worker tool allowlist.
+ *
+ * This module exists so that pure-data layers (`config-schema.ts`,
+ * `types.ts`) can reference the canonical `DEFAULT_WORKER_USER_TOOLS`
+ * literal without pulling `agent-host.ts`'s heavy `child_process` / `fs`
+ * imports into the schema/types graph (which would either be circular
+ * or pull subprocess plumbing into pure-data files).
+ *
+ * **Strict invariant:** this module MUST NOT have any imports beyond
+ * TypeScript built-ins. Anything more would re-introduce the very
+ * coupling this module exists to break.
+ *
+ * The companion `agent-host.ts` re-exports `DEFAULT_WORKER_USER_TOOLS`
+ * from this module for backward compatibility — existing internal
+ * imports (e.g., `execution.ts`, `worker-tools-allowlist.test.ts`)
+ * continue to work via the agent-host re-export. New code may import
+ * from either location; this module is the source of truth.
+ *
+ * `ENGINE_BRIDGE_TOOLS` and the `buildWorkerToolsAllowlist()` helper
+ * remain in `agent-host.ts` because that's where their consumers live
+ * and there is no duplication problem to solve for them.
+ *
+ * @module taskplane/tool-allowlist-constants
+ * @since TP-189 (Cluster B)
+ */
+
+/**
+ * Default user-tools portion of the worker `--tools` allowlist. This is the
+ * fallback used when neither `taskRunner.worker.tools` config nor the
+ * `TASKPLANE_WORKER_TOOLS` env var supplies a value. Engine bridge tools
+ * (review_step, notify_supervisor, escalate_to_supervisor,
+ * request_segment_expansion) are appended on top by
+ * `buildWorkerToolsAllowlist()` at the spawn site — they are NOT part of
+ * this default and should not be added by callers.
+ */
+export const DEFAULT_WORKER_USER_TOOLS = "read,write,edit,bash,grep,find,ls";

package/extensions/taskplane/types.ts

@@ -4,6 +4,10 @@
  */
 import { join } from "path";
 import type { ExitClassification, TaskExitDiagnostic } from "./diagnostics.js";
+// TP-189 (Cluster B): single source of truth for the worker user-tools
+// default literal. The constants module is import-free so this does NOT
+// create a cycle (types.ts -> tool-allowlist-constants.ts is a leaf).
+import { DEFAULT_WORKER_USER_TOOLS } from "./tool-allowlist-constants.ts";
 
 // ── Types ────────────────────────────────────────────────────────────
 
@@ -390,11 +394,12 @@ export const DEFAULT_ORCHESTRATOR_CONFIG: OrchestratorConfig = {
 	},
 	merge: {
 		model: "",
-		// NOTE (TP-184): Mirrors `DEFAULT_WORKER_USER_TOOLS` in
-		// `agent-host.ts`. Kept as a literal here because types.ts anchors
-		// the module-import graph (agent-host.ts imports from types.ts), so
-		// importing the constant the other direction would create a cycle.
-		tools: "read,write,edit,bash,grep,find,ls",
+		// TP-189 (Cluster B): merge default sourced from the import-free
+		// `tool-allowlist-constants.ts` module. The previous concern about
+		// importing from `agent-host.ts` (which DOES depend on types.ts and
+		// would create a cycle) no longer applies because the constant
+		// lives in a leaf module that imports nothing.
+		tools: DEFAULT_WORKER_USER_TOOLS,
 		thinking: "off",
 		verify: [],
 		order: "fewest-files-first",
@@ -1805,8 +1810,13 @@ export type Tier0RecoveryPattern =
  *
  * These are transient failures where re-running the task has a reasonable
  * chance of success. Classifications NOT in this set (e.g., user_killed,
- * stall_timeout, context_overflow) indicate persistent problems that
- * won't be fixed by retrying.
+ * stall_timeout, context_overflow, spawn_failure) indicate persistent
+ * problems that won't be fixed by retrying.
+ *
+ * **TP-190 (#561):** `spawn_failure` is intentionally excluded — spawn-stage
+ * errors (Pi CLI not findable, worktree provisioning failure, branch
+ * collision) are never transient and require operator action. Retrying
+ * silently would just burn the retry budget and delay the alert.
  *
  * @since TP-039
  */
@@ -2127,6 +2137,25 @@ export interface SupervisorAlertContext {
 	waveIndex?: number;
 	/** Exit reason string (for task-failure alerts) */
 	exitReason?: string;
+	/**
+	 * Structured exit category for task-failure alerts.
+	 *
+	 * Mirrors `LaneTaskOutcome.exitDiagnostic.classification` for IPC
+	 * consumption by the supervisor. Optional for backward compatibility
+	 * — absent when the engine produces a task-failure alert without
+	 * structured diagnostic data.
+	 *
+	 * Notable values consumed by the supervisor playbook:
+	 * - `"spawn_failure"` (TP-190, #561): worker process never spawned
+	 *   (Pi CLI not findable, worktree provisioning error, etc.). Never
+	 *   transient — the playbook MUST escalate immediately rather than
+	 *   retry. When the post-wave phase-transition logic detects an
+	 *   all-spawn-failed wave it also flips `batchState.phase` to
+	 *   `"failed"`; that transition is independent of this alert.
+	 *
+	 * @since TP-190 (#561)
+	 */
+	exitCategory?: ExitClassification;
 	/** Segment frontier snapshot for task-failure diagnosis */
 	segmentFrontier?: SupervisorSegmentFrontierSnapshot;
 	/** Agent ID (for agent-message alerts) */
@@ -2189,6 +2218,30 @@ export interface SupervisorAlert {
  */
 export type SupervisorAlertCallback = (alert: SupervisorAlert) => void;
 
+/**
+ * Information about a lane that has just reached a terminal state.
+ *
+ * Emitted at the no-progress kill and hard-fail decision points so the
+ * supervisor process can mark the lane as terminated and drop any further
+ * alerts queued for it (see {@link LaneTerminatedCallback}).
+ *
+ * @since TP-187 (#538)
+ */
+export interface LaneTerminatedInfo {
+	laneNumber: number;
+	agentId: string;
+	batchId: string;
+	terminatedAt: number;
+	reason: "no-progress-kill" | "hard-fail" | "supervisor-takeover";
+}
+
+/**
+ * Callback invoked when a lane reaches a terminal state.
+ *
+ * @since TP-187 (#538)
+ */
+export type LaneTerminatedCallback = (info: LaneTerminatedInfo) => void;
+
 /**
  * Build a batch progress snapshot from runtime state.
  *

package/extensions/taskplane/worktree.ts

@@ -1901,7 +1901,11 @@ export function runPreflight(config: OrchestratorConfig, repoRoot?: string): Pre
 		switch (piResult.errorKind) {
 			case "not-found":
 				message = "Pi not found on PATH";
-				hint = "Install Pi: npm install -g @mariozechner/pi-coding-agent";
+				// Issue #560: Pi was renamed from @mariozechner to @earendil-works
+				// in v0.74.0. Recommend the new scope for new installs; the legacy
+				// scope still resolves at runtime via Pi's bundled aliasing if a
+				// transitional install has it.
+				hint = "Install Pi: npm install -g @earendil-works/pi-coding-agent (legacy: @mariozechner/pi-coding-agent)";
 				break;
 			case "timeout":
 				message = `Pi did not respond within ${PI_PREFLIGHT_TIMEOUT_MS / 1000}s (retried once)`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskplane",
-  "version": "0.28.8",
+  "version": "0.29.1",
   "description": "AI agent orchestration for pi — parallel task execution with checkpoint discipline",
   "keywords": [
     "pi-package",