taskplane 0.30.4 → 0.30.6

package/extensions/taskplane/lane-runner.ts

@@ -69,10 +69,191 @@ import {
 	type SupervisorAlertCallback,
 	type StepSegmentMapping,
 	type SegmentScopeMode,
+	type RuntimeAgentEvent,
+	type EngineEvent,
+	type EngineEventType,
+	type ReviewDisposition,
+	type ReviewInterventionKind,
+	type SupervisorAlert,
+	type PauseSignal,
 } from "./types.ts";
+import type { TaskExitDiagnostic } from "./diagnostics.ts";
+import {
+	parseFindingCounts,
+	computeFindingTrend,
+	parseReviewLabelFromPath,
+	advanceReviewStreak,
+	reconstructReviewStreaks,
+	freshReviewStreakState,
+	shouldFireSpiral,
+	shouldFireOrderViolation,
+	sanitizeSpiralConfig,
+	parseReviewVerdict,
+	latestReviewFilesPerGate,
+	type ReviewStreakState,
+} from "./review-analysis.ts";
+// NOTE: emitEngineEvent is NOT statically imported from ./persistence.ts.
+// persistence.ts imports execLog from ./execution.ts, and execution.ts imports
+// executeTaskV2 from this module — a static import here would form a
+// lane-runner → persistence → execution → lane-runner cycle. Beyond being a
+// smell, that eager cycle pre-binds execution's executeTaskV2 to the real
+// export before tests can mock.module("lane-runner"), defeating the mock. The
+// review-event bridge below loads emitEngineEvent lazily (cached) instead.
+let cachedEmitEngineEvent: ((stateRoot: string, event: EngineEvent) => void) | null = null;
 
 const LANE_RUNNER_DIR = dirname(fileURLToPath(import.meta.url));
 
+/**
+ * Interval (ms) for the live worker-outbox poll during a running worker
+ * (mail-recognition fix). Surfaces reply/escalate mail to the supervisor
+ * mid-run instead of only after the worker exits. 3s balances responsiveness
+ * against fs churn; the post-exit final drain catches any last stragglers.
+ */
+const OUTBOX_LIVE_POLL_INTERVAL_MS = 3_000;
+
+/**
+ * #629: how many worker iterations the lane may spend REMEDIATING an
+ * outstanding non-APPROVE review gate when all checkboxes are already
+ * checked. Without this path, retry+resume after a finalize refusal never
+ * spawns a worker (the loop breaks on "no remaining steps") and the gate
+ * refuses again immediately — the alert's promised remedy was unreachable.
+ * Bounded so an unresolvable REVISE cannot loop forever.
+ */
+const MAX_REVIEW_REMEDIATION_ITERATIONS = 2;
+
+/**
+ * #630: how many times the lane relaunches a worker that exited while HOLDING
+ * for a supervisor ruling (an `escalate_to_supervisor` with no reply delivered
+ * since). Each relaunch re-checks for the ruling; beyond this the task fails
+ * with an explicit "hold unresolved" reason so the supervisor sees a dead
+ * lane as a governance signal, not as silence. (A first-class `held` state
+ * with an in-tool wait is the #627 design follow-up.)
+ */
+const MAX_HOLD_RELAUNCHES = 3;
+
+/** A review gate whose LATEST review file carries a non-APPROVE verdict. */
+interface BlockingReviewGate {
+	/** `{type}-step{N}` gate key */
+	gate: string;
+	/** Latest review filename for that gate */
+	filename: string;
+	verdict: "REVISE" | "RETHINK";
+}
+
+/**
+ * Scan a reviews directory and return every gate whose latest review file
+ * reads REVISE/RETHINK (#626 minimal finalize gate). Unreadable files are
+ * never blockers; a scan failure yields an empty list (fail-safe for
+ * finalization, which must not be corrupted by an fs hiccup).
+ */
+function findBlockingReviewGates(reviewsDir: string): BlockingReviewGate[] {
+	const blocking: BlockingReviewGate[] = [];
+	try {
+		if (!existsSync(reviewsDir)) return blocking;
+		const latest = latestReviewFilesPerGate(readdirSync(reviewsDir));
+		for (const [gate, filename] of latest) {
+			try {
+				const verdict = parseReviewVerdict(readFileSync(join(reviewsDir, filename), "utf-8"));
+				if (verdict === "REVISE" || verdict === "RETHINK") blocking.push({ gate, filename, verdict });
+			} catch {
+				/* unreadable review file — not a blocker */
+			}
+		}
+	} catch {
+		/* best effort */
+	}
+	return blocking;
+}
+
+/** `code-step4` → 4; null when the gate key has no step suffix. */
+function parseGateStepNumber(gate: string): number | null {
+	const m = /-step(\d+)$/i.exec(gate);
+	return m ? Number(m[1]) : null;
+}
+
+function formatBlockingGates(gates: BlockingReviewGate[]): string {
+	return gates.map((g) => `${g.gate} (${g.filename}: ${g.verdict})`).join("; ");
+}
+
+/** Default severity vocabulary when the reviewer config doesn't override it. */
+const DEFAULT_SEVERITY_LABELS = ["critical", "important", "minor"];
+/** Max recent dispositions retained per step for escalation context. */
+const RECENT_DISPOSITIONS_CAP = 6;
+
+/**
+ * In-memory per-step review-boundary state = the shared streak model plus
+ * live-only escalation cooldown bookkeeping.
+ */
+interface ReviewStepState extends ReviewStreakState {
+	/** Round at which the spiral escalation last fired (for cooldown); null = never. */
+	lastEscalationRound: number | null;
+	/** Round at which an order-violation last escalated (for cooldown); null = never. */
+	lastRefusedRound: number | null;
+}
+
+/**
+ * Resume reconstruction: seed per-step review streak state by replaying a task's
+ * prior review END boundaries from `.pi/supervisor/events.jsonl`. Best-effort
+ * (an optimization, not correctness-critical): any read/parse failure leaves the
+ * map empty and detection simply starts fresh. Escalation cooldown fields reset
+ * to null so an ongoing spiral re-alerts the supervisor after resume.
+ */
+function seedReviewStateFromHistory(
+	target: Map<string, ReviewStepState>,
+	stateRoot: string,
+	batchId: string,
+	taskId: string,
+	treatUnavailableAsNonApprove: boolean,
+): void {
+	try {
+		const eventsPath = join(stateRoot, ".pi", "supervisor", "events.jsonl");
+		if (!existsSync(eventsPath)) return;
+		const raw = readFileSync(eventsPath, "utf-8");
+		const events: Array<{
+			reviewStep?: number;
+			disposition?: string;
+			findingCounts?: Record<string, number> | null;
+		}> = [];
+		for (const line of raw.split("\n")) {
+			const trimmed = line.trim();
+			if (!trimmed) continue;
+			try {
+				const e = JSON.parse(trimmed) as Record<string, unknown>;
+				if (
+					(e.type === "review_completed" || e.type === "review_failed") &&
+					e.batchId === batchId &&
+					e.taskId === taskId
+				) {
+					events.push({
+						reviewStep: typeof e.reviewStep === "number" ? e.reviewStep : undefined,
+						disposition: typeof e.disposition === "string" ? e.disposition : undefined,
+						findingCounts:
+							e.findingCounts && typeof e.findingCounts === "object"
+								? (e.findingCounts as Record<string, number>)
+								: null,
+					});
+				}
+			} catch {
+				/* skip malformed line */
+			}
+		}
+		if (events.length === 0) return;
+		const streaks = reconstructReviewStreaks(events, {
+			treatUnavailableAsNonApprove,
+			recentCap: RECENT_DISPOSITIONS_CAP,
+		});
+		for (const [stepStr, streak] of streaks) {
+			target.set(`${taskId}:${stepStr}`, {
+				...streak,
+				lastEscalationRound: null,
+				lastRefusedRound: null,
+			});
+		}
+	} catch {
+		/* best effort */
+	}
+}
+
 // ── Segment Scoping Helpers (Phase A, TP-174) ────────────────────────
 
 /**
@@ -296,6 +477,13 @@ export interface LaneRunnerConfig {
 	 * @since TP-160
 	 */
 	reviewerTools: string;
+	/**
+	 * Ordered severity vocabulary for review finding-count analysis (review-boundary
+	 * notifications). Undefined → lane-runner default (critical/important/minor).
+	 */
+	reviewSeverityLabels?: string[];
+	/** Revision-spiral detection tuning. Undefined → lane-runner defaults. */
+	reviewSpiral?: import("./config-schema.ts").ReviewSpiralConfig;
 	/** Supervisor autonomy level for bridge-tool guards. */
 	supervisorAutonomy?: "interactive" | "supervised" | "autonomous";
 	/** Project name (for review request context) */
@@ -308,6 +496,8 @@ export interface LaneRunnerConfig {
 	maxIterations: number;
 	/** No-progress stall limit */
 	noProgressLimit: number;
+	/** Exit-intercept supervisor-reply window (seconds; default 60; 15..1800). */
+	exitInterceptTimeoutSec?: number;
 	/** Max worker time in minutes per iteration */
 	maxWorkerMinutes: number;
 	/** Context pressure warn threshold (0-100) */
@@ -369,7 +559,7 @@ export interface LaneRunnerTaskResult {
 export async function executeTaskV2(
 	unit: ExecutionUnit,
 	config: LaneRunnerConfig,
-	pauseSignal: { paused: boolean },
+	pauseSignal: PauseSignal,
 ): Promise<LaneRunnerTaskResult> {
 	const startTime = Date.now();
 	const statusPath = unit.packet.statusPath;
@@ -381,6 +571,380 @@ export async function executeTaskV2(
 	const segmentId = unit.segmentId;
 	const workerAgentId = buildRuntimeAgentId(config.agentIdPrefix, config.laneNumber, "worker");
 
+	// ── Live outbox surfacing (mail-recognition fix) ─────────────────
+	// Worker reply/escalate mail (notify_supervisor / escalate_to_supervisor
+	// → *.msg.json) must reach the supervisor WHILE the worker is still
+	// running — e.g. a worker asking for help to break a review spiral. The
+	// original code only read the outbox AFTER the worker subprocess exited
+	// (post-exit block below), so mid-run mail sat unread until exit and the
+	// supervisor "woke up" too late. This helper surfaces + acks each pending
+	// reply/escalate message; it runs on a live timer during the worker run
+	// (see the interval around `await spawned.promise`) AND once more after
+	// exit as a final drain. Acking (ackOutboxMessage) moves each message to
+	// processed/, so the live timer and the post-exit drain never
+	// double-surface the same message. Re-entrancy guarded so a slow cycle
+	// can't overlap the next tick.
+	let outboxDraining = false;
+	const drainAndSurfaceOutbox = (): void => {
+		if (outboxDraining) return;
+		outboxDraining = true;
+		try {
+			const outboxMessages = readOutbox(config.stateRoot, config.batchId, workerAgentId);
+			for (const msg of outboxMessages) {
+				const sanitized = msg.content.replace(/\r?\n/g, " / ").slice(0, 200);
+				logExecution(statusPath, `Agent ${msg.type}`, sanitized);
+
+				if (msg.type === "reply" || msg.type === "escalate") {
+					appendAgentEvent(config.stateRoot, config.batchId, workerAgentId, {
+						batchId: config.batchId,
+						agentId: workerAgentId,
+						role: "worker",
+						laneNumber: config.laneNumber,
+						taskId,
+						repoId: config.repoId,
+						ts: Date.now(),
+						type: msg.type === "reply" ? "reply_sent" : "escalation_sent",
+						payload: {
+							messageId: msg.id,
+							replyTo: msg.replyTo ?? null,
+							content: sanitized,
+						},
+					});
+
+					appendMailboxAuditEvent(config.stateRoot, config.batchId, {
+						type: msg.type === "reply" ? "message_replied" : "message_escalated",
+						from: workerAgentId,
+						to: "supervisor",
+						messageId: msg.id,
+						messageType: msg.type,
+						contentPreview: sanitized,
+					});
+
+					if (msg.type === "escalate" && msg.timestamp > lastSupervisorReplyTs) {
+						// #630: the worker is now waiting for a ruling. Remember it so an
+						// exit before a reply is treated as a hold, not a premature stop.
+						// Causal timestamp = the message's own creation time (a reply created after
+						// the escalation but before this drain must still count as a ruling).
+						// An escalation older than the last reply we saw was already answered
+						// (e.g. consumed by the exit-intercept before this drain) — no hold.
+						pendingEscalation = { id: msg.id, ts: msg.timestamp, preview: sanitized };
+					}
+					if (config.onSupervisorAlert) {
+						const isEscalation = msg.type === "escalate";
+						try {
+							config.onSupervisorAlert({
+								category: "agent-message",
+								summary:
+									`${isEscalation ? "\uD83D\uDEA8" : "\uD83D\uDCE8"} Agent ${isEscalation ? "escalation" : "reply"} from ${workerAgentId}\n` +
+									`  Task: ${taskId}\n` +
+									`  Lane: lane-${config.laneNumber}\n` +
+									`  Message: ${sanitized}`,
+								context: {
+									taskId,
+									laneId: `lane-${config.laneNumber}`,
+									laneNumber: config.laneNumber,
+									agentId: workerAgentId,
+									messageId: msg.id,
+									exitReason: `${isEscalation ? "agent_escalation" : "agent_reply"}: ${sanitized}`,
+								},
+							});
+						} catch {
+							/* best effort */
+						}
+					}
+				}
+
+				// Consume outbox message to prevent duplicate processing by the
+				// next live tick or the post-exit final drain.
+				ackOutboxMessage(config.stateRoot, config.batchId, workerAgentId, msg.id);
+			}
+		} catch {
+			/* best effort */
+		} finally {
+			outboxDraining = false;
+		}
+	};
+
+	// ── Review-boundary bridge + spiral detection (supervisor notifications) ──
+	// agent-host emits per-agent RuntimeAgentEvents review_requested /
+	// review_completed / review_failed as the worker calls the review_step tool.
+	// This handler: (1) bridges every boundary to the supervisor's live
+	// events.jsonl stream (emitEngineEvent) enriched with finding counts + trend
+	// + round, so the supervisor adjudicates each review case-by-case; and
+	// (2) tracks per-step spiral state and fires an actionable escalation
+	// (review-intervention-needed) when a step's reviews circle without
+	// converging, or when the worker trips the order-of-operations guard (REFUSED).
+	const reviewSeverityLabels =
+		config.reviewSeverityLabels && config.reviewSeverityLabels.length > 0
+			? config.reviewSeverityLabels
+			: DEFAULT_SEVERITY_LABELS;
+	// Sanitize (clamp threshold/cooldown >= 1, coerce booleans) so malformed
+	// config threaded via env can't cause escalate-every-review or nag-every-round.
+	// NOTE: `enabled` is the master switch for BOTH spiral and order-violation
+	// STEER escalations. When disabled, REFUSED/spiral still appear as ordinary
+	// per-boundary notifications (formatEventNotification) — just not as urgent
+	// steer interrupts.
+	const spiralCfg = sanitizeSpiralConfig(config.reviewSpiral);
+	const reviewStateByStep = new Map<string, ReviewStepState>();
+	// Resume reconstruction ("maintain the truth"): rebuild per-step streak state
+	// by replaying this task's prior review boundaries from events.jsonl, so a
+	// spiral in progress before a pause/resume isn't silently reset to zero.
+	seedReviewStateFromHistory(
+		reviewStateByStep,
+		config.stateRoot,
+		config.batchId,
+		taskId,
+		spiralCfg.treatUnavailableAsNonApprove,
+	);
+	const getReviewState = (stepKey: string): ReviewStepState => {
+		let st = reviewStateByStep.get(stepKey);
+		if (!st) {
+			st = { ...freshReviewStreakState(), lastEscalationRound: null, lastRefusedRound: null };
+			reviewStateByStep.set(stepKey, st);
+		}
+		return st;
+	};
+	// Read + parse finding counts from the exact review file agent-host referenced.
+	// Read the exact review file agent-host referenced (best-effort). Reused for
+	// both the authoritative verdict (#624) and the severity finding counts.
+	const readReviewFile = (reviewPath?: string): string | null => {
+		if (!reviewPath) return null;
+		try {
+			const abs = join(unit.packet.reviewsDir, basename(reviewPath));
+			if (!existsSync(abs)) return null;
+			return readFileSync(abs, "utf-8");
+		} catch {
+			return null;
+		}
+	};
+	// Fire an actionable review-intervention escalation. Delivery is set to steer
+	// (urgent) by category in the IPC handler (extension.ts).
+	const fireIntervention = (
+		kind: ReviewInterventionKind,
+		stepNum: number | undefined,
+		reviewType: string | undefined,
+		state: ReviewStepState,
+		ev: EngineEvent,
+	): void => {
+		if (!config.onSupervisorAlert) return;
+		const loc = `${taskId}${stepNum !== undefined ? ` step ${stepNum}` : ""} (lane ${config.laneNumber})`;
+		const label = ev.reviewLabel ? ` [${ev.reviewLabel}]` : "";
+		const countsStr = ev.findingCounts
+			? Object.entries(ev.findingCounts)
+					.map(([k, v]) => `${k}:${v}`)
+					.join(" ")
+			: "n/a";
+		const summary =
+			kind === "revision-spiral"
+				? `🌀 **Review spiral** — ${loc}${label}: ${state.consecutiveNonApprove} consecutive ` +
+					`non-approve reviews (latest ${ev.disposition ?? "?"}). Findings: ${countsStr}; ` +
+					`severity trend ${ev.findingTrend ?? "?"}${ev.findingMixed ? " (mixed)" : ""}.\n` +
+					`Adjudicate: steer the worker to a resolution — implement the remaining legitimate ` +
+					`findings, or if the reviews are circling the same class, tell it to stop and log a blocker.`
+				: `⛔ **Review order violation** — ${loc}${label}: the worker marked the step complete ` +
+					`before code review ran (REFUSED). Steer it to revert the premature completion and ` +
+					`re-review, or log a blocker.`;
+		const alert: SupervisorAlert = {
+			category: "review-intervention-needed",
+			summary,
+			context: {
+				taskId,
+				laneId: `lane-${config.laneNumber}`,
+				laneNumber: config.laneNumber,
+				agentId: workerAgentId,
+				reviewInterventionKind: kind,
+				reviewStep: stepNum,
+				reviewType,
+				reviewRound: ev.reviewRound,
+				reviewLabel: ev.reviewLabel,
+				disposition: ev.disposition,
+				recentDispositions: [...state.recentDispositions],
+				consecutiveNonApprove: state.consecutiveNonApprove,
+				findingCounts: ev.findingCounts,
+				findingTrend: ev.findingTrend,
+				findingDeltas: ev.findingDeltas,
+				findingMixed: ev.findingMixed,
+			},
+		};
+		try {
+			config.onSupervisorAlert(alert);
+		} catch {
+			/* best effort */
+		}
+	};
+
+	// Idempotency for END boundaries (Penster feedback on #632: a duplicate
+	// review_completed for R002 reached the supervisor). Whatever the upstream
+	// cause — a retried tool turn, a re-invoked review_step for the same round,
+	// or a doubled RPC event — one REVIEW FILE is one review: the second end
+	// boundary for the same (step, reviewType, reviewPath) must neither notify
+	// again nor advance the spiral streak again (which would fire the spiral a
+	// round early). Keyed by the resolved review path; falls back to the raw
+	// event identity when no path is known.
+	const seenReviewEnds = new Set<string>();
+	const bridgeReviewEvent = (evt: RuntimeAgentEvent): void => {
+		if (
+			evt.type !== "review_requested" &&
+			evt.type !== "review_completed" &&
+			evt.type !== "review_failed"
+		) {
+			return;
+		}
+		const payload = (evt.payload ?? {}) as {
+			step?: unknown;
+			reviewType?: unknown;
+			disposition?: unknown;
+			reviewPath?: unknown;
+		};
+		const stepNum = typeof payload.step === "number" ? payload.step : undefined;
+		const reviewType = typeof payload.reviewType === "string" ? payload.reviewType : undefined;
+		const payloadDisposition =
+			typeof payload.disposition === "string" ? (payload.disposition as ReviewDisposition) : undefined;
+		const reviewPath = typeof payload.reviewPath === "string" ? payload.reviewPath : undefined;
+		const isEnd = evt.type !== "review_requested";
+
+		// #624: the review FILE's `## Verdict:` is the authoritative disposition,
+		// overriding the upstream tool-return parse (which can miss on structured
+		// results). Read the file ONCE here; reused for finding counts below.
+		const reviewMd = isEnd ? readReviewFile(reviewPath) : null;
+		const fileVerdict = parseReviewVerdict(reviewMd);
+		const disposition = fileVerdict ?? payloadDisposition;
+
+		if (isEnd) {
+			const key = reviewPath
+				? `${stepNum ?? "?"}:${reviewType ?? "?"}:${reviewPath}`
+				: `${stepNum ?? "?"}:${reviewType ?? "?"}:${evt.ts}:${disposition ?? "?"}`;
+			if (seenReviewEnds.has(key)) {
+				logExecution(
+					statusPath,
+					"Duplicate review boundary",
+					`ignored repeated ${evt.type} for ${key.slice(0, 120)} (idempotency, one review file = one review)`,
+				);
+				return;
+			}
+			seenReviewEnds.add(key);
+		}
+
+		// Classify by the RESOLVED disposition: only a genuine UNAVAILABLE / total
+		// parse-miss (no verdict in the tool return AND none on disk) is
+		// review_failed. A real verdict — including one recovered from the file — is
+		// review_completed. This is what prevents the spurious "Reviewer
+		// unavailable" on every successful review (#624).
+		const engineType: EngineEventType = !isEnd
+			? "review_started"
+			: disposition === "UNAVAILABLE" || disposition === "UNKNOWN" || disposition === undefined
+				? "review_failed"
+				: "review_completed";
+
+		const engineEvent: EngineEvent = {
+			timestamp: new Date().toISOString(),
+			type: engineType,
+			batchId: config.batchId,
+			waveIndex: -1,
+			phase: "executing",
+			taskId,
+			laneNumber: config.laneNumber,
+			agentId: workerAgentId,
+			reviewStep: stepNum,
+			reviewType,
+			disposition,
+			reviewPath,
+		};
+
+		// Detection + enrichment on END boundaries (completed/failed) with a step.
+		if (isEnd && stepNum !== undefined) {
+			const state = getReviewState(`${taskId}:${stepNum}`);
+			const counts = reviewMd ? parseFindingCounts(reviewMd, reviewSeverityLabels) : {};
+			const hasCounts = Object.keys(counts).length > 0;
+			// Trend compares the PRIOR round's counts to this round's, so compute it
+			// BEFORE advancing the streak (which overwrites lastCounts). Semantics:
+			// a countless round (e.g. APPROVE, or an unparseable review) preserves the
+			// prior lastCounts, so the NEXT counted round trends vs the last COUNTED
+			// round — intentional, so a single missing review file doesn't blank the
+			// severity trend the supervisor relies on.
+			const trendRes = computeFindingTrend(state.lastCounts, counts, reviewSeverityLabels);
+			// Shared streak transition (round++, lastCounts, recentDispositions,
+			// consecutiveNonApprove) — identical to resume reconstruction.
+			advanceReviewStreak(state, {
+				disposition,
+				counts: hasCounts ? counts : null,
+				treatUnavailableAsNonApprove: spiralCfg.treatUnavailableAsNonApprove,
+				recentCap: RECENT_DISPOSITIONS_CAP,
+			});
+			engineEvent.reviewRound = state.round;
+			engineEvent.reviewLabel = parseReviewLabelFromPath(reviewPath);
+			if (hasCounts) {
+				engineEvent.findingCounts = counts;
+				engineEvent.findingTrend = trendRes.trend;
+				engineEvent.findingDeltas = trendRes.deltas;
+				engineEvent.findingMixed = trendRes.mixed;
+			}
+
+			// Live-only escalation (the streak counter was already advanced above).
+			if (disposition === "APPROVE") {
+				state.lastEscalationRound = null; // a fresh streak may escalate again
+			} else if (
+				disposition === "REVISE" ||
+				disposition === "RETHINK" ||
+				(disposition === "UNAVAILABLE" && spiralCfg.treatUnavailableAsNonApprove)
+			) {
+				maybeFireSpiral(stepNum, reviewType, state, engineEvent);
+			} else if (disposition === "REFUSED") {
+				// Orthogonal failure mode: does NOT touch the REVISE/RETHINK streak.
+				maybeFireOrderViolation(stepNum, reviewType, state, engineEvent);
+			}
+			// UNAVAILABLE (not counted) / UNKNOWN → no counter change.
+		}
+
+		const emit = (fn: (stateRoot: string, event: EngineEvent) => void): void => {
+			try {
+				fn(config.stateRoot, engineEvent);
+			} catch {
+				/* best effort — a bridge failure must never break the worker run */
+			}
+		};
+		// Cached lazy import (see the import-cycle note at the top of this file).
+		if (cachedEmitEngineEvent) {
+			emit(cachedEmitEngineEvent);
+		} else {
+			void import("./persistence.ts")
+				.then((m) => {
+					cachedEmitEngineEvent = m.emitEngineEvent;
+					emit(m.emitEngineEvent);
+				})
+				.catch(() => {
+					/* best effort */
+				});
+		}
+	};
+
+	// Spiral escalation: first fire at threshold; re-fire only if NOT converging
+	// (trend flat/rising) and the cooldown spacing has elapsed.
+	function maybeFireSpiral(
+		stepNum: number | undefined,
+		reviewType: string | undefined,
+		state: ReviewStepState,
+		ev: EngineEvent,
+	): void {
+		if (shouldFireSpiral(state, spiralCfg, ev.findingTrend)) {
+			fireIntervention("revision-spiral", stepNum, reviewType, state, ev);
+			state.lastEscalationRound = state.round;
+		}
+	}
+
+	// Order-violation escalation: actionable each occurrence, throttled by cooldown.
+	function maybeFireOrderViolation(
+		stepNum: number | undefined,
+		reviewType: string | undefined,
+		state: ReviewStepState,
+		ev: EngineEvent,
+	): void {
+		if (shouldFireOrderViolation(state, spiralCfg)) {
+			fireIntervention("order-violation", stepNum, reviewType, state, ev);
+			state.lastRefusedRound = state.round;
+		}
+	}
+
 	// ── 1. Ensure STATUS.md exists ──────────────────────────────────
 	if (!existsSync(statusPath)) {
 		const content = readFileSync(promptPath, "utf-8");
@@ -416,6 +980,35 @@ export async function executeTaskV2(
 
 	// ── 2. Iteration loop ───────────────────────────────────────────
 	let noProgressCount = 0;
+	// TP-145: Is this a non-final segment of a multi-segment task? If more
+	// segments follow, .DONE creation is suppressed after the loop so the engine
+	// can advance the segment frontier. Loop-invariant; also consulted by the
+	// #629 remediation spawn (the finalize gate never applies to a non-final
+	// segment).
+	const isNonFinalSegment =
+		segmentId != null &&
+		Array.isArray(unit.task.segmentIds) &&
+		unit.task.segmentIds.length > 1 &&
+		unit.task.segmentIds[unit.task.segmentIds.length - 1] !== segmentId;
+	/** #629: review-gate remediation iterations spent (bounded). */
+	let remediationIterations = 0;
+	/**
+	 * #630: the most recent escalation the worker filed that has NOT yet been
+	 * answered by a steer (set when surfaced; cleared when a steer is delivered
+	 * after it). While set, a clean worker exit is a HOLD exit, not a stall.
+	 */
+	let pendingEscalation: { id: string; ts: number; preview: string } | null = null;
+	/** #630: relaunches spent re-checking for a ruling (bounded). */
+	let holdRelaunches = 0;
+	/**
+	 * #630: creation timestamp of the most recent supervisor reply we have seen
+	 * (a steer delivered to the worker, or an instructional reply consumed by the
+	 * exit-intercept). An escalation drained LATER but CREATED before this reply
+	 * was already answered — it must not (re)create a hold.
+	 */
+	let lastSupervisorReplyTs = 0;
+	/** #629: gates the CURRENT iteration was spawned to remediate (empty = normal iteration). */
+	let remediationGates: BlockingReviewGate[] = [];
 	let totalIterations = 0;
 	let cumulativeCostUsd = 0;
 	let cumulativeTokens = 0;
@@ -434,14 +1027,28 @@ export async function executeTaskV2(
 				})()
 			: null;
 
-	for (let iter = 0; iter < config.maxIterations; iter++) {
+	// Productive-iteration budget. Hold exits (worker idles awaiting a ruling)
+	// do NOT consume it — they are bounded separately (MAX_HOLD_RELAUNCHES,
+	// reset by acknowledgements). Without this, a correctly-holding lane hit
+	// maxIterations (10) inside an hour (penster 20260906T194514). Explicit
+	// counter rather than `iter--` so the two budgets stay legible.
+	let productiveIterations = 0;
+	for (; productiveIterations < config.maxIterations; productiveIterations++) {
 		if (pauseSignal.paused) {
-			logExecution(statusPath, "Paused", `User paused at iteration ${totalIterations}`);
+			// A pause is NOT a terminal outcome. Returning "skipped" here converted a
+			// correctly-holding task into a skipped one and let a single-wave batch
+			// complete 0/1 and clean up its worktree (penster 20260906T194514).
+			// "pending" keeps the task re-executable on resume in this worktree.
+			logExecution(
+				statusPath,
+				"Paused",
+				`Paused at iteration ${totalIterations} — task remains pending`,
+			);
 			return makeResult(
 				taskId,
 				segmentId,
 				workerAgentId,
-				"skipped",
+				"pending",
 				startTime,
 				"Paused by user",
 				false,
@@ -475,7 +1082,7 @@ export async function executeTaskV2(
 		// TP-174: Read STATUS.md content once for segment-scoped checks
 		const iterStatusContent = readFileSync(statusPath, "utf-8");
 
-		const remainingSteps = parsed.steps.filter((step) => {
+		let remainingSteps = parsed.steps.filter((step) => {
 			// TP-174: When segment-scoped, only show steps that have work for this repoId
 			if (repoStepNumbers && !repoStepNumbers.has(step.number)) return false;
 			// TP-174: Use segment-scoped completion check in segment mode
@@ -486,7 +1093,45 @@ export async function executeTaskV2(
 			return !isStepComplete(ss);
 		});
 
-		if (remainingSteps.length === 0) break; // All done
+		// ── #629: review-gate remediation spawn ─────────────────────
+		// All checkboxes checked, but would the finalize gate refuse? If a gate's
+		// latest review is REVISE/RETHINK, breaking here means retry+resume never
+		// launches a worker and the refusal simply repeats. Spawn a bounded
+		// remediation iteration instead: the worker addresses the findings and
+		// re-runs review_step to obtain an APPROVE. Segment-scoped iterations
+		// (non-final segments) never finalize, so the gate does not apply there.
+		remediationGates = [];
+		if (remainingSteps.length === 0) {
+			const isFinalizingIteration = !isNonFinalSegment;
+			const blocking = isFinalizingIteration ? findBlockingReviewGates(unit.packet.reviewsDir) : [];
+			if (blocking.length === 0) break; // All done
+			if (remediationIterations >= MAX_REVIEW_REMEDIATION_ITERATIONS) {
+				logExecution(
+					statusPath,
+					"Review remediation exhausted",
+					`${remediationIterations} remediation iteration(s) did not clear: ${formatBlockingGates(blocking)}`,
+				);
+				break; // fall through to the finalize gate, which refuses with the alert
+			}
+			remediationIterations++;
+			remediationGates = blocking;
+			// Give the iteration an explicit focus step — the step of the first
+			// blocking gate (falling back to the last step) — so every downstream
+			// `remainingSteps[0]` consumer (Current Step field, prompt, checkbox
+			// counting) has a real step to point at. The step is NOT re-marked
+			// in-progress and its checkboxes are untouched.
+			const focusStepNumber = parseGateStepNumber(blocking[0].gate);
+			const focusStep =
+				parsed.steps.find((st) => st.number === focusStepNumber) ??
+				parsed.steps[parsed.steps.length - 1];
+			remainingSteps = focusStep ? [focusStep] : [];
+			if (remainingSteps.length === 0) break; // task has no parseable steps — nothing to remediate
+			logExecution(
+				statusPath,
+				"Review remediation",
+				`all checkboxes complete but latest review is not APPROVE — spawning remediation iteration ${remediationIterations}/${MAX_REVIEW_REMEDIATION_ITERATIONS}: ${formatBlockingGates(blocking)}`,
+			);
+		}
 
 		// TP-196 / #508: Pre-spawn segment-completion check.
 		//
@@ -500,7 +1145,10 @@ export async function executeTaskV2(
 		//      `repoStepNumbers` diverge (e.g., legacy/partial-marker tasks).
 		//   3. Gives behavioural tests a clean assertion target (via the pure
 		//      helper `shouldSkipSpawnForCompleteSegment`).
-		if (shouldSkipSpawnForCompleteSegment(iterStatusContent, repoStepNumbers, currentRepoId)) {
+		if (
+			remediationGates.length === 0 &&
+			shouldSkipSpawnForCompleteSegment(iterStatusContent, repoStepNumbers, currentRepoId)
+		) {
 			logExecution(
 				statusPath,
 				"Pre-spawn segment-completion check",
@@ -513,14 +1161,17 @@ export async function executeTaskV2(
 		updateStatusField(
 			statusPath,
 			"Current Step",
-			`Step ${remainingSteps[0].number}: ${remainingSteps[0].name}`,
+			remediationGates.length > 0
+				? `Review remediation — Step ${remainingSteps[0].number}: ${remainingSteps[0].name}`
+				: `Step ${remainingSteps[0].number}: ${remainingSteps[0].name}`,
 		);
 		updateStatusField(statusPath, "Iteration", `${totalIterations}`);
 
-		// Mark first incomplete step as in-progress
+		// Mark first incomplete step as in-progress (not during remediation: the
+		// focus step is already complete; its checkboxes/status stay untouched)
 		const firstStep = remainingSteps[0];
 		const firstStepStatus = currentStatus.steps.find((s) => s.number === firstStep.number);
-		if (firstStepStatus?.status !== "in-progress") {
+		if (remediationGates.length === 0 && firstStepStatus?.status !== "in-progress") {
 			updateStepStatus(statusPath, firstStep.number, "in-progress");
 			logExecution(statusPath, `Step ${firstStep.number} started`, firstStep.name);
 		}
@@ -679,7 +1330,42 @@ export async function executeTaskV2(
 			}
 		}
 
-		if (totalIterations > 1 && remainingSteps.length > 0) {
+		if (remediationGates.length > 0) {
+			promptLines.push(
+				``,
+				`⛔ REVIEW GATE OUTSTANDING — this task cannot finalize yet.`,
+				`All step checkboxes are checked, but the LATEST review for the following gate(s) is not APPROVE:`,
+				...remediationGates.map(
+					(g) =>
+						`  - ${g.gate}: ${g.filename} → ${g.verdict} (see ${join(unit.packet.reviewsDir, g.filename)})`,
+				),
+				``,
+				`Your job in this iteration: read each listed review file, address EVERY finding it raises`,
+				`(fix code, update docs/tests as required), commit, then call review_step for that step again`,
+				`to obtain a fresh review. Repeat until the latest review for each gate is APPROVE.`,
+				`Do NOT write .DONE and do NOT declare the task complete while any gate's latest verdict`,
+				`is REVISE or RETHINK — the runtime will refuse to finalize. Do NOT un-check or re-check`,
+				`step checkboxes. If a finding cannot be addressed, escalate_to_supervisor with specifics.`,
+			);
+		}
+
+		if (pendingEscalation && totalIterations > 1) {
+			// #630: the previous session exited while HOLDING for a ruling. The
+			// generic "you exited prematurely — work continuously" nag is the WRONG
+			// prompt here: it pushes a correctly-holding worker toward self-release
+			// (the TP-2037 class). Give a hold-resume prompt instead.
+			const ago = Math.max(1, Math.round((Date.now() - pendingEscalation.ts) / 60_000));
+			promptLines.push(
+				``,
+				`⏸️ YOU ARE ON HOLD awaiting a supervisor ruling.`,
+				`You escalated ${ago} min ago (escalation ${pendingEscalation.id}: "${pendingEscalation.preview.slice(0, 160)}").`,
+				`If a supervisor reply is delivered to you at the start of this session (as a steering message), act on it.`,
+				`If NO reply (or only an acknowledgement) has arrived: do NOT proceed past the hold, do NOT self-approve or`,
+				`write .DONE, and do NOT re-send the escalation. Work on anything that does not depend on the ruling`,
+				`(other remediable findings, unaffected checkboxes); otherwise add a one-line status note with`,
+				`notify_supervisor(replyTo="${pendingEscalation.id}") and end your turn; the runtime will relaunch you to re-check.`,
+			);
+		} else if (remediationGates.length === 0 && totalIterations > 1 && remainingSteps.length > 0) {
 			const remainingSet = new Set(remainingSteps.map((s) => s.number));
 			const completedSteps = parsed.steps.filter((s) => !remainingSet.has(s.number));
 			promptLines.push(
@@ -753,6 +1439,9 @@ export async function executeTaskV2(
 			thinking: config.workerThinking || undefined,
 			mailboxDir,
 			steeringPendingPath,
+			// Safety race for one intercept must exceed the configured reply window.
+			exitInterceptSafetyMs:
+				(Math.min(1800, Math.max(15, config.exitInterceptTimeoutSec ?? 60)) + 60) * 1000,
 			eventsPath,
 			exitSummaryPath: eventsPath.replace(/\.jsonl$/, "-exit.json"),
 			timeoutMs: config.maxWorkerMinutes * 60_000,
@@ -919,10 +1608,15 @@ export async function executeTaskV2(
 							/* best effort — don't block on alert failure */
 						}
 
-						// Poll worker mailbox inbox for supervisor reply (60s timeout)
-						const SUPERVISOR_REPLY_TIMEOUT_MS = 60_000;
+						// Poll worker mailbox inbox for supervisor reply. Window is configurable
+						// (taskRunner.worker.exitInterceptTimeoutSec, default 60s): a supervisor
+						// inside a long tool call cannot answer in 60s (penster feedback #3).
+						const SUPERVISOR_REPLY_TIMEOUT_MS =
+							Math.min(1800, Math.max(15, config.exitInterceptTimeoutSec ?? 60)) * 1000;
 						const POLL_INTERVAL_MS = 2_000;
 						const escalationTimestamp = Date.now();
+						let acceptedReplyTs = 0;
+						let acceptedReplyType = "";
 						const inboxDir = sessionInboxDir(config.stateRoot, config.batchId, workerAgentId);
 
 						const supervisorReply = await new Promise<string | null>((resolve) => {
@@ -944,6 +1638,8 @@ export async function executeTaskV2(
 											} catch {
 												/* best effort */
 											}
+											acceptedReplyTs = message.timestamp;
+											acceptedReplyType = message.type;
 											resolve(message.content);
 											return;
 										}
@@ -997,6 +1693,21 @@ export async function executeTaskV2(
 							"Exit intercept reprompt",
 							`Supervisor provided instructions (${supervisorReply.length} chars) — reprompting worker`,
 						);
+						// #630: a supervisor reply consumed HERE never reaches .steering-pending
+						// (it is returned as the next prompt). It is the ruling: release the hold.
+						if (acceptedReplyType === "info" && pendingEscalation) {
+							// Acknowledgement consumed by the intercept: engaged, still holding.
+							holdRelaunches = 0;
+							logExecution(
+								statusPath,
+								"Hold acknowledged",
+								`supervisor acknowledged escalation ${pendingEscalation.id} (via exit-intercept); still holding`,
+							);
+						} else {
+							lastSupervisorReplyTs = Math.max(lastSupervisorReplyTs, acceptedReplyTs || Date.now());
+							pendingEscalation = null;
+							holdRelaunches = 0;
+						}
 						return supervisorReply;
 					}
 				: undefined,
@@ -1025,7 +1736,7 @@ export async function executeTaskV2(
 		let workerKillReason: "context" | "timer" | null = null;
 		let iterationTelemetry: Partial<AgentHostResult> = {};
 
-		const spawned = spawnAgent(hostOpts, undefined, (telemetry) => {
+		const spawned = spawnAgent(hostOpts, bridgeReviewEvent, (telemetry) => {
 			try {
 				// Context pressure check
 				if (telemetry.contextUsage) {
@@ -1090,11 +1801,17 @@ export async function executeTaskV2(
 			}
 		}, 1000);
 
+		// Live outbox surfacing during the worker run (mail-recognition fix):
+		// poll the worker's outbox on a timer so reply/escalate mail reaches the
+		// supervisor mid-run, not only after the worker exits.
+		const outboxLivePoll = setInterval(drainAndSurfaceOutbox, OUTBOX_LIVE_POLL_INTERVAL_MS);
+
 		let workerResult: AgentHostResult;
 		try {
 			workerResult = await spawned.promise;
 		} finally {
 			clearInterval(reviewerRefresh);
+			clearInterval(outboxLivePoll);
 		}
 
 		// TP-115: Update lastTelemetry with definitive final values from AgentHostResult
@@ -1116,70 +1833,11 @@ export async function executeTaskV2(
 			workerResult.cacheReadTokens +
 			workerResult.cacheWriteTokens;
 
-		// ── TP-106: Poll worker outbox for replies/escalations ─────
-		try {
-			const outboxMessages = readOutbox(config.stateRoot, config.batchId, workerAgentId);
-			for (const msg of outboxMessages) {
-				const sanitized = msg.content.replace(/\r?\n/g, " / ").slice(0, 200);
-				logExecution(statusPath, `Agent ${msg.type}`, sanitized);
-
-				if (msg.type === "reply" || msg.type === "escalate") {
-					appendAgentEvent(config.stateRoot, config.batchId, workerAgentId, {
-						batchId: config.batchId,
-						agentId: workerAgentId,
-						role: "worker",
-						laneNumber: config.laneNumber,
-						taskId,
-						repoId: config.repoId,
-						ts: Date.now(),
-						type: msg.type === "reply" ? "reply_sent" : "escalation_sent",
-						payload: {
-							messageId: msg.id,
-							replyTo: msg.replyTo ?? null,
-							content: sanitized,
-						},
-					});
-
-					appendMailboxAuditEvent(config.stateRoot, config.batchId, {
-						type: msg.type === "reply" ? "message_replied" : "message_escalated",
-						from: workerAgentId,
-						to: "supervisor",
-						messageId: msg.id,
-						messageType: msg.type,
-						contentPreview: sanitized,
-					});
-
-					if (config.onSupervisorAlert) {
-						const isEscalation = msg.type === "escalate";
-						try {
-							config.onSupervisorAlert({
-								category: "agent-message",
-								summary:
-									`${isEscalation ? "🚨" : "📨"} Agent ${isEscalation ? "escalation" : "reply"} from ${workerAgentId}\n` +
-									`  Task: ${taskId}\n` +
-									`  Lane: lane-${config.laneNumber}\n` +
-									`  Message: ${sanitized}`,
-								context: {
-									taskId,
-									laneId: `lane-${config.laneNumber}`,
-									laneNumber: config.laneNumber,
-									agentId: workerAgentId,
-									messageId: msg.id,
-									exitReason: `${isEscalation ? "agent_escalation" : "agent_reply"}: ${sanitized}`,
-								},
-							});
-						} catch {
-							/* best effort */
-						}
-					}
-				}
-
-				// Consume outbox message to prevent duplicate processing in later iterations.
-				ackOutboxMessage(config.stateRoot, config.batchId, workerAgentId, msg.id);
-			}
-		} catch {
-			/* best effort */
-		}
+		// ── TP-106 / mail-recognition: final outbox drain ────────────
+		// Surface any reply/escalate mail written between the last live poll and
+		// worker exit. Live-surfaced messages were already acked, so this never
+		// double-surfaces them.
+		drainAndSurfaceOutbox();
 
 		// ── Steering annotation ─────────────────────────────────────
 		try {
@@ -1187,10 +1845,34 @@ export async function executeTaskV2(
 				const raw = readFileSync(steeringPendingPath, "utf-8");
 				for (const line of raw.split("\n").filter((l) => l.trim())) {
 					try {
-						const entry = JSON.parse(line) as { ts: number; content: string; id: string };
+						const entry = JSON.parse(line) as { ts: number; content: string; id: string; type?: string };
 						const sanitized = entry.content.replace(/\r?\n/g, " / ").replace(/\|/g, "\\|").slice(0, 200);
 						const ts = new Date(entry.ts).toISOString().slice(0, 16).replace("T", " ");
 						logExecution(statusPath, "⚠️ Steering", sanitized);
+						// #630: a steer delivered AFTER the escalation counts as the ruling
+						// (delivery, not content, is what we can observe here).
+						// #630 contract: an `info` message is an ACKNOWLEDGEMENT ("received,
+						// ruling pending") — the supervisor is engaged, so the relaunch counter
+						// resets, but the worker is still holding. Any other type (steer/query/
+						// abort) is the ruling/instruction and releases the hold. This is what
+						// lets an hours-long operator ruling neither burn the relaunch budget
+						// nor be mistaken for a ruling.
+						if (entry.type === "info") {
+							if (pendingEscalation && entry.ts >= pendingEscalation.ts) {
+								holdRelaunches = 0;
+								logExecution(
+									statusPath,
+									"Hold acknowledged",
+									`supervisor acknowledged escalation ${pendingEscalation.id}; still holding`,
+								);
+							}
+						} else {
+							lastSupervisorReplyTs = Math.max(lastSupervisorReplyTs, entry.ts);
+							if (pendingEscalation && entry.ts >= pendingEscalation.ts) {
+								pendingEscalation = null;
+								holdRelaunches = 0;
+							}
+						}
 					} catch {
 						/* skip malformed */
 					}
@@ -1227,6 +1909,73 @@ export async function executeTaskV2(
 		const progressDelta = afterTotalChecked - prevTotalChecked;
 
 		if (progressDelta <= 0) {
+			// #630: a clean exit while HOLDING for a supervisor ruling is evaluated
+			// FIRST — before the cumulative soft-progress check, which would otherwise
+			// let pre-existing uncommitted work mask every hold exit as "progress" and
+			// defeat the bounded relaunch contract.
+			if (pendingEscalation && workerResult.exitCode === 0 && !workerResult.killed) {
+				// #630: the worker exited cleanly while HOLDING for a supervisor ruling
+				// (escalation surfaced, no steer delivered since). That is governance,
+				// not a stall: do not count it toward the no-progress limit. Bounded by
+				// MAX_HOLD_RELAUNCHES; each relaunch re-checks for the ruling.
+				holdRelaunches++;
+				logExecution(
+					statusPath,
+					"Hold exit",
+					`Iteration ${totalIterations}: worker exited while awaiting a ruling for escalation ${pendingEscalation.id} (relaunch ${holdRelaunches}/${MAX_HOLD_RELAUNCHES}) — not counted toward stall`,
+				);
+				if (holdRelaunches > MAX_HOLD_RELAUNCHES) {
+					const reason = `Hold unresolved: escalation ${pendingEscalation.id} ("${pendingEscalation.preview.slice(0, 120)}") received no supervisor reply across ${MAX_HOLD_RELAUNCHES} relaunches`;
+					logExecution(statusPath, "Task blocked", reason);
+					updateStatusField(statusPath, "Status", "⏸️ Held — ruling outstanding");
+					if (config.onSupervisorAlert) {
+						try {
+							config.onSupervisorAlert({
+								category: "task-failure",
+								summary:
+									`⏸️ **Hold unresolved** — ${taskId} (lane ${config.laneNumber}) escalated for a ruling ` +
+									`(${pendingEscalation.id}: "${pendingEscalation.preview.slice(0, 160)}") and no reply reached it across ` +
+									`${MAX_HOLD_RELAUNCHES} relaunches. The lane is stopping with the work preserved in its worktree.\n` +
+									`Rule on the escalation, then orch_retry_task + orch_resume(force=true) to relaunch the worker ` +
+									`(it will receive your reply as a steer at start).`,
+								context: {
+									taskId,
+									laneId: `lane-${config.laneNumber}`,
+									laneNumber: config.laneNumber,
+									agentId: workerAgentId,
+									messageId: pendingEscalation.id,
+									exitReason: reason,
+								},
+							});
+						} catch {
+							/* best effort */
+						}
+					}
+					return makeResult(
+						taskId,
+						segmentId,
+						workerAgentId,
+						"failed",
+						startTime,
+						reason,
+						false,
+						totalIterations,
+						cumulativeCostUsd,
+						cumulativeTokens,
+						config,
+						statusPath,
+						reviewerStatePath,
+						lastTelemetry,
+						snapshotSegmentCtx,
+					);
+				}
+
+				// Not exhausted: this exit is accounted as a hold, not as progress or a stall,
+				// and it does not consume a productive iteration.
+				productiveIterations--;
+				continue;
+			}
+
 			// Check for soft progress: uncommitted changes in the worktree
 			// indicate the worker is actively editing code even if no checkbox
 			// was checked yet. This avoids false stall detection on complex
@@ -1258,6 +2007,16 @@ export async function executeTaskV2(
 					`Iteration ${totalIterations}: 0 new checkboxes but uncommitted source changes detected — not counting as stall`,
 				);
 				noProgressCount = 0;
+			} else if (remediationGates.length > 0) {
+				// #629: a review-remediation iteration checks 0 new boxes BY DESIGN
+				// (its output is a fresh review file, not a checkbox). It is bounded
+				// separately by MAX_REVIEW_REMEDIATION_ITERATIONS — do not count it
+				// toward the no-progress stall limit.
+				logExecution(
+					statusPath,
+					"Remediation iteration",
+					`Iteration ${totalIterations}: review-gate remediation — not counted toward stall`,
+				);
 			} else {
 				noProgressCount++;
 				logExecution(
@@ -1324,23 +2083,43 @@ export async function executeTaskV2(
 		// Mark completed steps
 		// TP-174: When segment-scoped, mark step complete when the segment's
 		// checkboxes are all checked (not the full step which may have other segments).
+		//
+		// Review-gated (penster 20260906T194514 feedback #3, item 4): a step whose
+		// LATEST review is REVISE/RETHINK must NOT be flipped to ✅ Complete just
+		// because its checkboxes are checked — the worker correctly reverts it to
+		// In Progress per the recovery recipe, this heuristic flipped it back on
+		// every relaunch (a phantom uncommitted STATUS edit "never authored by the
+		// worker"), and the flip trips review_step's complete-step guard. Same rule
+		// as the finalize gate.
+		const reviewBlockedSteps = new Set(
+			findBlockingReviewGates(unit.packet.reviewsDir)
+				.map((g) => parseGateStepNumber(g.gate))
+				.filter((n): n is number => n !== null),
+		);
+		const markComplete = (stepNum: number) => {
+			if (reviewBlockedSteps.has(stepNum)) {
+				logExecution(
+					statusPath,
+					"Step completion withheld",
+					`Step ${stepNum}: checkboxes complete but latest review is REVISE/RETHINK — not marking ✅ Complete`,
+				);
+				return;
+			}
+			updateStepStatus(statusPath, stepNum, "complete");
+		};
 		if (repoStepNumbers && currentRepoId) {
 			for (const stepNum of repoStepNumbers) {
 				if (isSegmentComplete(afterStatusContent, stepNum, currentRepoId)) {
 					// Only mark step complete in STATUS.md if ALL segments in that step
 					// are complete (not just ours). But for loop exit, we only care about ours.
 					const ss = afterStatus.steps.find((s) => s.number === stepNum);
-					if (isStepComplete(ss)) {
-						updateStepStatus(statusPath, stepNum, "complete");
-					}
+					if (isStepComplete(ss)) markComplete(stepNum);
 				}
 			}
 		} else {
 			for (const step of parsed.steps) {
 				const ss = afterStatus.steps.find((s) => s.number === step.number);
-				if (isStepComplete(ss)) {
-					updateStepStatus(statusPath, step.number, "complete");
-				}
+				if (isStepComplete(ss)) markComplete(step.number);
 			}
 		}
 
@@ -1358,7 +2137,18 @@ export async function executeTaskV2(
 				return isStepComplete(ss);
 			});
 		}
-		if (allComplete) break;
+		if (allComplete) {
+			// #629: all boxes checked — but if a finalizing task still has an
+			// outstanding non-APPROVE gate and remediation budget remains, loop
+			// back so the top-of-loop check spawns a remediation iteration
+			// instead of falling straight into the finalize refusal.
+			// (The top-of-loop check owns the budget decision and the
+			// "exhausted" log, so defer to it whenever a gate is outstanding.)
+			if (!isNonFinalSegment && findBlockingReviewGates(unit.packet.reviewsDir).length > 0) {
+				continue;
+			}
+			break;
+		}
 	}
 
 	// ── 3. Post-loop completion check ───────────────────────────────
@@ -1425,15 +2215,10 @@ export async function executeTaskV2(
 		);
 	}
 
-	// TP-145: Determine if this is a non-final segment of a multi-segment task.
-	// If more segments remain after this one, suppress .DONE creation so that
-	// the engine can advance the segment frontier and execute subsequent segments.
-	// .DONE must only exist when ALL segments of a multi-segment task are complete.
-	const isNonFinalSegment =
-		segmentId != null &&
-		Array.isArray(unit.task.segmentIds) &&
-		unit.task.segmentIds.length > 1 &&
-		unit.task.segmentIds[unit.task.segmentIds.length - 1] !== segmentId;
+	// TP-145: `isNonFinalSegment` (hoisted above the iteration loop) — if more
+	// segments remain after this one, suppress .DONE creation so the engine can
+	// advance the segment frontier. .DONE must only exist when ALL segments of
+	// a multi-segment task are complete.
 
 	// TP-165: Check for pending expansion requests in the worker's outbox.
 	// If the worker filed expansion requests, more segments may be added by the
@@ -1496,6 +2281,95 @@ export async function executeTaskV2(
 		);
 	}
 
+	// ── #626 minimal finalize gate: no .DONE over an outstanding REVISE ───
+	// Two live incidents merged unreviewed code: a worker self-released past a
+	// REVISE cap and wrote .DONE (TP-2037), and this very checkbox heuristic
+	// wrote .DONE for a correctly-holding worker (TP-2039). The gate: for each
+	// review gate ({type}-step{N}), the LATEST review file's verdict must not be
+	// REVISE/RETHINK. A re-review (higher R number) with APPROVE — or an
+	// operator ratification recorded as the next R-numbered review file — clears
+	// it. Steps with no reviews at all are not blocked here (full coverage gate
+	// is #626's designed follow-up).
+	const blockingGates = findBlockingReviewGates(unit.packet.reviewsDir);
+
+	if (blockingGates.length > 0) {
+		// Remove any worker-written .DONE (precedent: premature-.DONE removal in
+		// the non-final-segment path above).
+		if (existsSync(donePath)) {
+			try {
+				unlinkSync(donePath);
+			} catch {
+				/* best effort */
+			}
+		}
+		const gateList = formatBlockingGates(blockingGates);
+		logExecution(
+			statusPath,
+			"Finalize refused",
+			`Review gate: latest verdict is not APPROVE — ${gateList}`,
+		);
+		if (config.onSupervisorAlert) {
+			try {
+				config.onSupervisorAlert({
+					category: "review-intervention-needed",
+					summary:
+						`⛔ **Finalize refused** — ${taskId} (lane ${config.laneNumber}) attempted to ` +
+						`complete with an outstanding non-APPROVE review: ${gateList}.\n` +
+						`The task is marked failed instead of finalizing over the unresolved verdict. ` +
+						`Adjudicate: have the worker address the findings and re-run review_step ` +
+						`(orch_retry_task + orch_resume), or record an operator ratification as the ` +
+						`next R-numbered review file with an explicit APPROVE verdict.`,
+					context: {
+						taskId,
+						laneId: `lane-${config.laneNumber}`,
+						laneNumber: config.laneNumber,
+						agentId: workerAgentId,
+						reviewInterventionKind: "unresolved-verdict",
+						exitReason: `finalize refused: ${gateList}`,
+					},
+				});
+			} catch {
+				/* best effort */
+			}
+		}
+		const refusal = makeResult(
+			taskId,
+			segmentId,
+			workerAgentId,
+			"failed",
+			startTime,
+			`Review gate: cannot finalize — latest review verdict is not APPROVE (${gateList})`,
+			false,
+			totalIterations,
+			cumulativeCostUsd,
+			cumulativeTokens,
+			config,
+			statusPath,
+			reviewerStatePath,
+			lastTelemetry,
+			snapshotSegmentCtx,
+		);
+		// #629 side-effect 1: a governance refusal is NOT a crash. Attach a
+		// structured diagnostic so tier-0 auto-retry, reports and the dashboard
+		// can tell it apart (the worker exited cleanly; the review file must
+		// change before a retry can succeed).
+		const refusalDiagnostic: TaskExitDiagnostic = {
+			classification: "review_gate_refusal",
+			exitCode: 0,
+			errorMessage: `finalize refused: ${gateList}`,
+			tokensUsed: null,
+			contextPct: null,
+			partialProgressCommits: 0,
+			partialProgressBranch: null,
+			durationSec: Math.round((Date.now() - startTime) / 1000),
+			lastKnownStep: null,
+			lastKnownCheckbox: null,
+			repoId: config.repoId ?? "default",
+		};
+		refusal.outcome.exitDiagnostic = refusalDiagnostic;
+		return refusal;
+	}
+
 	// Create .DONE if not already present (final segment or single-segment/whole-task execution)
 	if (!existsSync(donePath)) {
 		writeFileSync(donePath, `Completed: ${new Date().toISOString()}\nTask: ${taskId}\n`);
@@ -1553,6 +2427,8 @@ export function mapLaneTaskStatusToTerminalSnapshotStatus(
 ): "idle" | "complete" | "failed" {
 	if (status === "succeeded") return "complete";
 	if (status === "skipped") return "idle";
+	// A paused (pending) task is not a failure — the lane is idle awaiting resume.
+	if (status === "pending") return "idle";
 	return "failed";
 }