taskplane 0.28.8 → 0.29.1

package/extensions/taskplane/execution.ts

@@ -8,9 +8,10 @@ import { join, dirname, basename, resolve, relative, delimiter as pathDelimiter
 import { userInfo } from "os";
 
 import { DONE_GRACE_MS, EXECUTION_POLL_INTERVAL_MS, ExecutionError, SESSION_SPAWN_RETRY_MAX } from "./types.ts";
-import type { AllocatedLane, AllocatedTask, DependencyGraph, LaneExecutionResult, LaneMonitorSnapshot, LaneTaskOutcome, LaneTaskStatus, MonitorState, MtimeTracker, OrchestratorConfig, ParsedTask, TaskMonitorSnapshot, WaveExecutionResult, WorkspaceConfig, ExecutionUnit, PacketPaths, RuntimeAgentId, RuntimeAgentRole, SupervisorAlertCallback } from "./types.ts";
+import type { AllocatedLane, AllocatedTask, DependencyGraph, LaneExecutionResult, LaneMonitorSnapshot, LaneTaskOutcome, LaneTaskStatus, MonitorState, MtimeTracker, OrchestratorConfig, ParsedTask, TaskMonitorSnapshot, WaveExecutionResult, WorkspaceConfig, ExecutionUnit, PacketPaths, RuntimeAgentId, RuntimeAgentRole, RuntimeLaneSnapshot, SupervisorAlertCallback } from "./types.ts";
 import { resolvePacketPaths, buildRuntimeAgentId } from "./types.ts";
-import { readRegistrySnapshot, readLaneSnapshot, isTerminalStatus, isProcessAlive, detectOrphans, markOrphansCrashed, buildRegistrySnapshot, writeRegistrySnapshot } from "./process-registry.ts";
+import type { TaskExitDiagnostic } from "./diagnostics.ts";
+import { readRegistrySnapshot, readLaneSnapshot, isTerminalStatus, isProcessAlive, detectOrphans, markOrphansCrashed, buildRegistrySnapshot, writeRegistrySnapshot, writeLaneSnapshot } from "./process-registry.ts";
 import { allocateLanes } from "./waves.ts";
 import { resolveOperatorId } from "./naming.ts";
 import { runGit, runGitWithEnv } from "./git.ts";
@@ -829,18 +830,31 @@ export async function resolveTaskMonitorState(
 			// Assume alive initially, but if stale for >30s consult the registry
 			// to avoid indefinite false "running" if the lane-runner died.
 			const staleMs = snap?.updatedAt ? (now - snap.updatedAt) : 0;
+			const trackerAgeMs = now - tracker.firstObservedAt;
 			if (staleMs > 30_000) {
 				// Snapshot hasn't been updated for 30s+ — check registry as fallback.
 				// But also check if the tracker just started (firstObservedAt within
 				// last 60s) — wave transitions can leave stale snapshots from the
 				// prior wave/task while the new worker is still spawning.
-				const trackerAgeMs = now - tracker.firstObservedAt;
 				if (trackerAgeMs < 60_000) {
 					// New task, stale snapshot — give the worker startup grace period
 					sessionAlive = true;
 				} else {
 					sessionAlive = isV2AgentAlive(sessionName, runtimeBackend, v2Context?.laneNumber);
 				}
+			} else if (snap == null && trackerAgeMs >= 60_000) {
+				// TP-190 (#561 sage post-mortem): when NO snapshot exists at all
+				// (not even stale) and the tracker has been observing this task
+				// for >= 60s, fall back to the registry liveness check. Without
+				// this branch, a snapshot-write failure in the spawn-failure catch
+				// (disk full, permission error, transient I/O hiccup) leaves
+				// `snap == null` AND `staleMs == 0`, which previously hit the
+				// unconditional-alive default below — reintroducing the same
+				// monitor hang the spawn-failure catch was supposed to fix.
+				// 60s tracker-age threshold matches the existing startup-grace
+				// boundary so we don't false-fail a slow-starting worker that
+				// hasn't yet written its first snapshot.
+				sessionAlive = isV2AgentAlive(sessionName, runtimeBackend, v2Context?.laneNumber);
 			} else {
 				sessionAlive = true;
 			}
@@ -1757,6 +1771,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 +1882,7 @@ export async function executeWave(
 			...buildWorkerEnv(workerConfig),
 			...buildReviewerEnv(reviewerConfig),
 			...buildWorkerExcludeEnv(workerExcludeExtensions),
-		}, onSupervisorAlert),
+		}, onSupervisorAlert, onLaneTerminated, onLaneRespawned),
 	);
 
 	// Start monitoring as a sibling async loop
@@ -2577,6 +2593,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 +2642,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 +2710,7 @@ export async function executeLaneV2(
 			warnPercent: 85,
 			killPercent: 95,
 			onSupervisorAlert,
+			onLaneTerminated,
 		};
 
 		try {
@@ -2700,17 +2736,90 @@ export async function executeLaneV2(
 		} catch (err: unknown) {
 			const errMsg = err instanceof Error ? err.message : String(err);
 			execLog(laneId, task.taskId, `Runtime V2 execution error: ${errMsg}`);
+
+			// TP-190 (#561): Spawn-stage failures (Pi CLI not findable, worktree
+			// provisioning failure, etc.) reach this catch synchronously —
+			// `spawnAgent()` calls `resolvePiCliPath()` and other resolvers that
+			// throw before any process is registered. Tag the outcome with the
+			// `spawn_failure` ExitClassification so:
+			//   1. The retry classifier (TIER0_RETRYABLE_CLASSIFICATIONS) excludes
+			//      it deterministically — spawn errors are never transient.
+			//   2. The supervisor `task-failure` IPC alert can carry
+			//      `context.exitCategory = "spawn_failure"` so the playbook can
+			//      escalate immediately rather than retrying.
+			//   3. The engine's post-wave logic can transition `phase` to
+			//      `"failed"` when every lane in a wave spawn-failed.
+			const spawnExitDiagnostic: TaskExitDiagnostic = {
+				classification: "spawn_failure",
+				exitCode: null,
+				errorMessage: errMsg,
+				tokensUsed: null,
+				contextPct: null,
+				partialProgressCommits: 0,
+				partialProgressBranch: null,
+				durationSec: 0,
+				lastKnownStep: null,
+				lastKnownCheckbox: null,
+				repoId: lane.repoId ?? "default",
+			};
+			const workerAgentId = buildRuntimeAgentId(agentIdPrefix, lane.laneNumber, "worker");
 			outcomes.push({
 				taskId: task.taskId,
 				status: "failed",
 				segmentId: taskSegmentId,
 				startTime: Date.now(),
 				endTime: Date.now(),
-				exitReason: `Runtime V2 execution error: ${errMsg}`,
-				sessionName: buildRuntimeAgentId(agentIdPrefix, lane.laneNumber, "worker"),
+				exitReason: `spawn failure: ${errMsg}`,
+				sessionName: workerAgentId,
 				doneFileFound: false,
 				laneNumber: lane.laneNumber,
+				exitDiagnostic: spawnExitDiagnostic,
 			});
+
+			// TP-190 (#561): Write a synthetic terminal lane snapshot so the
+			// monitor (`monitorLanes` → `resolveTaskMonitorState`) reads
+			// `snap.taskId === taskId` AND `snap.status === "failed"`, which sets
+			// `sessionAlive = false` and triggers Priority 3 ("Session exited
+			// without .DONE → failed"). Without this, the monitor's
+			// `snap == null` startup-grace branch keeps `sessionAlive = true`
+			// indefinitely and `executeWave` blocks forever on `await
+			// monitorPromise`. Use the full `RuntimeLaneSnapshot` shape so
+			// dashboard consumers stay schema-consistent.
+			try {
+				const spawnFailureSnapshot: RuntimeLaneSnapshot = {
+					batchId,
+					laneNumber: lane.laneNumber,
+					laneId: `lane-${lane.laneNumber}`,
+					repoId: lane.repoId ?? "default",
+					taskId: task.taskId,
+					segmentId: taskSegmentId,
+					status: "failed",
+					worker: {
+						agentId: workerAgentId,
+						status: "crashed",
+						elapsedMs: 0,
+						toolCalls: 0,
+						contextPct: 0,
+						costUsd: 0,
+						lastTool: "",
+						inputTokens: 0,
+						outputTokens: 0,
+						cacheReadTokens: 0,
+						cacheWriteTokens: 0,
+					},
+					reviewer: null,
+					progress: null,
+					updatedAt: Date.now(),
+				};
+				writeLaneSnapshot(stateRoot, batchId, lane.laneNumber, spawnFailureSnapshot as unknown as Record<string, unknown>);
+			} catch (snapErr) {
+				// Best effort — if the snapshot write fails, the monitor's
+				// 30s-staleness fallback (snap with old updatedAt) eventually
+				// kicks in via the registry liveness check. Log so this is
+				// visible in operator diagnostics, but do NOT throw.
+				execLog(laneId, task.taskId, `spawn-failure snapshot write failed (non-fatal): ${snapErr instanceof Error ? snapErr.message : String(snapErr)}`);
+			}
+
 			shouldSkipRemaining = true;
 		}
 	}

package/extensions/taskplane/extension.ts

@@ -42,6 +42,7 @@ import {
 	checkRateLimit,
 	recordSend,
 	appendMailboxAuditEvent,
+	drainAgentOutbox,
 } from "./mailbox.ts";
 import {
 	readRegistrySnapshot,
@@ -1016,6 +1017,13 @@ export function startBatchInWorker(
 	onMonitorUpdate?: (state: import("./types.ts").MonitorState) => void,
 	onTerminal?: () => void,
 	onSupervisorAlert?: (alert: import("./types.ts").SupervisorAlert) => void,
+	/**
+	 * TP-187 (#538): Lane-terminated and lane-respawned IPC events. The
+	 * supervisor process tracks terminated lanes/agents and uses this to
+	 * suppress zombie alerts from already-dead lanes.
+	 */
+	onLaneTerminated?: (info: import("./types.ts").LaneTerminatedInfo) => void,
+	onLaneRespawned?: (laneNumber: number, agentId: string, batchId: string) => void,
 ): ChildProcess | null {
 	const workerPath = resolveEngineWorkerPath();
 
@@ -1053,6 +1061,8 @@ export function startBatchInWorker(
 				wkData.force ?? false,
 				onSupervisorAlert ?? null,
 				wkData.supervisorAutonomy ?? "autonomous",
+				null, // onLaneTerminated — main-thread fallback path; alerts are local-only
+				null, // onLaneRespawned — main-thread fallback path; suppression maps stay clear
 			)
 			: () => executeOrchBatch(
 				wkData.args ?? "",
@@ -1068,6 +1078,8 @@ export function startBatchInWorker(
 				null, // onEngineEvent
 				onSupervisorAlert ?? null,
 				wkData.supervisorAutonomy ?? "autonomous",
+				null, // onLaneTerminated — main-thread fallback path
+				null, // onLaneRespawned — main-thread fallback path
 			);
 		startBatchAsync(fallbackFn, batchState, ctx, updateWidget, onTerminal);
 		return null;
@@ -1170,6 +1182,15 @@ export function startBatchInWorker(
 				onSupervisorAlert?.(msg.alert);
 				break;
 
+			// TP-187 (#538): Lane termination handling
+			case "lane-terminated":
+				onLaneTerminated?.(msg.info);
+				break;
+
+			case "lane-respawned":
+				onLaneRespawned?.(msg.laneNumber, msg.agentId, msg.batchId);
+				break;
+
 			case "state-sync":
 				applySerializedState(batchState, msg.state);
 				rotateStderrLogToBatch(msg.state.batchId);
@@ -1659,6 +1680,82 @@ export default function (pi: ExtensionAPI) {
 	let supervisorState = freshSupervisorState();
 	let supervisorConfig: SupervisorConfig = { ...DEFAULT_SUPERVISOR_CONFIG };
 
+	// TP-187 (#538): Zombie-alert filter state
+	// Lane numbers and agent IDs that have reached a terminal state (no-progress
+	// kill, hard-fail, or supervisor-takeover). Supervisor-alert IPC messages
+	// whose context targets a terminated lane/agent are dropped before they
+	// reach pi.sendUserMessage so the operator does not see zombie alerts.
+	//
+	// Lifecycle (Step 1 design):
+	//   - Lane reaches terminal state -> add to maps (value = epoch ms)
+	//   - Lane re-spawned for fresh task -> remove from maps
+	//   - orch_resume() called -> clear both maps
+	//   - New batchId observed -> clear both maps
+	//   - supervisor_takeover() invoked -> mark all known active lanes/agents
+	const terminatedLanes = new Map<number, number>();
+	const terminatedAgents = new Map<string, number>();
+
+	const clearTerminationFilter = (reason: string): void => {
+		if (terminatedLanes.size === 0 && terminatedAgents.size === 0) return;
+		process.stderr.write(
+			`[taskplane:zombie-filter] cleared termination filter (reason: ${reason}, ` +
+			`lanes=${terminatedLanes.size}, agents=${terminatedAgents.size})\n`,
+		);
+		terminatedLanes.clear();
+		terminatedAgents.clear();
+	};
+
+	/**
+	 * TP-187 (#538) — sage post-integration follow-up: gate lane-terminated /
+	 * lane-respawned IPC on the current batchId so a stale message from a prior
+	 * batch (engine-worker process not yet shut down, or out-of-order delivery)
+	 * cannot taint the supervisor's terminated-lane filter for the live batch.
+	 * Returns true when the IPC's batchId matches the current batch (or when
+	 * the supervisor has not yet seen any state-sync, in which case we accept
+	 * the IPC — first batch, no risk of staleness).
+	 */
+	const ipcBatchIdMatches = (incomingBatchId: string | undefined): boolean => {
+		// FIX (#559) + sage post-mortem: use `orchBatchState.batchId`, NOT
+		// `batchState.batchId` and NOT `supervisorState.batchId`.
+		//
+		// `batchState` was the original (crashing) reference — NOT bound in
+		// this closure. Other regions of extension.ts legitimately bind a
+		// different `batchState` via destructuring inside their own functions,
+		// but those bindings are not visible here.
+		//
+		// `supervisorState.batchId` (the first attempted fix) is bound but is
+		// only populated when `activateSupervisor()` runs — supervisor activation
+		// is a separate event triggered by alerts/intercepts, not by every batch.
+		// For batches where the supervisor never activates, that field stays
+		// empty for the entire batch and the gate never fires (everything passes
+		// the empty-string accept-all branch), defeating the zombie-alert filter.
+		//
+		// `orchBatchState.batchId` is the canonical live runtime batch ID for
+		// the extension closure: declared on line 1669, populated by the same
+		// state-sync IPC that the supervisor reads from, and reliably present
+		// from the moment the engine-worker emits its first state-sync frame
+		// onward. The only window where it is `""` is the legitimate gap
+		// between batch launch and first state-sync — pre-planning, before any
+		// terminated-lane IPC could fire.
+		const currentBatchId = orchBatchState.batchId;
+		if (!currentBatchId) return true; // no live batch yet — accept
+		if (!incomingBatchId) return true; // legacy IPC without batchId — accept (back-compat)
+		return incomingBatchId === currentBatchId;
+	};
+
+	/**
+	 * TP-187 (#538): True iff this alert targets a lane or agent that has
+	 * already been marked terminal. Used by the supervisor-alert IPC handler
+	 * to drop zombie alerts before they reach pi.sendUserMessage.
+	 */
+	const isAlertSuppressed = (alert: import("./types.ts").SupervisorAlert): boolean => {
+		const ctx = alert.context;
+		if (!ctx) return false;
+		if (typeof ctx.laneNumber === "number" && terminatedLanes.has(ctx.laneNumber)) return true;
+		if (typeof ctx.agentId === "string" && ctx.agentId && terminatedAgents.has(ctx.agentId)) return true;
+		return false;
+	};
+
 	// Register supervisor prompt hook: while active, injects supervisor
 	// system prompt on every LLM turn. No-op when supervisor is inactive.
 	registerSupervisorPromptHook(pi, supervisorState);
@@ -2095,6 +2192,9 @@ export default function (pi: ExtensionAPI) {
 		orchBatchState = freshOrchBatchState();
 		latestMonitorState = null;
 
+		// TP-187 (#538): Clear zombie-alert filter for the new batch.
+		clearTerminationFilter("new_batch_started");
+
 		orchBatchState.phase = "launching";
 		orchBatchState.startedAt = Date.now();
 		updateOrchWidget();
@@ -2205,8 +2305,44 @@ export default function (pi: ExtensionAPI) {
 			// ── TP-076: Supervisor alert handler — injects alerts as user messages ──
 			(alert) => {
 				if (!supervisorState.active) return; // Don't send orphaned messages
+				// TP-187 (#538): Drop zombie alerts for already-terminated lanes/agents.
+				if (isAlertSuppressed(alert)) {
+					process.stderr.write(
+						`[taskplane:zombie-filter] dropped alert (category=${alert.category}, ` +
+						`lane=${alert.context?.laneNumber ?? "?"}, agent=${alert.context?.agentId ?? "?"})\n`,
+					);
+					return;
+				}
 				pi.sendUserMessage(alert.summary, { deliverAs: "followUp" });
 			},
+			// TP-187 (#538): Lane-terminated handler.
+			(info) => {
+				if (!ipcBatchIdMatches(info.batchId)) {
+					process.stderr.write(
+						`[taskplane:zombie-filter] ignored stale lane-terminated IPC ` +
+						`(incoming batchId=${info.batchId}, current=${orchBatchState.batchId})\n`,
+					);
+					return;
+				}
+				terminatedLanes.set(info.laneNumber, info.terminatedAt);
+				if (info.agentId) terminatedAgents.set(info.agentId, info.terminatedAt);
+				process.stderr.write(
+					`[taskplane:zombie-filter] lane ${info.laneNumber} (${info.agentId}) terminated ` +
+					`(reason: ${info.reason}); ${terminatedLanes.size} lane(s) suppressed\n`,
+				);
+			},
+			// TP-187 (#538): Lane-respawned handler.
+			(laneNumber, agentId, incomingBatchId) => {
+				if (!ipcBatchIdMatches(incomingBatchId)) {
+					process.stderr.write(
+						`[taskplane:zombie-filter] ignored stale lane-respawned IPC ` +
+						`(incoming batchId=${incomingBatchId}, current=${orchBatchState.batchId})\n`,
+					);
+					return;
+				}
+				terminatedLanes.delete(laneNumber);
+				if (agentId) terminatedAgents.delete(agentId);
+			},
 		);
 
 		// Activate supervisor agent
@@ -2439,6 +2575,9 @@ export default function (pi: ExtensionAPI) {
 		orchBatchState = freshOrchBatchState();
 		latestMonitorState = null;
 
+		// TP-187 (#538): Clear zombie-alert filter so post-resume alerts pass through.
+		clearTerminationFilter("orch_resume_called");
+
 		orchBatchState.phase = "launching";
 		orchBatchState.startedAt = Date.now();
 		updateOrchWidget();
@@ -2542,8 +2681,44 @@ export default function (pi: ExtensionAPI) {
 			// ── TP-076: Supervisor alert handler — injects alerts as user messages ──
 			(alert) => {
 				if (!supervisorState.active) return; // Don't send orphaned messages
+				// TP-187 (#538): Drop zombie alerts for already-terminated lanes/agents.
+				if (isAlertSuppressed(alert)) {
+					process.stderr.write(
+						`[taskplane:zombie-filter] dropped alert (category=${alert.category}, ` +
+						`lane=${alert.context?.laneNumber ?? "?"}, agent=${alert.context?.agentId ?? "?"})\n`,
+					);
+					return;
+				}
 				pi.sendUserMessage(alert.summary, { deliverAs: "followUp" });
 			},
+			// TP-187 (#538): Lane-terminated handler.
+			(info) => {
+				if (!ipcBatchIdMatches(info.batchId)) {
+					process.stderr.write(
+						`[taskplane:zombie-filter] ignored stale lane-terminated IPC ` +
+						`(incoming batchId=${info.batchId}, current=${orchBatchState.batchId})\n`,
+					);
+					return;
+				}
+				terminatedLanes.set(info.laneNumber, info.terminatedAt);
+				if (info.agentId) terminatedAgents.set(info.agentId, info.terminatedAt);
+				process.stderr.write(
+					`[taskplane:zombie-filter] lane ${info.laneNumber} (${info.agentId}) terminated ` +
+					`(reason: ${info.reason}); ${terminatedLanes.size} lane(s) suppressed\n`,
+				);
+			},
+			// TP-187 (#538): Lane-respawned handler.
+			(laneNumber, agentId, incomingBatchId) => {
+				if (!ipcBatchIdMatches(incomingBatchId)) {
+					process.stderr.write(
+						`[taskplane:zombie-filter] ignored stale lane-respawned IPC ` +
+						`(incoming batchId=${incomingBatchId}, current=${orchBatchState.batchId})\n`,
+					);
+					return;
+				}
+				terminatedLanes.delete(laneNumber);
+				if (agentId) terminatedAgents.delete(agentId);
+			},
 		);
 
 		// Activate supervisor agent on resume
@@ -2676,6 +2851,91 @@ export default function (pi: ExtensionAPI) {
 
 	// ── TP-077: Supervisor Recovery Tools ────────────────────────────
 
+	/**
+	 * Core logic for `supervisor_takeover(reason)`. Pauses the running wave,
+	 * drains all per-agent on-disk outboxes for the current batch, and marks
+	 * every active lane as terminated so any in-transit zombie alerts are
+	 * suppressed. Distinct from `orch_abort`:
+	 *   - `orch_abort` kills sessions and deletes batch state (destructive).
+	 *   - `supervisor_takeover` pauses + drains + parks; worktrees, branches,
+	 *     state, and sessions all remain so the operator can recover manually.
+	 *
+	 * @since TP-187 (#538)
+	 */
+	function doSupervisorTakeover(reason: string): string {
+		const messages: string[] = [];
+		const trimmedReason = (reason ?? "").trim() || "(no reason provided)";
+		messages.push(`🛡️ Supervisor takeover requested: ${trimmedReason}`);
+
+		// 1. Pause the wave (mirror orch_pause logic but tolerate non-active phases).
+		const pausablePhases = new Set(["launching", "executing", "merging", "planning"]);
+		if (pausablePhases.has(orchBatchState.phase)) {
+			orchBatchState.pauseSignal.paused = true;
+			activeWorker?.send({ type: "pause" });
+			messages.push(`  ✓ Wave paused (batch ${orchBatchState.batchId})`);
+		} else {
+			messages.push(`  — Batch phase is \`${orchBatchState.phase}\`; no active wave to pause`);
+		}
+
+		// 2. Drain on-disk outboxes for every known agent in the current batch.
+		const stateRoot = execCtx?.workspaceRoot ?? execCtx?.repoRoot;
+		let drainedAgents = 0;
+		let drainedMessages = 0;
+		if (stateRoot && orchBatchState.batchId) {
+			try {
+				const agentIds = discoverMailboxAgentIds(stateRoot, orchBatchState.batchId);
+				for (const agentId of agentIds) {
+					try {
+						const n = drainAgentOutbox(stateRoot, orchBatchState.batchId, agentId);
+						if (n > 0) {
+							drainedAgents++;
+							drainedMessages += n;
+						}
+					} catch { /* per-agent drain best-effort */ }
+				}
+				messages.push(
+					`  ✓ Drained on-disk outboxes (${drainedMessages} message(s) across ${drainedAgents} agent(s))`,
+				);
+			} catch (err) {
+				messages.push(
+					`  ⚠ Drain failed: ${err instanceof Error ? err.message : String(err)}`,
+				);
+			}
+		} else {
+			messages.push("  — No active batch state; outbox drain skipped");
+		}
+
+		// 3. Mark all currently-known active lanes/agents as terminated so any
+		// in-transit zombie alerts get filtered. The maps are kept until the next
+		// `orch_resume` (or new batch) per the Step 1 lifecycle.
+		const takeoverTs = Date.now();
+		let markedLanes = 0;
+		for (const lane of orchBatchState.currentLanes ?? []) {
+			terminatedLanes.set(lane.laneNumber, takeoverTs);
+			if (lane.laneSessionId) {
+				terminatedAgents.set(lane.laneSessionId, takeoverTs);
+				terminatedAgents.set(`${lane.laneSessionId}-worker`, takeoverTs);
+				terminatedAgents.set(`${lane.laneSessionId}-reviewer`, takeoverTs);
+			}
+			markedLanes++;
+		}
+		messages.push(
+			`  ✓ Suppressed alerts for ${markedLanes} lane(s) (lifted on next \`orch_resume\`)`,
+		);
+
+		// 4. Worktrees, branches, state, sessions are intentionally NOT touched.
+		messages.push("  ✓ Worktrees, branches, batch state, and sessions preserved");
+
+		messages.push("");
+		messages.push("Recommended next steps:");
+		messages.push("  • `orch_status()` to inspect current state");
+		messages.push("  • `orch_resume(force=true)` to re-engage the batch (clears alert suppression)");
+		messages.push("  • `orch_abort()` if escalation to destructive shutdown is required");
+
+		updateOrchWidget();
+		return messages.join("\n");
+	}
+
 	/**
 	 * Core logic for orch_retry_task. Resets a failed task to pending for re-execution.
 	 *
@@ -3801,6 +4061,49 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	// TP-187 (#538): supervisor_takeover — pause + drain + park (non-destructive).
+	pi.registerTool({
+		name: "supervisor_takeover",
+		label: "Supervisor Takeover",
+		description:
+			"Take manual control of a misbehaving batch without destroying state. " +
+			"Pauses the running wave, drains all per-agent on-disk outboxes, and " +
+			"suppresses any in-transit alerts from already-running lanes so they " +
+			"do not land in your queue as zombie alerts. Worktrees, branches, " +
+			"batch state, and sessions are all preserved — distinct from " +
+			"`orch_abort` which kills sessions and deletes state. Use " +
+			"`orch_resume(force=true)` afterward to re-engage the batch (the " +
+			"alert suppression is lifted automatically on resume).",
+		promptSnippet: "supervisor_takeover(reason) — pause + drain + park for manual recovery",
+		promptGuidelines: [
+			"Call supervisor_takeover when the batch is producing alert spam, " +
+				"hitting a death-spiral pattern, or you need to investigate without " +
+				"continuing execution.",
+			"This is the non-destructive escape hatch. Prefer this over orch_abort " +
+				"when you may want to resume the same batch later.",
+			"Always include a clear `reason` describing what triggered the takeover " +
+				"— it is logged for audit.",
+			"After takeover, call orch_status() to inspect, then either " +
+				"orch_resume(force=true) to continue or orch_abort() to escalate.",
+		],
+		parameters: Type.Object({
+			reason: Type.String({
+				description: "Why takeover is being requested (logged for audit; required).",
+			}),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			try {
+				const result = doSupervisorTakeover(params.reason ?? "");
+				return { content: [{ type: "text" as const, text: result }], details: undefined };
+			} catch (err) {
+				return {
+					content: [{ type: "text" as const, text: `Error during supervisor takeover: ${err instanceof Error ? err.message : String(err)}` }],
+					details: undefined,
+				};
+			}
+		},
+	});
+
 	pi.registerTool({
 		name: "orch_integrate",
 		label: "Integrate Batch",