@gajae-code/coding-agent 0.16.7 → 0.17.1

package/src/sdk/broker/lifecycle.ts

@@ -69,7 +69,7 @@ import {
 	sanitizeSdkStartupMessage,
 } from "../startup-capability";
 import type { Broker, BrokerCleanupEvidence, BrokerCleanupIdentity, BrokerResponse } from "./broker";
-import { matchesIndexedEndpointFile, readEndpointFile } from "./endpoint-authority";
+import { endpointIncarnation, matchesIndexedEndpointFile, readEndpointFile } from "./endpoint-authority";
 import { decodeLifecycleUtf8, parseLifecycleJson } from "./lifecycle-codec";
 import type {
 	LifecycleCleanupProof,
@@ -79,6 +79,7 @@ import type {
 	LifecycleWorktreeIntent,
 } from "./lifecycle-ledger";
 import {
+	observeProcessIncarnation,
 	type ProcessIncarnationCommandRunner,
 	type ProcessIncarnationOptions,
 	parseDarwinProcessIncarnation,
@@ -2404,6 +2405,7 @@ async function executeUncertainRetirement(
 					...(record.processIncarnation === undefined ? {} : { processIncarnation: record.processIncarnation }),
 					...(record.hostIncarnation === undefined ? {} : { hostIncarnation: record.hostIncarnation }),
 					...(record.endpointMtimeMs === undefined ? {} : { endpointMtimeMs: record.endpointMtimeMs }),
+					...(record.endpointFileId === undefined ? {} : { endpointFileId: record.endpointFileId }),
 					...(record.lifecycleRequestId === undefined ? {} : { lifecycleRequestId: record.lifecycleRequestId }),
 				});
 				const verifiedIndexSeq = broker.index.findSessionClosedEvidence(record);
@@ -2537,6 +2539,13 @@ function validateLifecycleMetadataReplay(cleanup: CleanupEvidence): BrokerRespon
 				return fail("terminal_uncertain", "Lifecycle metadata candidate could not be safely inspected.");
 			}
 			if (!current) continue;
+			if (
+				file.completed &&
+				path.resolve(candidate) === path.resolve(file.plannedPath) &&
+				current.identity.size === 0n &&
+				current.identity.nlink === 1n
+			)
+				continue;
 			if (!sameLifecycleCleanupIdentity(current.identity, file.identity))
 				return fail("terminal_uncertain", "Lifecycle metadata candidate lacks exact replay authority.");
 			// A completed file's recorded retained quarantine is receipt-bound durable
@@ -2876,14 +2885,11 @@ async function reconcileLifecycleCleanup(
 				// A completed file's recorded retained quarantine is durable evidence,
 				// not a survivor — accept it only at its receipt-bound path and identity.
 				if (
-					file.detachedPath &&
-					path.resolve(candidate) === path.resolve(file.detachedPath) &&
-					stat.isFile() &&
-					!stat.isSymbolicLink() &&
-					stat.nlink === 1 &&
-					stat.size === 0
-				)
-					continue;
+					(file.detachedPath && path.resolve(candidate) === path.resolve(file.detachedPath)) ||
+					path.resolve(candidate) === path.resolve(file.plannedPath)
+				) {
+					if (stat.isFile() && !stat.isSymbolicLink() && stat.nlink === 1 && stat.size === 0) continue;
+				}
 				return fail(
 					"terminal_uncertain",
 					"Lifecycle cleanup receipt marks a target complete while an authorized candidate remains.",
@@ -3411,6 +3417,22 @@ async function removeOwnedLifecycleArtifacts(
 			{ dev: BigInt(endpointParent.dev), ino: BigInt(endpointParent.ino) },
 		);
 		if (!lifecycleProofWithinDeadline(proofBudget)) return false;
+		if (endpointRemoval.ok) {
+			// POSIX exact-unlink scrubs the detached exchange payload and may retain
+			// its zero-byte quarantine name as durable internal evidence even when
+			// the canonical removal itself succeeded. Carry that known placeholder
+			// into the enclosing close reconciliation so it is not mistaken for a
+			// live endpoint payload.
+			for (const candidate of [plannedEndpointPath, retryEndpointPath, finalEndpointPath]) {
+				try {
+					const metadata = fsSync.lstatSync(candidate);
+					if (metadata.isFile() && metadata.nlink === 1 && metadata.size === 0)
+						onDurablePlaceholder?.(path.resolve(candidate));
+				} catch {
+					// A missing quarantine alias carries no retained authority.
+				}
+			}
+		}
 		if (!endpointRemoval.ok) {
 			if (endpointRemoval.retainedUnknownPath) {
 				onRetainedUnknown?.();
@@ -3499,6 +3521,14 @@ async function recordTerminalUncertain(
 			...(registered.processIncarnation === undefined ? {} : { processIncarnation: registered.processIncarnation }),
 			...(registered.hostIncarnation === undefined ? {} : { hostIncarnation: registered.hostIncarnation }),
 			...(registered.endpointMtimeMs === undefined ? {} : { endpointMtimeMs: registered.endpointMtimeMs }),
+			...(registered.endpointFileId !== undefined &&
+			registered.pid === pid &&
+			path.resolve(registered.locator.stateRoot) === path.resolve(root) &&
+			expected !== undefined &&
+			registered.lifecycleRequestId === expected.effectMarker &&
+			(registered.hostIncarnation ?? registered.processIncarnation) === expected.incarnation
+				? { endpointFileId: registered.endpointFileId }
+				: {}),
 			...(registered.lifecycleRequestId === undefined
 				? expected?.effectMarker === undefined
 					? {}
@@ -3517,6 +3547,70 @@ async function recordTerminalUncertain(
 		});
 }
 
+/**
+ * Release the worktree held by a forced stop of a stale-endpoint session, bound to
+ * the exact stale identity the caller already validated against the requested close
+ * authority. A successor incarnation can re-register under this session id in the
+ * window between that authority check and this claim, so refresh once and append a
+ * terminal-uncertain marker ONLY when the current row is still that captured
+ * identity and its owning process is not observably alive. A rotated successor no
+ * longer matches, so it is left untouched and nothing is released — the strict
+ * "uncertain counts as occupied" rule keeps protecting it.
+ *
+ * Unlike `recordTerminalUncertain`, the compare and the append share one refresh
+ * boundary and the marker is keyed to the captured generation/pid/incarnation
+ * rather than to whatever row a second refresh happens to read. A successor that
+ * rotates in while the append is in flight therefore cannot be marked terminal:
+ * the claim targets the old generation, whose row never outranks the successor's
+ * higher generation in the projection (#5581).
+ */
+async function releaseForcedStaleWorktree(broker: Broker, id: string, expected: IndexedSession): Promise<void> {
+	await broker.index.refresh();
+	const current = broker.index.listSessions().sessions.find(session => session.sessionId === id);
+	if (
+		!current ||
+		current.endpointGeneration !== expected.endpointGeneration ||
+		current.pid !== expected.pid ||
+		(current.hostIncarnation ?? current.processIncarnation) !==
+			(expected.hostIncarnation ?? expected.processIncarnation)
+	)
+		return;
+	// For a force-stopped stale-endpoint session, release the worktree unless the
+	// owning process is provably alive. An `alive` process still owns its checkout,
+	// so it stays occupied even under force. Both `exited` (proven gone) and
+	// `uncertain` (the pid-reuse case, which can never be proven exited) are treated
+	// as terminal here: otherwise the row stays occupied forever and follow-up
+	// delegate launches into the same checkout are refused with worktree_in_use
+	// indefinitely. The identity guards above (generation/PID/incarnation) already
+	// ensure a live successor that rotated in under the same id is never released.
+	const observation = observeProcess(current.pid, current.hostIncarnation ?? current.processIncarnation, value =>
+		processIncarnationForBroker(broker, value),
+	);
+	if (observation === "alive") return;
+	if (observation === "uncertain")
+		logger.warn("sdk broker recording forced stale-worktree release under uncertain process state", {
+			sessionId: id,
+			pid: current.pid,
+			endpointGeneration: current.endpointGeneration,
+		});
+	await broker.index.append({
+		type: "lifecycle_terminal",
+		sessionId: id,
+		locator: current.locator,
+		endpointGeneration: current.endpointGeneration,
+		pid: current.pid,
+		...(current.processIncarnation === undefined ? {} : { processIncarnation: current.processIncarnation }),
+		...(current.hostIncarnation === undefined ? {} : { hostIncarnation: current.hostIncarnation }),
+		...(current.endpointMtimeMs === undefined ? {} : { endpointMtimeMs: current.endpointMtimeMs }),
+		...(current.lifecycleRequestId === undefined ? {} : { lifecycleRequestId: current.lifecycleRequestId }),
+		terminalUncertain: true,
+		// Marks this claim as the forced release, which is the only terminal-uncertain
+		// claim that frees the worktree. The fail-closed teardown tail writes
+		// `terminalUncertain` without it and keeps its checkout (see `worktreeOccupant`).
+		forcedStaleRelease: true,
+	});
+}
+
 async function waitUntil(timing: LifecycleTiming, deadline: number): Promise<void> {
 	while (timing.now() < deadline) await timing.sleep(Math.max(0, Math.min(POLL_MS, deadline - timing.now())));
 }
@@ -3734,13 +3828,20 @@ async function signalVerifiedSession(
 	signal: NodeJS.Signals,
 	expected?: EffectMarker,
 ): Promise<boolean> {
-	if (!(await hasDurableProcessIdentity(record, id, expected))) return false;
+	// An exited process may remain a zombie until its parent reaps it. Its
+	// incarnation is intentionally unavailable at that point, but native
+	// observation positively classifies the pid as absent. Treat that as a
+	// successful no-op so close can continue with endpoint/index cleanup rather
+	// than escalating to an unverifiable signal and reporting terminal uncertainty.
+	if (!(await hasDurableProcessIdentity(record, id, expected)))
+		return observeProcessIncarnation(record.pid).status === "absent";
 	try {
-		if (!(await hasDurableProcessIdentity(record, id, expected))) return false;
+		if (!(await hasDurableProcessIdentity(record, id, expected)))
+			return observeProcessIncarnation(record.pid).status === "absent";
 		process.kill(record.pid, signal);
 		return true;
 	} catch {
-		return false;
+		return observeProcessIncarnation(record.pid).status === "absent";
 	}
 }
 
@@ -3812,7 +3913,17 @@ async function removeExactDeadSessionEndpoint(
 			? authorizedDetachedSource
 			: candidates.find(candidate => {
 					try {
-						return fsSync.lstatSync(candidate).isFile();
+						const metadata = fsSync.lstatSync(candidate);
+						// A native-proven scrubbed placeholder is no longer endpoint JSON.
+						// Unknown empty files and nonempty replacements still require validation.
+						if (
+							durablePlaceholders?.has(path.resolve(candidate)) &&
+							metadata.isFile() &&
+							metadata.nlink === 1 &&
+							metadata.size === 0
+						)
+							return false;
+						return metadata.isFile();
 					} catch {
 						return false;
 					}
@@ -3902,6 +4013,12 @@ async function hasOwnedEndpointPayload(
 ): Promise<boolean> {
 	const directory = path.join(root, "sdk");
 	const endpointName = `${id}.json`;
+	const knownScrubbedPlaceholders = new Set([
+		`.gjc-delete-endpoint-${effectMarker}-${endpointName}`,
+		`.gjc-delete-endpoint-retry-${effectMarker}-${endpointName}`,
+		`.gjc-delete-endpoint-final-${effectMarker}-${endpointName}`,
+		`.gjc-delete-endpoint-detached-${effectMarker}-${endpointName}`,
+	]);
 	let names: string[];
 	try {
 		names = await fs.readdir(directory);
@@ -3917,7 +4034,9 @@ async function hasOwnedEndpointPayload(
 			if (
 				!metadata.isFile() ||
 				metadata.size > 0 ||
-				(metadata.size === 0 && !durablePlaceholders.has(path.resolve(candidate)))
+				(metadata.size === 0 &&
+					!durablePlaceholders.has(path.resolve(candidate)) &&
+					!knownScrubbedPlaceholders.has(name))
 			)
 				return true;
 		} catch (error) {
@@ -4210,6 +4329,15 @@ export function worktreeOccupantForTest(
 	return worktreeOccupant(sessions, worktreePath, observe);
 }
 
+/** Test seam for the forced stale-worktree release boundary. */
+export async function releaseForcedStaleWorktreeForTest(
+	broker: Broker,
+	id: string,
+	expected: IndexedSession,
+): Promise<void> {
+	await releaseForcedStaleWorktree(broker, id, expected);
+}
+
 async function preparePlannedWorktree(
 	plan: GjcLaunchWorktreePlan,
 	opts: { signal: AbortSignal; deadlineAt: number; now: () => number },
@@ -4832,32 +4960,6 @@ type CloseRecord = {
 	processIncarnation?: string;
 };
 
-function endpointIncarnation(
-	record: Pick<CloseRecord, "endpointGeneration" | "endpointMtimeMs" | "pid">,
-	sessionId: string,
-): string | undefined {
-	if (
-		!Number.isSafeInteger(record.endpointGeneration) ||
-		record.endpointGeneration <= 0 ||
-		!Number.isSafeInteger(record.pid) ||
-		record.pid <= 0 ||
-		typeof record.endpointMtimeMs !== "number" ||
-		!Number.isFinite(record.endpointMtimeMs) ||
-		record.endpointMtimeMs <= 0
-	)
-		return undefined;
-	return createHash("sha256")
-		.update(
-			JSON.stringify({
-				endpointGeneration: record.endpointGeneration,
-				endpointMtimeMs: record.endpointMtimeMs,
-				pid: record.pid,
-				sessionId,
-			}),
-		)
-		.digest("hex");
-}
-
 function requestedCloseAuthority(input: Input): { authority: CloseAuthority | undefined } | { error: BrokerResponse } {
 	const endpointGeneration = input.endpointGeneration;
 	const endpointIncarnation = input.endpointIncarnation;
@@ -5028,13 +5130,15 @@ async function executeLifecycleResponse(
 					return fail("endpoint_stale", "Live session changed while its resume authority was being verified.");
 				if (current.endpointMtimeMs === undefined)
 					return fail("endpoint_stale", "Live session endpoint authority is incomplete.");
+				const finalIncarnation = endpointIncarnation(current, requestedSessionId!);
+				if (!finalIncarnation) return fail("endpoint_stale", "Live session endpoint incarnation is unavailable.");
 				return {
 					ok: true,
 					result: {
 						sessionId: requestedSessionId,
 						cwd: finalScope.cwd,
 						endpointGeneration: current.endpointGeneration,
-						endpointIncarnation: initialIncarnation,
+						endpointIncarnation: finalIncarnation,
 						pid: current.pid,
 						endpointMtimeMs: current.endpointMtimeMs,
 						endpoint: endpoint.result,
@@ -5515,6 +5619,7 @@ async function executeLifecycleResponse(
 				endpointGeneration: verified.endpointGeneration,
 				endpointMtimeMs: verified.endpointMtimeMs,
 				pid: spawnedAuthority.pid,
+				...(verified.endpointFileId === undefined ? {} : { endpointFileId: verified.endpointFileId }),
 			},
 			launch.id,
 		);
@@ -5545,6 +5650,14 @@ async function executeLifecycleResponse(
 	let record = broker.index.listSessions().sessions.find(session => session.sessionId === id);
 	if (operation === "session.close") {
 		if (!record) return fail("not_found", "session is not indexed");
+		// A forced stop of a session whose endpoint is already stale (its coordinator
+		// service went away mid-run) cannot reach the runtime to prove teardown. The
+		// caller has explicitly requested force, so when the endpoint proves stale
+		// below and the owning process is no longer observably alive, record a
+		// terminal-uncertain claim before surfacing endpoint_stale — otherwise the
+		// row keeps holding its worktree forever, since an OS probe of a reused pid
+		// returns `uncertain` and never `exited` (#5581).
+		const forceReleaseStaleWorktree = input.forceReleaseStaleWorktree === true;
 		if (record.terminalUncertain)
 			return fail("terminal_uncertain", "Session ownership is uncertain and cannot be closed safely.");
 		if (!isSessionAuthorityEligible(record))
@@ -5589,7 +5702,26 @@ async function executeLifecycleResponse(
 			}
 		}
 		if (!endpointResult.ok) {
-			if (endpointResult.error.code === "endpoint_stale") return endpointResult;
+			if (endpointResult.error.code === "endpoint_stale") {
+				// `record` matched the requested close authority above, so it is the exact
+				// stale identity the forced stop targeted — never a live successor, which
+				// would have failed that authority check. Release its worktree bound to
+				// that identity so a rotated successor is left untouched (#5581).
+				// Best-effort: the endpoint_stale outcome is already proven and must be
+				// returned. A release failure (index/broker write error) must not mask it;
+				// the stale-endpoint recovery paths retry the release later.
+				if (forceReleaseStaleWorktree) {
+					try {
+						await releaseForcedStaleWorktree(broker, id, record);
+					} catch (error) {
+						logger.warn("sdk broker forced stale-worktree release failed; returning endpoint_stale", {
+							sessionId: id,
+							error: String(error),
+						});
+					}
+				}
+				return endpointResult;
+			}
 			if (endpointResult.error.code !== "resource_gone") return endpointResult;
 			usedSignalFallback = true;
 		} else {

package/src/sdk/broker/process-incarnation.ts

@@ -121,6 +121,90 @@ export function isProcessIncarnation(value: unknown): value is string {
 	);
 }
 
+/**
+ * Read-only, non-mutating observation of whether a pid currently names a
+ * verifiable process incarnation.
+ *
+ * - `status: "present"` carries the exact kernel-reported identity evidence
+ *   (the same value `processIncarnation` returns).
+ * - `status: "absent"` is positive OS-confirmed death proof (POSIX
+ *   `kill(pid, 0)` returning `ESRCH`, or Windows `OpenProcess` failing with
+ *   the exact code the kernel reports for an unresolved client id) — never a
+ *   permission failure or an ambiguous disappearance.
+ * - `status: "unknown"` covers every inconclusive case (invalid pid, missing
+ *   or unavailable native addon, permission denial, platform limitation).
+ *   Callers MUST NOT treat this as death proof.
+ */
+export type ProcessIncarnationObservation =
+	| { status: "present"; incarnation: string }
+	| { status: "absent" }
+	| { status: "unknown"; reasonCode: string };
+
+/** Raw shape returned by the native `Process.observe` binding. */
+export type NativeProcessObserveResult = { status?: unknown; incarnation?: unknown; reasonCode?: unknown };
+
+export interface ObserveProcessIncarnationOptions {
+	/**
+	 * Injectable native observe function, used by tests to exercise error
+	 * classification (malformed shapes, unavailable addon) without a global
+	 * mock. Defaults to the real `Process.observe` binding.
+	 */
+	observe?: (pid: number) => NativeProcessObserveResult;
+}
+
+/**
+ * Read-only process-incarnation observation for `pid`, distinguishing a
+ * proved-live incarnation from positive OS-confirmed absence from every
+ * inconclusive outcome. Never signals, kills, reaps, waits on, or spawns any
+ * process — it only reads existing native process-table state via
+ * `Process.observe`.
+ *
+ * `pid` must be a positive safe integer; any other value (including `0`,
+ * negative, `NaN`, or non-integer) is reported as `unknown` rather than
+ * risking an ambiguous platform-specific interpretation (`0`/negative PIDs
+ * address process groups on POSIX, not a single process).
+ */
+export function observeProcessIncarnation(
+	pid: number,
+	options: ObserveProcessIncarnationOptions = {},
+): ProcessIncarnationObservation {
+	if (!Number.isSafeInteger(pid) || pid <= 0 || pid > 0x7fff_ffff) {
+		return { status: "unknown", reasonCode: "invalid_pid" };
+	}
+	try {
+		const observe =
+			options.observe ?? (nativeProcessBindings().Process as { observe?: (pid: number) => unknown }).observe;
+		if (typeof observe !== "function") {
+			// Older addon build predating Process.observe: liveness cannot be
+			// determined through this path, and that is not death proof.
+			return { status: "unknown", reasonCode: "observe_unavailable" };
+		}
+		const result = observe(pid) as NativeProcessObserveResult;
+		if (result?.status === "present" && isProcessIncarnation(result.incarnation) && result.reasonCode === undefined) {
+			return { status: "present", incarnation: result.incarnation };
+		}
+		if (result?.status === "absent" && result.incarnation === undefined && result.reasonCode === undefined) {
+			return { status: "absent" };
+		}
+		if (
+			result?.status === "unknown" &&
+			result.incarnation === undefined &&
+			typeof result.reasonCode === "string" &&
+			/^[a-z][a-z0-9_]{0,63}$/.test(result.reasonCode)
+		) {
+			return { status: "unknown", reasonCode: result.reasonCode };
+		}
+		// A native result shape that matches none of the above (e.g. "present"
+		// without a canonical incarnation) is a contract mismatch, not evidence of
+		// anything — report unknown rather than guessing.
+		return { status: "unknown", reasonCode: "malformed_observation" };
+	} catch {
+		// The native addon is missing/unloadable on this host. Not proof of
+		// death: the caller has no OS confirmation either way.
+		return { status: "unknown", reasonCode: "native_addon_unavailable" };
+	}
+}
+
 /** A PID is reusable; bind it to the strongest OS-provided process start incarnation available. */
 export function processIncarnation(pid: number, options: ProcessIncarnationOptions = {}): string | undefined {
 	if (!Number.isSafeInteger(pid) || pid <= 0) return undefined;
@@ -128,8 +212,8 @@ export function processIncarnation(pid: number, options: ProcessIncarnationOptio
 	if (platform === process.platform && options.runCommand === undefined) {
 		try {
 			const nativeProcess = nativeProcessBindings().Process.fromPid(pid) as { incarnation?: unknown } | null;
-			// null is the native binding's authoritative absent-process result: the
-			// process is dead or its PID was never opened.  Returning undefined here
+			// A null native reference cannot provide an incarnation: the process
+			// may be absent or inaccessible. Returning undefined here
 			// avoids repeatedly spawning powershell.exe (whose Get-Process uses the same
 			// OpenProcess path and therefore cannot recover a valid incarnation either)
 			// during the broker's ~5 s liveness polling, which on Windows 11 produces a

package/src/sdk/broker/runtime.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import * as fsp from "node:fs/promises";
 import * as path from "node:path";
 
 import { currentExecutablePath } from "@gajae-code/natives";
@@ -123,17 +124,92 @@ function expectedPackageName(packageDirectory: string): void {
 	}
 }
 
+type SdkInternalRuntimeEvidence = { kind: "bun-source" | "compiled"; markerPath: string };
+
+/**
+ * Classify this process's runtime from exact marker and embedded-file evidence.
+ * Both the spawn descriptor and the published runtime image derive from this one
+ * authority; neither may fall back to argv or PATH.
+ */
+function classifySdkInternalRuntime(options: SdkInternalRuntimeDescriptorTestOptions): SdkInternalRuntimeEvidence {
+	const markerPath = options.markerPath ?? internalSourceMarker;
+	const embeddedFiles = options.embeddedFiles ?? (typeof Bun === "undefined" ? undefined : Bun.embeddedFiles);
+	if (!embeddedFiles) throw new Error("SDK internal launch refused: Bun runtime evidence is unavailable.");
+	const markerName = path.basename(markerPath.replaceAll("\\", "/"));
+	const markerEntries = embeddedFiles.filter(file => embeddedFileName(file) === markerName);
+	const compiledMarkerPath = isCompiledMarkerPath(markerPath);
+	const exactCompiledArtifact = COMPILED_MARKER_NAME.test(markerName) && markerEntries.length === 1;
+	const isSourceMarker = path.isAbsolute(markerPath) && !compiledMarkerPath;
+	if (embeddedFiles.length === 0 && isSourceMarker) return { kind: "bun-source", markerPath };
+	if (exactCompiledArtifact && compiledMarkerPath) return { kind: "compiled", markerPath };
+	throw new Error("SDK internal launch refused: compiled-runtime marker evidence is inconsistent.");
+}
+
+/**
+ * The image a source-runtime internal spawn executes: this process's own Bun.
+ * It is the spawn command file, so it must be executable, not merely readable.
+ */
+function sourceRuntimeImage(options: SdkInternalRuntimeDescriptorTestOptions): string {
+	if (options.bunAvailable === false || typeof Bun === "undefined")
+		throw new Error("SDK internal launch refused: Bun source runtime is unavailable.");
+	return regularExecutablePath(path.resolve(options.execPath ?? process.execPath), "runtime executable");
+}
+
+/** The runtime image alone, without the source-tree assets a full spawn also proves. */
+function provenRuntimeImage(options: SdkInternalRuntimeDescriptorTestOptions): string {
+	const evidence = classifySdkInternalRuntime(options);
+	return evidence.kind === "bun-source" ? sourceRuntimeImage(options) : compiledExecutable(options);
+}
+
+/**
+ * The image the same classification names, without the on-disk proof a spawn
+ * requires. A proof-first publication is exactly backwards for the broker that
+ * matters here: a runtime deleted between this process's exec and its
+ * publication makes `regularExecutablePath` throw, so the one broker that can
+ * never spawn would publish no evidence and read as reusable forever.
+ *
+ * Publishing the classified path instead moves the verdict to the reader, which
+ * already retires only on proven absence. It is evidence, never a spawn source.
+ * A Bun virtual bundle path is not publishable: nothing on disk backs it, so a
+ * reader would probe `ENOENT` and retire a healthy compiled broker.
+ */
+function classifiedRuntimeImage(options: SdkInternalRuntimeDescriptorTestOptions): string | undefined {
+	const evidence = classifySdkInternalRuntime(options);
+	const execPath = options.execPath ?? process.execPath;
+	if (evidence.kind === "bun-source") {
+		// Without Bun there is no source runtime to name; `execPath` would be some
+		// other interpreter, which is worse evidence than none.
+		if (options.bunAvailable === false || typeof Bun === "undefined") return undefined;
+		return isBunVirtualExecutablePath(execPath) ? undefined : path.resolve(execPath);
+	}
+	if (!isBunVirtualExecutablePath(execPath)) return path.resolve(execPath);
+	const currentExecutable = currentExecutablePath();
+	if (!currentExecutable || isBunVirtualExecutablePath(currentExecutable)) return undefined;
+	return path.resolve(currentExecutable);
+}
+
+/** Publication evidence: the proven image, else the classified path, else nothing. */
+function publishedRuntimeImage(options: SdkInternalRuntimeDescriptorTestOptions): string | undefined {
+	try {
+		return provenRuntimeImage(options);
+	} catch {
+		try {
+			return classifiedRuntimeImage(options);
+		} catch {
+			return undefined;
+		}
+	}
+}
+
 function sourceDescriptor(
 	action: SdkInternalAction,
 	options: SdkInternalRuntimeDescriptorTestOptions,
 	markerPath: string,
 ): SdkInternalSpawnCommand {
-	if (options.bunAvailable === false || typeof Bun === "undefined")
-		throw new Error("SDK internal launch refused: Bun source runtime is unavailable.");
+	const runtime = sourceRuntimeImage(options);
 	const brokerDirectory = path.resolve(options.brokerDirectory ?? import.meta.dir);
 	const packageDirectory = path.resolve(brokerDirectory, "../../..");
 	const sourceDirectory = path.resolve(brokerDirectory, "../..");
-	const runtime = regularReadablePath(path.resolve(options.execPath ?? process.execPath), "runtime executable");
 	const cli = regularReadablePath(
 		path.resolve(options.cliPath ?? path.join(sourceDirectory, "cli.ts")),
 		"CLI entrypoint",
@@ -168,25 +244,68 @@ function resolveSdkInternalSpawnCommandWithEvidence(
 	action: SdkInternalAction,
 	options: SdkInternalRuntimeDescriptorTestOptions,
 ): SdkInternalSpawnCommand {
-	const markerPath = options.markerPath ?? internalSourceMarker;
-	const embeddedFiles = options.embeddedFiles ?? (typeof Bun === "undefined" ? undefined : Bun.embeddedFiles);
-	if (!embeddedFiles) throw new Error("SDK internal launch refused: Bun runtime evidence is unavailable.");
-	const markerName = path.basename(markerPath.replaceAll("\\", "/"));
-	const markerEntries = embeddedFiles.filter(file => embeddedFileName(file) === markerName);
-	const compiledMarkerPath = isCompiledMarkerPath(markerPath);
-	const exactCompiledArtifact = COMPILED_MARKER_NAME.test(markerName) && markerEntries.length === 1;
-	const isSourceMarker = path.isAbsolute(markerPath) && !compiledMarkerPath;
-	if (embeddedFiles.length === 0 && isSourceMarker) return sourceDescriptor(action, options, markerPath);
-	if (exactCompiledArtifact && compiledMarkerPath) {
-		const executable = compiledExecutable(options);
-		return {
-			kind: "compiled",
-			file: executable,
-			args: ["sdk", action],
-			env: internalEnvironment(options.environment ?? process.env, false),
-		};
+	const evidence = classifySdkInternalRuntime(options);
+	if (evidence.kind === "bun-source") return sourceDescriptor(action, options, evidence.markerPath);
+	return {
+		kind: "compiled",
+		file: compiledExecutable(options),
+		args: ["sdk", action],
+		env: internalEnvironment(options.environment ?? process.env, false),
+	};
+}
+
+/**
+ * The on-disk image internal SDK spawns from this process execute, or
+ * `undefined` only when runtime evidence cannot be classified at all. It comes
+ * from the same marker authority a spawn uses, but deliberately not from the
+ * source-tree assets a spawn also proves (CLI entrypoint, isolated Bun config,
+ * package identity): a failure to read one of those says nothing about the
+ * runtime image, and publishing `undefined` for it would blind every reader.
+ *
+ * An image the classification names but this process can no longer prove is
+ * still published. `undefined` means only "no evidence" -- readers keep such a
+ * broker reusable, so a broker whose own image vanished before it published
+ * must not hide behind it.
+ */
+export function sdkInternalRuntimeImage(): string | undefined {
+	return publishedRuntimeImage({});
+}
+
+/** A stat that has not answered by here is inconclusive, never proof of absence. */
+const RUNTIME_IMAGE_PROBE_TIMEOUT_MS = 1_000;
+
+/**
+ * Only these prove the image is gone. Every other failure (`EACCES`, `EPERM`,
+ * `ELOOP`, `EIO`, a sandbox that hides the path from this caller, anything
+ * unrecognized) describes the caller's view, not the image: the broker may still
+ * execute a file this process cannot even inspect.
+ */
+function isProvenRuntimeImageAbsence(error: unknown): boolean {
+	const code = (error as NodeJS.ErrnoException | null)?.code;
+	return code === "ENOENT" || code === "ENOTDIR";
+}
+
+/**
+ * Whether a published runtime image is still a regular file on disk. A resident broker keeps
+ * answering requests after the executable it was started from is deleted (a
+ * Homebrew Bun upgrade removing the Cellar path, an install directory swapped
+ * underneath it), yet every internal spawn it then attempts is refused. Callers
+ * use this to retire such an incumbent before a session launch reaches it, so it
+ * answers `true` on every inconclusive outcome, including a probe that outlives
+ * its bound: a false retirement kills a healthy broker.
+ */
+export async function isSdkInternalRuntimeImagePresent(file: string): Promise<boolean> {
+	const probe = fsp.stat(path.resolve(file)).then(
+		stats => stats.isFile(),
+		(error: unknown) => !isProvenRuntimeImageAbsence(error),
+	);
+	const inconclusive = Promise.withResolvers<boolean>();
+	const timer: NodeJS.Timeout = setTimeout(() => inconclusive.resolve(true), RUNTIME_IMAGE_PROBE_TIMEOUT_MS);
+	try {
+		return await Promise.race([probe, inconclusive.promise]);
+	} finally {
+		clearTimeout(timer);
 	}
-	throw new Error("SDK internal launch refused: compiled-runtime marker evidence is inconsistent.");
 }
 
 /** Resolve the production descriptor from the statically imported marker and current Bun runtime evidence. */
@@ -201,3 +320,8 @@ export function resolveSdkInternalSpawnCommandForTest(
 ): SdkInternalSpawnCommand {
 	return resolveSdkInternalSpawnCommandWithEvidence(action, options);
 }
+
+/** Test hook: the publication decision under injected evidence, same authority as production. */
+export function sdkInternalRuntimeImageForTest(options: SdkInternalRuntimeDescriptorTestOptions): string | undefined {
+	return publishedRuntimeImage(options);
+}