taskplane 0.30.5 → 0.30.6

package/extensions/taskplane/supervisor-primer.md

@@ -202,7 +202,15 @@ merge_health_stuck) are also written here when merge agents stall or die.
 
 **Audit trail:** `.pi/supervisor/actions.jsonl`
 
-Every recovery action you take is logged here as JSONL. Destructive actions
+Every recovery action you take is logged here as JSONL — **always via the
+`log_recovery_action` tool**, which stamps `ts` and `batchId` in code. This
+includes **hand-remediation**: any hot-fix commit, review-file ratification,
+or manual state repair you perform under an operator ruling is a recovery
+action — log it (`classification: "destructive"`, `command` = the commit sha
+or file written, `context` = the ruling). The runtime has no other record of
+hand edits. Never
+append to this file by hand (your clock is unreliable; hand-written entries
+carry fabricated timestamps). Destructive actions
 must be logged *before* execution (with result="pending"), then again after
 (with actual result). This file is read during takeover rehydration.
 
@@ -485,6 +493,57 @@ grep -c "^<<<<<<<" {file}  # count conflicts per file
 to take effect. Alternatively, you (the supervisor) can read the config file
 directly and apply the relevant value when executing recovery.
 
+### Pattern 9: You Inherited an "executing" Batch (Replacement Supervisor)
+
+**Symptom:** You took over the supervisor lock (previous session died, wedged,
+or was replaced). `orch_status` says the batch is `executing`, but nothing is
+happening: the registry's `updatedAt` is frozen, `orch_pause` is accepted but
+inert, workers may be dead but still marked `running`.
+
+**Cause:** The engine is a forked child of the *previous* supervisor's
+process. Your session has no engine attached. Persisted `executing` means
+"the orchestrator disconnected mid-batch" — which `orch_resume` is designed
+to recover — but only once it is VERIFIED that the old engine is gone (a dead
+supervisor pid does not prove a dead engine).
+
+**What the runtime does for you (#631):**
+- The takeover summary prints an **Engine:** line from
+  `.pi/runtime/<batchId>/engine.json`: `alive` (pid), `dead`/`exited`, or no
+  identity recorded. It also lists **dead agents still marked running** — do
+  NOT hand-edit `registry.json` for those; resume reconciles them.
+- An orphaned engine pauses itself when its supervisor disconnects (finishes
+  in-flight lanes, persists `paused`, exits). Give it a moment.
+- `orch_resume`, `orch_retry_task`, `orch_skip_task`, `orch_force_merge`
+  decide from that evidence: engine **dead/exited** → proceed via the normal
+  persisted-state eligibility; engine **alive** → refuse and name the pid
+  (`force` does NOT bypass this — double-driving corrupts state). The check
+  runs against the PERSISTED batch regardless of what phase you have cached.
+- **No identity recorded** (pre-#631 engine) → the tools **refuse**: unknown
+  ownership is not confirmed shutdown, and a dead supervisor pid does not prove
+  a dead engine. Verify out-of-band that no engine process exists
+  (`Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match
+  "engine-worker" }` / `pgrep -af engine-worker`), then record it with
+  `orch_confirm_engine_shutdown(note)` — written to `engine.json` and the
+  audit trail — and re-run the tool. Never use it to override a refusal that
+  names a LIVE pid.
+- `orch_pause` with no engine attached performs an **administrative pause**
+  (persists `phase: paused` on disk) when the engine is confirmed gone. This is
+  the non-destructive stop; you never need to hand-edit `batch-state.json`.
+
+**Recovery:**
+1. Read the takeover summary's Engine line.
+2. Engine alive → wait for it to wind down (or, if the operator agrees, terminate
+   that pid explicitly) and re-check.
+3. Engine dead/exited → `orch_resume(force=true)`. Dead workers reconcile as
+   `re-execute` in their existing worktrees; committed work survives. Any
+   worker still alive is terminated with VERIFICATION (SIGTERM → wait →
+   SIGKILL → wait) before its lane re-executes; if termination cannot be
+   confirmed the task fails with that reason instead of running two agents in
+   one worktree.
+3b. No identity → verify, `orch_confirm_engine_shutdown(note)`, then step 3.
+4. Never `supervisor_takeover` or `orch_abort` here — both are destructive for
+   an inherited paused/held lane (see #628).
+
 ---
 
 ## 8. Batch State Editing Guide
@@ -701,7 +760,9 @@ When you're unsure:
 - Good for overnight/unattended batches
 - The operator trusts you to make reasonable decisions
 
-In ALL modes, you log every action to the audit trail.
+In ALL modes, you log every action to the audit trail via the
+`log_recovery_action` tool (never a hand-written append — timestamps must be
+code-stamped).
 
 ---
 
@@ -719,6 +780,7 @@ or check status manually. The engine wakes you up when you're needed.
 | `merge-failure` | ⚠️ | Wave merge failed and batch paused |
 | `batch-complete` | ✅/⚠️ | Batch finished (all waves done, with or without failures) |
 | `worker-exit-intercept` | 🔄 | A worker exited without making progress — session still alive, awaiting instructions |
+| `review-intervention-needed` | 🌀/⛔ | A step's reviews are spiraling (repeated non-approve) or the worker tripped the order-of-operations guard — adjudicate per **Playbook D** |
 
 ### Alert Format
 
@@ -782,6 +844,8 @@ If the batch is actively running, call `orch_pause()` first.
 - `read_agent_status(lane?)` — Read STATUS.md + telemetry for a lane (step, progress, context %, cost, elapsed). Omit lane for all lanes.
 - `trigger_wrap_up(lane)` — Write `.task-wrap-up` signal to gracefully stop a worker on a lane.
 - `read_lane_logs(lane)` — Read stderr/crash logs and exit diagnostics for a lane.
+- `log_recovery_action(action, classification, context, command, result, detail, …)` — Append an audit-trail entry (ts/batchId code-stamped). The ONLY correct way to write `actions.jsonl`.
+- `orch_confirm_engine_shutdown(note, batchId?)` — Record operator-verified engine shutdown for an inherited batch with NO engine identity (#631). Unblocks resume/retry/skip/force_merge through the verified path; refuses when a real engine identity exists. Audited.
 - `list_active_agents()` — List active worker/reviewer/merge agents with role, lane, task, context %, elapsed, cost.
 
 Plus general tools: `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`
@@ -794,6 +858,37 @@ 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.
 
+### Review-Boundary Notifications (Active Adjudication)
+
+Beyond the alerts above, you are notified at **every review boundary** — when a
+worker's `review_step` tool starts and completes. These are informational
+(delivered follow-up, they queue to your next turn), but they exist so you can
+adjudicate reviews **case by case** instead of waiting for a spiral to fully
+form. Each review-completed notification carries:
+
+- **Disposition** — `APPROVE` / `REVISE` / `RETHINK` / `REFUSED` / `UNAVAILABLE`.
+- **Round** — how many times this step has been reviewed (e.g. `round 4`).
+- **Findings + trend** (when the reviewer emits an `Issues Found` section) —
+  counts by severity (the project's configured `severityLabels`, e.g.
+  critical/important/minor or P0/P1/P2) and a **trend**: `dropping` (converging —
+  severity falling round over round), `flat`, or `rising`, plus a `mixed` flag
+  when severities move in opposite directions.
+
+**Reading the signal — converging vs circling (the core judgment):**
+
+- **Let it run:** disposition `REVISE`/`RETHINK` but trend `dropping` — the
+  worker is making the reviewer progressively happier; this is healthy
+  deepening. Do not interfere.
+- **Intervene:** trend `flat`/`rising` across rounds, or the same finding class
+  recurring — the loop is circling, not converging. Adjudicate (see Playbook D).
+
+When the deterministic threshold is crossed (default **3 consecutive
+non-approve on the same step**) you additionally get an **urgent
+`review-intervention-needed` alert** delivered as a *steer* — it interrupts your
+current turn. Act on it per Playbook D. `REFUSED` (order-of-operations
+violation) and `UNAVAILABLE` (broken reviewer) are surfaced as distinct signals,
+not counted toward the revision spiral.
+
 ---
 
 ## 13b. Recovery Playbooks (TP-078)
@@ -997,6 +1092,91 @@ BATCH COMPLETE: {batchId}
 │         → Suggest: orch_integrate()
 ```
 
+### Playbook D: Review Spiral / Adjudication
+
+**Trigger:** a `review-intervention-needed` alert, OR your own read of the
+review-boundary notifications (see "Review-Boundary Notifications" in §13a).
+Alert context includes `reviewInterventionKind` (`revision-spiral` |
+`order-violation`), `taskId`, `reviewStep`, `laneNumber`, `agentId`,
+`disposition`, `recentDispositions`, `consecutiveNonApprove`, `reviewRound`,
+`findingCounts`, `findingTrend`.
+
+```
+REVIEW INTERVENTION: {taskId} step {reviewStep} (lane {laneNumber})
+│
+├─ kind = "order-violation"  (disposition REFUSED)
+│   The worker marked the step complete BEFORE code review ran.
+│   → Steer the worker (send_agent_message to {agentId}) to:
+│       1. Revert the step's Status to In Progress in STATUS.md
+│       2. Re-run review_step for that step, THEN mark it complete
+│   → Report: "Order-of-operations violation on {taskId} step {N} —
+│     instructed the worker to revert and re-review."
+│
+└─ kind = "revision-spiral"  (3+ consecutive non-approve on the same step)
+    │
+    ├─ 1. Read findingTrend + recentDispositions in the alert:
+    │     │
+    │     ├─ trend = "dropping" (CONVERGING)
+    │     │   → Usually LET IT RUN one or two more rounds — the worker is
+    │     │     resolving real findings and severity is falling. Only step in
+    │     │     if the round count is very high (diminishing returns).
+    │     │
+    │     └─ trend = "flat" / "rising" (CIRCLING)
+    │         │
+    │         ├─ 2. Read the latest review file
+    │         │     (.reviews/R{NNN}-{type}-step{N}.md) and the worker's
+    │         │     STATUS.md to judge WHY it's stuck:
+    │         │     │
+    │         │     ├─ Findings are legitimate but the worker keeps missing
+    │         │     │   them → steer with CONCRETE, specific instructions on
+    │         │     │   exactly what to implement (quote the finding).
+    │         │     │
+    │         │     ├─ Findings are subjective / diminishing returns / the
+    │         │     │   reviewer is over-strict → tell the worker the step is
+    │         │     │   good enough; instruct it to proceed.
+    │         │     │
+    │         │     └─ The task is genuinely too hard / underspecified →
+    │         │         tell the worker to STOP, log a clear blocker in
+    │         │         STATUS.md, and exit. Then escalate to the operator
+    │         │         with the blocker text.
+    │         │
+    │         └─ 3. Report your decision AND why (cite the trend + round,
+    │             e.g. "step 4 at round 6, criticals flat — steering the
+    │             worker to implement the two outstanding findings").
+```
+
+**Worker on HOLD for a ruling (#630 Tier-1 contract).** A worker that escalated
+and is waiting exits its turn; the runtime relaunches it (bounded, 3) with a
+hold-resume prompt instead of failing it as a stall. Your messages to it have
+two meanings, chosen by `send_agent_message` **type**:
+
+- `type="info"` → **acknowledgement** ("received, ruling pending; expect ~N
+  hours"). The worker stays on hold; its relaunch budget resets. Use this for
+  any ruling that will take a while so the task does not fail as
+  `Hold unresolved` before the ruling exists.
+- `type="steer"` (default) → **the ruling / instruction**. Releases the hold;
+  the worker acts on it.
+
+If neither arrives within 3 relaunches the task fails with `Hold unresolved`
+(work preserved in the worktree); after ruling, `orch_retry_task` +
+`orch_resume(force=true)`.
+
+**kind = "unresolved-verdict"** (finalize refused): the task tried to complete
+while some gate's LATEST review file still reads REVISE/RETHINK — the runtime
+refused `.DONE` and marked the task failed instead of letting it merge
+unreviewed. Adjudicate: have the worker address the findings and re-run
+`review_step` (then `orch_retry_task` + `orch_resume(force=true)`), or — for an
+operator-ratified override — record the ruling as the next R-numbered review
+file with an explicit APPROVE verdict, then retry the task.
+
+Steer the worker with `send_agent_message(to, content)` using the `agentId`
+from the alert context. **Your judgment IS the adjudication** — the goal is to
+keep the task converging on the project's real goals, not to let a review loop
+burn indefinitely nor to rubber-stamp incomplete work. Log the decision to the
+audit trail. Re-escalations are trend-gated (you won't be nagged while a spiral
+is converging), so a fresh `review-intervention-needed` after you've acted means
+it is still NOT converging — consider a firmer intervention (stop + blocker).
+
 ### Quick Reference: Recovery Action Matrix
 
 | Alert | Diagnosis | Action | Autonomy |

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
 
@@ -3563,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";
 	}
 }
 
@@ -3697,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) {
@@ -3832,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,
@@ -3983,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;
 }
 
 /**
@@ -4007,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",
 ]);
 
 /**
@@ -4248,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,
@@ -4293,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`);
@@ -4414,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;
 	}