taskplane 0.28.8 → 0.29.1

package/bin/get-version.mjs

@@ -0,0 +1,50 @@
+/**
+ * `getVersion` — capture a CLI's version string with stdout-precedence,
+ * stderr-fallback, and null-on-failure semantics.
+ *
+ * Extracted from the inline `getVersion()` in `bin/taskplane.mjs` so it
+ * can be unit-tested without subprocessing the whole CLI.
+ *
+ * Behavior:
+ *   - Spawns `${cmd} ${flag}` with shell:true and stdio:['ignore','pipe','pipe']
+ *   - Returns null if `spawnSync` itself throws (e.g., command not found)
+ *   - Returns null if the subprocess errored OR exited with non-zero status
+ *     (matches the prior `execSync`-throws-on-failure contract)
+ *   - On success, returns stdout if non-empty, else stderr (some CLIs
+ *     notably `pi` print version output to stderr)
+ *   - Returns null if both streams are empty
+ *
+ * @since TP-189-C (extracted) / TP-185 follow-up (original fix scope)
+ *
+ * @param {string} cmd — command name (or already-formed token sequence)
+ * @param {string} [flag="--version"] — flag appended to cmd
+ * @returns {string | null} trimmed version string, or null on any failure
+ */
+
+import { spawnSync } from "node:child_process";
+
+export function getVersion(cmd, flag = "--version") {
+	let result;
+	try {
+		// shell:true matches the prior execSync behavior — accepts a
+		// space-joined command string and resolves via PATH lookup.
+		result = spawnSync(`${cmd} ${flag}`, [], {
+			shell: true,
+			encoding: "utf-8",
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+	} catch {
+		return null;
+	}
+	// Match prior contract: any non-success path → null.
+	// `execSync` previously threw on either spawn failure or non-zero exit,
+	// and the caller's catch returned null. Replicate that here so a CLI
+	// that exits 1 with shell error text in stderr (e.g., "command not
+	// found") does NOT surface as a fake version string.
+	if (!result || result.error || result.status !== 0) return null;
+	const stdout = (result.stdout ?? "").toString().trim();
+	const stderr = (result.stderr ?? "").toString().trim();
+	if (stdout) return stdout;
+	if (stderr) return stderr;
+	return null;
+}

package/bin/taskplane.mjs

@@ -36,6 +36,7 @@ import {
 	ALL_GITIGNORE_PATTERNS,
 	patternToRegex,
 } from "./gitignore-patterns.mjs";
+import { getVersion } from "./get-version.mjs";
 
 // ─── Paths ──────────────────────────────────────────────────────────────────
 
@@ -127,14 +128,10 @@ function commandExists(cmd) {
 	}
 }
 
-/** Get command version string. */
-function getVersion(cmd, flag = "--version") {
-	try {
-		return execSync(`${cmd} ${flag}`, { stdio: "pipe" }).toString().trim();
-	} catch {
-		return null;
-	}
-}
+// `getVersion` lives in `./get-version.mjs` so it can be unit-tested
+// without subprocessing the full CLI. Imported above. (TP-189-C / TP-185
+// follow-up: capture both stdout and stderr because `pi --version`
+// prints to stderr; null on failure preserves the original contract.)
 
 /**
  * Parse the tabular output from `pi --list-models` into structured model rows.

package/extensions/taskplane/agent-bridge-extension.ts

@@ -146,6 +146,12 @@ function writeSegmentExpansionRequest(request: SegmentExpansionRequest): string
  * section. All-checkboxes-checked is also NOT a trigger — it is the normal
  * pre-code-review state.
  *
+ * Fenced code blocks (delimited by ``` or ~~~) inside a step's body are
+ * skipped during the scan (TP-189-A3). This avoids a false-positive
+ * refusal when a step documents the literal `**Status:** ✅ Complete`
+ * pattern as part of its own instructions — a legitimate authoring case
+ * that doesn't represent an actual completion claim.
+ *
  * Designed to fail-open: any I/O error or a missing step heading returns
  * `false` (the review proceeds). The prompt-side Recovery Recipe is the
  * primary defense; this guard is a hard backstop, not a gatekeeper.
@@ -165,15 +171,64 @@ export function isStepMarkedComplete(statusPath: string, stepNum: number): boole
 	const lines = content.split(/\r?\n/);
 	const stepHeadingRe = new RegExp(`^###\\s+Step\\s+${stepNum}\\b`);
 	const nextStepHeadingRe = /^###\s+Step\s+\d+\b/;
-
+	// TP-189-A3: track fenced-code-block state per CommonMark semantics.
+	// A fence opens with 3+ backticks OR 3+ tildes optionally followed by
+	// an info string (e.g., ```javascript). A fence CLOSES only when a
+	// matching delimiter (same char, length >= opener length) is seen on
+	// a line by itself — the closer line MUST NOT contain trailing
+	// non-whitespace text. This distinction matters: ```javascript
+	// inside an open fence is content, not a closer; mistreating it as a
+	// closer would let `**Status:** ✅ Complete` later in the same code
+	// block trip the guard. Tracking opener char + length also avoids
+	// premature close on `~~~` inside a backtick fence (or vice versa).
+	const openerRe = /^\s*(`{3,}|~{3,})(.*)$/;
 	let inSection = false;
+	let fenceOpener: { char: string; length: number } | null = null;
 	for (const line of lines) {
 		if (!inSection) {
 			if (stepHeadingRe.test(line)) inSection = true;
 			continue;
 		}
-		// Stop scanning at the next step heading.
-		if (nextStepHeadingRe.test(line)) break;
+		// Step boundaries are recognized only OUTSIDE a fenced block.
+		// (A `### Step N:` line inside a code-fence sample is content,
+		// not a real heading.)
+		if (fenceOpener === null && nextStepHeadingRe.test(line)) break;
+		// Detect fence delimiter lines.
+		const fenceMatch = line.match(openerRe);
+		if (fenceMatch) {
+			const delim = fenceMatch[1];
+			const trailing = fenceMatch[2] ?? "";
+			const char = delim[0]; // "`" or "~"
+			const length = delim.length;
+			if (fenceOpener === null) {
+				// Opening: any trailing text is the info string — allowed.
+				// CommonMark forbids backticks in a backtick info string,
+				// but rejecting that case here only risks false negatives
+				// (i.e., not opening a fence we should have); the worst-
+				// case impact is a real Status line being inspected as if
+				// outside a fence — which is the safe default.
+				fenceOpener = { char, length };
+				continue;
+			}
+			// Already inside a fence — a line counts as a closer ONLY if:
+			//   1. delimiter char matches the opener,
+			//   2. delimiter length >= opener length,
+			//   3. nothing follows the delimiter except whitespace.
+			const trailingIsWhitespace = /^\s*$/.test(trailing);
+			if (
+				char === fenceOpener.char &&
+				length >= fenceOpener.length &&
+				trailingIsWhitespace
+			) {
+				fenceOpener = null;
+				continue;
+			}
+			// Else: this line is content INSIDE the open fence (e.g.,
+			// ```javascript inside a 4-backtick fence, or a non-matching
+			// tilde delimiter). Fall through to the inFence skip below.
+		}
+		// Skip lines inside an open fenced code block.
+		if (fenceOpener !== null) continue;
 		// Match a literal status line within this step's section.
 		// Examples that should match:
 		//   **Status:** ✅ Complete

package/extensions/taskplane/agent-host.ts

@@ -87,23 +87,17 @@ export const ENGINE_BRIDGE_TOOLS = [
 	"request_segment_expansion",
 ] as const;
 
-/**
- * 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
- * (`ENGINE_BRIDGE_TOOLS`) are appended on top by
- * `buildWorkerToolsAllowlist()` at the spawn site — they are NOT part of
- * this default and should not be added by callers.
- *
- * NOTE: This literal is duplicated in `config-schema.ts` (defaults block)
- * and `types.ts` (defaults block) as well. Those modules intentionally
- * keep the literal to avoid pulling agent-host's heavy imports (child
- * process, fs) into pure schema/type files. If you change the default
- * here, update those copies too.
- *
- * @since TP-184
- */
-export const DEFAULT_WORKER_USER_TOOLS = "read,write,edit,bash,grep,find,ls";
+// TP-189 (Cluster B): `DEFAULT_WORKER_USER_TOOLS` now lives in the
+// import-free `./tool-allowlist-constants.ts` module so that pure-data
+// layers (`config-schema.ts`, `types.ts`) can import it without pulling
+// agent-host's heavy `child_process`/`fs` imports into the schema/type
+// graph. We re-export here so existing internal imports (e.g.,
+// `execution.ts`, `worker-tools-allowlist.test.ts`) continue to work
+// without churn.
+//
+// @since TP-184 (constant introduced) / TP-189 (moved to constants module)
+export { DEFAULT_WORKER_USER_TOOLS } from "./tool-allowlist-constants.ts";
+import { DEFAULT_WORKER_USER_TOOLS } from "./tool-allowlist-constants.ts";
 
 /**
  * Build the final worker `--tools` allowlist string by combining the

package/extensions/taskplane/config-schema.ts

@@ -37,6 +37,12 @@
  * @module config/schema
  */
 
+// TP-189 (Cluster B): single source of truth for the worker user-tools
+// default literal. This is a deliberately import-free module so we can
+// import it here without pulling `agent-host.ts`'s `child_process`/`fs`
+// imports into the schema layer.
+import { DEFAULT_WORKER_USER_TOOLS } from "./tool-allowlist-constants.ts";
+
 // ── Config Version ───────────────────────────────────────────────────
 
 /**
@@ -594,14 +600,11 @@ export const DEFAULT_TASK_RUNNER_SECTION: TaskRunnerSection = {
 	testing: { commands: {} },
 	standards: { docs: [], rules: [] },
 	standardsOverrides: {},
-	// NOTE (TP-184): The user-tools default literal here mirrors
-	// `DEFAULT_WORKER_USER_TOOLS` in `agent-host.ts`. We keep the literal
-	// instead of importing the constant because this file is currently
-	// import-free (pure schema/defaults) and importing from agent-host.ts
-	// would pull child_process/fs into the schema layer. If you change the
-	// default, update both copies. Engine bridge tools are appended at the
-	// lane-runner spawn site by `buildWorkerToolsAllowlist()`, not here.
-	worker: { model: "", tools: "read,write,edit,bash,grep,find,ls", thinking: "", excludeExtensions: [] },
+	// TP-189 (Cluster B): user-tools default sourced from
+	// `tool-allowlist-constants.ts` (single source of truth). Engine
+	// bridge tools are appended at the lane-runner spawn site by
+	// `buildWorkerToolsAllowlist()`, not here.
+	worker: { model: "", tools: DEFAULT_WORKER_USER_TOOLS, thinking: "", excludeExtensions: [] },
 	reviewer: { model: "", tools: "read,bash,grep,find,ls", thinking: "on", excludeExtensions: [] },
 	context: {
 		workerContextWindow: 0,
@@ -653,10 +656,12 @@ export const DEFAULT_ORCHESTRATOR_SECTION: OrchestratorSection = {
 	},
 	merge: {
 		model: "",
-		// NOTE (TP-184): Mirrors `DEFAULT_WORKER_USER_TOOLS`. Merge agent does
-		// not run through `buildWorkerToolsAllowlist()` (no bridge-tool needs)
-		// so this literal is independent of the worker allowlist plumbing.
-		tools: "read,write,edit,bash,grep,find,ls",
+		// TP-189 (Cluster B): merge default mirrors the worker user-tools
+		// constant. The merge agent does NOT run through
+		// `buildWorkerToolsAllowlist()` (no bridge-tool needs), so this
+		// reference is purely for default-value parity — not a hard
+		// coupling to the worker allowlist plumbing.
+		tools: DEFAULT_WORKER_USER_TOOLS,
 		thinking: "off",
 		verify: [],
 		order: "fewest-files-first",

package/extensions/taskplane/diagnostics.ts

@@ -52,7 +52,14 @@ export interface SessionTokenCounts {
  * | `session_vanished`   | Session disappeared without exit summary             |
  * | `stall_timeout`      | No STATUS.md progress for stall_timeout minutes      |
  * | `user_killed`        | User manually killed the session (e.g., forced process kill) |
+ * | `spawn_failure`      | Worker process never spawned (e.g., Pi CLI not findable, worktree provisioning) |
  * | `unknown`            | Could not determine cause                            |
+ *
+ * Note: `spawn_failure` (TP-190, #561) is set BEFORE any agent process exists —
+ * it is produced synchronously when `spawnAgent()` throws (resolvePiCliPath
+ * miss, file-system error, etc.). It is intentionally NOT in
+ * `TIER0_RETRYABLE_CLASSIFICATIONS` because spawn-stage failures are never
+ * transient; retrying without operator intervention only burns budget.
  */
 export type ExitClassification =
 	| "completed"
@@ -64,6 +71,7 @@ export type ExitClassification =
 	| "session_vanished"
 	| "stall_timeout"
 	| "user_killed"
+	| "spawn_failure"
 	| "unknown";
 
 /**
@@ -79,6 +87,7 @@ export const EXIT_CLASSIFICATIONS: readonly ExitClassification[] = [
 	"session_vanished",
 	"stall_timeout",
 	"user_killed",
+	"spawn_failure",
 	"unknown",
 ] as const;
 

package/extensions/taskplane/engine-worker.ts

@@ -40,6 +40,17 @@ export type WorkerToMainMessage =
 	| { type: "monitor-update"; state: MonitorState }
 	| { type: "engine-event"; event: EngineEvent }
 	| { type: "supervisor-alert"; alert: SupervisorAlert }
+	/**
+	 * TP-187 (#538): Lane has reached a terminal state. The supervisor process
+	 * uses this to mark the lane terminated and filter any subsequently-arriving
+	 * (zombie) alerts whose `context.laneNumber`/`context.agentId` matches.
+	 */
+	| { type: "lane-terminated"; info: import("./types.ts").LaneTerminatedInfo }
+	/**
+	 * TP-187 (#538): Lane number has been re-allocated to a fresh task. The
+	 * supervisor lifts the suppression so subsequent alerts pass through.
+	 */
+	| { type: "lane-respawned"; laneNumber: number; agentId: string; batchId: string }
 	| { type: "state-sync"; state: SerializedBatchState }
 	| { type: "complete"; state: SerializedBatchState }
 	| { type: "error"; message: string; stack?: string; source?: WorkerErrorSource };
@@ -325,6 +336,18 @@ if (process.env.TASKPLANE_ENGINE_FORK === "1" && typeof process.send === "functi
 			send({ type: "supervisor-alert", alert });
 		};
 
+		// TP-187 (#538): Lane termination callback — forwards lane-terminated to
+		// the supervisor process so it can suppress in-flight zombie alerts.
+		const onLaneTerminated = (info: import("./types.ts").LaneTerminatedInfo) => {
+			send({ type: "lane-terminated", info });
+		};
+
+		// TP-187 (#538): Lane respawn callback — forwards lane-respawned to
+		// the supervisor process so it can lift suppression for re-allocated lanes.
+		const onLaneRespawned = (laneNumber: number, agentId: string, batchId: string) => {
+			send({ type: "lane-respawned", laneNumber, agentId, batchId });
+		};
+
 		// ── Execute engine ───────────────────────────────────────────
 		const enginePromise = data.mode === "resume"
 			? resumeOrchBatch(
@@ -340,6 +363,8 @@ if (process.env.TASKPLANE_ENGINE_FORK === "1" && typeof process.send === "functi
 				data.force ?? false,
 				onSupervisorAlert,
 				data.supervisorAutonomy ?? "autonomous",
+				onLaneTerminated,
+				onLaneRespawned,
 			)
 			: executeOrchBatch(
 				data.args ?? "",
@@ -355,6 +380,8 @@ if (process.env.TASKPLANE_ENGINE_FORK === "1" && typeof process.send === "functi
 				onEngineEvent,
 				onSupervisorAlert,
 				data.supervisorAutonomy ?? "autonomous",
+				onLaneTerminated,
+				onLaneRespawned,
 			);
 
 		enginePromise

package/extensions/taskplane/engine.ts

@@ -17,8 +17,9 @@ import { applyMergeRetryLoop, computeCleanupGatePolicy, computeMergeFailurePolic
 import type { CleanupGateRepoFailure } from "./messages.ts";
 import { assembleDiagnosticInput, emitDiagnosticReports } from "./diagnostic-reports.ts";
 import { resolveOperatorId } from "./naming.ts";
-import { applyPartialProgressToOutcomes, buildTier0EventBase, deleteBatchState, emitEngineEvent, emitTier0Event, loadBatchHistory, loadBatchState, persistRuntimeState, saveBatchHistory, seedPendingOutcomesForAllocatedLanes, syncTaskOutcomesFromMonitor, upsertTaskOutcome } from "./persistence.ts";
+import { applyPartialProgressToOutcomes, buildTier0EventBase, deleteBatchState, emitEngineEvent, emitTier0Event, loadBatchHistory, loadBatchState, persistRuntimeState, saveBatchHistory, saveBatchMetaRuntimeArtifact, seedPendingOutcomesForAllocatedLanes, syncTaskOutcomesFromMonitor, upsertTaskOutcome } from "./persistence.ts";
 import { readRegistrySnapshot, isTerminalStatus, isProcessAlive as registryIsProcessAlive } from "./process-registry.ts";
+import { drainAgentOutbox } from "./mailbox.ts";
 import { buildBatchProgressSnapshot, buildEngineEventBase, buildSegmentId, buildSupervisorSegmentFrontierSnapshot, defaultResilienceState, FATAL_DISCOVERY_CODES, generateBatchId, TIER0_RETRYABLE_CLASSIFICATIONS, TIER0_RETRY_BUDGETS, tier0ScopeKey, tier0WaveScopeKey } from "./types.ts";
 import type { AllocatedLane, AllocatedTask, BatchHistorySummary, BatchTaskSummary, BatchWaveSummary, DiscoveryResult, EngineEventCallback, EscalationContext, LaneExecutionResult, LaneTaskOutcome, MergeWaveResult, OrchBatchPhase, OrchBatchRuntimeState, OrchestratorConfig, ParsedTask, PersistedSegmentRecord, SegmentExpansionRequest, SupervisorAlert, SupervisorAlertCallback, TaskRunnerConfig, TaskSegmentPlan, TaskSegmentPlanMap, TaskSegmentNode, Tier0EscalationPattern, Tier0RecoveryPattern, TokenCounts, WaveExecutionResult, WorkspaceConfig } from "./types.ts";
 import { buildDependencyGraph, computeWaveAssignments, resolveBaseBranch, resolveRepoRoot, validateGraph } from "./waves.ts";
@@ -67,6 +68,114 @@ function emitTier0Escalation(
 /** Zero-token sentinel used for task/wave/batch aggregation. */
 const ZERO_TOKENS: TokenCounts = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, costUsd: 0 };
 
+/**
+ * TP-190 (#561): Determine whether a wave's failures are entirely
+ * Runtime V2 spawn-stage failures.
+ *
+ * Returns `true` only when:
+ *   - At least one task failed (`failedTaskIds.length > 0`)
+ *   - No task succeeded — checked via BOTH the wave's projected
+ *     `succeededTaskIds` (terminal task-level completion) AND a scan of
+ *     `laneResults[].tasks[]` for any per-task outcome with
+ *     `status === "succeeded"` (catches non-terminal segment successes
+ *     on multi-segment tasks that schedule a continuation round and
+ *     therefore don't appear in `succeededTaskIds`)
+ *   - Every failed outcome carries
+ *     `exitDiagnostic.classification === "spawn_failure"`
+ *
+ * The engine uses the result to transition `batchState.phase` to
+ * `"failed"` (not `"executing"` and not `"paused"`) so `orch_status()`
+ * and the dashboard surface an actionable answer for the operator.
+ * Spawn-stage errors (Pi CLI not findable, worktree provisioning
+ * failure, branch collision) are never transient — they require an
+ * external fix before re-running, so `"paused"` would be misleading.
+ *
+ * **Sage post-mortem note (multi-segment edge case, post-PR-#566):** the
+ * earlier version of this function checked only `succeededTaskIds.length
+ * !== 0` to gate the all-failed verdict. That field is the *projected*
+ * terminal-completion set: it's populated only when a task reaches its
+ * final segment. A wave that has a multi-segment task succeed on segment
+ * 1 (with a continuation segment in a later round) would have an empty
+ * `succeededTaskIds` even though work demonstrably succeeded. Combined
+ * with a single-segment spawn-failure on a different task, the wave
+ * would falsely trip the all-spawn-failed verdict. The added
+ * `laneResults` scan closes this gap by inspecting raw per-task outcome
+ * status before terminal projection.
+ *
+ * Pure function — exported for unit testing alongside the engine's
+ * post-wave handling logic.
+ *
+ * @since TP-190 (#561)
+ */
+export function isAllLanesSpawnFailedWave(
+	waveResult: {
+		failedTaskIds: string[];
+		succeededTaskIds: string[];
+		/**
+		 * Optional per-lane outcomes. When provided, the function additionally
+		 * checks whether ANY task outcome carried `status === "succeeded"`,
+		 * which covers non-terminal segment successes that don't appear in the
+		 * projected `succeededTaskIds`. Optional for backward compatibility
+		 * with the v0.29.0 callers and the existing TP-190 unit tests; the
+		 * production call site (engine.ts post-wave) always passes the full
+		 * `WaveExecutionResult` and gets the stricter check.
+		 */
+		laneResults?: ReadonlyArray<{ tasks: ReadonlyArray<{ status: string }> }>;
+	},
+	allTaskOutcomes: LaneTaskOutcome[],
+): boolean {
+	if (waveResult.failedTaskIds.length === 0) return false;
+	if (waveResult.succeededTaskIds.length !== 0) return false;
+	// TP-190 (#561) sage post-mortem: scan per-lane outcomes for any
+	// `status === "succeeded"`. This catches non-terminal segment successes
+	// that don't appear in `succeededTaskIds` (the latter is the terminal
+	// projection populated only when a multi-segment task reaches its final
+	// segment).
+	if (waveResult.laneResults) {
+		for (const laneResult of waveResult.laneResults) {
+			for (const taskOutcome of laneResult.tasks) {
+				if (taskOutcome.status === "succeeded") return false;
+			}
+		}
+	}
+	return waveResult.failedTaskIds.every((failedId) => {
+		const outcome = allTaskOutcomes.find((o) => o.taskId === failedId);
+		return outcome?.exitDiagnostic?.classification === "spawn_failure";
+	});
+}
+
+/**
+ * TP-190 (#561): Build the spawn-failure-specific extras layered onto a
+ * `task-failure` supervisor alert when the underlying outcome was a
+ * spawn-stage failure.
+ *
+ * Returns:
+ *   - `exitCategory`: the structured `ExitClassification` that the
+ *     supervisor playbook can branch on (e.g.,
+ *     `"spawn_failure"` → escalate immediately rather than retry).
+ *   - `summaryLine`: an extra `  Spawn failure: … escalate immediately…`
+ *     line for human-readable display, blank string when the outcome
+ *     is not a spawn failure (so the existing summary template renders
+ *     unchanged for non-spawn cases).
+ *
+ * Pure function — exported for unit testing alongside the alert-emission
+ * logic in `executeOrchBatch` and `resumeOrchBatch`. Both call sites
+ * read from `outcome.exitDiagnostic?.classification` so the helper takes
+ * the optional classification directly.
+ *
+ * @since TP-190 (#561)
+ */
+export function buildSpawnFailureAlertExtras(
+	outcome: { exitDiagnostic?: { classification?: string } | undefined } | undefined,
+): { exitCategory: import("./diagnostics.ts").ExitClassification | undefined; summaryLine: string } {
+	const raw = outcome?.exitDiagnostic?.classification;
+	const exitCategory = raw as import("./diagnostics.ts").ExitClassification | undefined;
+	const summaryLine = raw === "spawn_failure"
+		? `  Spawn failure: worker process never started — escalate immediately (do not retry)\n`
+		: "";
+	return { exitCategory, summaryLine };
+}
+
 /** Map embedded outcome telemetry to the batch-history TokenCounts shape. */
 export function taskTokensFromOutcomeTelemetry(outcome: LaneTaskOutcome): TokenCounts {
 	const telemetry = outcome.telemetry;
@@ -1281,6 +1390,20 @@ async function attemptWorkerCrashRetry(
 			continue;
 		}
 
+		// TP-190 (#561): Defense-in-depth — spawn-stage failures (Pi CLI not
+		// findable, worktree provisioning failure, branch collision) are NEVER
+		// transient. Retrying without operator intervention only burns the
+		// retry budget and delays the supervisor alert. The generic
+		// `TIER0_RETRYABLE_CLASSIFICATIONS.has()` gate below also catches this
+		// (spawn_failure is not in the set), but the explicit early-return
+		// here gives operators a clearer log message at the gate site.
+		if (classification === "spawn_failure") {
+			execLog("batch", batchState.batchId,
+				`tier0: task ${taskId} spawn_failure — operator action required, NOT auto-retrying (TP-190)`,
+			);
+			continue;
+		}
+
 		// Check if retryable
 		if (!TIER0_RETRYABLE_CLASSIFICATIONS.has(classification)) {
 			execLog("batch", batchState.batchId,
@@ -1781,6 +1904,8 @@ async function attemptStaleWorktreeRecovery(
 	onSupervisorAlert?: SupervisorAlertCallback,
 	supervisorAutonomy: "interactive" | "supervised" | "autonomous" = "autonomous",
 	runnerConfig?: TaskRunnerConfig,
+	onLaneTerminated?: import("./types.ts").LaneTerminatedCallback,
+	onLaneRespawned?: (laneNumber: number, agentId: string, batchId: string) => void,
 ): Promise<WaveExecutionResult | null> {
 	// Only attempt recovery for ALLOC_WORKTREE_FAILED
 	if (!waveResult.allocationError || waveResult.allocationError.code !== "ALLOC_WORKTREE_FAILED") {
@@ -1896,6 +2021,8 @@ async function attemptStaleWorktreeRecovery(
 			excludeExtensions: runnerConfig.worker.excludeExtensions ?? [],
 		} : undefined,
 		runnerConfig?.workerExcludeExtensions ?? [],
+		onLaneTerminated,
+		onLaneRespawned,
 	);
 
 	return retryResult;
@@ -1973,6 +2100,18 @@ export async function executeOrchBatch(
 	onEngineEvent?: EngineEventCallback | null,
 	onSupervisorAlert?: SupervisorAlertCallback | null,
 	supervisorAutonomy: "interactive" | "supervised" | "autonomous" = "autonomous",
+	/**
+	 * TP-187 (#538): Optional callback fired when a lane reaches a terminal
+	 * state. The supervisor process forwards this over IPC and uses it to
+	 * suppress zombie alerts queued for the now-dead lane.
+	 */
+	onLaneTerminated?: import("./types.ts").LaneTerminatedCallback | null,
+	/**
+	 * TP-187 (#538): Optional callback fired when a lane is freshly
+	 * (re-)allocated to a task. The supervisor process uses it to lift any
+	 * zombie-alert suppression carried over from a prior wave.
+	 */
+	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,
@@ -1999,6 +2138,23 @@ export async function executeOrchBatch(
 		}
 	};
 
+	// ── TP-187 (#538): Lane termination forwarding helper ──────
+	// Forwards lane-terminated events through the same callback chain so the
+	// supervisor process can suppress zombie alerts queued for a dead lane.
+	const emitLaneTerminated = (info: import("./types.ts").LaneTerminatedInfo): void => {
+		if (onLaneTerminated) {
+			try {
+				onLaneTerminated(info);
+			} catch (err: unknown) {
+				const msg = err instanceof Error ? err.message : String(err);
+				execLog("batch", batchState.batchId, `lane-terminated callback failed: ${msg}`, {
+					laneNumber: info.laneNumber,
+					reason: info.reason,
+				});
+			}
+		}
+	};
+
 	// ── TP-040 R002: Terminal event emission helper ──────────────
 	// Routes all early-return and terminal paths through consistent event
 	// emission so external consumers always receive a deterministic terminal
@@ -2312,6 +2468,22 @@ export async function executeOrchBatch(
 	// ── TS-009: Persist state on batch start (after wave computation) ──
 	persistRuntimeState("batch-start", batchState, wavePlan, latestAllocatedLanes, allTaskOutcomes, discoveryRef, stateRoot);
 
+	// ── TP-187 (#539): Persist batch-meta runtime artifact ──────────────
+	// Captures the wave plan and core scalars to a runtime-side file that
+	// survives `orch_abort()` (which deletes `.pi/batch-state.json`). Used by
+	// `orch_resume(force=true)` to deterministically reconstruct state when
+	// the main batch-state file is gone. Best-effort write: failures log only.
+	saveBatchMetaRuntimeArtifact(stateRoot, {
+		schemaVersion: 1,
+		batchId: batchState.batchId,
+		wavePlan: wavePlan.map(wave => [...wave]),
+		baseBranch: batchState.baseBranch,
+		orchBranch: batchState.orchBranch,
+		mode: workspaceConfig ? "workspace" : "repo",
+		startedAt: batchState.startedAt,
+		totalWaves: wavePlan.length,
+	});
+
 	// ── 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
@@ -2507,6 +2679,8 @@ export async function executeOrchBatch(
 				excludeExtensions: runnerConfig.worker.excludeExtensions ?? [],
 			} : undefined,
 			runnerConfig?.workerExcludeExtensions ?? [],
+			emitLaneTerminated,
+			onLaneRespawned ?? undefined,
 		);
 
 		// ── TP-039: Tier 0 — Stale worktree recovery ────────────
@@ -2530,6 +2704,8 @@ export async function executeOrchBatch(
 				emitAlert,
 				supervisorAutonomy,
 				runnerConfig,
+				emitLaneTerminated,
+				onLaneRespawned ?? undefined,
 			);
 			if (retryResult) {
 				const staleRecovered = !retryResult.allocationError;
@@ -3030,11 +3206,17 @@ export async function executeOrchBatch(
 			const frontierSummary = segmentFrontier
 				? `  Segment frontier: ${segmentFrontier.terminalSegments}/${segmentFrontier.totalSegments} terminal\n`
 				: "";
+			// TP-190 (#561): Surface the structured exit category so the supervisor
+			// playbook can branch deterministically. In particular,
+			// `exitCategory === "spawn_failure"` signals an immediate-escalation
+			// failure (not a retry candidate) — the worker process never spawned.
+			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` +
@@ -3054,10 +3236,62 @@ export async function executeOrchBatch(
 					laneNumber: laneForTask?.laneNumber,
 					waveIndex: waveIdx,
 					exitReason,
+					exitCategory,
 					partialProgress: hasPartialProgress,
 					batchProgress: buildBatchProgressSnapshot(batchState),
 				},
 			});
+
+			// TP-187 (#538): Hard-fail termination — synchronously drain the
+			// agent's outbox so stale escalations/replies don't get re-discovered
+			// later, then emit lane-terminated so the supervisor process
+			// suppresses any in-transit zombie alerts targeting this lane/agent.
+			if (laneForTask) {
+				const hardFailAgentId = outcome?.sessionName && outcome.sessionName.length > 0
+					? outcome.sessionName
+					: `${laneForTask.laneSessionId}-worker`;
+				try {
+					const drained = drainAgentOutbox(stateRoot, batchState.batchId, hardFailAgentId);
+					if (drained > 0) {
+						execLog("batch", batchState.batchId, `hard-fail outbox drain: ${drained} entr${drained === 1 ? "y" : "ies"} for ${hardFailAgentId}`);
+					}
+				} catch { /* best effort — do not block termination */ }
+				emitLaneTerminated({
+					laneNumber: laneForTask.laneNumber,
+					agentId: hardFailAgentId,
+					batchId: batchState.batchId,
+					terminatedAt: Date.now(),
+					reason: "hard-fail",
+				});
+			}
+		}
+
+		// ── TP-190 (#561): All-lane spawn-failure phase transition ──
+		// When every task in this wave failed AND every failure is a
+		// `spawn_failure` (worker process never started), the operator cannot
+		// recover without changing something external (Pi CLI install, file
+		// permissions, branch state). Transition `phase` to `"failed"` so
+		// `orch_status()` and the dashboard surface an actionable answer
+		// (`failed`) instead of leaving the operator with `executing` while
+		// every lane is dead. We use `"failed"` rather than `"paused"` (per
+		// PROMPT design): `paused` implies an operator-flippable resume,
+		// which is wrong here — spawn failures require an external fix first.
+		// `isAllLanesSpawnFailedWave` is exported as a pure helper for unit
+		// testing.
+		const allFailedAreSpawnFailures = isAllLanesSpawnFailedWave(waveResult, allTaskOutcomes);
+		if (allFailedAreSpawnFailures) {
+			batchState.phase = "failed";
+			execLog("batch", batchState.batchId,
+				`phase → failed: every lane in wave ${waveIdx + 1} hit spawn_failure (TP-190 #561)`,
+				{ failedTasks: waveResult.failedTaskIds.join(",") },
+			);
+			onNotify(
+				ORCH_MESSAGES.orchBatchFailed(batchState.batchId, `all lanes in wave ${waveIdx + 1} failed to spawn (Runtime V2 spawn-failure — see task-failure alerts above)`),
+				"error",
+			);
+			persistRuntimeState("wave-spawn-failure", batchState, wavePlan, latestAllocatedLanes, allTaskOutcomes, discoveryRef, stateRoot);
+			emitTerminalEvent(`All-lane spawn failure at wave ${waveIdx + 1}`);
+			break;
 		}
 
 		// ── TS-009: Persist state after wave execution ──