taskplane 0.21.10 → 0.22.0

package/extensions/taskplane/engine-worker.ts

@@ -21,6 +21,7 @@ import type {
 	OrchBatchPhase,
 	OrchBatchRuntimeState,
 	OrchestratorConfig,
+	SupervisorAlert,
 	TaskRunnerConfig,
 	WorkspaceConfig,
 	WorkspaceRepoConfig,
@@ -35,6 +36,7 @@ export type WorkerToMainMessage =
 	| { type: "notify"; msg: string; level: "info" | "warning" | "error" }
 	| { type: "monitor-update"; state: MonitorState }
 	| { type: "engine-event"; event: EngineEvent }
+	| { type: "supervisor-alert"; alert: SupervisorAlert }
 	| { type: "state-sync"; state: SerializedBatchState }
 	| { type: "complete"; state: SerializedBatchState }
 	| { type: "error"; message: string };
@@ -246,6 +248,11 @@ if (process.env.TASKPLANE_ENGINE_FORK === "1" && typeof process.send === "functi
 			send({ type: "engine-event", event });
 		};
 
+		// TP-076: Supervisor alert callback — sends structured alerts to main thread
+		const onSupervisorAlert = (alert: import("./types.ts").SupervisorAlert) => {
+			send({ type: "supervisor-alert", alert });
+		};
+
 		// ── Execute engine ───────────────────────────────────────────
 		const enginePromise = data.mode === "resume"
 			? resumeOrchBatch(
@@ -259,6 +266,7 @@ if (process.env.TASKPLANE_ENGINE_FORK === "1" && typeof process.send === "functi
 				data.workspaceRoot,
 				data.agentRoot,
 				data.force ?? false,
+				onSupervisorAlert,
 			)
 			: executeOrchBatch(
 				data.args ?? "",
@@ -272,6 +280,7 @@ if (process.env.TASKPLANE_ENGINE_FORK === "1" && typeof process.send === "functi
 				data.workspaceRoot,
 				data.agentRoot,
 				onEngineEvent,
+				onSupervisorAlert,
 			);
 
 		enginePromise

package/extensions/taskplane/engine.ts

@@ -18,8 +18,8 @@ import { assembleDiagnosticInput, emitDiagnosticReports } from "./diagnostic-rep
 import { resolveOperatorId } from "./naming.ts";
 import { applyPartialProgressToOutcomes, buildTier0EventBase, deleteBatchState, emitEngineEvent, emitTier0Event, loadBatchHistory, loadBatchState, persistRuntimeState, saveBatchHistory, seedPendingOutcomesForAllocatedLanes, syncTaskOutcomesFromMonitor, upsertTaskOutcome } from "./persistence.ts";
 import { listOrchSessions } from "./sessions.ts";
-import { buildEngineEventBase, 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, TaskRunnerConfig, Tier0EscalationPattern, Tier0RecoveryPattern, TokenCounts, WaveExecutionResult, WorkspaceConfig } from "./types.ts";
+import { buildBatchProgressSnapshot, buildEngineEventBase, 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, SupervisorAlert, SupervisorAlertCallback, TaskRunnerConfig, Tier0EscalationPattern, Tier0RecoveryPattern, TokenCounts, WaveExecutionResult, WorkspaceConfig } from "./types.ts";
 import { buildDependencyGraph, computeWaves, resolveBaseBranch, resolveRepoRoot, validateGraph } from "./waves.ts";
 import { deleteBranchBestEffort, forceCleanupWorktree, formatPreflightResults, listWorktrees, preserveFailedLaneProgress, removeAllWorktrees, removeWorktree, runPreflight, safeResetWorktree, sleepSync } from "./worktree.ts";
 import { runPreflightCleanup, formatPreflightCleanup } from "./cleanup.ts";
@@ -744,6 +744,7 @@ async function attemptStaleWorktreeRecovery(
  * @param workspaceRoot - Workspace root for resolving task area paths (defaults to cwd)
  * @param agentRoot   - Agent root for config resolution
  * @param onEngineEvent - Optional callback for engine lifecycle events (TP-040)
+ * @param onSupervisorAlert - Optional callback for supervisor alerts (TP-076)
  */
 export async function executeOrchBatch(
 	args: string,
@@ -757,6 +758,7 @@ export async function executeOrchBatch(
 	workspaceRoot?: string,
 	agentRoot?: string,
 	onEngineEvent?: EngineEventCallback | null,
+	onSupervisorAlert?: SupervisorAlertCallback | null,
 ): Promise<void> {
 	const repoRoot = cwd;
 	// State files (.pi/batch-state.json, lane-state, etc.) belong in the workspace root,
@@ -768,6 +770,21 @@ export async function executeOrchBatch(
 	// batchState.batchId is read at call time (it's set in Phase 1).
 	const emitEvent: typeof emitEngineEvent = (sr, event, cb) => emitEngineEvent(sr, event, cb);
 
+	// ── TP-076: Supervisor alert emission helper ─────────────────
+	// Wraps the optional callback with a null guard for terse call sites.
+	const emitAlert = (alert: SupervisorAlert): void => {
+		if (onSupervisorAlert) {
+			try {
+				onSupervisorAlert(alert);
+			} catch (err: unknown) {
+				const msg = err instanceof Error ? err.message : String(err);
+				execLog("batch", batchState.batchId, `supervisor alert callback failed: ${msg}`, {
+					alertCategory: alert.category,
+				});
+			}
+		}
+	};
+
 	// ── 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
@@ -1309,6 +1326,34 @@ export async function executeOrchBatch(
 				reason: outcome?.exitReason || "unknown",
 				partialProgress: (outcome?.partialProgressCommits ?? 0) > 0,
 			}, onEngineEvent);
+
+			// ── TP-076: Emit supervisor alert for task failure ──────
+			const laneForTask = latestAllocatedLanes.find(l => l.tasks.some(t => t.taskId === taskId));
+			const exitReason = outcome?.exitReason || "unknown";
+			const hasPartialProgress = (outcome?.partialProgressCommits ?? 0) > 0;
+			emitAlert({
+				category: "task-failure",
+				summary:
+					`⚠️ Task failure: ${taskId}\n` +
+					`  Exit reason: ${exitReason}\n` +
+					`  Lane: ${laneForTask?.laneId ?? "unknown"} (lane ${laneForTask?.laneNumber ?? "?"})\n` +
+					`  Partial progress preserved: ${hasPartialProgress ? "yes" : "no"}\n` +
+					`  Batch: wave ${waveIdx + 1}/${batchState.totalWaves}, ` +
+					`${batchState.succeededTasks} succeeded, ${batchState.failedTasks} failed\n\n` +
+					`Available actions:\n` +
+					`  - orch_status() to inspect current state\n` +
+					`  - orch_resume(force=true) to retry\n` +
+					`  - Read STATUS.md and lane logs for diagnosis`,
+				context: {
+					taskId,
+					laneId: laneForTask?.laneId,
+					laneNumber: laneForTask?.laneNumber,
+					waveIndex: waveIdx,
+					exitReason,
+					partialProgress: hasPartialProgress,
+					batchProgress: buildBatchProgressSnapshot(batchState),
+				},
+			});
 		}
 
 		// ── TS-009: Persist state after wave execution ──
@@ -1575,6 +1620,27 @@ export async function executeOrchBatch(
 				persistWarning,
 				"error",
 			);
+
+			// ── TP-076: Emit supervisor alert for rollback safe-stop ──
+			const rollbackError = `Safe-stop at wave ${waveIdx + 1}: verification rollback failed.${persistWarning}`;
+			emitAlert({
+				category: "merge-failure",
+				summary:
+					`⚠️ Merge failed for wave ${waveIdx + 1} — verification rollback failed\n` +
+					`  Batch force-paused for manual recovery.\n` +
+					`  ${persistWarning ? persistWarning.trim() : "Check .pi/verification/ for recovery commands."}\n\n` +
+					`Available actions:\n` +
+					`  - Check .pi/verification/ transaction records for recovery commands\n` +
+					`  - orch_status() to inspect current state\n` +
+					`  - orch_resume(force=true) after manual recovery`,
+				context: {
+					waveIndex: waveIdx,
+					laneNumber: mergeResult.failedLane ?? undefined,
+					mergeError: rollbackError,
+					batchProgress: buildBatchProgressSnapshot(batchState),
+				},
+			});
+
 			preserveWorktreesForResume = true;
 			break;
 		}
@@ -1660,6 +1726,26 @@ export async function executeOrchBatch(
 				persistRuntimeState("merge-rollback-safe-stop", batchState, wavePlan, latestAllocatedLanes, allTaskOutcomes, discoveryRef, stateRoot);
 				onNotify(retryOutcome.notifyMessage, "error");
 
+				// ── TP-076: Emit supervisor alert for merge safe-stop ──
+				emitAlert({
+					category: "merge-failure",
+					summary:
+						`⚠️ Merge failed for wave ${waveIdx + 1} — rollback failure, batch force-paused\n` +
+						`  Merge policy: safe-stop (rollback failed)\n` +
+						`  Failed lane: ${mergeResult.failedLane ?? "unknown"}\n` +
+						`  Error: ${retryOutcome.errorMessage}\n\n` +
+						`Available actions:\n` +
+						`  - Investigate failed merge, check .pi/verification/ for recovery commands\n` +
+						`  - orch_status() to inspect current state\n` +
+						`  - orch_resume(force=true) after manual recovery`,
+					context: {
+						waveIndex: waveIdx,
+						laneNumber: mergeResult.failedLane ?? undefined,
+						mergeError: retryOutcome.errorMessage,
+						batchProgress: buildBatchProgressSnapshot(batchState),
+					},
+				});
+
 				// Emit merge safe-stop event (treated as exhausted — no further automatic recovery possible)
 				const mergeSafeStopSuggestion = "Merge rollback failed — batch force-paused for manual recovery. Check .pi/verification/ for recovery commands.";
 				emitTier0Event(stateRoot, {
@@ -1714,6 +1800,28 @@ export async function executeOrchBatch(
 				batchState.errors.push(exhaustionMsg);
 				persistRuntimeState("merge-retry-exhausted", batchState, wavePlan, latestAllocatedLanes, allTaskOutcomes, discoveryRef, stateRoot);
 				onNotify(retryOutcome.notifyMessage, "error");
+
+				// ── TP-076: Emit supervisor alert for merge retry exhausted ──
+				emitAlert({
+					category: "merge-failure",
+					summary:
+						`⚠️ Merge failed for wave ${waveIdx + 1} — retry exhausted\n` +
+						`  Classification: ${retryOutcome.classification ?? "unknown"}\n` +
+						`  Attempts: ${retryOutcome.lastDecision.currentAttempt}/${retryOutcome.lastDecision.maxAttempts}\n` +
+						`  Failed lane: ${mergeResult.failedLane ?? "unknown"}\n` +
+						`  Error: ${exhaustionMsg}\n\n` +
+						`Available actions:\n` +
+						`  - Investigate merge failure and retry manually\n` +
+						`  - orch_status() to inspect current state\n` +
+						`  - orch_resume(force=true) after fixing the issue`,
+					context: {
+						waveIndex: waveIdx,
+						laneNumber: mergeResult.failedLane ?? undefined,
+						mergeError: exhaustionMsg,
+						batchProgress: buildBatchProgressSnapshot(batchState),
+					},
+				});
+
 				preserveWorktreesForResume = true;
 				break;
 			} else {
@@ -1730,6 +1838,27 @@ export async function executeOrchBatch(
 				batchState.errors.push(policyResult.errorMessage + classNote);
 				persistRuntimeState(policyResult.persistTrigger, batchState, wavePlan, latestAllocatedLanes, allTaskOutcomes, discoveryRef, stateRoot);
 				onNotify(policyResult.notifyMessage + classNote, policyResult.notifyLevel);
+
+				// ── TP-076: Emit supervisor alert for merge failure (no-retry policy) ──
+				emitAlert({
+					category: "merge-failure",
+					summary:
+						`⚠️ Merge failed for wave ${waveIdx + 1}\n` +
+						`  Policy: ${policyResult.policy}${classNote}\n` +
+						`  Failed lane: ${mergeResult.failedLane ?? "unknown"}\n` +
+						`  Error: ${mergeResult.failureReason || "unknown"}\n\n` +
+						`Available actions:\n` +
+						`  - Investigate failed merge\n` +
+						`  - orch_status() to inspect current state\n` +
+						`  - orch_resume(force=true) after fixing the issue`,
+					context: {
+						waveIndex: waveIdx,
+						laneNumber: mergeResult.failedLane ?? undefined,
+						mergeError: mergeResult.failureReason || "unknown",
+						batchProgress: buildBatchProgressSnapshot(batchState),
+					},
+				});
+
 				// DO NOT cleanup/reset worktrees — preserve state for debugging/resume
 				preserveWorktreesForResume = true;
 				break;
@@ -2390,6 +2519,46 @@ export async function executeOrchBatch(
 	// ── TS-009: Persist terminal state ──
 	persistRuntimeState("batch-terminal", batchState, wavePlan, latestAllocatedLanes, allTaskOutcomes, discoveryRef, stateRoot);
 
+	// ── TP-076: Emit supervisor alert for batch completion ──────
+	if (batchState.phase === "completed" || batchState.phase === "failed") {
+		const batchDurationMs = batchState.endedAt ? batchState.endedAt - batchState.startedAt : 0;
+		const durationStr = batchDurationMs > 0
+			? `${Math.floor(batchDurationMs / 60000)}m ${Math.round((batchDurationMs % 60000) / 1000)}s`
+			: "unknown";
+		if (batchState.phase === "completed" && batchState.failedTasks === 0) {
+			emitAlert({
+				category: "batch-complete",
+				summary:
+					`✅ Batch ${batchState.batchId} completed\n` +
+					`  ${batchState.succeededTasks}/${batchState.totalTasks} tasks succeeded\n` +
+					`  ${batchState.totalWaves} wave(s), duration: ${durationStr}\n` +
+					`  Merged to orch branch: ${batchState.orchBranch}\n\n` +
+					`Ready for integration. Run orch_integrate() or review first.`,
+				context: {
+					batchProgress: buildBatchProgressSnapshot(batchState),
+					batchDurationMs,
+				},
+			});
+		} else {
+			emitAlert({
+				category: "batch-complete",
+				summary:
+					`⚠️ Batch ${batchState.batchId} finished with failures\n` +
+					`  ${batchState.succeededTasks} succeeded, ${batchState.failedTasks} failed, ` +
+					`${batchState.skippedTasks} skipped, ${batchState.blockedTasks} blocked\n` +
+					`  Duration: ${durationStr}\n\n` +
+					`Available actions:\n` +
+					`  - orch_status() to review final state\n` +
+					`  - orch_integrate() if succeeded work should be kept\n` +
+					`  - orch_resume(force=true) to retry failed tasks`,
+				context: {
+					batchProgress: buildBatchProgressSnapshot(batchState),
+					batchDurationMs,
+				},
+			});
+		}
+	}
+
 	// ── TP-040: Emit batch terminal event (R002: unified via helper) ─
 	emitTerminalEvent();
 

package/extensions/taskplane/extension.ts

@@ -935,6 +935,7 @@ export function startBatchInWorker(
 	updateWidget: () => void,
 	onMonitorUpdate?: (state: import("./types.ts").MonitorState) => void,
 	onTerminal?: () => void,
+	onSupervisorAlert?: (alert: import("./types.ts").SupervisorAlert) => void,
 ): ChildProcess | null {
 	const workerPath = resolveEngineWorkerPath();
 
@@ -1011,6 +1012,11 @@ export function startBatchInWorker(
 			case "engine-event":
 				break;
 
+			// ── TP-076: Supervisor alert handling ────────────────
+			case "supervisor-alert":
+				onSupervisorAlert?.(msg.alert);
+				break;
+
 			case "state-sync":
 				applySerializedState(batchState, msg.state);
 				updateWidget();
@@ -1050,6 +1056,28 @@ export function startBatchInWorker(
 			"error",
 		);
 		updateWidget();
+		// ── TP-076: Alert supervisor about engine process error ──
+		onSupervisorAlert?.({
+			category: "task-failure",
+			summary:
+				`🔴 Engine process error — batch ${batchState.batchId} marked as failed\n` +
+				`  Error: ${err.message}\n\n` +
+				`This is a critical engine failure. The batch cannot continue.\n` +
+				`Available actions:\n` +
+				`  - orch_status() to inspect state\n` +
+				`  - orch_resume(force=true) to retry from last checkpoint`,
+			context: {
+				batchProgress: batchState.totalTasks > 0 ? {
+					succeededTasks: batchState.succeededTasks,
+					failedTasks: batchState.failedTasks,
+					skippedTasks: batchState.skippedTasks,
+					blockedTasks: batchState.blockedTasks,
+					totalTasks: batchState.totalTasks,
+					currentWave: batchState.currentWaveIndex + 1,
+					totalWaves: batchState.totalWaves,
+				} : undefined,
+			},
+		});
 		settle();
 	});
 
@@ -1065,6 +1093,28 @@ export function startBatchInWorker(
 				"error",
 			);
 			updateWidget();
+			// ── TP-076: Alert supervisor about unexpected engine exit ──
+			onSupervisorAlert?.({
+				category: "task-failure",
+				summary:
+					`🔴 Engine process died unexpectedly (exit code ${code})\n` +
+					`  Batch ${batchState.batchId} marked as failed.\n\n` +
+					`This is a critical engine failure. The batch cannot continue.\n` +
+					`Available actions:\n` +
+					`  - orch_status() to inspect state\n` +
+					`  - orch_resume(force=true) to retry from last checkpoint`,
+				context: {
+					batchProgress: batchState.totalTasks > 0 ? {
+						succeededTasks: batchState.succeededTasks,
+						failedTasks: batchState.failedTasks,
+						skippedTasks: batchState.skippedTasks,
+						blockedTasks: batchState.blockedTasks,
+						totalTasks: batchState.totalTasks,
+						currentWave: batchState.currentWaveIndex + 1,
+						totalWaves: batchState.totalWaves,
+					} : undefined,
+				},
+			});
 		}
 		settle();
 	});
@@ -1893,33 +1943,11 @@ export default function (pi: ExtensionAPI) {
 					};
 				transitionToRoutingMode(pi, supervisorState, postBatchContext);
 			},
-			// Fallback: run engine on main thread if worker spawn fails (R001 §1)
-			() => executeOrchBatch(
-				trimmedTarget,
-				orchConfig,
-				runnerConfig,
-				repoRoot,
-				orchBatchState,
-				(message, level) => {
-					ctx.ui.notify(message, level);
-					updateOrchWidget();
-				},
-				(monState: MonitorState) => {
-					const changed = !latestMonitorState ||
-						latestMonitorState.totalDone !== monState.totalDone ||
-						latestMonitorState.totalFailed !== monState.totalFailed ||
-						latestMonitorState.lanes.some((l, i) =>
-							l.currentTaskId !== monState.lanes[i]?.currentTaskId ||
-							l.currentStep !== monState.lanes[i]?.currentStep ||
-							l.completedChecks !== monState.lanes[i]?.completedChecks,
-						);
-					latestMonitorState = monState;
-					if (changed) updateOrchWidget();
-				},
-				execCtx!.workspaceConfig,
-				execCtx!.workspaceRoot,
-				execCtx!.pointer?.agentRoot,
-			),
+			// ── TP-076: Supervisor alert handler — injects alerts as user messages ──
+			(alert) => {
+				if (!supervisorState.active) return; // Don't send orphaned messages
+				ctx.sendUserMessage(alert.summary, { deliverAs: "followUp" });
+			},
 		);
 
 		// Activate supervisor agent
@@ -2135,25 +2163,11 @@ export default function (pi: ExtensionAPI) {
 					};
 				transitionToRoutingMode(pi, supervisorState, postBatchContext);
 			},
-			// Fallback: run resume on main thread if worker spawn fails (R001 §1)
-			() => resumeOrchBatch(
-				orchConfig,
-				runnerConfig,
-				execCtx!.repoRoot,
-				orchBatchState,
-				(message, level) => {
-					ctx.ui.notify(message, level);
-					updateOrchWidget();
-				},
-				(monState: MonitorState) => {
-					latestMonitorState = monState;
-					updateOrchWidget();
-				},
-				execCtx!.workspaceConfig,
-				execCtx!.workspaceRoot,
-				execCtx!.pointer?.agentRoot,
-				force,
-			),
+			// ── TP-076: Supervisor alert handler — injects alerts as user messages ──
+			(alert) => {
+				if (!supervisorState.active) return; // Don't send orphaned messages
+				ctx.sendUserMessage(alert.summary, { deliverAs: "followUp" });
+			},
 		);
 
 		// Activate supervisor agent on resume

package/extensions/taskplane/resume.ts

@@ -16,7 +16,7 @@ import { applyMergeRetryLoop, computeCleanupGatePolicy, computeMergeFailurePolic
 import type { CleanupGateRepoFailure } from "./messages.ts";
 import { resolveOperatorId } from "./naming.ts";
 import { applyPartialProgressToOutcomes, deleteBatchState, hasTaskDoneMarker, loadBatchState, persistRuntimeState, seedPendingOutcomesForAllocatedLanes, syncTaskOutcomesFromMonitor, upsertTaskOutcome } from "./persistence.ts";
-import { defaultResilienceState, StateFileError } from "./types.ts";
+import { buildBatchProgressSnapshot, defaultResilienceState, StateFileError } from "./types.ts";
 import type { AllocatedLane, AllocatedTask, LaneExecutionResult, LaneTaskOutcome, LaneTaskStatus, MergeWaveResult, OrchBatchPhase, OrchBatchRuntimeState, OrchestratorConfig, ParsedTask, PersistedBatchState, PersistedLaneRecord, ReconciledTaskState, ResumeEligibility, ResumePoint, TaskRunnerConfig, WaveExecutionResult, WorkspaceConfig } from "./types.ts";
 import { buildDependencyGraph, resolveBaseBranch, resolveRepoRoot } from "./waves.ts";
 import { deleteBranchBestEffort, forceCleanupWorktree, listWorktrees, preserveFailedLaneProgress, removeAllWorktrees, removeWorktree, safeResetWorktree, sleepSync } from "./worktree.ts";
@@ -749,6 +749,7 @@ export async function resumeOrchBatch(
 	workspaceRoot?: string,
 	agentRoot?: string,
 	force: boolean = false,
+	onSupervisorAlert?: import("./types.ts").SupervisorAlertCallback | null,
 ): Promise<void> {
 	const repoRoot = cwd;
 	// State files (.pi/batch-state.json, lane-state, etc.) belong in the workspace root,
@@ -756,6 +757,20 @@ export async function resumeOrchBatch(
 	const stateRoot = workspaceRoot ?? cwd;
 	const prefix = orchConfig.orchestrator.tmux_prefix;
 
+	// ── TP-076: Supervisor alert emission helper ─────────────────
+	const emitAlert = (alert: import("./types.ts").SupervisorAlert): void => {
+		if (onSupervisorAlert) {
+			try {
+				onSupervisorAlert(alert);
+			} catch (err: unknown) {
+				const msg = err instanceof Error ? err.message : String(err);
+				execLog("resume", "unknown", `supervisor alert callback failed: ${msg}`, {
+					alertCategory: alert.category,
+				});
+			}
+		}
+	};
+
 	// ── 1. Load persisted state ──────────────────────────────────
 	let persistedState: PersistedBatchState | null;
 	try {
@@ -1569,6 +1584,37 @@ export async function resumeOrchBatch(
 			batchState.blockedTaskIds.add(blocked);
 		}
 
+		// ── TP-076: Emit supervisor alerts for task failures ────
+		for (const taskId of waveResult.failedTaskIds) {
+			const outcome = allTaskOutcomes.find(o => o.taskId === taskId);
+			const laneForTask = latestAllocatedLanes.find(l => l.tasks.some(t => t.taskId === taskId));
+			const exitReason = outcome?.exitReason || "unknown";
+			const hasPartialProgress = (outcome?.partialProgressCommits ?? 0) > 0;
+			emitAlert({
+				category: "task-failure",
+				summary:
+					`⚠️ Task failure: ${taskId}\n` +
+					`  Exit reason: ${exitReason}\n` +
+					`  Lane: ${laneForTask?.laneId ?? "unknown"} (lane ${laneForTask?.laneNumber ?? "?"})\n` +
+					`  Partial progress preserved: ${hasPartialProgress ? "yes" : "no"}\n` +
+					`  Batch: wave ${waveIdx + 1}/${batchState.totalWaves}, ` +
+					`${batchState.succeededTasks} succeeded, ${batchState.failedTasks} failed\n\n` +
+					`Available actions:\n` +
+					`  - orch_status() to inspect current state\n` +
+					`  - orch_resume(force=true) to retry\n` +
+					`  - Read STATUS.md and lane logs for diagnosis`,
+				context: {
+					taskId,
+					laneId: laneForTask?.laneId,
+					laneNumber: laneForTask?.laneNumber,
+					waveIndex: waveIdx,
+					exitReason,
+					partialProgress: hasPartialProgress,
+					batchProgress: buildBatchProgressSnapshot(batchState),
+				},
+			});
+		}
+
 		persistRuntimeState("wave-execution-complete", batchState, wavePlan, latestAllocatedLanes, allTaskOutcomes, discovery, stateRoot);
 
 		const elapsedSec = Math.round((waveResult.endedAt - waveResult.startedAt) / 1000);
@@ -1750,6 +1796,26 @@ export async function resumeOrchBatch(
 				persistWarning,
 				"error",
 			);
+
+			// ── TP-076: Emit supervisor alert for rollback safe-stop ──
+			emitAlert({
+				category: "merge-failure",
+				summary:
+					`⚠️ Merge failed for wave ${waveIdx + 1} — verification rollback failed\n` +
+					`  Batch force-paused for manual recovery.\n` +
+					`  Check .pi/verification/ for recovery commands.\n\n` +
+					`Available actions:\n` +
+					`  - Check .pi/verification/ transaction records\n` +
+					`  - orch_status() to inspect current state\n` +
+					`  - orch_resume(force=true) after manual recovery`,
+				context: {
+					waveIndex: waveIdx,
+					laneNumber: mergeResult.failedLane ?? undefined,
+					mergeError: `Safe-stop: verification rollback failed at wave ${waveIdx + 1}`,
+					batchProgress: buildBatchProgressSnapshot(batchState),
+				},
+			});
+
 			preserveWorktreesForResume = true;
 			break;
 		}
@@ -1805,6 +1871,24 @@ export async function resumeOrchBatch(
 				batchState.errors.push(retryOutcome.errorMessage);
 				persistRuntimeState("merge-rollback-safe-stop", batchState, wavePlan, latestAllocatedLanes, allTaskOutcomes, discovery, stateRoot);
 				onNotify(retryOutcome.notifyMessage, "error");
+
+				// ── TP-076: Emit supervisor alert for merge safe-stop ──
+				emitAlert({
+					category: "merge-failure",
+					summary:
+						`⚠️ Merge failed for wave ${waveIdx + 1} — rollback failure\n` +
+						`  Error: ${retryOutcome.errorMessage}\n\n` +
+						`Available actions:\n` +
+						`  - orch_status() to inspect current state\n` +
+						`  - orch_resume(force=true) after manual recovery`,
+					context: {
+						waveIndex: waveIdx,
+						laneNumber: mergeResult.failedLane ?? undefined,
+						mergeError: retryOutcome.errorMessage,
+						batchProgress: buildBatchProgressSnapshot(batchState),
+					},
+				});
+
 				preserveWorktreesForResume = true;
 				break;
 			} else if (retryOutcome.kind === "exhausted") {
@@ -1824,6 +1908,26 @@ export async function resumeOrchBatch(
 				batchState.errors.push(exhaustionMsg);
 				persistRuntimeState("merge-retry-exhausted", batchState, wavePlan, latestAllocatedLanes, allTaskOutcomes, discovery, stateRoot);
 				onNotify(retryOutcome.notifyMessage, "error");
+
+				// ── TP-076: Emit supervisor alert for merge retry exhausted ──
+				emitAlert({
+					category: "merge-failure",
+					summary:
+						`⚠️ Merge failed for wave ${waveIdx + 1} — retry exhausted\n` +
+						`  Classification: ${retryOutcome.classification ?? "unknown"}\n` +
+						`  Error: ${exhaustionMsg}\n\n` +
+						`Available actions:\n` +
+						`  - Investigate merge failure and retry manually\n` +
+						`  - orch_status() to inspect current state\n` +
+						`  - orch_resume(force=true) after fixing the issue`,
+					context: {
+						waveIndex: waveIdx,
+						laneNumber: mergeResult.failedLane ?? undefined,
+						mergeError: exhaustionMsg,
+						batchProgress: buildBatchProgressSnapshot(batchState),
+					},
+				});
+
 				preserveWorktreesForResume = true;
 				break;
 			} else {
@@ -1840,6 +1944,26 @@ export async function resumeOrchBatch(
 				batchState.errors.push(policyResult.errorMessage + classNote);
 				persistRuntimeState(policyResult.persistTrigger, batchState, wavePlan, latestAllocatedLanes, allTaskOutcomes, discovery, stateRoot);
 				onNotify(policyResult.notifyMessage + classNote, policyResult.notifyLevel);
+
+				// ── TP-076: Emit supervisor alert for merge failure (no-retry policy) ──
+				emitAlert({
+					category: "merge-failure",
+					summary:
+						`⚠️ Merge failed for wave ${waveIdx + 1}\n` +
+						`  Policy: ${policyResult.policy}${classNote}\n` +
+						`  Error: ${mergeResult.failureReason || "unknown"}\n\n` +
+						`Available actions:\n` +
+						`  - Investigate failed merge\n` +
+						`  - orch_status() to inspect current state\n` +
+						`  - orch_resume(force=true) after fixing the issue`,
+					context: {
+						waveIndex: waveIdx,
+						laneNumber: mergeResult.failedLane ?? undefined,
+						mergeError: mergeResult.failureReason || "unknown",
+						batchProgress: buildBatchProgressSnapshot(batchState),
+					},
+				});
+
 				preserveWorktreesForResume = true;
 				break;
 			}
@@ -2132,6 +2256,46 @@ export async function resumeOrchBatch(
 
 	persistRuntimeState("batch-terminal", batchState, wavePlan, latestAllocatedLanes, allTaskOutcomes, discovery, stateRoot);
 
+	// ── TP-076: Emit supervisor alert for batch completion ──────
+	if (batchState.phase === "completed" || batchState.phase === "failed") {
+		const batchDurationMs = batchState.endedAt ? batchState.endedAt - batchState.startedAt : 0;
+		const durationStr = batchDurationMs > 0
+			? `${Math.floor(batchDurationMs / 60000)}m ${Math.round((batchDurationMs % 60000) / 1000)}s`
+			: "unknown";
+		if (batchState.phase === "completed" && batchState.failedTasks === 0) {
+			emitAlert({
+				category: "batch-complete",
+				summary:
+					`✅ Batch ${batchState.batchId} completed\n` +
+					`  ${batchState.succeededTasks}/${batchState.totalTasks} tasks succeeded\n` +
+					`  ${batchState.totalWaves} wave(s), duration: ${durationStr}\n` +
+					`  Merged to orch branch: ${batchState.orchBranch}\n\n` +
+					`Ready for integration. Run orch_integrate() or review first.`,
+				context: {
+					batchProgress: buildBatchProgressSnapshot(batchState),
+					batchDurationMs,
+				},
+			});
+		} else {
+			emitAlert({
+				category: "batch-complete",
+				summary:
+					`⚠️ Batch ${batchState.batchId} finished with failures\n` +
+					`  ${batchState.succeededTasks} succeeded, ${batchState.failedTasks} failed, ` +
+					`${batchState.skippedTasks} skipped, ${batchState.blockedTasks} blocked\n` +
+					`  Duration: ${durationStr}\n\n` +
+					`Available actions:\n` +
+					`  - orch_status() to review final state\n` +
+					`  - orch_integrate() if succeeded work should be kept\n` +
+					`  - orch_resume(force=true) to retry failed tasks`,
+				context: {
+					batchProgress: buildBatchProgressSnapshot(batchState),
+					batchDurationMs,
+				},
+			});
+		}
+	}
+
 	// ── TP-031: Emit diagnostic reports (JSONL + markdown) ──
 	// Non-fatal: errors are logged but never crash batch finalization.
 	emitDiagnosticReports(assembleDiagnosticInput(orchConfig, batchState, wavePlan, latestAllocatedLanes, allTaskOutcomes, stateRoot));

package/extensions/taskplane/supervisor-primer.md

@@ -703,6 +703,74 @@ In ALL modes, you log every action to the audit trail.
 
 ---
 
+## 13a. Autonomous Alert Handling (TP-076)
+
+The engine sends you **structured alerts** via IPC when significant events
+occur. These alerts arrive as conversation messages — you don't need to poll
+or check status manually. The engine wakes you up when you're needed.
+
+### Alert Categories
+
+| Category | Emoji | When |
+|----------|-------|------|
+| `task-failure` | ⚠️ | A task failed after deterministic recovery was exhausted |
+| `merge-failure` | ⚠️ | Wave merge failed and batch paused |
+| `batch-complete` | ✅/⚠️ | Batch finished (all waves done, with or without failures) |
+
+### Alert Format
+
+Each alert contains:
+- **Summary**: Human-readable text describing what happened and what actions
+  are available. This is what you see in the conversation.
+- **Context**: Structured data (taskId, laneId, waveIndex, exitReason,
+  batchProgress, etc.) embedded in the message for your reference.
+
+### Response Protocol
+
+When you receive an alert, follow this sequence:
+
+1. **Acknowledge** — "I see the failure. Investigating."
+2. **Diagnose** — Call `orch_status()`, read STATUS.md, check logs
+3. **Decide** — Based on diagnosis, choose an action
+4. **Act** — Execute the recovery (resume, retry, skip, abort)
+5. **Report** — Tell the operator what happened and what was done
+6. **Learn** — If this is a recurring pattern, note it for future improvement
+
+### Autonomy Rules for Alert Response
+
+- **Do NOT ask the operator for permission** on routine recovery actions:
+  - Retrying a failed task (`orch_resume(force=true)`)
+  - Skipping dependents of a failed task
+  - Reading logs and batch state for diagnosis
+  
+- **DO escalate to the operator** for genuinely ambiguous situations:
+  - The same task has failed multiple times with different errors
+  - An unknown error type you haven't seen before
+  - Destructive actions (aborting a batch with partial work)
+  - Repeated merge failures on the same wave
+
+### Available Tools for Recovery
+
+You have these orchestrator tools available:
+- `orch_status()` — Check current batch state
+- `orch_resume(force=true)` — Resume/retry from last checkpoint
+- `orch_pause()` — Pause the batch gracefully
+- `orch_abort(hard?)` — Abort the batch
+- `orch_integrate(mode?, force?)` — Integrate completed batch
+- `orch_start(target)` — Start a new batch
+
+Plus general tools: `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`
+for inspecting files, running git commands, and editing batch state.
+
+### Critical Engine Alerts
+
+If the engine process itself crashes (process error or unexpected exit), you
+receive a critical alert with category `task-failure` and a 🔴 emoji. These
+indicate an infrastructure-level failure, not a task-level failure. Recovery
+typically requires `orch_resume(force=true)` after checking batch state.
+
+---
+
 ## 14. Your Startup Checklist
 
 When you activate at the start of a batch:

package/extensions/taskplane/types.ts

@@ -1780,6 +1780,120 @@ export interface EngineEvent {
  */
 export type EngineEventCallback = (event: EngineEvent) => void;
 
+
+// ── Supervisor Alert Types (TP-076) ──────────────────────────────────
+
+/**
+ * Alert category for supervisor notifications.
+ *
+ * Matches the alert categories in the autonomous supervisor spec:
+ * - `task-failure`:   A task failed after deterministic recovery was exhausted
+ * - `merge-failure`:  Wave merge failed and batch paused
+ * - `batch-complete`: Batch finished (all waves done)
+ *
+ * Note: `stall` detection is deferred to a future phase (requires
+ * last-activity tracking not yet built).
+ *
+ * @since TP-076
+ */
+export type SupervisorAlertCategory = "task-failure" | "merge-failure" | "batch-complete";
+
+/**
+ * Structured context payload for supervisor alerts.
+ *
+ * All fields are IPC-serializable (no functions, no circular refs, no Maps/Sets).
+ * Each alert category populates the relevant subset of optional fields.
+ *
+ * @since TP-076
+ */
+export interface SupervisorAlertContext {
+	/** Task ID (for task-failure alerts) */
+	taskId?: string;
+	/** Lane ID, e.g., "lane-1" (for task-failure alerts) */
+	laneId?: string;
+	/** Lane number (for task-failure and merge-failure alerts) */
+	laneNumber?: number;
+	/** Wave index, 0-based (for merge-failure and batch-complete alerts) */
+	waveIndex?: number;
+	/** Exit reason string (for task-failure alerts) */
+	exitReason?: string;
+	/** Whether partial progress was preserved (for task-failure alerts) */
+	partialProgress?: boolean;
+	/** Batch progress summary */
+	batchProgress?: {
+		succeededTasks: number;
+		failedTasks: number;
+		skippedTasks: number;
+		blockedTasks: number;
+		totalTasks: number;
+		currentWave: number;
+		totalWaves: number;
+	};
+	/** Merge failure reason (for merge-failure alerts) */
+	mergeError?: string;
+	/** Batch duration in milliseconds (for batch-complete alerts) */
+	batchDurationMs?: number;
+}
+
+/**
+ * Structured supervisor alert message.
+ *
+ * Emitted by the engine (child process) via IPC when the supervisor
+ * needs to be notified of an event requiring attention or acknowledgement.
+ *
+ * Design:
+ * - All fields are plain JSON-serializable values (IPC-safe).
+ * - `category` determines the alert type and which `context` fields are populated.
+ * - `summary` is a pre-formatted, human-readable string suitable for direct
+ *   display to the supervisor LLM as a conversation message.
+ * - `context` provides structured data for programmatic consumption.
+ *
+ * @since TP-076
+ */
+export interface SupervisorAlert {
+	/** Alert category — determines handling behavior */
+	category: SupervisorAlertCategory;
+	/** Human-readable summary suitable for display as a chat message */
+	summary: string;
+	/** Structured context data (all fields IPC-serializable) */
+	context: SupervisorAlertContext;
+}
+
+/**
+ * Callback type for supervisor alert emission.
+ *
+ * The engine (child process) calls this when it needs to alert the
+ * supervisor about a significant event. The main thread handler
+ * converts the alert into a `sendUserMessage` call to wake the
+ * supervisor LLM.
+ *
+ * @since TP-076
+ */
+export type SupervisorAlertCallback = (alert: SupervisorAlert) => void;
+
+/**
+ * Build a batch progress snapshot from runtime state.
+ *
+ * Pure function — extracts the current progress counters from
+ * OrchBatchRuntimeState into the IPC-serializable format used
+ * by SupervisorAlertContext.batchProgress.
+ *
+ * @since TP-076
+ */
+export function buildBatchProgressSnapshot(
+	batchState: OrchBatchRuntimeState,
+): NonNullable<SupervisorAlertContext["batchProgress"]> {
+	return {
+		succeededTasks: batchState.succeededTasks,
+		failedTasks: batchState.failedTasks,
+		skippedTasks: batchState.skippedTasks,
+		blockedTasks: batchState.blockedTasks,
+		totalTasks: batchState.totalTasks,
+		currentWave: batchState.currentWaveIndex + 1, // 1-based for display
+		totalWaves: batchState.totalWaves,
+	};
+}
+
 /**
  * Build the base fields for an engine event.
  *

package/package.json

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