taskplane 0.30.4 → 0.30.6

package/extensions/taskplane/supervisor.ts

@@ -50,6 +50,12 @@ import {
 	rename as fsRename,
 } from "fs/promises";
 import { execFileSync } from "child_process";
+import { assessEngineLiveness } from "./engine-identity.ts";
+import {
+	isProcessAlive as registryIsProcessAlive,
+	isTerminalStatus as registryIsTerminalStatus,
+	readRegistrySnapshot,
+} from "./process-registry.ts";
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import type { Model, Api } from "@mariozechner/pi-ai";
 import type {
@@ -2383,6 +2389,15 @@ Use these to:
    issue using the patterns in supervisor-primer.md and take appropriate
    recovery action based on your autonomy level (${autonomyLabel}).
 
+2a. **Adjudicate reviews.** You are notified at every review boundary, and get
+   an urgent (steer) \`review-intervention-needed\` alert when a step's reviews
+   spiral (repeated non-approve) or a worker trips the order-of-operations guard.
+   Actively adjudicate — don't just relay to the operator. Use the finding
+   **trend** to tell converging (\`dropping\` — let it run) from circling
+   (\`flat\`/\`rising\` — intervene), then steer the worker to a resolution
+   (implement the remaining valid findings, or stop and log a blocker) via
+   \`send_agent_message\`. Follow **Playbook D** in supervisor-primer.md.
+
 3. **Keep the operator informed.** Provide clear, natural status updates.
    When the operator asks "how's it going?" — read batch state and summarize.
 
@@ -2430,24 +2445,23 @@ ${autonomyGuidance}
 
 ## Audit Trail
 
-Log every recovery action to \`${actionsPath}\` as a single-line JSON entry.
+Log every recovery action with the **\`log_recovery_action\` tool** — it appends
+to \`${actionsPath}\` with a **code-stamped timestamp and batchId**.
 
-**Format** (one JSON object per line):
-\`\`\`json
-{"ts":"<ISO 8601>","action":"<action_name>","classification":"<diagnostic|tier0_known|destructive>","context":"<why>","command":"<what>","result":"<pending|success|failure|skipped>","detail":"<outcome>","batchId":"${batchState.batchId || "BATCH_ID"}"}
-\`\`\`
+**NEVER hand-write \`actions.jsonl\`** (no bash \`echo >>\`): you have no reliable
+clock, so hand-written entries carry fabricated timestamps and break the audit
+trail's integrity as evidence.
 
 **Rules:**
-1. For **destructive** actions: write a "pending" entry BEFORE executing, then
-   write a result entry AFTER with "success" or "failure" and detail.
-2. For **diagnostic** and **tier0_known** actions: write a single result entry
-   AFTER execution.
-3. Include optional fields when relevant: \`waveIndex\`, \`laneNumber\`, \`taskId\`, \`durationMs\`.
-4. Use the \`bash\` tool to append entries. Example:
-   \`echo '{"ts":"...","action":"merge_retry","classification":"tier0_known","context":"merge timeout on wave 2","command":"git merge --no-ff task/lane-2","result":"success","detail":"merged with 0 conflicts","batchId":"..."}' >> ${actionsPath}\`
+1. For **destructive** actions: call \`log_recovery_action(..., result="pending")\`
+   BEFORE executing, then call again AFTER with \`"success"\` or \`"failure"\` and detail.
+2. For **diagnostic** and **tier0_known** actions: one call AFTER execution.
+3. Include \`waveIndex\`, \`laneNumber\`, \`taskId\` when relevant.
+4. Stick to the schema fields — do not invent ad-hoc field names.
 
 **Why this matters:** When you're taken over by another session or the operator
-asks "what did you do?", the audit trail is the definitive record.
+asks "what did you do?", the audit trail is the definitive record — and its
+timestamps are only trustworthy because code stamps them.
 
 ## Operational Knowledge
 
@@ -3200,13 +3214,18 @@ export async function deactivateSupervisor(
  *
  * @since TP-128
  */
-export async function transitionToRoutingMode(
-	pi: ExtensionAPI,
-	state: SupervisorState,
-	routingContext: SupervisorRoutingContext,
-): Promise<void> {
-	if (!state.active) return;
-
+/**
+ * Tear down batch-monitoring infrastructure (event tailer, heartbeat timer,
+ * lockfile). Idempotent — safe to call multiple times.
+ *
+ * Extracted from `transitionToRoutingMode` (#621) so the batch-end epilogue can
+ * stop background timers EAGERLY when it must defer its display banners past an
+ * in-flight tool call. Stopping the heartbeat immediately prevents a
+ * timer-origin `pi.sendMessage(..., {triggerTurn:false})` from splicing a custom
+ * entry between an assistant `tool_use` and its `tool_result` during the defer
+ * window.
+ */
+export function stopBatchMonitoring(state: SupervisorState): void {
 	// Tear down batch-monitoring infrastructure
 	stopEventTailer(state.eventTailer);
 
@@ -3223,6 +3242,16 @@ export async function transitionToRoutingMode(
 		}
 	}
 	state.lockSessionId = "";
+}
+
+export async function transitionToRoutingMode(
+	pi: ExtensionAPI,
+	state: SupervisorState,
+	routingContext: SupervisorRoutingContext,
+): Promise<void> {
+	if (!state.active) return;
+
+	stopBatchMonitoring(state);
 
 	// Present deferred batch summary if any
 	if (state.pendingSummaryDeps && state.batchStateRef && state.stateRoot) {
@@ -3548,8 +3577,12 @@ export function isProcessAlive(pid: number): boolean {
 	try {
 		process.kill(pid, 0);
 		return true;
-	} catch {
-		return false;
+	} catch (err: unknown) {
+		// #631: only ESRCH (no such process) is "dead". EPERM = exists without
+		// signal permission; unknown errors fail closed (alive) — this feeds the
+		// lock-takeover ownership decision.
+		const code = (err as { code?: string } | null)?.code;
+		return code !== "ESRCH";
 	}
 }
 
@@ -3682,6 +3715,64 @@ export function buildTakeoverSummary(stateRoot: string, batchState: PersistedBat
 		`**Tasks:** ${succeeded} succeeded, ${failed} failed, ${running} running, ${pending} pending`,
 	);
 
+	// #631: ownership evidence — is the previous ENGINE still running? A dead
+	// supervisor pid does not imply a dead engine (forked child). This line is
+	// what tells the replacement operator whether orch_resume can proceed.
+	const activePhase =
+		batchState.phase === "executing" ||
+		batchState.phase === "launching" ||
+		batchState.phase === "merging" ||
+		batchState.phase === "planning";
+	const liveness = assessEngineLiveness(stateRoot, batchState.batchId);
+	if (liveness.identity?.taskplaneBuild) {
+		lines.push(
+			`**Build:** taskplane ${liveness.identity.taskplaneVersion ?? "?"} (build ${liveness.identity.taskplaneBuild}) drove this batch`,
+		);
+	}
+	if (liveness.status === "alive") {
+		lines.push(
+			`**Engine:** ⚠️ PID ${liveness.identity!.pid} is still ALIVE (forked by supervisor PID ${liveness.identity!.supervisorPid}). ` +
+				`This session has no engine attached; recovery tools will refuse until it exits (it pauses itself on supervisor disconnect) or is terminated.`,
+		);
+	} else if (liveness.status === "dead" || liveness.status === "exited") {
+		lines.push(
+			`**Engine:** PID ${liveness.identity!.pid} is ${liveness.status}${liveness.identity!.exitReason ? ` (${liveness.identity!.exitReason})` : ""}` +
+				(activePhase
+					? ` — persisted phase "${batchState.phase}" is an orphan; orch_resume(force=true) reconciles and re-drives it.`
+					: "."),
+		);
+	} else if (activePhase) {
+		lines.push(
+			`**Engine:** no identity recorded for this batch (pre-#631 engine or never forked). Recovery tools decide from the previous supervisor's liveness.`,
+		);
+	}
+
+	// #631/#630: workers the registry still calls "running" whose process is gone.
+	// Operators should NOT hand-edit registry.json for these — resume's liveness
+	// check (`!terminal && isProcessAlive(pid)`) already treats them as dead.
+	try {
+		const registry = readRegistrySnapshot(stateRoot, batchState.batchId);
+		if (registry) {
+			const deadRunning = Object.values(registry.agents).filter(
+				(m) => !registryIsTerminalStatus(m.status) && !registryIsProcessAlive(m.pid),
+			);
+			if (deadRunning.length > 0) {
+				lines.push("");
+				lines.push(
+					`**Dead agents still marked ${deadRunning[0].status} in the registry** (${deadRunning.length}):`,
+				);
+				for (const m of deadRunning) {
+					lines.push(
+						`  - ${m.agentId} (${m.role}${m.taskId ? `, ${m.taskId}` : ""}) PID ${m.pid} — process gone; registry last updated ${new Date(registry.updatedAt).toISOString()}. ` +
+							`No registry edit needed: orch_resume reconciles it (re-execute in the existing worktree).`,
+					);
+				}
+			}
+		}
+	} catch {
+		/* best effort */
+	}
+
 	// Recent actions from audit trail (using readAuditTrail helper)
 	const recentActions = readAuditTrail(stateRoot, { limit: 5 });
 	if (recentActions.length > 0) {
@@ -3817,6 +3908,56 @@ export function safeSendMessageFromTimer(
 	}
 }
 
+/**
+ * Stale-safe wrapper for a UI / side-effect call that touches a possibly-stale
+ * `ExtensionContext` or `ExtensionAPI` from a long-lived ASYNC callback —
+ * engine-worker IPC handlers (`child.on("message"|"error"|"exit")`), widget
+ * refresh, the batch-end epilogue, and supervisor-alert delivery (#620).
+ *
+ * Pi invalidates captured `ctx`/`pi` handles on session replacement/reload, and
+ * also at the end of headless `-p` runs while the forked engine worker is still
+ * emitting IPC. Every `ctx` accessor (`ctx.ui`, `ctx.isIdle()`, …) and the
+ * `pi.send*` methods then call Pi's `assertActive`, which throws
+ * `"This extension ctx is stale after session replacement or reload"`. Such a
+ * throw inside a `child_process` / EventEmitter callback is an
+ * `uncaughtException` that kills the supervising Pi process.
+ *
+ * Return value semantics (to prevent caller misuse):
+ *   - `false`  → STALE only. The session is gone; caller should skip any
+ *              further UI work for this event.
+ *   - `true`   → success OR a non-stale failure that was logged. NOT a
+ *              success-only signal — a `true` may mean "logged and continued".
+ *
+ * Any non-stale error is logged (so genuine failures still surface in
+ * stderr/telemetry) but is deliberately NOT rethrown:
+ * rethrowing from an IPC/EventEmitter callback would re-introduce the exact
+ * process-fatal crash class this guards against. This mirrors the proven #597
+ * `safeSendMessageFromTimer` contract, generalized to any thunk so it can wrap
+ * `ctx.ui.notify`, `ctx.ui.setWidget`, and `pi.sendUserMessage` alike.
+ *
+ * @since #620
+ */
+export function safeCtxCallFromCallback(fn: () => void, label = "ui"): boolean {
+	try {
+		fn();
+		return true;
+	} catch (err) {
+		if (isStaleExtensionCtx(err)) {
+			// Pi replaced/ended the session — no live UI sink. Skip, never crash.
+			return false;
+		}
+		// Not stale: surface it (so real failures are visible) but do not rethrow,
+		// because a throw from an async IPC callback is a process-fatal uncaught
+		// exception — the very failure mode #620 fixes.
+		console.error(
+			`[taskplane] ${label} call from async callback threw (non-stale): ${
+				err instanceof Error ? (err.stack ?? err.message) : String(err)
+			}`,
+		);
+		return true;
+	}
+}
+
 export function startHeartbeat(
 	stateRoot: string,
 	state: SupervisorState,
@@ -3968,6 +4109,18 @@ interface ParsedEvent {
 	suggestion?: string;
 	affectedTaskIds?: string[];
 	message?: string;
+	// ── Review-boundary optional fields ──────────────────────────
+	agentId?: string;
+	reviewStep?: number;
+	reviewType?: string;
+	disposition?: string;
+	reviewRound?: number;
+	reviewLabel?: string;
+	reviewPath?: string;
+	findingCounts?: Record<string, number>;
+	findingTrend?: "dropping" | "flat" | "rising";
+	findingDeltas?: Record<string, number>;
+	findingMixed?: boolean;
 }
 
 /**
@@ -3992,6 +4145,11 @@ const SIGNIFICANT_EVENT_TYPES = new Set<UnifiedEventType>([
 	"batch_complete",
 	"batch_paused",
 	"tier0_escalation",
+	// Review boundaries: surfaced at EVERY start/end so the supervisor can
+	// adjudicate each revision case-by-case (not coalesced into digests).
+	"review_started",
+	"review_completed",
+	"review_failed",
 ]);
 
 /**
@@ -4233,6 +4391,38 @@ export function parseJsonlLines(data: string, partialLine: string): [ParsedEvent
  *
  * @since TP-041
  */
+/**
+ * Compact "where" descriptor for a review-boundary notification: task, step,
+ * and lane so the supervisor can address the right worker when adjudicating.
+ */
+function reviewLocation(event: ParsedEvent): string {
+	const parts: string[] = [];
+	if (event.taskId) parts.push(`task ${event.taskId}`);
+	if (typeof event.reviewStep === "number") parts.push(`step ${event.reviewStep}`);
+	if (typeof event.laneNumber === "number") parts.push(`lane ${event.laneNumber}`);
+	return parts.length > 0 ? parts.join(", ") : "a step";
+}
+
+/**
+ * Compact adjudication signals for a review notification: round, finding counts,
+ * and severity trend — the three signals an adjudicating supervisor uses to tell
+ * "converging (let it run)" from "circling (intervene)" at a glance.
+ */
+function reviewSignals(event: ParsedEvent): string {
+	const bits: string[] = [];
+	if (typeof event.reviewRound === "number") bits.push(`round ${event.reviewRound}`);
+	if (event.findingCounts && Object.keys(event.findingCounts).length > 0) {
+		const counts = Object.entries(event.findingCounts)
+			.map(([k, v]) => `${k}:${v}`)
+			.join(" ");
+		const trend = event.findingTrend
+			? `, trend ${event.findingTrend}${event.findingMixed ? " (mixed)" : ""}`
+			: "";
+		bits.push(`findings ${counts}${trend}`);
+	}
+	return bits.length > 0 ? ` [${bits.join("; ")}]` : "";
+}
+
 export function formatEventNotification(
 	event: ParsedEvent,
 	autonomy: SupervisorAutonomyLevel,
@@ -4278,6 +4468,31 @@ export function formatEventNotification(
 			const mins = event.stalledMinutes ?? "?";
 			return `🔒 Merge agent on lane ${lane} appears stuck (no output for ${mins} min). Consider killing and retrying.`;
 		}
+		case "review_started": {
+			const loc = reviewLocation(event);
+			const typeLabel = event.reviewType ? `${event.reviewType} ` : "";
+			return `🔍 **Review starting** — ${typeLabel}review of ${loc}.`;
+		}
+		case "review_completed": {
+			const loc = reviewLocation(event);
+			const disp = (event.disposition || "UNKNOWN").toUpperCase();
+			const icon =
+				disp === "APPROVE" ? "✅" : disp === "REFUSED" ? "⛔" : disp === "UNKNOWN" ? "❔" : "🔁";
+			const tail =
+				disp === "APPROVE"
+					? ""
+					: disp === "REFUSED"
+						? " — reviewer refused (step marked complete before review). The worker must revert and re-review."
+						: " — changes requested. Watch for repeated revisions on this step.";
+			return `${icon} **Review ${disp}** — ${loc}.${reviewSignals(event)}${tail}`;
+		}
+		case "review_failed": {
+			const loc = reviewLocation(event);
+			return (
+				`⚠️ **Reviewer unavailable** — ${loc}. The reviewer subprocess failed or produced no ` +
+				`verdict (not a revision spiral — a broken-reviewer signal). Consider checking reviewer config.`
+			);
+		}
 		case "batch_complete": {
 			const parts: string[] = [];
 			if (event.succeededTasks !== undefined) parts.push(`${event.succeededTasks} succeeded`);
@@ -4399,14 +4614,22 @@ export function shouldNotify(
 	eventType: UnifiedEventType,
 	autonomy: SupervisorAutonomyLevel,
 ): boolean {
-	// Always notify for terminal/failure events regardless of autonomy
+	// Always notify for terminal/failure events regardless of autonomy.
+	// Review boundaries are included on purpose: the supervisor must be informed
+	// at EVERY review start/end in ALL autonomy levels — in autonomous mode this
+	// is precisely when it adjudicates revisions case-by-case (operator-as-alarm
+	// is the opposite of autonomous execution). Suppressing review_* in
+	// autonomous mode would silently disable the feature where it matters most.
 	if (
 		eventType === "batch_complete" ||
 		eventType === "batch_paused" ||
 		eventType === "merge_failed" ||
 		eventType === "merge_health_dead" ||
 		eventType === "merge_health_stuck" ||
-		eventType === "tier0_escalation"
+		eventType === "tier0_escalation" ||
+		eventType === "review_started" ||
+		eventType === "review_completed" ||
+		eventType === "review_failed"
 	) {
 		return true;
 	}

package/extensions/taskplane/types.ts

@@ -369,6 +369,10 @@ export interface TaskRunnerConfig {
 		tools: string;
 		/** Package specifiers to exclude from extension forwarding (exact match). @since TP-180 */
 		excludeExtensions?: string[];
+		/** Ordered severity vocabulary for review finding-count analysis (review-boundary notifications). */
+		severityLabels?: string[];
+		/** Revision-spiral detection tuning. */
+		spiral?: import("./config-schema.ts").ReviewSpiralConfig;
 	};
 	/**
 	 * Worker agent model/thinking/tools configuration.
@@ -384,6 +388,8 @@ export interface TaskRunnerConfig {
 		tools: string;
 		/** Package specifiers to exclude from extension forwarding (exact match). @since TP-180 */
 		excludeExtensions?: string[];
+		/** Exit-intercept supervisor-reply window in seconds (default 60; 15..1800). */
+		exitInterceptTimeoutSec?: number;
 	};
 	/** Worker agent extension exclusion list. @since TP-180 */
 	workerExcludeExtensions?: string[];
@@ -561,6 +567,13 @@ export class WorktreeError extends Error {
  * catching errors for expected idempotent scenarios.
  */
 export interface RemoveWorktreeResult {
+	/**
+	 * #628: removal was refused because the worktree has uncommitted changes and
+	 * the caller did not pass allowDirty. The worktree and branch are preserved.
+	 */
+	refusedDirty?: boolean;
+	/** Number of uncommitted paths found when refusedDirty is true. */
+	dirtyFileCount?: number;
 	/** Whether the worktree directory was removed in this call */
 	removed: boolean;
 	/** Whether the worktree was already absent (idempotent no-op) */
@@ -1132,8 +1145,15 @@ export interface WaveExecutionResult {
 	stoppedEarly: boolean;
 	/** Task IDs that failed (including stalled) */
 	failedTaskIds: string[];
-	/** Task IDs that were skipped (due to pause, prior failure, or policy) */
+	/** Task IDs that were skipped (due to prior failure in lane, or policy) */
 	skippedTaskIds: string[];
+	/**
+	 * Task IDs that did NOT run to a terminal state because the batch was PAUSED
+	 * while they were pending/holding. They remain `pending` (not skipped, not
+	 * counted) and re-execute on resume. A wave with any paused task is not
+	 * complete; the engine finalizes the batch as `paused` instead of merging.
+	 */
+	pausedTaskIds?: string[];
 	/** Task IDs that succeeded */
 	succeededTaskIds: string[];
 	/** Task IDs blocked for future waves (transitive dependents of failed tasks) */
@@ -1191,6 +1211,20 @@ export type OrchBatchPhase =
  * - Tracks pauseSignal for /orch-pause
  * - Accumulates wave results for summary
  */
+/**
+ * Shared pause signal (engine ⇄ waves ⇄ lanes).
+ *
+ * `cause` says WHY the batch is paused: `operator` = /orch-pause (or an orphan
+ * engine winding down), `abort` = stop-all failure policy / orch_abort,
+ * `stop-wave` reserved for the stop-wave policy. Tier-0 retry may clear ONLY
+ * a policy cause — one boolean let a successful retry erase an operator's
+ * pause (Sage review of the 20260906T194514 incident).
+ */
+export interface PauseSignal {
+	paused: boolean;
+	cause?: "operator" | "stop-wave" | "abort" | "merge-failure";
+}
+
 export interface OrchBatchRuntimeState {
 	/** Current execution phase */
 	phase: OrchBatchPhase;
@@ -1200,10 +1234,18 @@ export interface OrchBatchRuntimeState {
 	baseBranch: string;
 	/** Orchestrator-managed branch name (e.g., 'orch/henry-20260318T140000'). Empty = legacy mode (merge into baseBranch directly). */
 	orchBranch: string;
+	/**
+	 * #610: epoch ms when this batch was integrated (manual or auto). Set in
+	 * memory by the integration path so a batch-end epilogue that was DEFERRED
+	 * behind the integrating turn is skipped instead of showing stale "ready for
+	 * integration" banners. Not persisted (the persisted checkpoint is deleted
+	 * on integration; batch-history carries its own integratedAt).
+	 */
+	integratedAt?: number;
 	/** Workspace execution mode (v2). Defaults to "repo" for backward compatibility. */
 	mode: WorkspaceMode;
 	/** Shared pause signal — set by /orch-pause, read by executeLane/executeWave */
-	pauseSignal: { paused: boolean };
+	pauseSignal: PauseSignal;
 	/** All wave results in order (grows as waves complete) */
 	waveResults: WaveExecutionResult[];
 	/** Current wave index (0-based into waves array, -1 if not started) */
@@ -2028,7 +2070,14 @@ export type EngineEventType =
 	| "merge_health_dead"
 	| "merge_health_stuck"
 	| "batch_complete"
-	| "batch_paused";
+	| "batch_paused"
+	// Review boundaries (review-boundary supervisor notifications). Bridged from
+	// the per-agent RuntimeAgentEvent review_* stream by lane-runner so the
+	// supervisor's live events.jsonl tailer surfaces every review start/end and
+	// can adjudicate revisions case-by-case.
+	| "review_started"
+	| "review_completed"
+	| "review_failed";
 
 /**
  * Structured engine event written to `.pi/supervisor/events.jsonl`.
@@ -2101,6 +2150,31 @@ export interface EngineEvent {
 	healthStatus?: MergeHealthStatus;
 	/** Minutes since last activity (for merge_health_warning, merge_health_stuck) */
 	stalledMinutes?: number;
+
+	// ── Review-boundary fields (review_started/completed/failed) ────
+
+	/** Worker agent ID that owns the review (for review_* events) */
+	agentId?: string;
+	/** Step number under review (for review_* events) */
+	reviewStep?: number;
+	/** Review type, e.g. "plan" | "code" (for review_* events) */
+	reviewType?: string;
+	/** Normalized reviewer verdict (for review_completed, review_failed) */
+	disposition?: ReviewDisposition;
+	/** Per-step review round (Nth verdict-producing review of this step) */
+	reviewRound?: number;
+	/** Human/file-correlation label, e.g. "R008-code-step4" */
+	reviewLabel?: string;
+	/** Review file path (relative), for correlation / optional re-parse */
+	reviewPath?: string;
+	/** Finding counts by severity label for this review */
+	findingCounts?: Record<string, number>;
+	/** Converging-vs-circling trend vs the previous round */
+	findingTrend?: "dropping" | "flat" | "rising";
+	/** Per-severity delta (curr - prev) */
+	findingDeltas?: Record<string, number>;
+	/** Whether severities moved in opposing directions */
+	findingMixed?: boolean;
 }
 
 /**
@@ -2145,7 +2219,21 @@ export type SupervisorAlertCategory =
 	| "worker-exit-intercept"
 	| "segment-expansion-requested"
 	| "segment-expansion-approved"
-	| "segment-expansion-rejected";
+	| "segment-expansion-rejected"
+	// Review-boundary supervisor notifications: an actionable escalation when a
+	// step's reviews are spiraling (repeated non-APPROVE) or the worker tripped
+	// the order-of-operations guard (REFUSED). Delivered `steer` (urgent) so the
+	// supervisor can adjudicate mid-run. `context.reviewInterventionKind`
+	// distinguishes the two situations.
+	| "review-intervention-needed";
+
+/** Which review situation triggered a `review-intervention-needed` alert. */
+export type ReviewInterventionKind =
+	| "revision-spiral"
+	| "order-violation"
+	// #626 minimal cut: a task attempted to finalize (.DONE) while a step's
+	// LATEST review verdict is still REVISE/RETHINK — finalization was refused.
+	| "unresolved-verdict";
 
 /**
  * Structured context payload for supervisor alerts.
@@ -2215,6 +2303,31 @@ export interface SupervisorAlertContext {
 	messageId?: string;
 	/** Segment expansion request ID (for segment-expansion alerts) */
 	expansionRequestId?: string;
+	// ── Review-intervention fields (review-intervention-needed alerts) ────
+	/** Which review situation triggered the escalation. */
+	reviewInterventionKind?: ReviewInterventionKind;
+	/** Step number under review. */
+	reviewStep?: number;
+	/** Review type ("plan" | "code"). */
+	reviewType?: string;
+	/** Per-step review round (Nth verdict-producing review of this step). */
+	reviewRound?: number;
+	/** Human/file-correlation label, e.g. "R008-code-step4". */
+	reviewLabel?: string;
+	/** Latest normalized disposition. */
+	disposition?: ReviewDisposition;
+	/** Recent disposition history for this step (oldest→newest, bounded). */
+	recentDispositions?: ReviewDisposition[];
+	/** Consecutive non-APPROVE count for this step at escalation time. */
+	consecutiveNonApprove?: number;
+	/** Finding counts by severity label for the latest review. */
+	findingCounts?: Record<string, number>;
+	/** Converging-vs-circling trend vs the previous round. */
+	findingTrend?: "dropping" | "flat" | "rising";
+	/** Per-severity delta (curr - prev) for the latest review. */
+	findingDeltas?: Record<string, number>;
+	/** Whether severities moved in opposing directions. */
+	findingMixed?: boolean;
 	/** Whether partial progress was preserved (for task-failure alerts) */
 	partialProgress?: boolean;
 	/** Batch progress summary */
@@ -4211,6 +4324,31 @@ export type RuntimeAgentEventType =
 	// Exit interception (TP-172)
 	| "exit_intercepted";
 
+/**
+ * Normalized outcome of a `review_step` tool call, extracted from the reviewer
+ * verdict the tool returns to the worker. Used by the review-boundary
+ * notification pipeline (agent-host emits it in `review_completed`; the
+ * supervisor adjudicates on it).
+ *
+ * - `APPROVE`     — reviewer approved the step.
+ * - `REVISE`      — changes requested (spiral-relevant).
+ * - `RETHINK`     — reconsider the approach (spiral-relevant).
+ * - `REFUSED`     — the TP-186 death-spiral guard refused to spawn a reviewer
+ *                   (step prematurely marked Complete). A correctness signal,
+ *                   not a normal verdict.
+ * - `UNAVAILABLE` — the reviewer subprocess failed / produced no output. A
+ *                   "reviewer broken" signal (surfaced as `review_failed`), NOT
+ *                   counted toward the revision spiral.
+ * - `UNKNOWN`     — verdict could not be parsed.
+ */
+export type ReviewDisposition =
+	| "APPROVE"
+	| "REVISE"
+	| "RETHINK"
+	| "REFUSED"
+	| "UNAVAILABLE"
+	| "UNKNOWN";
+
 // ── Runtime V2 Path Helpers (TP-102) ─────────────────────────────────
 
 /**