taskplane 0.30.4 → 0.30.6

package/extensions/taskplane/diagnostic-reports.ts

@@ -10,7 +10,7 @@
  *
  * @module orch/diagnostic-reports
  */
-import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { join } from "path";
 
 import { execLog } from "./execution.ts";
@@ -92,6 +92,12 @@ export interface DiagnosticReportInput {
 	totalTasks: number;
 	/** State root path where `.pi/` lives */
 	stateRoot: string;
+	/**
+	 * #629: per-task cost (USD) from outcome telemetry for the CURRENT pass.
+	 * `diagnostics.taskExits` is not populated by the v2 runtime, so without
+	 * this every report read $0.00. Optional for backward compatibility.
+	 */
+	taskCostUsd?: Record<string, number>;
 }
 
 // ── Diagnostics Directory ────────────────────────────────────────────
@@ -140,8 +146,8 @@ export function buildDiagnosticEvents(input: DiagnosticReportInput): DiagnosticE
 			classification = task.exitDiagnostic.classification;
 		}
 
-		// Cost: from taskExits, else 0
-		const cost = exitSummary?.cost ?? 0;
+		// Cost: from taskExits, else this pass's outcome telemetry, else 0
+		const cost = exitSummary?.cost ?? input.taskCostUsd?.[task.taskId] ?? 0;
 
 		// Duration: from taskExits, else compute from timestamps, else 0
 		let durationSec = 0;
@@ -177,6 +183,79 @@ export function buildDiagnosticEvents(input: DiagnosticReportInput): DiagnosticE
 
 // ── JSONL Generation ─────────────────────────────────────────────────
 
+// ── Cross-pass evidence preservation (#629 side-effect 2) ──
+
+/**
+ * Does this event carry any execution evidence? A task that was not executed
+ * in the current pass (e.g. a no-op resume) produces an evidence-empty event
+ * that would otherwise CLOBBER the prior pass's record when the report is
+ * rewritten (observed: a $55 / 1h42m run reported as $0 / 0s after two
+ * no-op resumes).
+ */
+export function hasExecutionEvidence(evt: DiagnosticEvent): boolean {
+	return (
+		(evt.classification !== "unknown" && evt.classification !== "") ||
+		evt.cost > 0 ||
+		evt.durationSec > 0 ||
+		evt.retries > 0 ||
+		evt.startedAt !== null ||
+		evt.endedAt !== null
+	);
+}
+
+/**
+ * Merge the previous report's events into the current pass's events.
+ *
+ * Rule: CURRENT STATE always comes from the new pass (`status`, `phase`,
+ * `mode`, `batchId`) — a legitimate retry or skip must be reflected. Execution
+ * EVIDENCE is merged FIELD-WISE: each evidence field takes the new pass's
+ * value when it is present/non-zero, else the previous value. This matters
+ * because resume's reconciliation synthesizes outcomes for tasks it did NOT
+ * execute that still carry the persisted classification and a fresh
+ * `endTime` — an all-or-nothing rule would treat those as "evidence" and
+ * erase the prior cost. Cost is never summed across passes (each pass's
+ * telemetry is that attempt's cost; no double counting). Tasks present only
+ * in the previous report are dropped (the new wave plan is authoritative for
+ * membership). Pure; deterministic order follows `next`.
+ */
+export function mergeDiagnosticEvents(
+	previous: DiagnosticEvent[],
+	next: DiagnosticEvent[],
+): DiagnosticEvent[] {
+	const prevByTask = new Map<string, DiagnosticEvent>();
+	for (const p of previous) prevByTask.set(p.taskId, p);
+	return next.map((n) => {
+		const p = prevByTask.get(n.taskId);
+		if (!p) return n;
+		const knownClass = n.classification && n.classification !== "unknown";
+		return {
+			...n,
+			classification: knownClass ? n.classification : p.classification,
+			cost: n.cost > 0 ? n.cost : p.cost,
+			durationSec: n.durationSec > 0 ? n.durationSec : p.durationSec,
+			retries: n.retries > 0 ? n.retries : p.retries,
+			exitReason: n.exitReason || p.exitReason,
+			startedAt: n.startedAt ?? p.startedAt,
+			endedAt: n.endedAt ?? p.endedAt,
+		};
+	});
+}
+
+/** Parse a previously written events JSONL file (tolerant: bad lines skipped). */
+export function parseEventsJsonl(content: string): DiagnosticEvent[] {
+	const out: DiagnosticEvent[] = [];
+	for (const line of content.split(/\r?\n/)) {
+		if (!line.trim()) continue;
+		try {
+			const obj = JSON.parse(line) as Partial<DiagnosticEvent>;
+			if (typeof obj.taskId === "string") out.push(obj as DiagnosticEvent);
+		} catch {
+			/* skip malformed */
+		}
+	}
+	return out;
+}
+
 /**
  * Serialize diagnostic events to JSONL format (one JSON object per line).
  */
@@ -222,7 +301,12 @@ export function buildMarkdownReport(
 	const { succeededTasks, failedTasks, skippedTasks, blockedTasks, totalTasks } = input;
 
 	const batchDurationSec = endedAt ? Math.round((endedAt - startedAt) / 1000) : 0;
-	const batchCost = diagnostics.batchCost ?? 0;
+	// #629: header cost from batch diagnostics when populated, else the sum of
+	// per-task evidence (which survives no-op passes via mergeDiagnosticEvents).
+	const batchCost =
+		diagnostics.batchCost && diagnostics.batchCost > 0
+			? diagnostics.batchCost
+			: events.reduce((sum, e) => sum + (Number.isFinite(e.cost) ? e.cost : 0), 0);
 
 	const lines: string[] = [];
 
@@ -337,10 +421,21 @@ export function emitDiagnosticReports(input: DiagnosticReportInput): void {
 		const opId = resolveOperatorId(input.orchConfig);
 		const dir = ensureDiagnosticsDir(input.stateRoot);
 
-		const events = buildDiagnosticEvents(input);
+		const jsonlPath = join(dir, `${opId}-${input.batchId}-events.jsonl`);
+
+		// #629: preserve prior-pass execution evidence for tasks this pass did
+		// not execute (state fields still come from this pass).
+		let events = buildDiagnosticEvents(input);
+		if (existsSync(jsonlPath)) {
+			try {
+				const previous = parseEventsJsonl(readFileSync(jsonlPath, "utf-8"));
+				events = mergeDiagnosticEvents(previous, events);
+			} catch {
+				/* unreadable prior report — proceed with this pass's events */
+			}
+		}
 
 		// ── JSONL event log ──
-		const jsonlPath = join(dir, `${opId}-${input.batchId}-events.jsonl`);
 		const jsonlContent = eventsToJsonl(events);
 		writeFileSync(jsonlPath, jsonlContent, "utf-8");
 
@@ -471,5 +566,13 @@ export function assembleDiagnosticInput(
 		blockedTasks: batchState.blockedTasks,
 		totalTasks: batchState.totalTasks,
 		stateRoot,
+		taskCostUsd: (() => {
+			const costs: Record<string, number> = {};
+			for (const [taskId, outcome] of outcomeByTaskId) {
+				const c = outcome.telemetry?.costUsd;
+				if (typeof c === "number" && Number.isFinite(c) && c > 0) costs[taskId] = c;
+			}
+			return costs;
+		})(),
 	};
 }

package/extensions/taskplane/diagnostics.ts

@@ -53,6 +53,7 @@ export interface SessionTokenCounts {
  * | `stall_timeout`      | No STATUS.md progress for stall_timeout minutes      |
  * | `user_killed`        | User manually killed the session (e.g., forced process kill) |
  * | `spawn_failure`      | Worker process never spawned (e.g., Pi CLI not findable, worktree provisioning) |
+ * | `review_gate_refusal`| Governance refusal: finalize blocked by an outstanding REVISE/RETHINK review verdict (#626/#629). The worker exited cleanly — NOT a crash, never auto-retried (the review file must change first) |
  * | `unknown`            | Could not determine cause                            |
  *
  * Note: `spawn_failure` (TP-190, #561) is set BEFORE any agent process exists —
@@ -72,6 +73,7 @@ export type ExitClassification =
 	| "stall_timeout"
 	| "user_killed"
 	| "spawn_failure"
+	| "review_gate_refusal"
 	| "unknown";
 
 /**
@@ -88,6 +90,7 @@ export const EXIT_CLASSIFICATIONS: readonly ExitClassification[] = [
 	"stall_timeout",
 	"user_killed",
 	"spawn_failure",
+	"review_gate_refusal",
 	"unknown",
 ] as const;
 

package/extensions/taskplane/engine-identity.ts

@@ -0,0 +1,401 @@
+/**
+ * engine-identity.ts — Persisted identity of the batch ENGINE process (#631).
+ *
+ * The orchestration engine runs as a forked child process of the supervisor's
+ * Pi session. If that session dies or is replaced while the batch is
+ * `executing`, the replacement supervisor inherits persisted state that says
+ * "executing" — but it has no engine attached, and it cannot tell from the
+ * supervisor lock alone whether the ORIGINAL engine is still alive (a dead
+ * supervisor pid does not imply a dead engine; a forked child survives its
+ * parent on Windows, and a wedged supervisor may leave a healthy engine
+ * driving lanes).
+ *
+ * This module gives a replacement session a verifiable answer:
+ *
+ *   - `alive`   the recorded engine pid still exists → refuse recovery
+ *               mutations (double-drive risk); tell the operator the pid.
+ *   - `dead`    the recorded pid no longer exists → confirmed orphan; the
+ *               persisted-state eligibility rules (`checkResumeEligibility`)
+ *               may proceed.
+ *   - `exited`  the engine recorded its own exit (clean or crash) → same as dead.
+ *   - `none`    no identity recorded (older batch, or the engine never forked)
+ *               → callers fall back to supervisor-lock evidence.
+ *
+ * Verified shutdown, not inferred inactivity: timestamps in batch-state.json
+ * are checkpoint times, not heartbeats, and are refreshed by recovery tools
+ * themselves — they are NOT used here.
+ *
+ * File: `{stateRoot}/.pi/runtime/{batchId}/engine.json` (additive; runtime
+ * dir already hosts registry.json). Best-effort I/O: a write failure never
+ * blocks batch start.
+ */
+
+import { createHash } from "crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+import { isProcessAlive } from "./process-registry.ts";
+import { runtimeRoot } from "./types.ts";
+
+export interface EngineIdentity {
+	batchId: string;
+	/** Engine (forked child) pid */
+	pid: number;
+	/** Pid of the supervisor session that forked it */
+	supervisorPid: number;
+	/** Epoch ms when the fork happened */
+	startedAt: number;
+	/** Epoch ms when the engine exited (set by the parent on child exit) */
+	exitedAt?: number;
+	/** Exit code when known */
+	exitCode?: number | null;
+	/** Why the exit was recorded (e.g. "child-exit", "session-end-kill", "abort") */
+	exitReason?: string;
+	/**
+	 * Build marker (Penster feedback on #632): which Taskplane code is actually
+	 * driving this batch. `version` is package.json's; `build` is a short
+	 * content fingerprint of the loaded extension source (sha256 prefix), so a
+	 * local pre-release deploy is distinguishable from the published version
+	 * even when the version string has not been bumped.
+	 */
+	taskplaneVersion?: string;
+	taskplaneBuild?: string;
+}
+
+/**
+ * Compute the build marker for the currently loaded Taskplane: package.json
+ * version + a short sha256 of the extension entry sources. Cached. Never throws.
+ */
+let cachedBuildMarker: { taskplaneVersion: string; taskplaneBuild: string } | null = null;
+export function taskplaneBuildMarker(): { taskplaneVersion: string; taskplaneBuild: string } {
+	if (cachedBuildMarker) return cachedBuildMarker;
+	let version = "unknown";
+	let build = "unknown";
+	try {
+		const here = dirname(fileURLToPath(import.meta.url));
+		const pkg = JSON.parse(readFileSync(join(here, "..", "..", "package.json"), "utf-8")) as {
+			version?: string;
+		};
+		if (typeof pkg.version === "string") version = pkg.version;
+		const h = createHash("sha256");
+		for (const file of [
+			"extension.ts",
+			"lane-runner.ts",
+			"engine.ts",
+			"resume.ts",
+			"engine-identity.ts",
+		]) {
+			try {
+				h.update(readFileSync(join(here, file)));
+			} catch {
+				/* skip */
+			}
+		}
+		build = h.digest("hex").slice(0, 12);
+	} catch {
+		/* best effort */
+	}
+	cachedBuildMarker = { taskplaneVersion: version, taskplaneBuild: build };
+	return cachedBuildMarker;
+}
+
+/**
+ * #631: ownership evidence ASSOCIATED WITH AN ORCH BRANCH, independent of full
+ * state reconstruction. Integration acts on a branch; the batch behind it may
+ * have no batch-state.json (aborted) and may not be *reconstructable* (worker
+ * manifests gone) while its engine identity still records a live pid.
+ * Reconstructability is a resumability requirement, not a prerequisite for
+ * recognising ownership. Scans `.pi/runtime/<batchId>/batch-meta.json` for
+ * `orchBranch === branch` and returns each such batch with its liveness.
+ * Unreadable/absent meta is skipped (no association can be established).
+ */
+export function findBatchesForOrchBranch(
+	stateRoot: string,
+	orchBranch: string,
+	probe: (pid: number) => boolean = isProcessAlive,
+): Array<{ batchId: string; liveness: EngineLiveness }> {
+	const out: Array<{ batchId: string; liveness: EngineLiveness }> = [];
+	const runtimeDir = join(stateRoot, ".pi", "runtime");
+	if (!existsSync(runtimeDir)) return out;
+	let entries: string[] = [];
+	try {
+		entries = readdirSync(runtimeDir);
+	} catch {
+		return out;
+	}
+	for (const batchId of entries) {
+		try {
+			const metaPath = join(runtimeDir, batchId, "batch-meta.json");
+			if (!existsSync(metaPath)) continue;
+			const meta = JSON.parse(readFileSync(metaPath, "utf-8")) as {
+				orchBranch?: unknown;
+				batchId?: unknown;
+			};
+			if (meta.orchBranch !== orchBranch) continue;
+			const id = typeof meta.batchId === "string" && meta.batchId ? meta.batchId : batchId;
+			out.push({ batchId: id, liveness: assessEngineLiveness(stateRoot, id, probe) });
+		} catch {
+			/* skip unreadable runtime dir */
+		}
+	}
+	return out;
+}
+
+export type EngineLivenessStatus = "alive" | "dead" | "exited" | "none";
+
+export interface EngineLiveness {
+	status: EngineLivenessStatus;
+	identity: EngineIdentity | null;
+}
+
+export function engineIdentityPath(stateRoot: string, batchId: string): string {
+	return join(runtimeRoot(stateRoot, batchId), "engine.json");
+}
+
+/**
+ * Publish a freshly started engine's identity. Returns false when it could not
+ * be written — callers treat that as "cannot own this batch verifiably" and
+ * refuse to start the engine (the identity is what lets a successor prove
+ * shutdown; an engine without one is an unownable orphan-in-waiting).
+ * The write goes through a temp file + rename so a reader never sees a
+ * partial record.
+ */
+export function writeEngineIdentity(
+	stateRoot: string,
+	identity: Omit<EngineIdentity, "exitedAt" | "exitCode" | "exitReason">,
+): boolean {
+	try {
+		const path = engineIdentityPath(stateRoot, identity.batchId);
+		mkdirSync(join(path, ".."), { recursive: true });
+		const tmp = `${path}.${process.pid}.tmp`;
+		writeFileSync(tmp, JSON.stringify({ ...identity, ...taskplaneBuildMarker() }, null, 2), "utf-8");
+		renameSync(tmp, path);
+		// Read-back: the record on disk must be the one we just published.
+		const check = readEngineIdentity(stateRoot, identity.batchId);
+		return check !== null && check.pid === identity.pid && check.exitedAt === undefined;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Mark the recorded engine as exited (keeps the file for forensics). Best effort.
+ *
+ * ATTEMPT-SCOPED: only marks the file when its recorded `pid` matches the
+ * exiting engine's pid. A delayed exit callback from an OLD parent must never
+ * mark a NEW live engine (which has since overwritten the identity) as exited.
+ * Returns true when the mark was applied.
+ */
+export function markEngineExited(
+	stateRoot: string,
+	batchId: string,
+	info: { pid: number; exitCode?: number | null; exitReason: string; exitedAt?: number },
+): boolean {
+	try {
+		const path = engineIdentityPath(stateRoot, batchId);
+		if (!existsSync(path)) return false;
+		const current = JSON.parse(readFileSync(path, "utf-8")) as EngineIdentity;
+		if (current.pid !== info.pid) return false; // a newer engine owns this file
+		current.exitedAt = info.exitedAt ?? Date.now();
+		current.exitCode = info.exitCode ?? null;
+		current.exitReason = info.exitReason;
+		writeFileSync(path, JSON.stringify(current, null, 2), "utf-8");
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Marker pid for an identity synthesized by operator confirmation (no real engine pid). */
+export const OPERATOR_CONFIRMED_PID = 0;
+
+/**
+ * The explicit, auditable LEGACY path (#631): for a batch with no engine
+ * identity (pre-#631 engine, or an engine that never got far enough to publish
+ * one), the runtime cannot verify shutdown and MUST fail closed. The operator
+ * verifies out-of-band that no engine process exists for this repo and records
+ * that confirmation here; it becomes an `exited` identity so every recovery
+ * gate proceeds through the normal verified path. Refuses (returns false) if a
+ * REAL identity exists — confirmation cannot override an alive engine.
+ */
+export function recordOperatorConfirmedShutdown(
+	stateRoot: string,
+	batchId: string,
+	confirmedBy: { supervisorPid: number; note?: string },
+): { ok: boolean; reason: string } {
+	const existing = readEngineIdentity(stateRoot, batchId);
+	if (existing && existing.pid !== OPERATOR_CONFIRMED_PID) {
+		return {
+			ok: false,
+			reason: `an engine identity IS recorded (PID ${existing.pid}${existing.exitedAt ? ", exited" : ""}); confirmation is only for batches with no identity — use the pid-verified path`,
+		};
+	}
+	try {
+		const path = engineIdentityPath(stateRoot, batchId);
+		mkdirSync(join(path, ".."), { recursive: true });
+		const now = Date.now();
+		const identity: EngineIdentity = {
+			batchId,
+			pid: OPERATOR_CONFIRMED_PID,
+			supervisorPid: confirmedBy.supervisorPid,
+			startedAt: now,
+			exitedAt: now,
+			exitCode: null,
+			exitReason: `operator-confirmed-shutdown${confirmedBy.note ? `: ${confirmedBy.note.slice(0, 200)}` : ""}`,
+		};
+		writeFileSync(path, JSON.stringify(identity, null, 2), "utf-8");
+		return { ok: true, reason: `recorded operator-confirmed shutdown for ${batchId}` };
+	} catch (err) {
+		return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+	}
+}
+
+export function readEngineIdentity(stateRoot: string, batchId: string): EngineIdentity | null {
+	try {
+		const path = engineIdentityPath(stateRoot, batchId);
+		if (!existsSync(path)) return null;
+		const parsed = JSON.parse(readFileSync(path, "utf-8")) as Partial<EngineIdentity>;
+		if (typeof parsed.pid !== "number" || typeof parsed.batchId !== "string") return null;
+		return parsed as EngineIdentity;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Is the recorded engine for this batch still running?
+ *
+ * `probe` is injectable for tests; defaults to a real pid probe.
+ */
+export function assessEngineLiveness(
+	stateRoot: string,
+	batchId: string,
+	probe: (pid: number) => boolean = isProcessAlive,
+): EngineLiveness {
+	const identity = readEngineIdentity(stateRoot, batchId);
+	if (!identity) return { status: "none", identity: null };
+	if (identity.exitedAt !== undefined) return { status: "exited", identity };
+	return { status: probe(identity.pid) ? "alive" : "dead", identity };
+}
+
+/**
+ * Decide whether a recovery mutation (resume / retry / skip / force-merge /
+ * administrative pause) may proceed against a batch whose persisted phase is
+ * ACTIVE but which has no engine attached to THIS process.
+ *
+ * Pure decision function (no I/O) so the policy is unit-testable:
+ *
+ *   - engine `alive`                       → refuse (double-drive)
+ *   - engine `dead` | `exited`             → proceed (verified shutdown)
+ *   - engine `none`                        → REFUSE, always. Unknown ownership is
+ *                                            not confirmed shutdown (a forked
+ *                                            engine outlives a dead supervisor).
+ *                                            The message names the explicit,
+ *                                            auditable legacy path:
+ *                                            orch_confirm_engine_shutdown after
+ *                                            out-of-band verification.
+ *
+ * `force` deliberately does NOT bypass an alive engine — that is the one case
+ * where proceeding can corrupt state.
+ */
+/**
+ * THE recovery-ownership rule (#631), as a pure function so every bypass
+ * scenario is unit-testable. `extension.ts` wraps it with I/O (engine
+ * liveness probe, logging).
+ *
+ *   1. an engine runs IN THIS PROCESS (forked child not yet terminated, or the
+ *      main-thread fallback) → refuse — even when the cached phase already
+ *      reads paused/failed/completed (teardown still in flight).
+ *   2–4. otherwise defer to `decideInheritedActivePhase` against the ACTUAL
+ *      target: alive elsewhere → refuse; none → refuse (confirm path);
+ *      dead/exited → proceed.
+ */
+export function decideRecoveryOwnership(input: {
+	operation: string;
+	local: { engineAttached: boolean; phase: string; batchId: string; pid: number | null };
+	target: { batchId: string; phase: string };
+	liveness: EngineLiveness;
+	priorSupervisor: { pid: number; alive: boolean } | null;
+}): InheritedPhaseDecision {
+	const { operation, local, target, liveness, priorSupervisor } = input;
+	if (local.engineAttached) {
+		const pid = local.pid ?? "?";
+		const terminalCache =
+			local.phase === "paused" ||
+			local.phase === "failed" ||
+			local.phase === "stopped" ||
+			local.phase === "completed";
+		return {
+			proceed: false,
+			reason: terminalCache
+				? `⏳ This session's engine (PID ${pid}) for batch ${local.batchId} is still shutting down — ${operation} would race its teardown. Retry in a moment.`
+				: `❌ Cannot ${operation} while batch ${local.batchId} is ${local.phase} in this session (engine PID ${pid}). Pause or wait for the current operation to finish first.`,
+		};
+	}
+	return decideInheritedActivePhase({
+		phase: target.phase,
+		batchId: target.batchId,
+		liveness,
+		priorSupervisor,
+		operation,
+	});
+}
+
+export interface InheritedPhaseDecision {
+	proceed: boolean;
+	/** Operator-facing explanation (refusal reason or proceed rationale) */
+	reason: string;
+}
+
+export function decideInheritedActivePhase(input: {
+	phase: string;
+	batchId: string;
+	liveness: EngineLiveness;
+	priorSupervisor: { pid: number; alive: boolean } | null;
+	operation: string;
+}): InheritedPhaseDecision {
+	const { phase, batchId, liveness, priorSupervisor, operation } = input;
+	const id = liveness.identity;
+	switch (liveness.status) {
+		case "alive":
+			return {
+				proceed: false,
+				reason:
+					`❌ Batch ${batchId} is "${phase}" and its engine process (PID ${id!.pid}, forked ` +
+					`${new Date(id!.startedAt).toISOString()} by supervisor PID ${id!.supervisorPid}) is still ALIVE ` +
+					`in another process. This session has no engine attached and cannot drive or signal it; ` +
+					`${operation} now would double-drive the batch.\n` +
+					`   Wait for that engine to finish or wind down (it pauses itself when its supervisor ` +
+					`disconnects), or terminate it explicitly (Windows: taskkill /PID ${id!.pid} /T; ` +
+					`POSIX: kill ${id!.pid}) and re-run ${operation}. force does not bypass this check.`,
+			};
+		case "dead":
+		case "exited":
+			return {
+				proceed: true,
+				reason:
+					`engine PID ${id!.pid} is ${liveness.status === "exited" ? `exited (${id!.exitReason ?? "recorded"})` : "dead"} ` +
+					`— inherited "${phase}" phase treated as disconnected; persisted-state eligibility applies`,
+			};
+		case "none": {
+			const supervisorNote = priorSupervisor
+				? priorSupervisor.alive
+					? `The previous supervisor (PID ${priorSupervisor.pid}) is still ALIVE, so its engine may well be driving the batch.`
+					: `The previous supervisor (PID ${priorSupervisor.pid}) is dead — but a forked engine can outlive its supervisor, so that alone does not prove the engine is gone.`
+				: `No previous-supervisor record is available either.`;
+			return {
+				proceed: false,
+				reason:
+					`❌ Batch ${batchId} is "${phase}" but this session has no engine attached and NO engine identity is ` +
+					`recorded for it (pre-#631 engine, or it never published one). ${supervisorNote} ` +
+					`Refusing ${operation}: unknown ownership is not confirmed shutdown.
+` +
+					`   Verify out-of-band that no engine process exists for this repo — Windows: ` +
+					`Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match "engine-worker" } ; ` +
+					`POSIX: pgrep -af engine-worker — then record it with orch_confirm_engine_shutdown(note) ` +
+					`(audited) and re-run ${operation}. No hand-edit of batch-state.json is needed.`,
+			};
+		}
+	}
+}