taskplane 0.28.8 → 0.29.0

package/extensions/taskplane/path-resolver.ts

@@ -86,15 +86,38 @@ export function getNpmGlobalRoot(): string {
 	return _npmGlobalRoot;
 }
 
+/**
+ * Pi CLI npm package scopes that taskplane resolves at runtime, ordered with
+ * the canonical (current) scope FIRST and legacy scopes after for backward
+ * compatibility. Issue #560: the Pi coding agent was renamed from
+ * `@mariozechner/pi-coding-agent` to `@earendil-works/pi-coding-agent` in
+ * Pi v0.74.0. Pi's own extension loader bundles BOTH scope aliases at runtime
+ * for in-process module imports, but spawn-side path resolution (this file)
+ * has to look on disk under whichever scope was actually installed.
+ *
+ * Order matters: the new scope is preferred so a system that has BOTH
+ * installed (e.g., during a transition window) picks up the current Pi.
+ */
+const PI_PACKAGE_SCOPES = ["@earendil-works", "@mariozechner"] as const;
+
 /**
  * Resolve the absolute path to the Pi coding agent CLI entrypoint (`cli.js`).
  *
- * The Pi CLI is installed as `@mariozechner/pi-coding-agent`. On Windows, invoking
- * `pi` directly executes a `.CMD` shim that cannot be spawned with `shell: false`.
- * This function locates the underlying `dist/cli.js` so callers can spawn it with
- * `node` directly, without a shell intermediary.
+ * The Pi CLI is installed under one of two npm scopes:
+ *   - `@earendil-works/pi-coding-agent` (current, as of Pi v0.74.0)
+ *   - `@mariozechner/pi-coding-agent` (legacy)
  *
- * Resolution order:
+ * On Windows, invoking `pi` directly executes a `.CMD` shim that cannot be
+ * spawned with `shell: false`. This function locates the underlying
+ * `dist/cli.js` so callers can spawn it with `node` directly, without a shell
+ * intermediary.
+ *
+ * Resolution order: the cross product of base directories × package scopes,
+ * with each base directory tried for the new scope before any base directory
+ * is tried for the legacy scope. (Equivalently: scope is the inner loop, base
+ * is the outer loop.)
+ *
+ * Base directories (outer loop):
  *   1. `npm root -g` result (dynamic — covers all setups: nvm, Homebrew, volta, etc.)
  *   2. `%APPDATA%\npm\node_modules\...` (Windows, APPDATA env var)
  *   3. `%USERPROFILE%\AppData\Roaming\npm\node_modules\...` (Windows, HOME-relative)
@@ -102,40 +125,53 @@ export function getNpmGlobalRoot(): string {
  *   5. `/usr/local/lib/node_modules/...` (macOS system Node, Linux)
  *   6. `/opt/homebrew/lib/node_modules/...` (macOS Homebrew)
  *
- * @returns Absolute path to `@mariozechner/pi-coding-agent/dist/cli.js`
- * @throws  {Error} If the CLI entrypoint cannot be found in any known location.
- *          The error message includes the `npm root -g` value for diagnosis.
+ * Scopes per base (inner loop):
+ *   a. `@earendil-works/pi-coding-agent/dist/cli.js`
+ *   b. `@mariozechner/pi-coding-agent/dist/cli.js`
+ *
+ * @returns Absolute path to a Pi CLI `dist/cli.js` (under whichever scope was found).
+ * @throws  {Error} If the CLI entrypoint cannot be found under any base × scope
+ *          combination. The error message includes the `npm root -g` value
+ *          AND lists both scopes searched, for operator diagnosis.
  */
 export function resolvePiCliPath(): string {
-	const relPath = join("@mariozechner", "pi-coding-agent", "dist", "cli.js");
-	const candidates: string[] = [];
+	const bases: string[] = [];
 
 	// 1. Dynamic: npm root -g (covers nvm, Homebrew, volta, custom npm prefix, etc.)
 	const npmRoot = getNpmGlobalRoot();
-	if (npmRoot) candidates.push(join(npmRoot, relPath));
+	if (npmRoot) bases.push(npmRoot);
 
 	// 2-3. Static Windows fallbacks
 	const home = process.env.HOME || process.env.USERPROFILE || "";
 	if (process.env.APPDATA) {
-		candidates.push(join(process.env.APPDATA, "npm", "node_modules", relPath));
+		bases.push(join(process.env.APPDATA, "npm", "node_modules"));
 	}
 	if (home) {
-		candidates.push(join(home, "AppData", "Roaming", "npm", "node_modules", relPath));
+		bases.push(join(home, "AppData", "Roaming", "npm", "node_modules"));
 		// 4. macOS/Linux custom global prefix
-		candidates.push(join(home, ".npm-global", "lib", "node_modules", relPath));
+		bases.push(join(home, ".npm-global", "lib", "node_modules"));
 	}
 	// 5. macOS system Node / Linux
-	candidates.push(join("/usr", "local", "lib", "node_modules", relPath));
+	bases.push(join("/usr", "local", "lib", "node_modules"));
 	// 6. macOS Homebrew
-	candidates.push(join("/opt", "homebrew", "lib", "node_modules", relPath));
+	bases.push(join("/opt", "homebrew", "lib", "node_modules"));
 
-	for (const candidate of candidates) {
-		if (existsSync(candidate)) return candidate;
+	// Cross product: scope is the inner loop so a single base directory is
+	// fully exhausted (new scope, then legacy scope) before falling back to
+	// the next base. This matches operator intuition ("check the most likely
+	// install location for either scope first").
+	for (const base of bases) {
+		for (const scope of PI_PACKAGE_SCOPES) {
+			const candidate = join(base, scope, "pi-coding-agent", "dist", "cli.js");
+			if (existsSync(candidate)) return candidate;
+		}
 	}
 
 	throw new Error(
-		"Cannot find Pi CLI entrypoint (@mariozechner/pi-coding-agent/dist/cli.js). " +
-		"Ensure the pi coding agent is installed globally via 'npm install -g @mariozechner/pi-coding-agent'. " +
+		"Cannot find Pi CLI entrypoint (pi-coding-agent/dist/cli.js) under any known npm scope " +
+		`(${PI_PACKAGE_SCOPES.join(" or ")}). ` +
+		"Install via 'npm install -g @earendil-works/pi-coding-agent' " +
+		"(or, for legacy installs, 'npm install -g @mariozechner/pi-coding-agent'). " +
 		`npm root -g returned: ${npmRoot || "(empty — npm may not be on PATH)"}`,
 	);
 }
@@ -189,12 +225,15 @@ export function resolveTaskplanePackageFile(repoRoot: string, relPath: string):
 	candidates.push(join("/opt", "homebrew", "lib", "node_modules", "taskplane", relPath));
 
 	// 8. Peer of pi's package (look adjacent to pi's CLI entrypoint).
-	// pi is at: <npmRoot>/@mariozechner/pi-coding-agent/dist/cli.js
-	// so piPkgDir = <npmRoot>/@mariozechner/pi-coding-agent  (resolve up 2 levels from cli.js)
-	// then go up TWO more levels to reach <npmRoot>, then into taskplane/
+	// pi is at: <npmRoot>/<scope>/pi-coding-agent/dist/cli.js (where <scope> is
+	//   @earendil-works (current) or @mariozechner (legacy)).
+	// so piPkgDir = <npmRoot>/<scope>/pi-coding-agent (resolve up 2 levels from cli.js).
+	// Then go up TWO more levels to reach <npmRoot>, then into taskplane/.
+	// This works regardless of which scope Pi is installed under because we
+	// only walk up the directory tree — we never name the scope explicitly.
 	try {
 		const piPath = process.argv[1] || "";
-		const piPkgDir = resolve(piPath, "..", ".."); // <npmRoot>/@mariozechner/pi-coding-agent
+		const piPkgDir = resolve(piPath, "..", ".."); // <npmRoot>/<scope>/pi-coding-agent
 		const npmRootFromPi = resolve(piPkgDir, "..", ".."); // <npmRoot>
 		candidates.push(join(npmRootFromPi, "taskplane", relPath));
 	} catch { /* ignore — process.argv[1] may be undefined in test contexts */ }

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

@@ -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);

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";