@gajae-code/coding-agent 0.16.7 → 0.17.1

package/src/sdk/broker/discovery.ts

@@ -2,17 +2,13 @@ import { randomBytes } from "node:crypto";
 import * as fsSync from "node:fs";
 import * as fs from "node:fs/promises";
 import path from "node:path";
-
-import type { NativeRetainedBrokerPublication } from "@gajae-code/natives";
-
-type NativeBrokerDiscoveryBindings = Pick<typeof import("@gajae-code/natives"), "retainBrokerPublication">;
-let nativeBrokerDiscoveryBindings: NativeBrokerDiscoveryBindings | undefined;
-
-function nativeBrokerDiscovery(): NativeBrokerDiscoveryBindings {
-	if (!nativeBrokerDiscoveryBindings)
-		nativeBrokerDiscoveryBindings = require("@gajae-code/natives") as NativeBrokerDiscoveryBindings;
-	return nativeBrokerDiscoveryBindings;
-}
+import type {
+	NativeBrokerRestartIntent,
+	NativeBrokerRestartIntentIdentity,
+	NativeRetainedBrokerPublication,
+} from "@gajae-code/natives";
+import { retainBrokerPublication as retainBrokerPublicationFn } from "@gajae-code/natives";
+import { BROKER_ARTIFACT_PATHS, canonicalServiceRootDigest } from "../service-artifact-paths";
 
 import { processIncarnation } from "./process-incarnation";
 import { assertSupportedStateVersion, SDK_STATE_VERSION } from "./state-version";
@@ -23,6 +19,14 @@ export interface RetainedBrokerDiscovery {
 	observeAsync(): Promise<BrokerPublicationObservation>;
 	heartbeat(heartbeatAt: number): Promise<boolean>;
 	close(): void;
+	/** Owner-side `prepared`: exclusively creates the durable restart-intent slot. */
+	prepareRestartIntent(intent: NativeBrokerRestartIntent): Promise<boolean>;
+	/** Owner-side `prepared` -> `committed`: rewrites the exact slot prepare created. */
+	commitRestartIntent(intent: NativeBrokerRestartIntent): Promise<boolean>;
+	/** Owner-side cancel of this process's own prepared/committed slot. */
+	cancelRestartIntent(): Promise<boolean>;
+	/** Successor-side clear of a predecessor's slot this process never prepared. */
+	clearForeignRestartIntent(identity: NativeBrokerRestartIntentIdentity): Promise<boolean>;
 }
 
 /**
@@ -216,12 +220,8 @@ function describeWithheldPublicationAuthority(agentDir: string): string | undefi
 }
 
 function requireRetainedBrokerPublication(agentDir: string): NativeRetainedBrokerPublication {
-	const retainBrokerPublication = nativeBrokerDiscovery().retainBrokerPublication;
-	if (typeof retainBrokerPublication !== "function") {
-		throw new Error("Loaded native bindings do not expose retained broker publication authority.");
-	}
 	try {
-		return retainBrokerPublication(agentDir);
+		return retainBrokerPublicationFn(agentDir);
 	} catch (error) {
 		// Fail closed exactly as before; only name the condition on the way out.
 		const obstruction = nativeRetainedObstruction(error);
@@ -299,6 +299,26 @@ class NativeRetainedBrokerDiscovery implements RetainedBrokerDiscovery {
 		this.#closed = true;
 		this.#publication.close();
 	}
+	async prepareRestartIntent(intent: NativeBrokerRestartIntent): Promise<boolean> {
+		if (this.#closed || !isValidRestartToken(intent.requestId) || !isValidRestartToken(intent.lease)) return false;
+		return (await this.#publication.prepareRestartIntentAsync(intent)).kind === "written";
+	}
+	async commitRestartIntent(intent: NativeBrokerRestartIntent): Promise<boolean> {
+		if (this.#closed || !isValidRestartToken(intent.requestId) || !isValidRestartToken(intent.lease)) return false;
+		return (await this.#publication.commitRestartIntentAsync(intent)).kind === "written";
+	}
+	async cancelRestartIntent(): Promise<boolean> {
+		if (this.#closed) return false;
+		return (await this.#publication.cancelRestartIntentAsync()).kind === "cancelled";
+	}
+	async clearForeignRestartIntent(identity: NativeBrokerRestartIntentIdentity): Promise<boolean> {
+		if (this.#closed) return false;
+		return (await this.#publication.clearRestartIntentAsync(identity)).kind === "cleared";
+	}
+}
+
+function isValidRestartToken(value: string): boolean {
+	return /^[A-Za-z0-9_-]{1,256}$/.test(value);
 }
 
 class LegacyWindowsBrokerDiscovery implements RetainedBrokerDiscovery {
@@ -322,6 +342,18 @@ class LegacyWindowsBrokerDiscovery implements RetainedBrokerDiscovery {
 		this.#discovery = next;
 		return true;
 	}
+	async prepareRestartIntent(_intent: NativeBrokerRestartIntent): Promise<boolean> {
+		return false;
+	}
+	async commitRestartIntent(_intent: NativeBrokerRestartIntent): Promise<boolean> {
+		return false;
+	}
+	async cancelRestartIntent(): Promise<boolean> {
+		return false;
+	}
+	async clearForeignRestartIntent(_identity: NativeBrokerRestartIntentIdentity): Promise<boolean> {
+		return false;
+	}
 	close(): void {
 		this.#closed = true;
 	}
@@ -336,6 +368,16 @@ export interface BrokerDiscovery {
 	version: typeof SDK_STATE_VERSION;
 	protocolVersion: 3;
 	packageGeneration: string;
+	/**
+	 * The runtime image this broker launches internal SDK processes with. Present
+	 * whenever the publisher could classify its own runtime, including when that
+	 * image was already gone at publication time -- absence is the reader's
+	 * verdict to reach, not a reason to publish nothing. Absent only for records
+	 * written before this field existed and for a publisher whose runtime
+	 * evidence could not be classified at all; readers then reuse the broker as
+	 * before rather than retiring it on unknown evidence.
+	 */
+	runtime?: string;
 	ownerId: string;
 	pid: number;
 	incarnation: string;
@@ -345,10 +387,18 @@ export interface BrokerDiscovery {
 	token: string;
 	startedAt: number;
 	heartbeatAt: number;
+	restartRequestId?: string;
+	rootDigest?: string;
+}
+export interface BrokerRestartIntent {
+	requestId: string;
+	lease: string;
+	expiresAt: number;
+	phase?: "prepared" | "committed" | "cancelled";
 }
 export type RedactedBrokerDiscovery = Omit<BrokerDiscovery, "token"> & { token: "[redacted]" };
 export type BrokerDiscoveryWrite = Omit<BrokerDiscovery, "incarnation"> & { incarnation?: string };
-export const brokerDiscoveryPath = (agentDir: string) => path.join(agentDir, "sdk", "broker.json");
+export const brokerDiscoveryPath = (agentDir: string) => path.join(agentDir, BROKER_ARTIFACT_PATHS.discovery);
 export const newBrokerToken = () => randomBytes(32).toString("hex");
 export const brokerProcessIncarnation = processIncarnation;
 export function isPidAlive(pid: number): boolean {
@@ -389,7 +439,6 @@ async function syncDirectory(directory: string): Promise<void> {
 export async function writeBrokerDiscovery(agentDir: string, discovery: BrokerDiscoveryWrite): Promise<void> {
 	const incarnation = discovery.incarnation ?? brokerProcessIncarnation(discovery.pid);
 	if (!incarnation) throw new Error(`Broker process incarnation is unavailable for pid ${discovery.pid}.`);
-	const record: BrokerDiscovery = { ...discovery, incarnation };
 	if (!isFixedWidthHeartbeat(discovery.heartbeatAt)) {
 		throw new Error("Broker heartbeatAt must be a fixed-width 13-digit millisecond timestamp.");
 	}
@@ -397,6 +446,11 @@ export async function writeBrokerDiscovery(agentDir: string, discovery: BrokerDi
 	const dir = path.dirname(file);
 	await fs.mkdir(dir, { recursive: true, mode: 0o700 });
 	await fs.chmod(dir, 0o700);
+	const record: BrokerDiscovery = {
+		...discovery,
+		incarnation,
+		rootDigest: await canonicalServiceRootDigest(agentDir),
+	};
 	const temp = `${file}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
 	try {
 		await fs.writeFile(temp, `${JSON.stringify(record)}\n`, { mode: 0o600 });
@@ -417,8 +471,12 @@ export async function publishBrokerDiscovery(
 ): Promise<RetainedBrokerDiscovery> {
 	const incarnation = discovery.incarnation ?? brokerProcessIncarnation(discovery.pid);
 	if (!incarnation) throw new Error(`Broker process incarnation is unavailable for pid ${discovery.pid}.`);
-	const published: BrokerDiscovery = { ...discovery, incarnation };
-	await writeBrokerDiscovery(agentDir, published);
+	await writeBrokerDiscovery(agentDir, { ...discovery, incarnation });
+	const published: BrokerDiscovery = {
+		...discovery,
+		incarnation,
+		rootDigest: await canonicalServiceRootDigest(agentDir),
+	};
 	if (platform === "win32") return new LegacyWindowsBrokerDiscovery(agentDir, published);
 	try {
 		return new NativeRetainedBrokerDiscovery(requireRetainedBrokerPublication(agentDir));
@@ -465,9 +523,11 @@ export async function readBrokerDiscovery(
 			d.pid <= 0 ||
 			typeof d.incarnation !== "string" ||
 			d.incarnation.length === 0 ||
+			(d.runtime !== undefined && (typeof d.runtime !== "string" || d.runtime.length === 0)) ||
 			!Number.isFinite(d.heartbeatAt)
 		)
 			return null;
+		if (d.restartRequestId !== undefined && !/^[A-Za-z0-9_-]{1,256}$/.test(d.restartRequestId)) return null;
 		if (!isPidAlive(d.pid)) return null;
 		const incarnation = brokerProcessIncarnation(d.pid);
 		if (!incarnation || incarnation !== d.incarnation || Date.now() - d.heartbeatAt > ttlMs) return null;
@@ -477,6 +537,99 @@ export async function readBrokerDiscovery(
 		throw e;
 	}
 }
+
+/**
+ * The restart-intent slot lives directly beneath `sdk/`, independent of
+ * `sdk/broker.lock/` -- so it durably survives a stale-lock reclaim that
+ * renames the incumbent's lock directory aside (`Broker#reclaimStaleLock`).
+ */
+export const brokerRestartIntentPath = (agentDir: string) => path.join(agentDir, BROKER_ARTIFACT_PATHS.restartIntent);
+
+export interface BrokerRestartIntentWithIdentity extends BrokerRestartIntent {
+	/** Existing platform file identity, for a successor's exact-identity clear. */
+	identity: NativeBrokerRestartIntentIdentity;
+}
+
+export async function readBrokerRestartIntent(agentDir: string): Promise<BrokerRestartIntentWithIdentity | null> {
+	const file = brokerRestartIntentPath(agentDir);
+	let handle: fs.FileHandle | undefined;
+	try {
+		handle = await fs.open(
+			file,
+			fsSync.constants.O_RDONLY | fsSync.constants.O_NOFOLLOW | fsSync.constants.O_NONBLOCK,
+		);
+		const before = await handle.stat({ bigint: true });
+		const parent = await fs.lstat(path.dirname(file), { bigint: true });
+		if (
+			!before.isFile() ||
+			before.nlink !== 1n ||
+			before.size > 4096n ||
+			!parent.isDirectory() ||
+			parent.isSymbolicLink()
+		)
+			throw new Error("Malformed broker restart intent.");
+		const buffer = new Uint8Array(4097);
+		let length = 0;
+		while (length < buffer.length) {
+			const read = await handle.read(buffer, length, buffer.length - length, length);
+			if (read.bytesRead === 0) break;
+			length += read.bytesRead;
+		}
+		if (length > 4096) throw new Error("Malformed broker restart intent.");
+		const after = await handle.stat({ bigint: true });
+		const lexical = await fs.lstat(file, { bigint: true });
+		const parentAfter = await fs.lstat(path.dirname(file), { bigint: true });
+		if (
+			after.dev !== before.dev ||
+			after.ino !== before.ino ||
+			after.size !== before.size ||
+			after.mtimeNs !== before.mtimeNs ||
+			after.ctimeNs !== before.ctimeNs ||
+			after.nlink !== 1n ||
+			lexical.isSymbolicLink() ||
+			lexical.dev !== after.dev ||
+			lexical.ino !== after.ino ||
+			lexical.mtimeNs !== after.mtimeNs ||
+			lexical.ctimeNs !== after.ctimeNs ||
+			parentAfter.isSymbolicLink() ||
+			parent.dev !== parentAfter.dev ||
+			parent.ino !== parentAfter.ino
+		)
+			throw new Error("Broker restart intent changed during observation.");
+		let value: unknown;
+		try {
+			value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(buffer.subarray(0, length)));
+		} catch {
+			throw new Error("Malformed broker restart intent.");
+		}
+		if (!value || typeof value !== "object" || Array.isArray(value))
+			throw new Error("Malformed broker restart intent.");
+		const intent = value as Partial<BrokerRestartIntent>;
+		if (
+			typeof intent.requestId !== "string" ||
+			!/^[A-Za-z0-9_-]{1,256}$/.test(intent.requestId) ||
+			typeof intent.lease !== "string" ||
+			!/^[A-Za-z0-9_-]{1,256}$/.test(intent.lease) ||
+			typeof intent.expiresAt !== "number" ||
+			!Number.isSafeInteger(intent.expiresAt) ||
+			intent.expiresAt <= 0 ||
+			(intent.phase !== "prepared" && intent.phase !== "committed" && intent.phase !== "cancelled")
+		)
+			throw new Error("Malformed broker restart intent.");
+		return {
+			requestId: intent.requestId,
+			lease: intent.lease,
+			expiresAt: intent.expiresAt,
+			phase: intent.phase,
+			identity: { dev: after.dev, ino: after.ino },
+		};
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT" && !handle) return null;
+		throw error;
+	} finally {
+		await handle?.close();
+	}
+}
 export function redactBrokerDiscovery(discovery: BrokerDiscovery): RedactedBrokerDiscovery {
 	return { ...discovery, token: "[redacted]" };
 }

package/src/sdk/broker/doctor-restart.ts

@@ -0,0 +1,206 @@
+import { randomUUID } from "node:crypto";
+import { SdkClient, SdkClientError } from "../client/client";
+import type {
+	BrokerRestartCommitOptions,
+	BrokerRestartOwnerIdentity,
+	BrokerRestartPrepareOptions,
+	BrokerRestartPrepareResult,
+	BrokerRestartResult,
+} from "./broker";
+import { launchAuthorizedBrokerSuccessor, oldOwnerConfirmedExited } from "./daemon-entry";
+import { type BrokerDiscovery, readBrokerDiscovery } from "./discovery";
+
+export interface DoctorBrokerRestartOptions {
+	agentDir: string;
+	deadlineMs?: number;
+	drain?: boolean;
+	requestId?: string;
+}
+
+/**
+ * Concrete typed before/after-effect outcome of a full D8 broker restart
+ * attempt. Every refusal names the exact stage and, where the broker itself
+ * refused, the broker's own typed error code -- never an opaque thrown
+ * message standing in for a decision this adapter could name.
+ */
+export type DoctorBrokerRestartOutcome =
+	| {
+			kind: "restarted";
+			requestId: string;
+			oldOwner: BrokerRestartOwnerIdentity;
+			successor: BrokerDiscovery;
+			/** True when an already-committed successor for this exact request was found and reused, not spawned. */
+			adopted: boolean;
+	  }
+	| { kind: "owner_unavailable"; reason: "no_discovery" | "owner_not_confirmed_live" }
+	| { kind: "prepare_refused"; code: string; message: string }
+	| { kind: "commit_refused"; code: string; message: string }
+	| { kind: "old_owner_exit_timeout"; requestId: string; oldOwner: BrokerRestartOwnerIdentity }
+	| {
+			kind: "successor_refused";
+			requestId: string;
+			oldOwner: BrokerRestartOwnerIdentity;
+			reason:
+				| "deadline_elapsed"
+				| "intent_not_committed"
+				| "spawn_failed"
+				| "spawn_exited_before_publication"
+				| "publication_timeout";
+			detail?: string;
+	  };
+
+function identity(discovery: BrokerDiscovery): BrokerRestartOwnerIdentity {
+	return {
+		ownerId: discovery.ownerId,
+		generation: discovery.packageGeneration,
+		pid: discovery.pid,
+		incarnation: discovery.incarnation,
+	};
+}
+
+function typedResult(response: unknown): BrokerRestartResult {
+	if (response && typeof response === "object" && "ok" in response) return response as BrokerRestartResult;
+	return { ok: false, error: { code: "protocol_error", message: "broker returned a malformed restart response" } };
+}
+
+export async function prepareDoctorBrokerRestart(
+	client: SdkClient,
+	discovery: BrokerDiscovery,
+	options: DoctorBrokerRestartOptions & { requestId: string },
+): Promise<BrokerRestartResult> {
+	const input: BrokerRestartPrepareOptions = {
+		...identity(discovery),
+		requestId: options.requestId,
+		deadlineAt: Date.now() + (options.deadlineMs ?? 30_000),
+		drain: options.drain,
+	};
+	return typedResult(await client.global("broker.prepare_restart", { ...input }));
+}
+
+export async function commitDoctorBrokerRestart(
+	client: SdkClient,
+	discovery: BrokerDiscovery,
+	prepared: BrokerRestartPrepareResult,
+	requestId: string,
+): Promise<BrokerRestartResult> {
+	const input: BrokerRestartCommitOptions = {
+		...identity(discovery),
+		requestId,
+		deadlineAt: prepared.expiresAt,
+		lease: prepared.lease,
+		occupancyEpoch: prepared.occupancyEpoch,
+	};
+	return typedResult(await client.global("broker.commit_restart", { ...input }));
+}
+
+export async function cancelDoctorBrokerRestart(client: SdkClient, requestId: string): Promise<BrokerRestartResult> {
+	return typedResult(await client.global("broker.cancel_restart", { requestId }));
+}
+
+const OLD_OWNER_EXIT_POLL_MS = 50;
+
+/**
+ * Owner-side prepare/commit/stop, positive-exit-confirmed cleanup, then
+ * exactly one successor launch or adoption. The exact sequence:
+ *
+ * 1. Read the CURRENT discovery snapshot (never a stale caller-supplied one)
+ *    and prove its owner is live via a real connected client, not an
+ *    incarnation string comparison alone.
+ * 2. `prepare_restart` against that exact owner tuple/generation; on any
+ *    prepare refusal, cancel the reservation and return the broker's own
+ *    typed refusal rather than throwing.
+ * 3. `commit_restart` with the exact lease/occupancyEpoch prepare returned.
+ *    Once committed, the owner is durably retiring: cancellation is no longer
+ *    safe and this function must never call cancel past this point.
+ * 4. Close the client (every path below runs with the client closed).
+ * 5. Wait, bounded by the request deadline, for `observeProcessIncarnation`
+ *    to positively confirm the exact old pid is OS-absent -- never inferred
+ *    from a changed/missing incarnation read, and never from discovery
+ *    disappearing (a crashed writer can leave a stale discovery file behind
+ *    just as easily as a clean exit can remove it).
+ * 6. Launch (or adopt an already-published) exactly one successor for this
+ *    requestId, holding the shared startup exclusion only around the launch
+ *    decision itself -- never across the successor's own publication wait,
+ *    which would deadlock this process against its own spawned child.
+ *
+ * The successor clears the durable committed intent itself, from inside its
+ * own `Broker#start()`, only after its own publication has independently
+ * proven it owns the root -- never here, and never before that proof exists.
+ */
+export async function restartBrokerForDoctor(options: DoctorBrokerRestartOptions): Promise<DoctorBrokerRestartOutcome> {
+	const old = await readBrokerDiscovery(options.agentDir);
+	if (!old) return { kind: "owner_unavailable", reason: "no_discovery" };
+	const oldOwner = identity(old);
+	const requestId = options.requestId ?? randomUUID();
+	const deadlineMs = options.deadlineMs ?? 30_000;
+	const deadlineAt = Date.now() + deadlineMs;
+
+	let client: SdkClient;
+	try {
+		client = await SdkClient.connect(old.url, old.token, { timeoutMs: deadlineMs });
+	} catch {
+		return { kind: "owner_unavailable", reason: "owner_not_confirmed_live" };
+	}
+
+	let prepared: BrokerRestartPrepareResult | undefined;
+	try {
+		const prepareResult = await prepareDoctorBrokerRestart(client, old, { ...options, requestId });
+		if (!prepareResult.ok)
+			return { kind: "prepare_refused", code: prepareResult.error.code, message: prepareResult.error.message };
+		prepared = prepareResult.result as BrokerRestartPrepareResult;
+
+		const commitResult = await commitDoctorBrokerRestart(client, old, prepared, requestId);
+		if (!commitResult.ok) {
+			// A commit refusal leaves the owner's own reservation in place; the
+			// owner's lease-expiry timer (or an explicit cancel by the same
+			// requestId) is what releases it, never a resurrect-old-owner retry
+			// from here.
+			try {
+				await cancelDoctorBrokerRestart(client, requestId);
+			} catch {
+				// Best-effort: an unreachable owner past a refused commit still
+				// self-expires its own lease.
+			}
+			return { kind: "commit_refused", code: commitResult.error.code, message: commitResult.error.message };
+		}
+	} catch (caught) {
+		throw caught instanceof SdkClientError
+			? caught
+			: new Error(
+					`SDK broker restart prepare/commit failed: ${caught instanceof Error ? caught.message : String(caught)}`,
+					{
+						cause: caught,
+					},
+				);
+	} finally {
+		await client.close().catch(() => undefined);
+	}
+
+	// Committed: the owner is durably retiring. Wait for its exact OS
+	// incarnation to be positively confirmed absent before authorizing any
+	// successor -- never inferred from discovery disappearing or from a
+	// PID-reuse-vulnerable incarnation mismatch alone.
+	while (Date.now() < deadlineAt) {
+		if (oldOwnerConfirmedExited(oldOwner.pid)) break;
+		await Bun.sleep(OLD_OWNER_EXIT_POLL_MS);
+	}
+	if (!oldOwnerConfirmedExited(oldOwner.pid)) return { kind: "old_owner_exit_timeout", requestId, oldOwner };
+
+	const successor = await launchAuthorizedBrokerSuccessor({
+		agentDir: options.agentDir,
+		requestId,
+		deadlineAt: prepared!.expiresAt,
+		packageGeneration: old.packageGeneration,
+	});
+	if (successor.kind === "refused")
+		return { kind: "successor_refused", requestId, oldOwner, reason: successor.reason, detail: successor.detail };
+	return {
+		kind: "restarted",
+		requestId,
+		oldOwner,
+		successor: successor.discovery,
+		adopted: successor.kind === "adopted",
+	};
+}
+
+export type { BrokerRestartResult };

package/src/sdk/broker/endpoint-authority.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import * as fsSync from "node:fs";
 import * as fs from "node:fs/promises";
 
@@ -20,6 +21,41 @@ export type IndexedEndpointAuthority = {
 	endpointFileId?: string;
 };
 
+/** Derive the broker-compatible opaque authority for one indexed endpoint generation. */
+export function endpointIncarnation(
+	record: { endpointGeneration: number; endpointMtimeMs?: number; pid: number; endpointFileId?: string },
+	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,
+				// Filesystem mtime is only millisecond-precise, and the two stat
+				// spellings used across this path (bigint mtimeNs/1e6 vs libuv
+				// double mtimeMs) can disagree by 1 float ulp (~0.00024ms) for the
+				// same file (#5376). Quantize so equivalent reads hash identically.
+				// The immutable endpoint file identity (dev:ino) stays exact, so a
+				// genuine same-millisecond successor replacement still changes the
+				// digest even when pid/generation are reused.
+				endpointMtimeMs: Math.round(record.endpointMtimeMs),
+				...(record.endpointFileId === undefined ? {} : { endpointFileId: record.endpointFileId }),
+				pid: record.pid,
+				sessionId,
+			}),
+		)
+		.digest("hex");
+}
+
 function readFlags(): number {
 	return fsSync.constants.O_RDONLY | (fsSync.constants.O_NOFOLLOW ?? 0) | (fsSync.constants.O_NONBLOCK ?? 0);
 }

package/src/sdk/broker/ensure.ts

@@ -7,8 +7,17 @@ import packageJson from "../../../package.json" with { type: "json" };
 import { acquireFileLock, type FileLockOptions, withFileLock } from "../../config/file-lock";
 import { loadInstallationHostId, loadLegacyInstallationHostId } from "../../config/machine-identity";
 import { SdkClient } from "../client/client";
-import { type BrokerDiscovery, brokerProcessIncarnation, readBrokerDiscovery } from "./discovery";
-import { resolveSdkInternalSpawnCommand, type SdkInternalSpawnCommand } from "./runtime";
+import {
+	type BrokerDiscovery,
+	brokerProcessIncarnation,
+	readBrokerDiscovery,
+	readBrokerRestartIntent,
+} from "./discovery";
+import {
+	isSdkInternalRuntimeImagePresent,
+	resolveSdkInternalSpawnCommand,
+	type SdkInternalSpawnCommand,
+} from "./runtime";
 import { BrokerStartupError, clearBrokerStartupFailureMarker, readBrokerStartupFailureMarker } from "./startup-failure";
 
 function resolveExpectedBrokerGeneration(): string {
@@ -20,8 +29,27 @@ export function isBrokerGenerationCompatible(discovery: BrokerDiscovery | null):
 	if (!discovery) return false;
 	return discovery.packageGeneration === resolveExpectedBrokerGeneration();
 }
+
+/**
+ * A live incumbent stops being reusable once the runtime image it launches
+ * internal processes with is provably gone. A broker outlives its own executable
+ * (a package manager replacing the interpreter it was started from, an install
+ * directory swapped underneath it): it keeps heartbeating and answering
+ * requests, but every `session.create` it accepts is refused at spawn time.
+ * Retiring it here repairs the endpoint before a caller reaches session
+ * creation. Absent runtime evidence -- a record predating the field, or a
+ * publisher that could not classify its own runtime at all -- and evidence this
+ * caller merely cannot inspect both keep the incumbent reusable.
+ */
+export async function isBrokerReusable(discovery: BrokerDiscovery | null): Promise<boolean> {
+	if (!isBrokerGenerationCompatible(discovery)) return false;
+	const runtime = discovery?.runtime;
+	return runtime === undefined || (await isSdkInternalRuntimeImagePresent(runtime));
+}
 export interface EnsureBrokerSettings {
 	agentDir: string;
+	/** Only an authorized doctor successor may consume a restart-intent publication. */
+	restartRequestId?: string;
 	heartbeatTtlMs?: number;
 	/**
 	 * Environment for the spawned detached broker. Defaults to `process.env`; tests
@@ -387,7 +415,7 @@ export async function closeBrokerClientBeforeDeadline(
 	await Promise.race([close, Bun.sleep(remainingMs)]);
 }
 
-async function retireStaleBrokerGeneration(
+async function retireUnusableBroker(
 	stale: BrokerDiscovery,
 	settings: EnsureBrokerSettings,
 	outerDeadline = Number.POSITIVE_INFINITY,
@@ -429,10 +457,10 @@ export async function reconcileBrokerGenerationForStartup(
 ): Promise<BrokerDiscovery | undefined> {
 	const current = await readBrokerDiscoveryBeforeDeadline(settings.agentDir, settings.heartbeatTtlMs, deadline);
 	if (!current) return undefined;
-	if (isBrokerGenerationCompatible(current)) return current;
-	await retireStaleBrokerGeneration(current, settings, deadline);
+	if (await isBrokerReusable(current)) return current;
+	await retireUnusableBroker(current, settings, deadline);
 	const replacement = await readBrokerDiscoveryBeforeDeadline(settings.agentDir, settings.heartbeatTtlMs, deadline);
-	return replacement && isBrokerGenerationCompatible(replacement) ? replacement : undefined;
+	return replacement && (await isBrokerReusable(replacement)) ? replacement : undefined;
 }
 function createFixtureLeaseFromChild(child: ChildProcess, terminate: () => Promise<void>): ExactFixtureBrokerLease {
 	let termination: Promise<void> | undefined;
@@ -485,23 +513,27 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 		settings.heartbeatTtlMs,
 		initialDiscoveryDeadline,
 	);
+	const restartIntent = await readBrokerRestartIntent(settings.agentDir);
+	if (restartIntent && restartIntent.expiresAt > Date.now() && restartIntent.requestId !== settings.restartRequestId)
+		throw new Error("broker_restart_in_progress");
 	if (initiator === "fixture-lease" && (priorOwner || existing)) throw fixtureLeaseUnavailable();
 	if (priorOwner) {
 		// A retained cleanup failure fences every discovery record. Only a ready
 		// record bound to this exact child incarnation may be reused.
-		if (priorOwner.canReuse(existing)) return { kind: "prior-local-owner", discovery: existing!, owner: priorOwner };
+		if (priorOwner.canReuse(existing) && (await isBrokerReusable(existing)))
+			return { kind: "prior-local-owner", discovery: existing!, owner: priorOwner };
 		await priorOwner.stop();
 		const discoveredAfterCleanup = await readBrokerDiscoveryBeforeDeadline(
 			settings.agentDir,
 			settings.heartbeatTtlMs,
 			initialDiscoveryDeadline,
 		);
-		if (discoveredAfterCleanup && isBrokerGenerationCompatible(discoveredAfterCleanup))
+		if (discoveredAfterCleanup && (await isBrokerReusable(discoveredAfterCleanup)))
 			return { kind: "external-discovery", discovery: discoveredAfterCleanup };
-		// Stale-generation retirement is serialized under the spawn lock below.
+		// Unusable-incumbent retirement is serialized under the spawn lock below.
 	} else if (existing) {
-		if (isBrokerGenerationCompatible(existing)) return { kind: "external-discovery", discovery: existing };
-		// Stale-generation retirement is serialized under the spawn lock below.
+		if (await isBrokerReusable(existing)) return { kind: "external-discovery", discovery: existing };
+		// Unusable-incumbent retirement is serialized under the spawn lock below.
 	}
 
 	// Only one process may spawn for this agent dir at a time; everyone else
@@ -512,6 +544,9 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 	try {
 		const deadline =
 			Date.now() + (initiator === "fixture-lease" ? FIXTURE_DISCOVERY_TIMEOUT_MS : DISCOVERY_TIMEOUT_MS);
+		const lockedIntent = await readBrokerRestartIntent(settings.agentDir);
+		if (lockedIntent && lockedIntent.expiresAt > Date.now() && lockedIntent.requestId !== settings.restartRequestId)
+			throw new Error("broker_restart_in_progress");
 		// The lock winner may still find a discovery published by an earlier winner
 		// that finished between our first read and the lock acquisition.
 		const discoveredUnderLock = await reconcileBrokerGenerationForStartup(settings, deadline);
@@ -546,7 +581,7 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 					deadline,
 				);
 				if (discovered) {
-					if (!isBrokerGenerationCompatible(discovered)) {
+					if (!(await isBrokerReusable(discovered))) {
 						await sleep(50);
 						continue;
 					}
@@ -577,7 +612,7 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 						settings.heartbeatTtlMs,
 						deadline,
 					);
-					if (winner && isBrokerGenerationCompatible(winner)) {
+					if (winner && (await isBrokerReusable(winner))) {
 						await owner.stop();
 						return { kind: "external-discovery", discovery: winner };
 					}
@@ -622,7 +657,7 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 						settings.heartbeatTtlMs,
 						recoveryDeadline,
 					);
-					if (incumbent && isBrokerGenerationCompatible(incumbent)) {
+					if (incumbent && (await isBrokerReusable(incumbent))) {
 						await owner.stop();
 						return { kind: "external-discovery", discovery: incumbent };
 					}