taskplane 0.30.4 → 0.30.6

package/extensions/taskplane/extension.ts

@@ -26,6 +26,7 @@ import {
 	StateFileError,
 	WorkspaceConfigError,
 	freshOrchBatchState,
+	generateBatchId,
 } from "./types.ts";
 import type {
 	AbortMode,
@@ -44,6 +45,7 @@ import {
 	loadBatchState,
 	saveBatchState,
 	detectOrphanSessions,
+	reconstructBatchStateFromRuntime,
 	updateBatchHistoryIntegration,
 } from "./persistence.ts";
 import {
@@ -53,7 +55,12 @@ import {
 	formatPreflightResults,
 	runPreflight,
 } from "./worktree.ts";
-import { computeTransitiveDependents, resolveCanonicalTaskPaths } from "./execution.ts";
+import {
+	batchTaskScope,
+	computeTransitiveDependents,
+	execLog,
+	resolveCanonicalTaskPaths,
+} from "./execution.ts";
 import { executeOrchBatch } from "./engine.ts";
 import { formatDiscoveryResults, runDiscovery } from "./discovery.ts";
 import { formatOrchSessions, listOrchSessions } from "./sessions.ts";
@@ -67,6 +74,7 @@ import {
 } from "./config.ts";
 import { resolveOperatorId } from "./naming.ts";
 import { reconstructAllocatedLanes, resumeOrchBatch } from "./resume.ts";
+import { markTaskSegmentsSkipped, resetTaskSegmentsForRetry } from "./segment-recovery.ts";
 import { buildExecutionContext } from "./workspace.ts";
 import { openSettingsTui } from "./settings-tui.ts";
 import { loadProjectConfig } from "./config-loader.ts";
@@ -102,11 +110,20 @@ import {
 	isProcessAlive as registryIsProcessAlive,
 	isTerminalStatus,
 } from "./process-registry.ts";
+import {
+	assessEngineLiveness,
+	decideRecoveryOwnership,
+	findBatchesForOrchBranch,
+	markEngineExited,
+	recordOperatorConfirmedShutdown,
+	writeEngineIdentity,
+} from "./engine-identity.ts";
 import type { MailboxMessageType } from "./types.ts";
 import {
 	activateSupervisor,
 	deactivateSupervisor,
 	transitionToRoutingMode,
+	stopBatchMonitoring,
 	freshSupervisorState,
 	registerSupervisorPromptHook,
 	checkSupervisorLockOnStartup,
@@ -117,7 +134,12 @@ import {
 	triggerSupervisorIntegration,
 	presentBatchSummary,
 	resolveModelFromString,
+	isStaleExtensionCtx,
+	safeCtxCallFromCallback,
+	logRecoveryAction,
 } from "./supervisor.ts";
+import { SupervisorNoticeGate } from "./supervisor-dispatch.ts";
+import { repairToolResultOrdering } from "./context-repair.ts";
 import type {
 	SupervisorConfig,
 	SupervisorRoutingContext,
@@ -333,6 +355,17 @@ export function resolveIntegrationContext(
 
 	// Source 2: CLI positional branch arg overrides or fills in
 	if (parsed.orchBranchArg) {
+		// #631: an explicit branch that differs from the persisted batch's branch
+		// must NOT inherit that batch's id — cleanup/history/ownership would then
+		// target an unrelated batch. The batch behind the selected branch (if any)
+		// is looked up from runtime artifacts by the caller.
+		if (orchBranch && batchId && orchBranch !== parsed.orchBranchArg) {
+			notices.push(
+				`ℹ️ Persisted batch ${batchId} belongs to ${orchBranch}; integrating ${parsed.orchBranchArg} instead — ` +
+					`batch-scoped cleanup/history will use the batch associated with that branch, if any.`,
+			);
+			batchId = "";
+		}
 		orchBranch = parsed.orchBranchArg;
 	}
 
@@ -1049,10 +1082,17 @@ export function startBatchAsync(
 					batchState.endedAt = Date.now();
 					batchState.errors.push(`Unhandled engine error: ${errMsg}`);
 				}
-				ctx.ui.notify(
-					`❌ Engine crashed with unhandled error: ${errMsg}\n` +
-						`   Batch ${batchState.batchId} marked as failed.`,
-					"error",
+				// #620: this .catch runs when the (main-thread fallback) engine promise
+				// rejects later — an async window where ctx may be stale. Guard the UI
+				// sink so a stale-ctx throw can't crash Pi; onTerminal still runs.
+				safeCtxCallFromCallback(
+					() =>
+						ctx.ui.notify(
+							`❌ Engine crashed with unhandled error: ${errMsg}\n` +
+								`   Batch ${batchState.batchId} marked as failed.`,
+							"error",
+						),
+					"startBatchAsync.catch.notify",
 				);
 				updateWidget();
 				// TP-041 R002-3: Deactivate supervisor on all terminal paths
@@ -1109,6 +1149,55 @@ function resolveEngineWorkerPath(): string {
  *
  * @since TP-071
  */
+/** #631: true while a main-thread fallback engine is running in this process. */
+let fallbackEngineActive = false;
+export function isFallbackEngineActive(): boolean {
+	return fallbackEngineActive;
+}
+
+/**
+ * #631: delete `batch-state.json` at `stateRoot` ONLY when it belongs to the
+ * integrated batch (same batchId) or branch (same orchBranch). Returns true when
+ * deleted, false when an unrelated batch's checkpoint was preserved, null when
+ * nothing was persisted.
+ */
+export function deleteBatchStateIfOwned(
+	stateRoot: string,
+	batchId: string,
+	orchBranch: string,
+): boolean | null {
+	let persisted: PersistedBatchState | null = null;
+	try {
+		persisted = loadBatchState(stateRoot);
+	} catch {
+		// Unreadable state: ownership cannot be established — preserve it (a corrupt
+		// checkpoint is still evidence an operator may need).
+		return false;
+	}
+	if (!persisted) return null;
+	const owned =
+		(batchId && persisted.batchId === batchId) || (orchBranch && persisted.orchBranch === orchBranch);
+	if (!owned) return false;
+	deleteBatchState(stateRoot);
+	return true;
+}
+
+/** #631: resolve true once the child has actually terminated, false on timeout. */
+export function waitForChildExit(child: ChildProcess, timeoutMs: number): Promise<boolean> {
+	if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve(true);
+	return new Promise((resolve) => {
+		const timer = setTimeout(() => {
+			child.off("exit", onExit);
+			resolve(false);
+		}, timeoutMs);
+		const onExit = () => {
+			clearTimeout(timer);
+			resolve(true);
+		};
+		child.once("exit", onExit);
+	});
+}
+
 export function startBatchInWorker(
 	wkData: EngineWorkerData,
 	batchState: import("./types.ts").OrchBatchRuntimeState,
@@ -1139,9 +1228,16 @@ export function startBatchInWorker(
 		});
 	} catch (spawnErr: unknown) {
 		const errMsg = spawnErr instanceof Error ? spawnErr.message : String(spawnErr);
-		ctx.ui.notify(
-			`⚠️ Engine process spawn failed: ${errMsg}\n   Falling back to main-thread execution.`,
-			"warning",
+		// #620: stale-safe (uniform with the async callbacks below). This runs
+		// synchronously during the command so ctx is normally fresh, but guarding
+		// keeps the "no bare ctx.ui.notify in startBatchInWorker" invariant simple.
+		safeCtxCallFromCallback(
+			() =>
+				ctx.ui.notify(
+					`⚠️ Engine process spawn failed: ${errMsg}\n   Falling back to main-thread execution.`,
+					"warning",
+				),
+			"spawn.fallback.notify",
 		);
 		// Construct fallback engine function from workerData and run on main thread
 		const wsConfig = wkData.workspaceConfig
@@ -1156,7 +1252,7 @@ export function startBatchInWorker(
 							wkData.cwd,
 							batchState,
 							(msg: string, lvl: "info" | "warning" | "error") => {
-								ctx.ui.notify(msg, lvl);
+								safeCtxCallFromCallback(() => ctx.ui.notify(msg, lvl), "fallback.notify");
 								updateWidget();
 							},
 							(monState: import("./types.ts").MonitorState) => {
@@ -1179,7 +1275,7 @@ export function startBatchInWorker(
 							wkData.cwd,
 							batchState,
 							(msg: string, lvl: "info" | "warning" | "error") => {
-								ctx.ui.notify(msg, lvl);
+								safeCtxCallFromCallback(() => ctx.ui.notify(msg, lvl), "fallback.notify");
 								updateWidget();
 							},
 							(monState: import("./types.ts").MonitorState) => {
@@ -1194,7 +1290,38 @@ export function startBatchInWorker(
 							null, // onLaneTerminated — main-thread fallback path
 							null, // onLaneRespawned — main-thread fallback path
 						);
-		startBatchAsync(fallbackFn, batchState, ctx, updateWidget, onTerminal);
+		// #631: the fallback runs the engine IN THIS PROCESS. It must be just as
+		// visible/ownable as a forked engine: publish an identity with our own pid
+		// and mark it exited when the run settles. If identity cannot be
+		// published, refuse to start (ownership invariant) instead of running an
+		// invisible engine.
+		const fbStateRoot = wkData.workspaceRoot ?? wkData.cwd;
+		const fbBatchId = wkData.authorizedBatchId ?? null;
+		if (
+			!fbBatchId ||
+			!writeEngineIdentity(fbStateRoot, {
+				batchId: fbBatchId,
+				pid: process.pid,
+				supervisorPid: process.pid,
+				startedAt: Date.now(),
+			})
+		) {
+			batchState.phase = "failed";
+			batchState.endedAt = Date.now();
+			batchState.errors.push(
+				"Engine start refused: fallback engine could not publish its identity (#631)",
+			);
+			updateWidget();
+			onTerminal?.();
+			return null;
+		}
+		batchState.batchId = fbBatchId; // engine adopts it (fresh) / resume verifies the target (resume)
+		fallbackEngineActive = true;
+		startBatchAsync(fallbackFn, batchState, ctx, updateWidget, () => {
+			fallbackEngineActive = false;
+			markEngineExited(fbStateRoot, fbBatchId, { pid: process.pid, exitReason: "fallback-settled" });
+			onTerminal?.();
+		});
 		return null;
 	}
 
@@ -1271,6 +1398,76 @@ export function startBatchInWorker(
 	});
 
 	// Send workerData as first IPC message
+	// #631: publish the engine's identity (pid) BEFORE the engine is told to
+	// start. A replacement supervisor uses it to VERIFY an orphaned engine is
+	// dead before touching an inherited batch (a dead supervisor pid does not
+	// imply a dead engine). The batchId is preallocated by the caller for BOTH
+	// modes (fresh: the engine adopts it; resume: the gated target), so there is
+	// no window in which this engine runs without a current identity record.
+	// Publication is REQUIRED: if it cannot be written, the batch cannot be
+	// owned verifiably — kill the child and fail closed (no fallback).
+	// Exit marking is ATTEMPT-SCOPED (pid-matched): a delayed exit callback from
+	// an old parent cannot mark a newer live engine as exited.
+	const engineStateRoot = wkData.workspaceRoot ?? wkData.cwd;
+	const enginePid = typeof child.pid === "number" ? child.pid : null;
+	const engineIdentityBatchId = wkData.authorizedBatchId ?? null;
+	if (!engineIdentityBatchId || enginePid === null) {
+		try {
+			child.kill();
+		} catch {
+			/* best effort */
+		}
+		const why = !engineIdentityBatchId
+			? "no authorized batchId was preallocated"
+			: "child has no pid";
+		batchState.phase = "failed";
+		batchState.endedAt = Date.now();
+		batchState.errors.push(`Engine start refused: ${why} (#631 ownership invariant)`);
+		safeCtxCallFromCallback(
+			() => ctx.ui.notify(`❌ Engine start refused: ${why}.`, "error"),
+			"spawn.identity.notify",
+		);
+		updateWidget();
+		onTerminal?.();
+		return null;
+	}
+	const published = writeEngineIdentity(engineStateRoot, {
+		batchId: engineIdentityBatchId,
+		pid: enginePid,
+		supervisorPid: process.pid,
+		startedAt: Date.now(),
+	});
+	if (!published) {
+		try {
+			child.kill();
+		} catch {
+			/* best effort */
+		}
+		batchState.phase = "failed";
+		batchState.endedAt = Date.now();
+		batchState.errors.push(
+			`Engine start refused: could not publish engine identity to ${engineStateRoot}/.pi/runtime/${engineIdentityBatchId}/engine.json (#631)`,
+		);
+		safeCtxCallFromCallback(
+			() =>
+				ctx.ui.notify(
+					`❌ Engine start refused: could not write engine identity under .pi/runtime/ — fix the filesystem and retry.`,
+					"error",
+				),
+			"spawn.identity.notify",
+		);
+		updateWidget();
+		onTerminal?.();
+		return null;
+	}
+	child.on("exit", (code: number | null) => {
+		markEngineExited(engineStateRoot, engineIdentityBatchId, {
+			pid: enginePid,
+			exitCode: code,
+			exitReason: "child-exit",
+		});
+	});
+
 	child.send({ type: "init", data: wkData });
 
 	// Terminal settlement guard (R001 §3): ensures onTerminal fires at most once.
@@ -1285,7 +1482,10 @@ export function startBatchInWorker(
 	child.on("message", (msg: WorkerToMainMessage) => {
 		switch (msg.type) {
 			case "notify":
-				ctx.ui.notify(msg.msg, msg.level);
+				// #620: ctx may be stale (session replaced/reload, or headless -p run
+				// finalized while this forked worker still emits IPC). Accessing
+				// ctx.ui throws assertActive; unguarded that crashes Pi. No-op on stale.
+				safeCtxCallFromCallback(() => ctx.ui.notify(msg.msg, msg.level), "ipc.notify");
 				updateWidget();
 				break;
 
@@ -1335,11 +1535,26 @@ export function startBatchInWorker(
 					batchState.errors.push(`Unhandled engine error${sourceLabel}: ${msg.message}`);
 					if (stackLine) batchState.errors.push(`Engine stack: ${stackLine}`);
 				}
-				ctx.ui.notify(
-					`❌ Engine crashed with unhandled error${sourceLabel}: ${msg.message}\n` +
-						(stackLine ? `   ${stackLine}\n` : "") +
-						`   Batch ${batchState.batchId} marked as failed.`,
-					"error",
+				// #620: persist the failed state FIRST so a dead UI sink can never
+				// prevent the dashboard/resume from seeing the failure. The engine-
+				// worker is dead and can't persist — we must. (Reordered ahead of the
+				// UI notify + supervisor alert, both of which are now stale-safe.)
+				try {
+					saveBatchState(JSON.stringify(batchState, null, 2), wkData.cwd);
+				} catch {
+					/* best effort */
+				}
+				// #620: stale-safe — a stale ctx here must not crash Pi nor block the
+				// supervisor alert below.
+				safeCtxCallFromCallback(
+					() =>
+						ctx.ui.notify(
+							`❌ Engine crashed with unhandled error${sourceLabel}: ${msg.message}\n` +
+								(stackLine ? `   ${stackLine}\n` : "") +
+								`   Batch ${batchState.batchId} marked as failed.`,
+							"error",
+						),
+					"ipc.error.notify",
 				);
 				// Alert supervisor — this is the PRIMARY notification path for engine
 				// crashes caught by uncaughtException/unhandledRejection handlers.
@@ -1371,13 +1586,6 @@ export function startBatchInWorker(
 								: undefined,
 					},
 				});
-				// Persist failed state to disk so dashboard/resume see it.
-				// The engine-worker is dead and can't persist — we must do it here.
-				try {
-					saveBatchState(JSON.stringify(batchState, null, 2), wkData.cwd);
-				} catch {
-					/* best effort */
-				}
 				updateWidget();
 				break;
 			}
@@ -1392,9 +1600,14 @@ export function startBatchInWorker(
 			batchState.endedAt = Date.now();
 			batchState.errors.push(`Engine process error: ${err.message}`);
 		}
-		ctx.ui.notify(
-			`❌ Engine process error: ${err.message}\n` + `   Batch ${batchState.batchId} marked as failed.`,
-			"error",
+		safeCtxCallFromCallback(
+			() =>
+				ctx.ui.notify(
+					`❌ Engine process error: ${err.message}\n` +
+						`   Batch ${batchState.batchId} marked as failed.`,
+					"error",
+				),
+			"child.error.notify",
 		);
 		updateWidget();
 		// ── TP-076: Alert supervisor about engine process error ──
@@ -1441,7 +1654,10 @@ export function startBatchInWorker(
 				batchState.endedAt = Date.now();
 				batchState.errors.push(`Engine process exited with code ${code}`);
 			}
-			ctx.ui.notify(`❌ Engine process exited unexpectedly (code ${code}).`, "error");
+			safeCtxCallFromCallback(
+				() => ctx.ui.notify(`❌ Engine process exited unexpectedly (code ${code}).`, "error"),
+				"child.exit.notify",
+			);
 			updateWidget();
 			// ── TP-076: Alert supervisor about unexpected engine exit ──
 			onSupervisorAlert?.({
@@ -1542,8 +1758,10 @@ export function buildIntegrationExecutor(
 				}
 			},
 			deleteBatchState: () => {
+				// #631: only delete the checkpoint of the batch actually integrated — never
+				// an unrelated persisted batch (whose engine may still be alive).
 				try {
-					deleteBatchState(stateRoot ?? repoRoot);
+					deleteBatchStateIfOwned(stateRoot ?? repoRoot, context.batchId, context.orchBranch);
 				} catch {
 					/* best effort */
 				}
@@ -1567,7 +1785,7 @@ export function buildIntegrationExecutor(
 		// as the manual /orch-integrate handler.
 		if (result.success && result.integratedLocally && context.batchId && opId) {
 			try {
-				deleteStaleBranches(repoRoot, opId, context.batchId);
+				deleteStaleBranches(repoRoot, opId, context.batchId, stateRoot ?? repoRoot);
 				dropBatchAutostash(repoRoot, context.batchId);
 			} catch {
 				/* best effort — don't fail integration for cleanup errors */
@@ -1604,7 +1822,21 @@ export function buildIntegrationExecutor(
  *
  * @since TP-043
  */
-export function buildCiDeps(repoRoot: string, stateRoot?: string): CiDeps {
+export function buildCiDeps(
+	repoRoot: string,
+	stateRoot?: string,
+	/**
+	 * #631: the IMMUTABLE identity of the batch whose PR this CI lifecycle belongs
+	 * to. Post-PR cleanup runs asynchronously (after CI passes and the PR merges)
+	 * — by then a NEWER batch may have persisted its checkpoint; deletion is
+	 * bound to this identity so it can never erase that one.
+	 */
+	owned?: { batchId: string; orchBranch: string },
+): CiDeps {
+	// Capture primitives now: a caller mutating its object later cannot change
+	// which batch this lifecycle is allowed to clean up.
+	const ownedBatchId = owned?.batchId;
+	const ownedOrchBranch = owned?.orchBranch;
 	return {
 		runCommand: (cmd: string, cmdArgs: string[]) => {
 			try {
@@ -1627,7 +1859,13 @@ export function buildCiDeps(repoRoot: string, stateRoot?: string): CiDeps {
 		runGit: (gitArgs: string[]) => runGit(gitArgs, repoRoot),
 		deleteBatchState: () => {
 			try {
-				deleteBatchState(stateRoot ?? repoRoot);
+				if (ownedBatchId !== undefined && ownedOrchBranch !== undefined) {
+					deleteBatchStateIfOwned(stateRoot ?? repoRoot, ownedBatchId, ownedOrchBranch);
+					return;
+				}
+				// No identity supplied (legacy caller): refuse rather than delete blindly.
+				execLog("supervisor", "none", "CI cleanup skipped: no owned batch identity supplied (#631)");
+				return;
 			} catch {
 				/* best effort */
 			}
@@ -1830,10 +2068,304 @@ export default function (pi: ExtensionAPI) {
 	// Tracked so pause/abort can send control messages to the engine.
 	let activeWorker: ChildProcess | null = null;
 
+	// ── #631: inherited-batch ownership evidence ──
+	// Set by supervisor lock takeover when this session imports a batch it did
+	// not start. `activeWorker` answers "is an engine attached to THIS process";
+	// this answers "what do we know about the previous owner" so the active-
+	// phase guards can decide whether an inherited "executing" batch is a
+	// disconnected orphan (resumable) or still being driven elsewhere (refuse).
+	let priorSupervisor: { pid: number; alive: boolean } | null = null;
+
+	/**
+	 * Is an engine running IN THIS PROCESS? Covers the forked child (until it has
+	 * actually terminated — exitCode/signalCode are set by Node on termination;
+	 * `killed` only means a signal was dispatched) and the main-thread fallback.
+	 */
+	function engineAttachedHere(): boolean {
+		if (isFallbackEngineActive()) return true;
+		return (
+			activeWorker !== null && activeWorker.exitCode === null && activeWorker.signalCode === null
+		);
+	}
+
+	/**
+	 * #631: THE ownership gate for every recovery mutation (resume / retry /
+	 * skip / force-merge / administrative pause). One rule, applied against the
+	 * ACTUAL persisted (or reconstructed) target — never against a phase this
+	 * session happens to have cached:
+	 *
+	 *   1. an engine is attached to THIS process (running or still exiting)
+	 *        → refuse: wait for it to exit (or pause it) — even when the cached
+	 *          phase already reads paused/failed: teardown is still in flight.
+	 *   2. the target's recorded engine is ALIVE elsewhere → refuse (double-drive).
+	 *   3. no identity recorded (or unreadable) → refuse: unknown ownership is not
+	 *        confirmed shutdown; the audited orch_confirm_engine_shutdown path exists.
+	 *   4. recorded engine dead/exited (incl. operator-confirmed) → proceed; the
+	 *        persisted-state eligibility rules take over.
+	 *
+	 * `force` never enters this decision. Returns a refusal message or null.
+	 */
+	function recoveryOwnershipGate(
+		operation: string,
+		stateRoot: string,
+		target: { batchId: string; phase: string },
+	): string | null {
+		const decision = decideRecoveryOwnership({
+			operation,
+			local: {
+				engineAttached: engineAttachedHere(),
+				phase: orchBatchState.phase,
+				batchId: orchBatchState.batchId,
+				pid: activeWorker?.pid ?? (isFallbackEngineActive() ? process.pid : null),
+			},
+			target,
+			liveness: assessEngineLiveness(stateRoot, target.batchId),
+			priorSupervisor,
+		});
+		execLog("supervisor", target.batchId, `ownership gate: ${operation}`, {
+			proceed: decision.proceed,
+			reason: decision.reason.slice(0, 200),
+		});
+		return decision.proceed ? null : decision.reason;
+	}
+
+	/**
+	 * #631: the ONE root every ownership decision AND every state mutation must
+	 * use. The engine persists at `workspaceRoot ?? cwd`; a gate that authorizes
+	 * the workspace-root batch while the mutation loads the repo-root batch (or
+	 * vice versa) protects the wrong target. When the two roots differ and BOTH
+	 * hold a persisted batch with different ids, that is a conflict — refuse
+	 * rather than pick one.
+	 */
+	function canonicalStateRoot(fallbackCwd: string): string {
+		return execCtx?.workspaceRoot ?? execCtx?.repoRoot ?? fallbackCwd;
+	}
+	function conflictingRootsRefusal(operation: string, fallbackCwd: string): string | null {
+		const canonical = canonicalStateRoot(fallbackCwd);
+		const repo = execCtx?.repoRoot ?? fallbackCwd;
+		if (canonical === repo) return null;
+		let a: PersistedBatchState | null = null;
+		let b: PersistedBatchState | null = null;
+		try {
+			a = loadBatchState(canonical);
+		} catch {
+			/* reported elsewhere */
+		}
+		try {
+			b = loadBatchState(repo);
+		} catch {
+			/* reported elsewhere */
+		}
+		if (a && b && a.batchId !== b.batchId) {
+			return (
+				`❌ Cannot ${operation}: conflicting batch state — workspace root holds ${a.batchId} (${a.phase}) ` +
+				`while the repo root holds ${b.batchId} (${b.phase}). Ownership can only be verified for one target; ` +
+				`remove or archive the stale one (${repo}/.pi/batch-state.json is not the canonical location in workspace mode).`
+			);
+		}
+		return null;
+	}
+
+	/**
+	 * #631: resolve the batch a recovery operation would act on, BEFORE
+	 * authorizing it. Persisted state first; on force-resume with no state file,
+	 * the same deterministic reconstruction the engine performs (so the parent
+	 * gates the very batch the child will resume — the child verifies the match).
+	 */
+	function resolveRecoveryTarget(
+		stateRoot: string,
+		allowReconstruction: boolean,
+	): { batchId: string; phase: string } | null {
+		try {
+			const persisted = loadBatchState(stateRoot);
+			if (persisted) return { batchId: persisted.batchId, phase: persisted.phase };
+		} catch {
+			/* the engine reports load errors with full context */
+		}
+		if (!allowReconstruction) return null;
+		try {
+			const r = reconstructBatchStateFromRuntime(stateRoot);
+			if (r.ok) return { batchId: r.batchId, phase: r.state.phase };
+		} catch {
+			/* nothing to reconstruct */
+		}
+		return null;
+	}
+
 	// ── Supervisor State (TP-041) ────────────────────────────────────
 	let supervisorState = freshSupervisorState();
 	let supervisorConfig: SupervisorConfig = { ...DEFAULT_SUPERVISOR_CONFIG };
 
+	// ── #621: Batch-end epilogue gate ────────────────────────────────
+	// The batch-end epilogue appends display banners via
+	// pi.sendMessage(..., {triggerTurn:false}), which immediately splices a
+	// custom entry into the session tree. If the interactive agent has a tool
+	// call in flight, that splice lands between an assistant `tool_use` and its
+	// `tool_result` and produces an Anthropic 400 that wedges the session. The
+	// gate runs the epilogue immediately when idle, else defers it to the next
+	// `agent_settled` boundary. `batchGeneration` tags deferred work so a newer
+	// batch invalidates a stale pending epilogue.
+	const noticeGate = new SupervisorNoticeGate();
+	let batchGeneration = 0;
+
+	// #621: Both /orch (doOrchStart) and /orch-resume (doOrchResume) must, on
+	// (re)start, supersede any batch-end epilogue still deferred from a previous
+	// batch: bump the generation (so a later agent_settled no longer matches the
+	// stale pending work) AND drop the pending closure. Extracted into one helper
+	// so the two entry points cannot drift apart again (the original /orch-resume
+	// gap was exactly this drift). Call immediately after freshOrchBatchState().
+	function supersedeDeferredEpilogue(): void {
+		batchGeneration++;
+		noticeGate.invalidate();
+	}
+
+	// #621: The batch-end epilogue, shared by /orch (doOrchStart) and
+	// /orch-resume (doOrchResume). Appends the batch-summary / integration-skipped
+	// banners and transitions the supervisor to routing mode. Both entry points
+	// historically inlined identical logic differing only in `repoRoot` vs
+	// `execCtx!.repoRoot` — the same value, since doOrchStart destructures
+	// `const { repoRoot } = execCtx`. Deferring the WHOLE epilogue (rather than
+	// individual sends) also protects the completed->triggerSupervisorIntegration
+	// branch, whose progress/result messages are the same splice hazard.
+	function runSupervisorBatchEndEpilogue(): void {
+		// #610: re-resolve at DISPATCH time. If this batch was already integrated
+		// (manually, or by auto-integration) — or its orch branch is simply gone —
+		// the "ready for integration" banners are stale and must not be shown.
+		if (orchBatchState.integratedAt) return;
+		if (orchBatchState.phase === "completed" && orchBatchState.orchBranch && execCtx) {
+			const branchExists = runGit(
+				["rev-parse", "--verify", `refs/heads/${orchBatchState.orchBranch}`],
+				execCtx.repoRoot,
+			).ok;
+			if (!branchExists) {
+				process.stderr.write(
+					`[taskplane] batch-end epilogue skipped: orch branch ${orchBatchState.orchBranch} no longer exists (already integrated) (#610)
+`,
+				);
+				return;
+			}
+		}
+		const mode = orchConfig.orchestrator.integration;
+		const opId = resolveOperatorId(orchConfig);
+		const sDeps: SummaryDeps = {
+			opId,
+			diagnostics: orchBatchState.diagnostics ?? null,
+			mergeResults: (orchBatchState.mergeResults || []).map((mr) => ({
+				waveIndex: mr.waveIndex,
+				status: mr.status,
+				failedLane: mr.failedLane,
+				failureReason: mr.failureReason,
+			})),
+		};
+		if (orchBatchState.phase === "completed" && (mode === "supervised" || mode === "auto")) {
+			triggerSupervisorIntegration(
+				pi,
+				supervisorState,
+				orchBatchState,
+				mode,
+				execCtx!.repoRoot,
+				// #610: record integration in memory on success so any later epilogue
+				// dispatch for this batch short-circuits instead of re-prompting.
+				((mode, context) => {
+					const r = buildIntegrationExecutor(
+						execCtx!.repoRoot,
+						opId,
+						execCtx!.workspaceRoot,
+					)(mode, context);
+					if (r.success && r.integratedLocally && orchBatchState.batchId === context.batchId) {
+						orchBatchState.integratedAt = Date.now();
+					}
+					return r;
+				}) satisfies IntegrationExecutor,
+				buildCiDeps(execCtx!.repoRoot, execCtx!.workspaceRoot, {
+					batchId: orchBatchState.batchId,
+					orchBranch: orchBatchState.orchBranch,
+				}),
+				sDeps,
+			);
+			return;
+		}
+		if ((mode === "supervised" || mode === "auto") && orchBatchState.phase !== "completed") {
+			pi.sendMessage(
+				{
+					customType: "supervisor-integration-skipped",
+					content: [
+						{
+							type: "text",
+							text:
+								`📋 **Batch ended** (phase: ${orchBatchState.phase}). ` +
+								`Integration skipped — only completed batches are eligible.\n` +
+								`Use \`/orch-resume\` to continue or \`/orch-integrate\` manually after resolving issues.`,
+						},
+					],
+					display: `Integration skipped — batch ${orchBatchState.phase}`,
+				},
+				{ triggerTurn: false },
+			);
+		}
+		presentBatchSummary(
+			pi,
+			orchBatchState,
+			execCtx!.workspaceRoot,
+			opId,
+			orchBatchState.diagnostics,
+			sDeps.mergeResults,
+		);
+		const postBatchContext: SupervisorRoutingContext =
+			orchBatchState.phase === "completed"
+				? {
+						routingState: "completed-batch",
+						contextMessage:
+							`Batch **${orchBatchState.batchId}** completed — ` +
+							`${orchBatchState.succeededTasks}/${orchBatchState.totalTasks} tasks succeeded.\n\n` +
+							`The orch branch \`${orchBatchState.orchBranch}\` is ready to integrate.\n` +
+							`Would you like me to integrate it, or would you prefer to review first?\n\n` +
+							`You can also:\n` +
+							`• Run \`/orch-integrate\` (or \`/orch-integrate --pr\`) to integrate\n` +
+							`• Create new tasks for the next batch\n` +
+							`• Run a health check`,
+					}
+				: {
+						routingState: "no-tasks",
+						contextMessage:
+							`Batch **${orchBatchState.batchId}** ended (${orchBatchState.phase}).\n\n` +
+							`${orchBatchState.succeededTasks} succeeded, ${orchBatchState.failedTasks} failed, ` +
+							`${orchBatchState.skippedTasks} skipped.\n\n` +
+							`What would you like to do next?`,
+					};
+		transitionToRoutingMode(pi, supervisorState, postBatchContext);
+	}
+
+	// #621: Route the batch-end epilogue through the idle gate. When the agent
+	// has a tool call in flight, eagerly stop batch monitoring (so a heartbeat
+	// timer send can't splice either) and defer the epilogue to the next settle.
+	function dispatchBatchEndEpilogue(ctx: ExtensionContext): void {
+		// #620: this runs from the engine-worker terminal (onTerminal) callback,
+		// where ctx may be stale. ctx.isIdle() is assertActive-guarded, so an
+		// unguarded call crashes Pi. If the ctx is stale the session is gone — there
+		// is no live UI to render the epilogue — so skip dispatch entirely, but still
+		// stop monitoring and drop any deferred epilogue so no later timer send
+		// fires against the dead session. Non-stale errors are logged, not rethrown
+		// (a throw here is an uncaught IPC-callback exception — the #620 crash class).
+		let idle: boolean;
+		try {
+			idle = ctx.isIdle();
+		} catch (err) {
+			if (!isStaleExtensionCtx(err)) {
+				console.error(
+					`[taskplane] dispatchBatchEndEpilogue ctx.isIdle() threw (non-stale): ${
+						err instanceof Error ? (err.stack ?? err.message) : String(err)
+					}`,
+				);
+			}
+			stopBatchMonitoring(supervisorState);
+			noticeGate.invalidate();
+			return;
+		}
+		if (!idle) stopBatchMonitoring(supervisorState);
+		noticeGate.runOrDefer(idle, batchGeneration, runSupervisorBatchEndEpilogue);
+	}
+
 	// TP-187 (#538): Zombie-alert filter state
 	// Lane numbers and agent IDs that have reached a terminal state (no-progress
 	// kill, hard-fail, or supervisor-takeover). Supervisor-alert IPC messages
@@ -1931,13 +2463,24 @@ export default function (pi: ExtensionAPI) {
 		const ctx = orchWidgetCtx;
 		const prefix = orchConfig.orchestrator.sessionPrefix;
 
-		ctx.ui.setWidget(
-			"task-orchestrator",
-			createOrchWidget(
-				() => orchBatchState,
-				() => latestMonitorState,
-				prefix,
-			),
+		// #620: updateOrchWidget is the single choke point for widget refresh and is
+		// called from BOTH synchronous command handlers (ctx fresh) AND long-lived
+		// async engine-worker IPC callbacks (ctx may be stale after session
+		// replacement/reload or a finalized headless -p run). ctx.ui.setWidget
+		// accesses the assertActive-guarded ctx.ui getter, so an unguarded call from
+		// the async path crashes Pi. Guarding here covers every caller at once; for
+		// the sync callers the stale branch simply never triggers.
+		safeCtxCallFromCallback(
+			() =>
+				ctx.ui.setWidget(
+					"task-orchestrator",
+					createOrchWidget(
+						() => orchBatchState,
+						() => latestMonitorState,
+						prefix,
+					),
+				),
+			"widget.setWidget",
 		);
 	}
 
@@ -2275,8 +2818,55 @@ export default function (pi: ExtensionAPI) {
 
 		const { repoRoot } = execCtx;
 
+		// #631: a fresh start deletes stale state and launches a NEW engine. That
+		// must never happen under an engine that is still alive — ours (cached
+		// completed/failed but the child has not terminated yet) or another
+		// process's (inherited terminal phase whose engine is still running).
+		// Ownership is checked against the persisted target, not the cached phase.
+		{
+			const startStateRoot = canonicalStateRoot(repoRoot);
+			const conflict = conflictingRootsRefusal("orch_start", repoRoot);
+			if (conflict) return { message: conflict, error: true };
+			if (engineAttachedHere()) {
+				return {
+					message: `⏳ This session's engine (PID ${activeWorker?.pid ?? process.pid}) for batch ${orchBatchState.batchId} is still shutting down — starting a new batch now would race its teardown. Retry in a moment.`,
+					error: true,
+				};
+			}
+			const existing = resolveRecoveryTarget(startStateRoot, false);
+			if (existing) {
+				const liveness = assessEngineLiveness(startStateRoot, existing.batchId);
+				// Same rule as every recovery mutation: alive or UNKNOWN ownership refuses.
+				// (.DONE files and terminal phases are not shutdown evidence — the engine
+				// persists again after cleanup.) Pre-#631 batches: one-time
+				// orch_confirm_engine_shutdown before the first fresh start.
+				{
+					const decision = decideRecoveryOwnership({
+						operation: "orch_start",
+						local: {
+							engineAttached: false,
+							phase: orchBatchState.phase,
+							batchId: orchBatchState.batchId,
+							pid: null,
+						},
+						target: existing,
+						liveness,
+						priorSupervisor,
+					});
+					execLog("supervisor", existing.batchId, "ownership gate: orch_start", {
+						proceed: decision.proceed,
+						status: liveness.status,
+						pid: liveness.identity?.pid,
+					});
+					if (!decision.proceed) return { message: decision.reason, error: true };
+				}
+			}
+		}
+
 		// Orphan detection
-		const orphanResult = detectOrphanSessions(orchConfig.orchestrator.sessionPrefix, repoRoot);
+		// #631: orphan/stale-state handling at the SAME root the gate authorized.
+		const orphanStateRoot = canonicalStateRoot(repoRoot);
+		const orphanResult = detectOrphanSessions(orchConfig.orchestrator.sessionPrefix, orphanStateRoot);
 
 		switch (orphanResult.recommendedAction) {
 			case "resume": {
@@ -2285,7 +2875,7 @@ export default function (pi: ExtensionAPI) {
 				const hasOrphans = orphanResult.orphanSessions.length > 0;
 				if (!hasOrphans && !resumablePhases.includes(phase)) {
 					try {
-						deleteBatchState(repoRoot);
+						deleteBatchState(orphanStateRoot);
 					} catch {
 						/* best effort */
 					}
@@ -2301,7 +2891,7 @@ export default function (pi: ExtensionAPI) {
 				return { message: orphanResult.userMessage, error: true };
 			case "cleanup-stale":
 				try {
-					deleteBatchState(repoRoot);
+					deleteBatchState(orphanStateRoot);
 				} catch {
 					/* best effort */
 				}
@@ -2375,8 +2965,13 @@ export default function (pi: ExtensionAPI) {
 
 		// Reset batch state for new execution
 		orchBatchState = freshOrchBatchState();
+		priorSupervisor = null; // #631: this session now owns the engine it is about to fork
 		latestMonitorState = null;
 
+		// #621: a new batch supersedes any epilogue still deferred from the
+		// previous batch. Bump the generation and drop the stale pending work.
+		supersedeDeferredEpilogue();
+
 		// TP-187 (#538): Clear zombie-alert filter for the new batch.
 		clearTerminationFilter("new_batch_started");
 
@@ -2384,12 +2979,18 @@ export default function (pi: ExtensionAPI) {
 		orchBatchState.startedAt = Date.now();
 		updateOrchWidget();
 
+		// #631: preallocate the batchId so the engine identity is published BEFORE
+		// the engine starts (the engine adopts it instead of generating its own).
+		const authorizedBatchId = generateBatchId();
+		orchBatchState.batchId = authorizedBatchId;
+
 		// Non-blocking engine launch in worker thread (TP-071)
 		activeWorker = startBatchInWorker(
 			{
 				engineWorker: true,
 				mode: "execute",
 				args: trimmedTarget,
+				authorizedBatchId,
 				orchConfig,
 				runnerConfig,
 				cwd: repoRoot,
@@ -2424,80 +3025,7 @@ export default function (pi: ExtensionAPI) {
 				if (changed) updateOrchWidget();
 			},
 			() => {
-				const mode = orchConfig.orchestrator.integration;
-				const opId = resolveOperatorId(orchConfig);
-				const sDeps: SummaryDeps = {
-					opId,
-					diagnostics: orchBatchState.diagnostics ?? null,
-					mergeResults: (orchBatchState.mergeResults || []).map((mr) => ({
-						waveIndex: mr.waveIndex,
-						status: mr.status,
-						failedLane: mr.failedLane,
-						failureReason: mr.failureReason,
-					})),
-				};
-				if (orchBatchState.phase === "completed" && (mode === "supervised" || mode === "auto")) {
-					triggerSupervisorIntegration(
-						pi,
-						supervisorState,
-						orchBatchState,
-						mode,
-						repoRoot,
-						buildIntegrationExecutor(repoRoot, opId, execCtx!.workspaceRoot),
-						buildCiDeps(repoRoot, execCtx!.workspaceRoot),
-						sDeps,
-					);
-					return;
-				}
-				if ((mode === "supervised" || mode === "auto") && orchBatchState.phase !== "completed") {
-					pi.sendMessage(
-						{
-							customType: "supervisor-integration-skipped",
-							content: [
-								{
-									type: "text",
-									text:
-										`📋 **Batch ended** (phase: ${orchBatchState.phase}). ` +
-										`Integration skipped — only completed batches are eligible.\n` +
-										`Use \`/orch-resume\` to continue or \`/orch-integrate\` manually after resolving issues.`,
-								},
-							],
-							display: `Integration skipped — batch ${orchBatchState.phase}`,
-						},
-						{ triggerTurn: false },
-					);
-				}
-				presentBatchSummary(
-					pi,
-					orchBatchState,
-					execCtx!.workspaceRoot,
-					opId,
-					orchBatchState.diagnostics,
-					sDeps.mergeResults,
-				);
-				const postBatchContext: SupervisorRoutingContext =
-					orchBatchState.phase === "completed"
-						? {
-								routingState: "completed-batch",
-								contextMessage:
-									`Batch **${orchBatchState.batchId}** completed — ` +
-									`${orchBatchState.succeededTasks}/${orchBatchState.totalTasks} tasks succeeded.\n\n` +
-									`The orch branch \`${orchBatchState.orchBranch}\` is ready to integrate.\n` +
-									`Would you like me to integrate it, or would you prefer to review first?\n\n` +
-									`You can also:\n` +
-									`• Run \`/orch-integrate\` (or \`/orch-integrate --pr\`) to integrate\n` +
-									`• Create new tasks for the next batch\n` +
-									`• Run a health check`,
-							}
-						: {
-								routingState: "no-tasks",
-								contextMessage:
-									`Batch **${orchBatchState.batchId}** ended (${orchBatchState.phase}).\n\n` +
-									`${orchBatchState.succeededTasks} succeeded, ${orchBatchState.failedTasks} failed, ` +
-									`${orchBatchState.skippedTasks} skipped.\n\n` +
-									`What would you like to do next?`,
-							};
-				transitionToRoutingMode(pi, supervisorState, postBatchContext);
+				dispatchBatchEndEpilogue(ctx);
 			},
 			// ── TP-076: Supervisor alert handler — injects alerts as user messages ──
 			(alert) => {
@@ -2510,7 +3038,20 @@ export default function (pi: ExtensionAPI) {
 					);
 					return;
 				}
-				pi.sendUserMessage(alert.summary, { deliverAs: "followUp" });
+				// #620: stale-safe — pi.sendUserMessage is assertActive-guarded on
+				// ExtensionAPI; a stale ctx from this async worker-IPC alert callback
+				// would otherwise crash Pi. #597 safeSendMessageFromTimer covers
+				// sendMessage only, so use the general callback guard here.
+				safeCtxCallFromCallback(
+					() =>
+						pi.sendUserMessage(alert.summary, {
+							// #review-boundary: spiral/order escalations are urgent — steer
+							// (interrupt current turn) so the supervisor adjudicates now;
+							// routine alerts stay followUp (queue to next turn boundary).
+							deliverAs: alert.category === "review-intervention-needed" ? "steer" : "followUp",
+						}),
+					"alert.sendUserMessage",
+				);
 			},
 			// TP-187 (#538): Lane-terminated handler.
 			(info) => {
@@ -2772,7 +3313,59 @@ export default function (pi: ExtensionAPI) {
 		if (orchBatchState.phase === "paused" || orchBatchState.pauseSignal.paused) {
 			return ORCH_MESSAGES.pauseAlreadyPaused(orchBatchState.batchId);
 		}
+
+		// #631: no engine attached to THIS process (phase inherited at takeover).
+		// A pauseSignal here is inert — nothing runs in-process to honor it. Decide
+		// from verified engine liveness:
+		//   - orphan engine confirmed gone → ADMINISTRATIVE pause: persist
+		//     phase=paused on disk (the non-destructive stop the operator otherwise
+		//     had to hand-edit). Surviving worker processes, if any, are reconciled
+		//     by orch_resume (registry pid liveness), not by this call.
+		//   - engine alive elsewhere → we cannot signal it; report, do not lie.
+		if (!engineAttachedHere()) {
+			const stateRoot = execCtx?.workspaceRoot ?? execCtx?.repoRoot ?? process.cwd();
+			const refusal = recoveryOwnershipGate("orch_pause (administrative)", stateRoot, {
+				batchId: orchBatchState.batchId,
+				phase: orchBatchState.phase,
+			});
+			if (refusal) {
+				return (
+					`⚠️ Batch ${orchBatchState.batchId} is "${orchBatchState.phase}" but no engine is attached to this session — ` +
+					`a pause signal here would be inert.\n${refusal}`
+				);
+			}
+			const decision = { reason: "recorded engine verified gone" };
+			try {
+				const persisted = loadBatchState(stateRoot);
+				if (!persisted) return "❌ No persisted batch state found to pause.";
+				if (persisted.batchId !== orchBatchState.batchId) {
+					return `❌ Persisted batch (${persisted.batchId}) does not match the inherited batch (${orchBatchState.batchId}); refusing to pause.`;
+				}
+				const prevPhase = persisted.phase;
+				persisted.phase = "paused";
+				persisted.updatedAt = Date.now();
+				persisted.errors.push(
+					`Administrative pause by replacement supervisor (PID ${process.pid}) — inherited phase "${prevPhase}" with no live engine (${decision.reason.slice(0, 160)})`,
+				);
+				saveBatchState(JSON.stringify(persisted, null, 2), stateRoot);
+				orchBatchState.phase = "paused";
+				orchBatchState.pauseSignal.paused = true;
+				orchBatchState.pauseSignal.cause = "operator";
+				updateOrchWidget();
+				return (
+					`⏸️ Batch ${orchBatchState.batchId} administratively paused (was "${prevPhase}"; ${decision.reason}).
+` +
+					`   No engine was running to honor a live pause; state is now resumable on disk. ` +
+					`Any worker processes that outlived the engine are reconciled by orch_resume(force=true) ` +
+					`(registry pid liveness → re-execute in the existing worktree).`
+				);
+			} catch (err) {
+				return `❌ Administrative pause failed: ${err instanceof Error ? err.message : String(err)}`;
+			}
+		}
+
 		orchBatchState.pauseSignal.paused = true;
+		orchBatchState.pauseSignal.cause = "operator"; // in-process (fallback) engine reads this directly
 		// TP-071: Forward pause to engine process (its pauseSignal is separate)
 		activeWorker?.send({ type: "pause" });
 		updateOrchWidget();
@@ -2795,23 +3388,39 @@ export default function (pi: ExtensionAPI) {
 			};
 		}
 
-		// Prevent resume if a batch is actively running
-		if (
-			orchBatchState.phase === "launching" ||
-			orchBatchState.phase === "executing" ||
-			orchBatchState.phase === "merging" ||
-			orchBatchState.phase === "planning"
-		) {
-			return {
-				message: `⚠️ A batch is currently ${orchBatchState.phase} (${orchBatchState.batchId}). Cannot resume.`,
-				error: true,
-			};
+		// #631: resolve the ACTUAL target (persisted, or reconstructed on force with
+		// no state file) and run the single ownership gate against it — never
+		// against a cached phase. The resolved batchId is also the id the new
+		// engine is authorized for (identity published before it starts).
+		const resumeStateRoot = execCtx?.workspaceRoot ?? execCtx?.repoRoot ?? ctx.cwd;
+		const resumeTarget = resolveRecoveryTarget(resumeStateRoot, force);
+		if (!resumeTarget) {
+			if (engineAttachedHere()) {
+				return {
+					message: `❌ Cannot orch_resume: this session's engine for batch ${orchBatchState.batchId} is still running.`,
+					error: true,
+				};
+			}
+			// No target to gate: let the engine produce the canonical "no state" error.
+		} else {
+			const refusal = recoveryOwnershipGate("orch_resume", resumeStateRoot, resumeTarget);
+			if (refusal) return { message: refusal, error: true };
 		}
+		const resumeTargetBatchId = resumeTarget?.batchId ?? null;
 
 		// Reset batch state for resume
 		orchBatchState = freshOrchBatchState();
+		priorSupervisor = null; // #631: this session now owns the engine it is about to fork
 		latestMonitorState = null;
 
+		// #621: a resume supersedes any epilogue still deferred from the previous
+		// batch, exactly as doOrchStart does. Without this, an epilogue deferred
+		// mid-tool by the prior batch keeps the same batchGeneration; if the user
+		// resumes before `agent_settled` flushes it, onSettled() sees a matching
+		// generation and fires the stale epilogue against the resumed batch
+		// (wrong/duplicate banner). Shared helper mirrors doOrchStart exactly.
+		supersedeDeferredEpilogue();
+
 		// TP-187 (#538): Clear zombie-alert filter so post-resume alerts pass through.
 		clearTerminationFilter("orch_resume_called");
 
@@ -2825,6 +3434,7 @@ export default function (pi: ExtensionAPI) {
 				engineWorker: true,
 				mode: "resume",
 				args: "",
+				authorizedBatchId: resumeTargetBatchId ?? undefined,
 				orchConfig,
 				runnerConfig,
 				cwd: execCtx!.repoRoot,
@@ -2844,80 +3454,7 @@ export default function (pi: ExtensionAPI) {
 				updateOrchWidget();
 			},
 			() => {
-				const mode = orchConfig.orchestrator.integration;
-				const opId = resolveOperatorId(orchConfig);
-				const sDeps: SummaryDeps = {
-					opId,
-					diagnostics: orchBatchState.diagnostics ?? null,
-					mergeResults: (orchBatchState.mergeResults || []).map((mr) => ({
-						waveIndex: mr.waveIndex,
-						status: mr.status,
-						failedLane: mr.failedLane,
-						failureReason: mr.failureReason,
-					})),
-				};
-				if (orchBatchState.phase === "completed" && (mode === "supervised" || mode === "auto")) {
-					triggerSupervisorIntegration(
-						pi,
-						supervisorState,
-						orchBatchState,
-						mode,
-						execCtx!.repoRoot,
-						buildIntegrationExecutor(execCtx!.repoRoot, opId, execCtx!.workspaceRoot),
-						buildCiDeps(execCtx!.repoRoot, execCtx!.workspaceRoot),
-						sDeps,
-					);
-					return;
-				}
-				if ((mode === "supervised" || mode === "auto") && orchBatchState.phase !== "completed") {
-					pi.sendMessage(
-						{
-							customType: "supervisor-integration-skipped",
-							content: [
-								{
-									type: "text",
-									text:
-										`📋 **Batch ended** (phase: ${orchBatchState.phase}). ` +
-										`Integration skipped — only completed batches are eligible.\n` +
-										`Use \`/orch-resume\` to continue or \`/orch-integrate\` manually after resolving issues.`,
-								},
-							],
-							display: `Integration skipped — batch ${orchBatchState.phase}`,
-						},
-						{ triggerTurn: false },
-					);
-				}
-				presentBatchSummary(
-					pi,
-					orchBatchState,
-					execCtx!.workspaceRoot,
-					opId,
-					orchBatchState.diagnostics,
-					sDeps.mergeResults,
-				);
-				const postBatchContext: SupervisorRoutingContext =
-					orchBatchState.phase === "completed"
-						? {
-								routingState: "completed-batch",
-								contextMessage:
-									`Batch **${orchBatchState.batchId}** completed — ` +
-									`${orchBatchState.succeededTasks}/${orchBatchState.totalTasks} tasks succeeded.\n\n` +
-									`The orch branch \`${orchBatchState.orchBranch}\` is ready to integrate.\n` +
-									`Would you like me to integrate it, or would you prefer to review first?\n\n` +
-									`You can also:\n` +
-									`• Run \`/orch-integrate\` (or \`/orch-integrate --pr\`) to integrate\n` +
-									`• Create new tasks for the next batch\n` +
-									`• Run a health check`,
-							}
-						: {
-								routingState: "no-tasks",
-								contextMessage:
-									`Batch **${orchBatchState.batchId}** ended (${orchBatchState.phase}).\n\n` +
-									`${orchBatchState.succeededTasks} succeeded, ${orchBatchState.failedTasks} failed, ` +
-									`${orchBatchState.skippedTasks} skipped.\n\n` +
-									`What would you like to do next?`,
-							};
-				transitionToRoutingMode(pi, supervisorState, postBatchContext);
+				dispatchBatchEndEpilogue(ctx);
 			},
 			// ── TP-076: Supervisor alert handler — injects alerts as user messages ──
 			(alert) => {
@@ -2930,7 +3467,20 @@ export default function (pi: ExtensionAPI) {
 					);
 					return;
 				}
-				pi.sendUserMessage(alert.summary, { deliverAs: "followUp" });
+				// #620: stale-safe — pi.sendUserMessage is assertActive-guarded on
+				// ExtensionAPI; a stale ctx from this async worker-IPC alert callback
+				// would otherwise crash Pi. #597 safeSendMessageFromTimer covers
+				// sendMessage only, so use the general callback guard here.
+				safeCtxCallFromCallback(
+					() =>
+						pi.sendUserMessage(alert.summary, {
+							// #review-boundary: spiral/order escalations are urgent — steer
+							// (interrupt current turn) so the supervisor adjudicates now;
+							// routine alerts stay followUp (queue to next turn boundary).
+							deliverAs: alert.category === "review-intervention-needed" ? "steer" : "followUp",
+						}),
+					"alert.sendUserMessage",
+				);
 			},
 			// TP-187 (#538): Lane-terminated handler.
 			(info) => {
@@ -2984,7 +3534,13 @@ export default function (pi: ExtensionAPI) {
 		const mode: AbortMode = hard ? "hard" : "graceful";
 		const prefix = orchConfig.orchestrator.sessionPrefix;
 
-		const stateRoot = execCtx?.repoRoot ?? ctx.cwd;
+		// #631: state is read, persisted and deleted at the CANONICAL root — the same
+		// root the ownership gate below authorizes against.
+		const stateRoot = canonicalStateRoot(ctx.cwd);
+		{
+			const conflict = conflictingRootsRefusal("orch_abort", ctx.cwd);
+			if (conflict) return conflict;
+		}
 		const messages: string[] = [`🛑 Abort requested (${mode} mode, prefix: ${prefix})...`];
 
 		// Step 1: Write abort signal file
@@ -3006,18 +3562,87 @@ export default function (pi: ExtensionAPI) {
 		// Step 2: Set pause signal and forward to worker
 		if (orchBatchState.pauseSignal) {
 			orchBatchState.pauseSignal.paused = true;
+			orchBatchState.pauseSignal.cause = "abort";
 			messages.push("  ✓ Pause signal set on in-memory batch state");
 		}
-		// TP-071: Forward pause to engine and kill on hard abort
-		if (activeWorker) {
-			activeWorker.send({ type: "pause" });
-			if (hard) {
-				activeWorker.kill();
-				activeWorker = null;
-				messages.push("  ✓ Engine process killed (hard abort)");
-			} else {
-				messages.push("  ✓ Pause signal forwarded to engine process");
+		// ── #631: ownership + verified shutdown BEFORE any destructive step ──
+		// Abort persists `stopped` and deletes batch state. That may only happen
+		// once no engine can still be writing that state:
+		//   - engine attached HERE → cooperatively pause, then VERIFY it has exited
+		//     (graceful: within the grace period, then escalate; hard: kill now);
+		//     the main-thread fallback must have settled. Unverified → refuse cleanup.
+		//   - engine elsewhere → same rule as every recovery mutation: alive or
+		//     unknown (no identity) → refuse; verified dead/exited → proceed.
+		const ownershipRoot = stateRoot;
+		if (!engineAttachedHere()) {
+			const target = resolveRecoveryTarget(ownershipRoot, false);
+			if (target) {
+				const decision = decideRecoveryOwnership({
+					operation: "orch_abort",
+					local: {
+						engineAttached: false,
+						phase: orchBatchState.phase,
+						batchId: orchBatchState.batchId,
+						pid: null,
+					},
+					target,
+					liveness: assessEngineLiveness(ownershipRoot, target.batchId),
+					priorSupervisor,
+				});
+				if (!decision.proceed) {
+					try {
+						unlinkSync(abortSignalFile);
+					} catch {}
+					return `${decision.reason}\n   (abort here cannot stop that engine; it would only delete state underneath it)`;
+				}
+			}
+		} else if (activeWorker) {
+			// Forked engine in this session.
+			const child = activeWorker;
+			child.send({ type: "pause" });
+			const graceMs = Math.max(0, orchConfig.failure.abort_grace_period * 1000);
+			let exited = false;
+			if (!hard) {
+				messages.push(
+					`  ✓ Pause signal forwarded to engine process — waiting up to ${Math.round(graceMs / 1000)}s for it to checkpoint and exit`,
+				);
+				exited = await waitForChildExit(child, graceMs);
+			}
+			if (!exited) {
+				child.kill();
+				exited = await waitForChildExit(child, 5_000);
+			}
+			if (!exited) {
+				try {
+					child.kill("SIGKILL");
+				} catch {}
+				exited = await waitForChildExit(child, 3_000);
+			}
+			if (!exited) {
+				return (
+					`❌ Abort: engine process (PID ${child.pid}) is still alive after pause${hard ? "" : ` (${Math.round(graceMs / 1000)}s grace)`}, SIGTERM and SIGKILL. ` +
+					`Refusing to persist/delete batch state underneath a live engine. Terminate it manually and re-run orch_abort.`
+				);
+			}
+			activeWorker = null;
+			messages.push(
+				`  ✓ Engine process exit verified (PID ${child.pid}${hard ? ", hard abort" : ""})`,
+			);
+		} else {
+			// Main-thread fallback engine: it shares orchBatchState, so the pause
+			// signal above reaches it directly; wait for it to settle.
+			const graceMs = Math.max(2_000, orchConfig.failure.abort_grace_period * 1000);
+			const deadline = Date.now() + graceMs;
+			while (isFallbackEngineActive() && Date.now() < deadline) {
+				await new Promise((r) => setTimeout(r, 250));
+			}
+			if (isFallbackEngineActive()) {
+				return (
+					`❌ Abort: the in-process (fallback) engine has not settled within ${Math.round(graceMs / 1000)}s of the pause signal. ` +
+					`Refusing to persist/delete batch state underneath it. Wait for it to pause, then re-run orch_abort.`
+				);
 			}
+			messages.push("  ✓ In-process engine settled");
 		}
 
 		const hasActiveBatch =
@@ -3140,6 +3765,7 @@ export default function (pi: ExtensionAPI) {
 		const pausablePhases = new Set(["launching", "executing", "merging", "planning"]);
 		if (pausablePhases.has(orchBatchState.phase)) {
 			orchBatchState.pauseSignal.paused = true;
+			orchBatchState.pauseSignal.cause = "operator";
 			activeWorker?.send({ type: "pause" });
 			messages.push(`  ✓ Wave paused (batch ${orchBatchState.batchId})`);
 		} else {
@@ -3212,12 +3838,6 @@ export default function (pi: ExtensionAPI) {
 	 * The engine picks up the state change on its next poll cycle.
 	 */
 	function doOrchRetryTask(taskId: string, ctx: ExtensionContext): string {
-		// TP-077 R001-1: Reject while engine is actively running (no IPC retry path)
-		const activePhases = new Set(["launching", "executing", "merging", "planning"]);
-		if (activePhases.has(orchBatchState.phase)) {
-			return `❌ Cannot retry task while batch is ${orchBatchState.phase}. Pause or wait for the current operation to finish first.`;
-		}
-
 		const stateRoot = execCtx?.workspaceRoot ?? execCtx?.repoRoot ?? ctx.cwd;
 
 		// Load persisted state
@@ -3232,6 +3852,16 @@ export default function (pi: ExtensionAPI) {
 			return "❌ No batch state found. There is no active or recent batch to modify.";
 		}
 
+		// #631: single ownership gate against the PERSISTED target (TP-077 R001-1's
+		// "reject while the engine is running" is case 1 of the gate).
+		{
+			const refusal = recoveryOwnershipGate("orch_retry_task", stateRoot, {
+				batchId: state.batchId,
+				phase: state.phase,
+			});
+			if (refusal) return refusal;
+		}
+
 		// Find the task
 		const taskRecord = state.tasks.find((t) => t.taskId === taskId);
 		if (!taskRecord) {
@@ -3239,12 +3869,24 @@ export default function (pi: ExtensionAPI) {
 			return `❌ Task "${taskId}" not found in batch ${state.batchId}.\nKnown tasks: ${knownIds || "(none)"}`;
 		}
 
-		// Validate: only failed or stalled tasks can be retried
-		if (taskRecord.status !== "failed" && taskRecord.status !== "stalled") {
-			return `❌ Cannot retry task "${taskId}" — current status is "${taskRecord.status}". Only failed or stalled tasks can be retried.`;
+		// Validate: failed, stalled or SKIPPED tasks can be retried. Skipped is
+		// included because a runtime defect (pause → skipped, penster
+		// 20260906T194514) left tasks skipped that never ran; the documented
+		// recovery (retry → resume) must be able to start from that state.
+		if (
+			taskRecord.status !== "failed" &&
+			taskRecord.status !== "stalled" &&
+			taskRecord.status !== "skipped"
+		) {
+			return `❌ Cannot retry task "${taskId}" — current status is "${taskRecord.status}". Only failed, stalled or skipped tasks can be retried.`;
 		}
 
 		const prevStatus = taskRecord.status;
+		// Preserve recovery provenance: a saved partial-progress branch is the only
+		// record of work whose worktree may already be gone. Report it instead of
+		// silently clearing it.
+		const preservedBranch = taskRecord.partialProgressBranch;
+		const preservedCommits = taskRecord.partialProgressCommits;
 
 		// Reset task to pending
 		taskRecord.status = "pending";
@@ -3253,12 +3895,21 @@ export default function (pi: ExtensionAPI) {
 		taskRecord.startedAt = null;
 		taskRecord.endedAt = null;
 		taskRecord.exitDiagnostic = undefined;
-		taskRecord.partialProgressCommits = undefined;
-		taskRecord.partialProgressBranch = undefined;
+		// Keep partialProgressBranch/Commits: they are recovery PROVENANCE (a saved
+		// ref may be the only copy of the work); the engine overwrites them when the
+		// re-executed task produces new partial progress.
+
+		// #629: on the v2 runtime the SEGMENT record is authoritative — resume's
+		// reconstructSegmentFrontier() re-derives task status from segments, so a
+		// task-only reset is silently undone and the wave is counted as done.
+		// Reset the failed/stalled segments too (worktree identity preserved).
+		const segmentReset = resetTaskSegmentsForRetry(state, taskId);
 
 		// Adjust counters: only decrement failedTasks if the task was in a failure state
 		if (prevStatus === "failed" || prevStatus === "stalled") {
 			state.failedTasks = Math.max(0, state.failedTasks - 1);
+		} else if (prevStatus === "skipped") {
+			state.skippedTasks = Math.max(0, (state.skippedTasks ?? 0) - 1);
 		}
 
 		// Recompute blocked dependents — the retried task is no longer a failure,
@@ -3273,6 +3924,7 @@ export default function (pi: ExtensionAPI) {
 			const newBlocked = computeTransitiveDependents(
 				remainingFailures,
 				orchBatchState.dependencyGraph,
+				batchTaskScope(state.wavePlan),
 			);
 			state.blockedTaskIds = [...newBlocked].sort();
 			state.blockedTasks = newBlocked.size;
@@ -3286,6 +3938,19 @@ export default function (pi: ExtensionAPI) {
 		if (state.phase === "failed") {
 			state.phase = "stopped";
 		}
+		// A "completed" batch that wrongly skipped a task (the pause→skipped defect)
+		// must be re-openable: retrying a task in a completed batch moves the batch
+		// to "stopped" (resumable with force). The ownership gate above already
+		// verified no engine is driving it; refuse if the batch was integrated.
+		let reopenedCompleted = false;
+		if (state.phase === "completed") {
+			if (orchBatchState.batchId === state.batchId && orchBatchState.integratedAt) {
+				return `❌ Cannot retry "${taskId}": batch ${state.batchId} has already been integrated. Start a new batch for follow-up work.`;
+			}
+			state.phase = "stopped";
+			state.endedAt = null;
+			reopenedCompleted = true;
+		}
 
 		// Update timestamp
 		state.updatedAt = Date.now();
@@ -3313,9 +3978,20 @@ export default function (pi: ExtensionAPI) {
 			state.phase === "stopped"
 				? "Use orch_resume(force=true) to re-execute the batch."
 				: "Use orch_resume() to re-execute the batch.";
+		const provenanceNote = preservedBranch
+			? `   Preserved progress: branch ${preservedBranch}${preservedCommits ? ` (${preservedCommits} commit(s))` : ""} — the worktree may be recreated from the base; inspect/cherry-pick that branch if the work must carry forward.\n`
+			: "";
+		const reopenNote = reopenedCompleted
+			? `   Batch was "completed" — reopened as "stopped" (task ${taskId} had been ${prevStatus}).\n`
+			: "";
 		return (
 			`✅ Task "${taskId}" reset to pending for re-execution.\n` +
 			`   Previous status: ${prevStatus}\n` +
+			(segmentReset.resetSegmentIds.length > 0
+				? `   Segments reset: ${segmentReset.resetSegmentIds.join(", ")}${segmentReset.preservedSegmentIds.length > 0 ? ` (preserved: ${segmentReset.preservedSegmentIds.join(", ")})` : ""}\n`
+				: "") +
+			reopenNote +
+			provenanceNote +
 			`   Batch phase: ${state.phase} | Failed: ${state.failedTasks}/${state.totalTasks}\n` +
 			`   ${resumeHint}`
 		);
@@ -3328,12 +4004,6 @@ export default function (pi: ExtensionAPI) {
 	 * The engine picks up the state change on its next poll cycle.
 	 */
 	function doOrchSkipTask(taskId: string, ctx: ExtensionContext): string {
-		// TP-077 R001-1: Reject while engine is actively running (no IPC skip path)
-		const activePhases = new Set(["launching", "executing", "merging", "planning"]);
-		if (activePhases.has(orchBatchState.phase)) {
-			return `❌ Cannot skip task while batch is ${orchBatchState.phase}. Pause or wait for the current operation to finish first.`;
-		}
-
 		const stateRoot = execCtx?.workspaceRoot ?? execCtx?.repoRoot ?? ctx.cwd;
 
 		// Load persisted state
@@ -3348,6 +4018,16 @@ export default function (pi: ExtensionAPI) {
 			return "❌ No batch state found. There is no active or recent batch to modify.";
 		}
 
+		// #631: single ownership gate against the PERSISTED target (TP-077 R001-1's
+		// "reject while the engine is running" is case 1 of the gate).
+		{
+			const refusal = recoveryOwnershipGate("orch_skip_task", stateRoot, {
+				batchId: state.batchId,
+				phase: state.phase,
+			});
+			if (refusal) return refusal;
+		}
+
 		// Find the task
 		const taskRecord = state.tasks.find((t) => t.taskId === taskId);
 		if (!taskRecord) {
@@ -3371,6 +4051,8 @@ export default function (pi: ExtensionAPI) {
 		taskRecord.status = "skipped";
 		taskRecord.exitReason = "Skipped by supervisor";
 		taskRecord.endedAt = Date.now();
+		// #629: keep segment records in agreement (segment authority on v2).
+		markTaskSegmentsSkipped(state, taskId, taskRecord.endedAt);
 
 		// Adjust counters
 		state.skippedTasks = (state.skippedTasks ?? 0) + 1;
@@ -3396,6 +4078,7 @@ export default function (pi: ExtensionAPI) {
 			const newBlocked = computeTransitiveDependents(
 				remainingFailures,
 				orchBatchState.dependencyGraph,
+				batchTaskScope(state.wavePlan),
 			);
 
 			// Find tasks that were blocked but are now unblocked
@@ -3478,12 +4161,6 @@ export default function (pi: ExtensionAPI) {
 		skipFailed: boolean,
 		ctx: ExtensionContext,
 	): string {
-		// Reject while engine is actively running
-		const activePhases = new Set(["launching", "executing", "merging", "planning"]);
-		if (activePhases.has(orchBatchState.phase)) {
-			return `❌ Cannot force merge while batch is ${orchBatchState.phase}. Pause or wait for the current operation to finish first.`;
-		}
-
 		const stateRoot = execCtx?.workspaceRoot ?? execCtx?.repoRoot ?? ctx.cwd;
 
 		// Load persisted state
@@ -3498,6 +4175,16 @@ export default function (pi: ExtensionAPI) {
 			return "❌ No batch state found. There is no active or recent batch to modify.";
 		}
 
+		// #631: single ownership gate against the PERSISTED target (TP-077 R001-1's
+		// "reject while the engine is running" is case 1 of the gate).
+		{
+			const refusal = recoveryOwnershipGate("orch_force_merge", stateRoot, {
+				batchId: state.batchId,
+				phase: state.phase,
+			});
+			if (refusal) return refusal;
+		}
+
 		// Force-merge is a recovery action for non-running failed/paused batches.
 		const resumablePhases = new Set(["paused", "stopped", "failed"]);
 		if (!resumablePhases.has(state.phase)) {
@@ -3608,6 +4295,7 @@ export default function (pi: ExtensionAPI) {
 				const newBlocked = computeTransitiveDependents(
 					remainingFailures,
 					orchBatchState.dependencyGraph,
+					batchTaskScope(state.wavePlan),
 				);
 				state.blockedTaskIds = [...newBlocked].sort();
 				state.blockedTasks = newBlocked.size;
@@ -3702,8 +4390,14 @@ export default function (pi: ExtensionAPI) {
 		// Resolve integration context
 		const { repoRoot } = execCtx!;
 		const stateRoot = execCtx!.workspaceRoot;
+		// #631: batch state is resolved at the CANONICAL root (workspace root in
+		// workspace mode) — the same root the ownership gate authorizes against.
+		{
+			const conflict = conflictingRootsRefusal("orch_integrate", repoRoot);
+			if (conflict) return { message: conflict, error: true };
+		}
 		const resolution = resolveIntegrationContext(parsed, {
-			loadBatchState: () => loadBatchState(repoRoot),
+			loadBatchState: () => loadBatchState(stateRoot ?? repoRoot),
 			getCurrentBranch: () => getCurrentBranch(repoRoot),
 			listOrchBranches: () => {
 				const result = runGit(["branch", "--list", "orch/*"], repoRoot);
@@ -3724,11 +4418,83 @@ export default function (pi: ExtensionAPI) {
 			return { message: resolution.error, error: severity !== "info" };
 		}
 
-		const { orchBranch, baseBranch, batchId, currentBranch, notices } =
-			resolution as IntegrationContext;
+		const { orchBranch, baseBranch, currentBranch, notices } = resolution as IntegrationContext;
+		let batchId = (resolution as IntegrationContext).batchId;
 		const outputLines: string[] = [];
 		let hasWarning = false;
 
+		// #631: integration merges and cleans up the orch branch. A "completed"
+		// phase on disk is not proof the engine has finished tearing down (or that
+		// an inherited batch's engine is gone). Refuse while it is verifiably alive.
+		// (dead/exited/none proceed — integration does not drive the engine.)
+		{
+			if (engineAttachedHere()) {
+				return {
+					message: `⏳ This session's engine (PID ${activeWorker?.pid ?? process.pid}) is still running/shutting down — integrate after it exits.`,
+					error: true,
+				};
+			}
+			// Ownership is looked up BY THE SELECTED BRANCH at the canonical state root —
+			// not by whichever batch happens to be persisted or reconstructable. The
+			// batch behind `orchBranch` may have no batch-state.json (aborted) and may
+			// not be reconstructable (worker manifests gone) while its engine identity
+			// still records a live pid. Every associated batch must pass the full rule
+			// (alive/none → refuse; dead/exited → proceed). Persisted state for the same
+			// branch is included; a persisted batch for a DIFFERENT branch is irrelevant.
+			const integRoot = stateRoot ?? repoRoot;
+			const associated = new Map<
+				string,
+				{ batchId: string; phase: string; liveness: ReturnType<typeof assessEngineLiveness> }
+			>();
+			for (const b of findBatchesForOrchBranch(integRoot, orchBranch)) {
+				associated.set(b.batchId, { batchId: b.batchId, phase: "unknown", liveness: b.liveness });
+			}
+			try {
+				const persisted = loadBatchState(integRoot);
+				if (persisted && (persisted.orchBranch === orchBranch || persisted.batchId === batchId)) {
+					associated.set(persisted.batchId, {
+						batchId: persisted.batchId,
+						phase: persisted.phase,
+						liveness: assessEngineLiveness(integRoot, persisted.batchId),
+					});
+				}
+			} catch {
+				/* reported elsewhere */
+			}
+			if (batchId && !associated.has(batchId)) {
+				associated.set(batchId, {
+					batchId,
+					phase: "completed",
+					liveness: assessEngineLiveness(integRoot, batchId),
+				});
+			}
+			for (const target of associated.values()) {
+				const decision = decideRecoveryOwnership({
+					operation: "orch_integrate",
+					local: {
+						engineAttached: false,
+						phase: orchBatchState.phase,
+						batchId: orchBatchState.batchId,
+						pid: null,
+					},
+					target: { batchId: target.batchId, phase: target.phase },
+					liveness: target.liveness,
+					priorSupervisor,
+				});
+				if (!decision.proceed) return { message: decision.reason, error: true };
+			}
+			// No batch is associated with this branch (pure branch integration):
+			// nothing an engine could be driving — proceed.
+
+			// Bind cleanup/history to the batch behind THIS branch. The resolver
+			// leaves batchId empty when an explicit branch differs from persisted
+			// state; a unique associated runtime batch fills it in. Ambiguous (>1)
+			// → leave empty: batch-scoped cleanup is skipped rather than guessed.
+			if (!batchId && associated.size === 1) {
+				batchId = [...associated.values()][0].batchId;
+			}
+		}
+
 		for (const notice of notices) {
 			outputLines.push(notice);
 		}
@@ -3863,7 +4629,7 @@ export default function (pi: ExtensionAPI) {
 
 		const branchCleanupLines: string[] = [];
 		for (const repo of allRepos) {
-			const branchCleanup = deleteStaleBranches(repo.root, opId, batchId);
+			const branchCleanup = deleteStaleBranches(repo.root, opId, batchId, stateRoot ?? repoRoot);
 			const totalDeleted =
 				branchCleanup.deletedTaskBranches.length + branchCleanup.deletedSavedBranches.length;
 			if (totalDeleted > 0 || branchCleanup.failedDeletes.length > 0) {
@@ -3910,6 +4676,17 @@ export default function (pi: ExtensionAPI) {
 			hasWarning = true;
 		}
 
+		// #610: the batch is integrated. Any batch-end epilogue still DEFERRED behind
+		// this turn (the engine finished while the supervisor was mid-turn, #621)
+		// would fire at agent_settled with stale content — "Ready for integration /
+		// run orch_integrate()" or the supervised "Integration Plan … merge commit"
+		// prompt for an orch branch that no longer exists. Supersede it now, and mark
+		// the in-memory batch integrated so a not-yet-deferred dispatch also skips.
+		if (orchBatchState.batchId === batchId || !batchId) {
+			orchBatchState.integratedAt = Date.now();
+		}
+		supersedeDeferredEpilogue();
+
 		// TP-179: Write integratedAt to batch history before deleting state
 		if (batchId) {
 			try {
@@ -3919,8 +4696,16 @@ export default function (pi: ExtensionAPI) {
 			}
 		}
 
+		// #631: delete persisted state ONLY if it belongs to the integrated branch/batch.
+		// An explicit branch integration must not erase an unrelated batch's recovery
+		// checkpoint (its engine may even still be alive).
 		try {
-			deleteBatchState(stateRoot);
+			const deleted = deleteBatchStateIfOwned(stateRoot ?? repoRoot, batchId, orchBranch);
+			if (deleted === false) {
+				outputLines.push(
+					`ℹ️ Persisted batch state belongs to a different batch/branch — left in place (not part of this integration).`,
+				);
+			}
 		} catch {
 			/* best effort */
 		}
@@ -4161,6 +4946,14 @@ export default function (pi: ExtensionAPI) {
 
 					ctx.ui.notify(`🔄 **${reason}** Activating supervisor.\n\n` + summary, "info");
 
+					// #631: record what we know about the previous owner. The engine of a
+					// batch we did not start is NOT attached to this process; the active-
+					// phase guards use this + engine.json to decide whether an inherited
+					// "executing" phase is a resumable orphan.
+					priorSupervisor =
+						"lock" in lockResult && lockResult.lock
+							? { pid: lockResult.lock.pid, alive: isProcessAlive(lockResult.lock.pid) }
+							: null;
 					// Populate orchBatchState from persisted state
 					orchBatchState.batchId = batchState.batchId;
 					orchBatchState.phase = batchState.phase as typeof orchBatchState.phase;
@@ -4207,6 +5000,14 @@ export default function (pi: ExtensionAPI) {
 						"warning",
 					);
 
+					// #631: record what we know about the previous owner. The engine of a
+					// batch we did not start is NOT attached to this process; the active-
+					// phase guards use this + engine.json to decide whether an inherited
+					// "executing" phase is a resumable orphan.
+					priorSupervisor =
+						"lock" in lockResult && lockResult.lock
+							? { pid: lockResult.lock.pid, alive: isProcessAlive(lockResult.lock.pid) }
+							: null;
 					// Populate orchBatchState from persisted state
 					orchBatchState.batchId = batchState.batchId;
 					orchBatchState.phase = batchState.phase as typeof orchBatchState.phase;
@@ -4709,6 +5510,7 @@ export default function (pi: ExtensionAPI) {
 			"The 'to' parameter must be a valid agent session name from the current batch.",
 			"Use orch_status() to see active session names.",
 			"Default type is 'steer' (course correction). Other types: 'query', 'abort', 'info'.",
+			"HOLD CONTRACT (#630): when a worker is holding for a ruling you escalated for, send type='info' to ACKNOWLEDGE (\"received, ruling pending\") — it keeps the worker on hold and resets its relaunch budget. Send type='steer' only for the actual ruling/instruction — it releases the hold.",
 			"Messages are limited to 4KB. For larger context, write to a file and reference by path.",
 		],
 		parameters: Type.Object({
@@ -4810,6 +5612,29 @@ export default function (pi: ExtensionAPI) {
 			return `❌ Batch ${state.batchId} is in terminal phase (${state.phase}). Start or resume a batch before sending messages.`;
 		}
 
+		// #630: a registry agent still marked running whose PROCESS is gone gets a
+		// distinct, actionable error (pid, last-seen, what to do) instead of the
+		// generic "unknown session" that collectKnownAgentIds would otherwise
+		// produce after filtering dead pids. This is the #630 incident: the worker
+		// died after an unanswered escalation; registry stayed `running` frozen.
+		try {
+			const registry = readRegistrySnapshot(stateRoot, state.batchId);
+			const manifest = registry?.agents[to];
+			if (manifest && !isTerminalStatus(manifest.status) && !registryIsProcessAlive(manifest.pid)) {
+				const lastSeen = new Date(registry!.updatedAt).toISOString();
+				return (
+					`❌ Agent "${to}" is DEAD: its process (PID ${manifest.pid}) no longer exists, but the registry still ` +
+					`marks it "${manifest.status}" (last registry update ${lastSeen}${manifest.taskId ? `, task ${manifest.taskId}` : ""}). ` +
+					`No live consumer can receive this message.\n` +
+					`   Do NOT hand-edit registry.json. orch_resume(force=true) reconciles the dead worker ` +
+					`(re-execute in its existing worktree; committed work survives) — if the batch is inherited, ` +
+					`the ownership gate must pass first (see the takeover summary's Engine line).`
+				);
+			}
+		} catch {
+			/* registry unreadable — fall through to the normal validation */
+		}
+
 		// Build valid runtime agent IDs (registry-first, legacy fallback).
 		const validSessions = new Set<string>(collectKnownAgentIds(stateRoot, state));
 
@@ -5255,6 +6080,188 @@ export default function (pi: ExtensionAPI) {
 		return lines.join("\n");
 	}
 
+	/**
+	 * #631: record operator-verified engine shutdown for the current/persisted
+	 * batch. Shared by the supervisor tool and the /orch-confirm-engine-shutdown
+	 * command. Always audited.
+	 */
+	function doOrchConfirmEngineShutdown(
+		note: string,
+		stateRoot: string,
+		explicitBatchId?: string,
+	): string {
+		// Target: an EXPLICIT batchId (exactly the batch a refusal named — works for
+		// meta-only legacy batches that are not reconstructable), else the same
+		// target the recovery gates use: persisted → reconstructed → cached.
+		const explicit = (explicitBatchId ?? "").trim();
+		if (explicit && !/^[A-Za-z0-9._-]+$/.test(explicit)) {
+			return `❌ Invalid batchId "${explicit}".`;
+		}
+		const target = explicit ? null : resolveRecoveryTarget(stateRoot, true);
+		const batchId =
+			explicit || target?.batchId || orchBatchState.batchId || supervisorState.batchId || "";
+		if (!batchId) {
+			return (
+				"❌ No batch to confirm shutdown for (no batch on disk, nothing reconstructable, nothing in memory). " +
+				"Pass the batchId named by the refusal explicitly."
+			);
+		}
+		if (!note || note.trim().length < 8) {
+			return "❌ A verification note is required (what you checked and how) — it is written to engine.json and the audit trail.";
+		}
+		const result = recordOperatorConfirmedShutdown(stateRoot, batchId, {
+			supervisorPid: process.pid,
+			note,
+		});
+		logRecoveryAction(stateRoot, batchId, {
+			action: "confirm_engine_shutdown",
+			classification: "destructive",
+			context: `operator-verified engine shutdown for inherited batch: ${note.slice(0, 300)}`,
+			command: "orch_confirm_engine_shutdown",
+			result: result.ok ? "success" : "failure",
+			detail: result.reason,
+		});
+		return result.ok
+			? `✅ ${result.reason}. Recovery tools (orch_resume(force=true), retry/skip/force_merge) will now proceed via the verified path. Audit entry written.`
+			: `❌ Not recorded: ${result.reason}`;
+	}
+
+	pi.registerCommand("orch-confirm-engine-shutdown", {
+		description:
+			"Record operator-verified engine shutdown for a batch with no engine identity (#631): /orch-confirm-engine-shutdown [--batch <batchId>] <what you verified>",
+		handler: async (args, ctx) => {
+			// Syntax: /orch-confirm-engine-shutdown [--batch <batchId>] <note>
+			let raw = (args ?? "").trim();
+			let explicitBatchId: string | undefined;
+			const m = /(?:^|\s)--batch\s+(\S+)/.exec(raw);
+			if (m) {
+				explicitBatchId = m[1];
+				raw = raw.replace(m[0], " ").trim();
+			}
+			const stateRoot = execCtx?.workspaceRoot ?? execCtx?.repoRoot ?? ctx.cwd;
+			const result = doOrchConfirmEngineShutdown(raw, stateRoot, explicitBatchId);
+			ctx.ui.notify(result, result.startsWith("✅") ? "info" : "warning");
+		},
+	});
+
+	// ── #631: explicit, audited legacy shutdown confirmation ──
+	// For a batch with NO engine identity (pre-#631 engine, or one that never
+	// published), recovery tools fail closed: unknown ownership is not confirmed
+	// shutdown. The operator verifies out-of-band that no engine process exists,
+	// then records it here. The record is an `exited` identity (so every gate
+	// proceeds through the normal verified path) AND an audit-trail entry.
+	pi.registerTool({
+		name: "orch_confirm_engine_shutdown",
+		label: "Confirm Engine Shutdown",
+		description:
+			"Record that the operator verified NO engine process is running for the inherited batch (used only when " +
+			"no engine identity is recorded, so the runtime cannot verify it). Unblocks orch_resume/retry/skip/force_merge. " +
+			"Refuses when a real engine identity exists — that path is pid-verified and cannot be overridden.",
+		promptSnippet:
+			"orch_confirm_engine_shutdown(note) — record operator-verified engine shutdown for a batch with no engine identity",
+		promptGuidelines: [
+			"Only after verifying out-of-band that no engine process exists for this repo (e.g. Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match 'engine-worker' } on Windows; pgrep -af engine-worker on POSIX).",
+			"Never use this to override a refusal that names a live engine PID — wait for it or terminate it.",
+			"The note should say what you checked; it is written to engine.json and the audit trail.",
+		],
+		parameters: Type.Object({
+			note: Type.String({
+				description:
+					"What was verified and how (e.g. 'no engine-worker processes in Get-CimInstance output at 21:32')",
+			}),
+			batchId: Type.Optional(
+				Type.String({
+					description:
+						"Exact batchId to confirm (the one named by the refusal). Omit to use the persisted/reconstructed batch.",
+				}),
+			),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const text = doOrchConfirmEngineShutdown(params.note, resolveToolStateRoot(ctx), params.batchId);
+			return { content: [{ type: "text" as const, text }], details: undefined };
+		},
+	});
+
+	// ── #625: Audit-trail tool ───────────────────────────────────
+	// The supervisor's audit trail (.pi/supervisor/actions.jsonl) was previously
+	// hand-appended via bash per the system-prompt instructions — the LLM invented
+	// the `ts` values (5+ hours off, non-monotonic, crossing calendar days).
+	// logRecoveryAction() existed but nothing exposed it. This tool code-stamps
+	// ts and batchId so the audit trail is trustworthy.
+	pi.registerTool({
+		name: "log_recovery_action",
+		label: "Log Recovery Action",
+		description:
+			"Append an entry to the supervisor audit trail (.pi/supervisor/actions.jsonl). " +
+			"Timestamps and batchId are stamped by code — never hand-write the file.",
+		promptSnippet:
+			"log_recovery_action(action, classification, context, command, result, detail, …) — append audit-trail entry",
+		promptGuidelines: [
+			"Use log_recovery_action for EVERY audit-trail entry — never append to actions.jsonl with bash.",
+			"Timestamps and batchId are stamped automatically; do not supply them.",
+			'For destructive actions: log result="pending" BEFORE executing, then log the real result after.',
+			"classification: diagnostic | tier0_known | destructive.",
+		],
+		parameters: Type.Object({
+			action: Type.String({ description: 'Action identifier, e.g. "merge_retry", "kill_session"' }),
+			classification: Type.Union(
+				[Type.Literal("diagnostic"), Type.Literal("tier0_known"), Type.Literal("destructive")],
+				{ description: "Recovery action classification" },
+			),
+			context: Type.String({ description: "Why this action was taken" }),
+			command: Type.String({ description: "Command or operation executed" }),
+			result: Type.Union(
+				[
+					Type.Literal("pending"),
+					Type.Literal("success"),
+					Type.Literal("failure"),
+					Type.Literal("skipped"),
+				],
+				{ description: "Outcome (pending = before a destructive action)" },
+			),
+			detail: Type.String({ description: "Result detail — error on failure, summary on success" }),
+			waveIndex: Type.Optional(Type.Number({ description: "Wave index if wave-scoped" })),
+			laneNumber: Type.Optional(Type.Number({ description: "Lane number if lane-scoped" })),
+			taskId: Type.Optional(Type.String({ description: "Task ID if task-scoped" })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			try {
+				const stateRoot = resolveToolStateRoot(ctx);
+				const batchId = orchBatchState.batchId || supervisorState.batchId || "unknown";
+				logRecoveryAction(stateRoot, batchId, {
+					action: params.action,
+					classification: params.classification,
+					context: params.context,
+					command: params.command,
+					result: params.result,
+					detail: params.detail,
+					...(params.waveIndex !== undefined ? { waveIndex: params.waveIndex } : {}),
+					...(params.laneNumber !== undefined ? { laneNumber: params.laneNumber } : {}),
+					...(params.taskId !== undefined ? { taskId: params.taskId } : {}),
+				});
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Audit entry logged: ${params.action} (${params.classification}, ${params.result})`,
+						},
+					],
+					details: undefined,
+				};
+			} catch (err) {
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Error logging audit entry: ${err instanceof Error ? err.message : String(err)}`,
+						},
+					],
+					details: undefined,
+				};
+			}
+		},
+	});
+
 	pi.registerTool({
 		name: "trigger_wrap_up",
 		label: "Trigger Wrap Up",
@@ -5611,6 +6618,33 @@ export default function (pi: ExtensionAPI) {
 
 	// ── Session Lifecycle ────────────────────────────────────────────
 
+	// #621 (defense in depth): repair tool_use/tool_result ordering on every
+	// outgoing request. The `context` event fires before each provider call on
+	// the pi-internal AgentMessage[] (before convertToLlm). Any supervisor
+	// `custom` message that was spliced between an assistant tool_use and its
+	// tool_result (from ANY send site — batch summary, integration progress/
+	// result, heartbeat, routing) is moved back after the tool-result group, so
+	// the request is always valid and a mistimed injection can never wedge the
+	// session. Only transforms the per-request context; the persisted tree is
+	// untouched (self-correcting across reloads).
+	pi.on("context", (event: { messages: unknown[] }) => {
+		const repaired = repairToolResultOrdering(event.messages as Array<Record<string, unknown>>);
+		if (repaired !== event.messages) return { messages: repaired };
+	});
+
+	// #621: Flush a deferred batch-end epilogue once the interactive agent has
+	// fully settled (all tool_results appended). Re-check idleness here because a
+	// prior settle handler may have started another run.
+	pi.on("agent_settled", (_event: unknown, ctx: ExtensionContext) => {
+		noticeGate.onSettled(ctx.isIdle(), batchGeneration);
+	});
+
+	// #621: Drop any deferred epilogue and disable the gate on shutdown so a
+	// stale closure cannot fire against a replaced session.
+	pi.on("session_shutdown", () => {
+		noticeGate.dispose();
+	});
+
 	pi.on("session_start", async (_event, ctx) => {
 		// Store widget context for dashboard updates (needed even if startup fails)
 		orchWidgetCtx = ctx;
@@ -5747,6 +6781,14 @@ export default function (pi: ExtensionAPI) {
 						"info",
 					);
 
+					// #631: record what we know about the previous owner. The engine of a
+					// batch we did not start is NOT attached to this process; the active-
+					// phase guards use this + engine.json to decide whether an inherited
+					// "executing" phase is a resumable orphan.
+					priorSupervisor =
+						"lock" in lockResult && lockResult.lock
+							? { pid: lockResult.lock.pid, alive: isProcessAlive(lockResult.lock.pid) }
+							: null;
 					// Populate orchBatchState from persisted state for the supervisor
 					// prompt rebuild. We copy the key fields used by the system prompt.
 					orchBatchState.batchId = batchState.batchId;
@@ -5798,6 +6840,11 @@ export default function (pi: ExtensionAPI) {
 
 					// Store the live lock info so the /orch handler can detect it
 					// (preventing a second /orch from starting a concurrent batch).
+					// #631: the other session's engine is live and NOT ours — record it.
+					priorSupervisor =
+						"lock" in lockResult && lockResult.lock
+							? { pid: lockResult.lock.pid, alive: isProcessAlive(lockResult.lock.pid) }
+							: null;
 					orchBatchState.batchId = batchState.batchId;
 					orchBatchState.phase = batchState.phase as typeof orchBatchState.phase;
 					orchBatchState.baseBranch = batchState.baseBranch;