taskplane 0.28.8 → 0.29.0

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/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";
@@ -1781,6 +1782,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 +1899,8 @@ async function attemptStaleWorktreeRecovery(
 			excludeExtensions: runnerConfig.worker.excludeExtensions ?? [],
 		} : undefined,
 		runnerConfig?.workerExcludeExtensions ?? [],
+		onLaneTerminated,
+		onLaneRespawned,
 	);
 
 	return retryResult;
@@ -1973,6 +1978,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 +2016,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 +2346,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 +2557,8 @@ export async function executeOrchBatch(
 				excludeExtensions: runnerConfig.worker.excludeExtensions ?? [],
 			} : undefined,
 			runnerConfig?.workerExcludeExtensions ?? [],
+			emitLaneTerminated,
+			onLaneRespawned ?? undefined,
 		);
 
 		// ── TP-039: Tier 0 — Stale worktree recovery ────────────
@@ -2530,6 +2582,8 @@ export async function executeOrchBatch(
 				emitAlert,
 				supervisorAutonomy,
 				runnerConfig,
+				emitLaneTerminated,
+				onLaneRespawned ?? undefined,
 			);
 			if (retryResult) {
 				const staleRecovered = !retryResult.allocationError;
@@ -3058,6 +3112,29 @@ export async function executeOrchBatch(
 					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",
+				});
+			}
 		}
 
 		// ── TS-009: Persist state after wave execution ──

package/extensions/taskplane/execution.ts

@@ -1757,6 +1757,8 @@ export async function executeWave(
 	reviewerConfig?: { model?: string; thinking?: string; tools?: string; excludeExtensions?: string[] },
 	workerConfig?: { model?: string; thinking?: string; tools?: string; excludeExtensions?: string[] } | null,
 	workerExcludeExtensions?: string[],
+	onLaneTerminated?: import("./types.ts").LaneTerminatedCallback,
+	onLaneRespawned?: (laneNumber: number, agentId: string, batchId: string) => void,
 ): Promise<WaveExecutionResult> {
 	const startedAt = Date.now();
 	const policy = config.failure.on_task_failure;
@@ -1866,7 +1868,7 @@ export async function executeWave(
 			...buildWorkerEnv(workerConfig),
 			...buildReviewerEnv(reviewerConfig),
 			...buildWorkerExcludeEnv(workerExcludeExtensions),
-		}, onSupervisorAlert),
+		}, onSupervisorAlert, onLaneTerminated, onLaneRespawned),
 	);
 
 	// Start monitoring as a sibling async loop
@@ -2577,6 +2579,14 @@ export async function executeLaneV2(
 	isWorkspaceMode?: boolean,
 	extraEnvVars?: Record<string, string>,
 	onSupervisorAlert?: SupervisorAlertCallback,
+	onLaneTerminated?: import("./types.ts").LaneTerminatedCallback,
+	/**
+	 * TP-187 (#538): Optional callback fired BEFORE the first task of this
+	 * lane begins. The supervisor process uses it to lift any zombie-alert
+	 * suppression that was applied when this lane number was previously
+	 * terminated (e.g., in a prior wave).
+	 */
+	onLaneRespawned?: (laneNumber: number, agentId: string, batchId: string) => void,
 ): Promise<LaneExecutionResult> {
 	const laneId = lane.laneId;
 	const laneStartTime = Date.now();
@@ -2618,6 +2628,17 @@ export async function executeLaneV2(
 		agentPrefix: agentIdPrefix,
 	});
 
+	// TP-187 (#538): Lane is freshly starting — emit lane-respawned so any
+	// zombie-alert suppression carried over from a prior wave's termination of
+	// this lane number is lifted before new alerts begin to flow.
+	if (onLaneRespawned) {
+		try {
+			onLaneRespawned(lane.laneNumber, buildRuntimeAgentId(agentIdPrefix, lane.laneNumber, "worker"), batchId);
+		} catch (err) {
+			execLog(laneId, "LANE", `lane-respawned callback failed: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
+
 	for (const task of lane.tasks) {
 		const taskSegmentId = task.task.activeSegmentId ?? null;
 		if (shouldSkipRemaining || pauseSignal.paused) {
@@ -2675,6 +2696,7 @@ export async function executeLaneV2(
 			warnPercent: 85,
 			killPercent: 95,
 			onSupervisorAlert,
+			onLaneTerminated,
 		};
 
 		try {