@gajae-code/coding-agent 0.16.7 → 0.17.1

package/src/sdk/broker/broker.ts

@@ -3,7 +3,7 @@ import type { BigIntStats } from "node:fs";
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import path from "node:path";
-import type { NativeDirectoryTreeSnapshot } from "@gajae-code/natives";
+import type { NativeBrokerRestartIntent, NativeDirectoryTreeSnapshot } from "@gajae-code/natives";
 import { logger, resolveEquivalentPath } from "@gajae-code/utils";
 import packageJson from "../../../package.json" with { type: "json" };
 import type { ModelProfileErrorDetails } from "../../config/model-profile-contract";
@@ -14,6 +14,7 @@ import {
 	BROKER_RUNTIME_CLOSE_CAPABILITY_FIELD,
 } from "../host/control/runtime-gate";
 import { createDefaultSdkHostModelResolver, type SdkHostModelResolver } from "../host/model-pin";
+import { canonicalServiceRootDigest } from "../service-artifact-paths";
 import {
 	type DirectoryMigrationPolicy,
 	listManagedSessionCandidates,
@@ -32,9 +33,10 @@ import {
 	type RedactedBrokerDiscovery,
 	type RetainedBrokerDiscovery,
 	readBrokerDiscovery,
+	readBrokerRestartIntent,
 	redactBrokerDiscovery,
 } from "./discovery";
-import { matchesIndexedEndpointFile, readEndpointFile } from "./endpoint-authority";
+import { endpointIncarnation, matchesIndexedEndpointFile, readEndpointFile } from "./endpoint-authority";
 import { deriveIdempotencyIdentity, getBrokerIdentityKey } from "./identity";
 import {
 	canonicalDeleteLocatorPath,
@@ -52,6 +54,7 @@ import {
 	type LifecycleState,
 } from "./lifecycle-ledger";
 import { createMasterCapabilityVerifier, readEndpoint } from "./master-capability";
+import { sdkInternalRuntimeImage } from "./runtime";
 import { type IndexedSession, isSessionAuthorityEligible, SessionIndex, type SessionList } from "./session-index";
 import {
 	type ResolvedScopeV1,
@@ -77,6 +80,8 @@ import { BrokerTransport } from "./transport";
 export interface BrokerSettings {
 	agentDir: string;
 	packageGeneration?: string;
+	/** Published runtime image; tests inject one to model a vanished executable. */
+	runtime?: string;
 	port?: number;
 	heartbeatTtlMs?: number;
 	/** Broker-owned migration policy. Client lifecycle frames cannot select it. */
@@ -91,11 +96,20 @@ export interface BrokerSettings {
 	masterOrphanGraceMs?: number;
 	/** Host model resolver override for lifecycle tests and embedders. */
 	resolveModelPin?: SdkHostModelResolver;
+	/**
+	 * Exact restart request this process instance is the authorized successor
+	 * for. Set only by the real `broker-internal` entry point from its own
+	 * `GJC_BROKER_RESTART_REQUEST` environment read — never inferred here from
+	 * `process.env` directly, so the value this broker publishes is exactly the
+	 * value its launcher decided, with no cast/assumed tag in between.
+	 */
+	restartRequestId?: string;
 }
 
 type ResolvedBrokerSettings = {
 	agentDir: string;
 	packageGeneration: string;
+	runtime?: string;
 	port: number;
 	heartbeatTtlMs: number;
 	resolveDirectoryMigration: (_cwd: string) => Promise<DirectoryMigrationPolicy>;
@@ -103,6 +117,7 @@ type ResolvedBrokerSettings = {
 	spawnSubstrateProvider?: SpawnSubstrateProvider;
 	spawnPromptLayer?: SpawnPromptLayer;
 	masterOrphanGraceMs: number;
+	restartRequestId?: string;
 };
 export function resolveBrokerPackageGeneration(): string {
 	const v = (packageJson as { version?: unknown }).version;
@@ -300,6 +315,16 @@ function lifecycleFingerprint(operation: string, input: Record<string, unknown>)
 		.update(JSON.stringify({ operation, input: lifecycleRequestIdentity(input) }))
 		.digest("hex");
 }
+
+function publicLifecycleLookupInput(
+	input: Record<string, unknown>,
+): { operation: "session.create"; target: Record<string, unknown> } | BrokerResponse {
+	if (input.operation !== "session.create")
+		return error("invalid_input", "session.lookup only supports operation session.create");
+	const target = objectRecord(input.target);
+	if (!target) return error("invalid_input", "session.lookup target must be an object");
+	return { operation: "session.create", target };
+}
 function lifecycleResponseState(response: BrokerResponse): LifecycleState {
 	if (response.ok) return "terminal_ok";
 	if (isCleanupPending(response)) return "effect_started";
@@ -732,31 +757,6 @@ type LifecycleReplayEndpoint = {
 };
 
 type EndpointAuthority = { endpointGeneration?: number; endpointIncarnation?: string };
-function endpointIncarnation(
-	record: Pick<IndexedSession, "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(
-			canonicalJson({
-				endpointGeneration: record.endpointGeneration,
-				endpointMtimeMs: record.endpointMtimeMs,
-				pid: record.pid,
-				sessionId,
-			}),
-		)
-		.digest("hex");
-}
 function expectedEndpointAuthority(input: Record<string, unknown>): EndpointAuthority | BrokerResponse {
 	const endpointGeneration = input.endpointGeneration;
 	const endpointIncarnation = input.endpointIncarnation;
@@ -1117,6 +1117,32 @@ export interface StartupAdmissionTiming {
 	sleep(ms: number, signal?: AbortSignal): Promise<void>;
 }
 
+export interface BrokerRestartOwnerIdentity {
+	ownerId: string;
+	generation: string;
+	pid: number;
+	incarnation: string;
+}
+export interface BrokerRestartPrepareOptions extends BrokerRestartOwnerIdentity {
+	requestId: string;
+	deadlineAt: number;
+	drain?: boolean;
+}
+export interface BrokerRestartPrepareResult {
+	lease: string;
+	occupancyEpoch: number;
+	expiresAt: number;
+	requestId: string;
+	owner: BrokerRestartOwnerIdentity;
+}
+export interface BrokerRestartCommitOptions extends BrokerRestartPrepareOptions {
+	lease: string;
+	occupancyEpoch: number;
+}
+export type BrokerRestartResult =
+	| { ok: true; result: BrokerRestartPrepareResult | { committed: true } | { cancelled: true } }
+	| { ok: false; error: { code: string; message: string } };
+
 export type StartupAdmissionResult<T> =
 	| { status: "completed"; admittedAt: number; value: T }
 	| { status: "admission_timeout"; reason: "admission_timeout" }
@@ -1289,10 +1315,20 @@ export class Broker {
 	#rejectCompletion!: (error: unknown) => void;
 	#resolveModelPin: SdkHostModelResolver;
 	#ownsResolveModelPin: boolean;
+	#restart:
+		| {
+				options: BrokerRestartPrepareOptions;
+				lease: string;
+				occupancyEpoch: number;
+				expiresAt: number;
+				timer: NodeJS.Timeout;
+		  }
+		| undefined;
 	constructor(settings: BrokerSettings) {
 		this.settings = {
 			agentDir: settings.agentDir,
 			packageGeneration: settings.packageGeneration ?? resolveBrokerPackageGeneration(),
+			runtime: settings.runtime,
 			port: settings.port ?? 0,
 			heartbeatTtlMs: settings.heartbeatTtlMs ?? BROKER_HEARTBEAT_TTL_MS,
 			resolveDirectoryMigration: settings.resolveDirectoryMigration ?? (async () => "copy-retain"),
@@ -1300,6 +1336,7 @@ export class Broker {
 			spawnSubstrateProvider: settings.spawnSubstrateProvider,
 			spawnPromptLayer: settings.spawnPromptLayer,
 			masterOrphanGraceMs: settings.masterOrphanGraceMs ?? MASTER_ORPHAN_GRACE_DEFAULT_MS,
+			...(settings.restartRequestId === undefined ? {} : { restartRequestId: settings.restartRequestId }),
 		};
 		this.index = new SessionIndex(settings.agentDir);
 		this.ledger = new LifecycleLedger(settings.agentDir);
@@ -2402,9 +2439,23 @@ export class Broker {
 	async #createLock(): Promise<void> {
 		await fs.mkdir(this.#lock, { mode: 0o700 });
 		try {
+			const incarnation = brokerProcessIncarnation(process.pid);
+			// A minimal, non-secret receipt delta for D9 stale-artifact detach
+			// (sequenced follow-up): the OS incarnation and a digest of the exact
+			// resolved root this lock authorizes, so a later positive-death check can
+			// cross-bind this owner record against the discovery record it authored
+			// without re-deriving anything from file content or adding new identity.
+			const rootDigest = await canonicalServiceRootDigest(this.settings.agentDir);
 			await fs.writeFile(
 				this.#lockRecordPath(),
-				JSON.stringify({ version: 1, ownerId: this.#owner, pid: process.pid, acquiredAt: Date.now() }),
+				JSON.stringify({
+					version: 1,
+					ownerId: this.#owner,
+					pid: process.pid,
+					acquiredAt: Date.now(),
+					...(incarnation ? { incarnation } : {}),
+					rootDigest,
+				}),
 				{ flag: "wx", mode: 0o600 },
 			);
 		} catch (e) {
@@ -2577,6 +2628,7 @@ export class Broker {
 				version: 1,
 				protocolVersion: 3,
 				packageGeneration: this.settings.packageGeneration,
+				runtime: this.settings.runtime ?? sdkInternalRuntimeImage(),
 				ownerId: this.#owner,
 				pid: process.pid,
 				incarnation,
@@ -2586,6 +2638,9 @@ export class Broker {
 				token,
 				startedAt: now,
 				heartbeatAt: now,
+				...(this.settings.restartRequestId === undefined
+					? {}
+					: { restartRequestId: this.settings.restartRequestId }),
 			};
 			// Readiness must not be externally visible until the initial session
 			// checkpoint settles. The bootstrap watchdog owns this pre-publication
@@ -2603,6 +2658,23 @@ export class Broker {
 				void this.#watchPublication();
 				void this.#reapSpawnOrphans();
 			}, cadenceMs);
+			// This process is now the independently verified successor: its own
+			// discovery just published under its own retained authority. Release the
+			// predecessor's reservation only now, keyed to the exact request this
+			// process was launched for -- never on a startup that carries no restart
+			// request, and never before this publish proved this is the real owner.
+			if (this.settings.restartRequestId !== undefined && this.#publication) {
+				try {
+					const intent = await readBrokerRestartIntent(this.settings.agentDir);
+					if (intent && intent.phase === "committed" && intent.requestId === this.settings.restartRequestId)
+						await this.#publication.clearForeignRestartIntent(intent.identity);
+				} catch {
+					// Best-effort reservation release. The admission gate in ensure.ts keys
+					// off requestId equality, which already matches this exact successor,
+					// so a retained committed intent here blocks nothing further; a failed
+					// clear must never fail this broker's own successful startup.
+				}
+			}
 			return this.discovery;
 		} catch (error) {
 			await this.#transport?.stop();
@@ -2620,6 +2692,130 @@ export class Broker {
 	get completion(): Promise<void> {
 		return this.#completion;
 	}
+	#restartIdentity(): BrokerRestartOwnerIdentity | undefined {
+		const d = this.discovery;
+		if (!d?.incarnation) return undefined;
+		return { ownerId: d.ownerId, generation: d.packageGeneration, pid: d.pid, incarnation: d.incarnation };
+	}
+	#restartBusy(): boolean {
+		for (const session of this.index.listSessions().sessions) {
+			if (session.live && !session.terminal) return true;
+		}
+		return this.#admitted.size > 1;
+	}
+	async prepareRestart(options: BrokerRestartPrepareOptions): Promise<BrokerRestartResult> {
+		const identity = this.#restartIdentity();
+		if (
+			!identity ||
+			options.ownerId !== identity.ownerId ||
+			options.generation !== identity.generation ||
+			options.pid !== identity.pid ||
+			options.incarnation !== identity.incarnation ||
+			!options.requestId ||
+			!Number.isSafeInteger(options.deadlineAt) ||
+			options.deadlineAt <= Date.now()
+		)
+			return { ok: false, error: { code: "restart_identity_mismatch", message: "broker owner identity mismatch" } };
+		if (this.#restart) {
+			if (this.#restart.options.requestId !== options.requestId)
+				return {
+					ok: false,
+					error: { code: "restart_request_mismatch", message: "restart request is already prepared" },
+				};
+			return {
+				ok: true,
+				result: {
+					lease: this.#restart.lease,
+					occupancyEpoch: this.#restart.occupancyEpoch,
+					expiresAt: this.#restart.expiresAt,
+					requestId: this.#restart.options.requestId,
+					owner: identity,
+				},
+			};
+		}
+		this.#startupAdmissions.close();
+		const occupancyEpoch = this.index.listSessions().indexSeq;
+		const lease = randomBytes(24).toString("base64url");
+		const expiresAt = Math.min(options.deadlineAt, Date.now() + 30_000);
+		const timer = setTimeout(() => void this.cancelRestart(options.requestId), Math.max(1, expiresAt - Date.now()));
+		this.#restart = { options, lease, occupancyEpoch, expiresAt, timer };
+		const abortPrepare = async (code: string, message: string): Promise<BrokerRestartResult> => {
+			clearTimeout(timer);
+			this.#restart = undefined;
+			this.#startupAdmissions.reopen();
+			return { ok: false, error: { code, message } };
+		};
+		try {
+			await this.index.refresh();
+		} catch {
+			return abortPrepare("restart_prepare_failed", "broker occupancy could not be refreshed");
+		}
+		const deadline = Math.min(options.deadlineAt, Date.now() + 30_000);
+		while (options.drain && this.#restartBusy() && Date.now() < deadline) await Bun.sleep(25);
+		if (this.#restartBusy()) return abortPrepare("restart_busy", "broker has active or admitted work");
+		const intent: NativeBrokerRestartIntent = { requestId: options.requestId, lease, expiresAt };
+		const publication = this.#publication;
+		if (!publication || !(await publication.prepareRestartIntent(intent)))
+			return abortPrepare("restart_prepare_failed", "restart intent could not be durably prepared");
+		return { ok: true, result: { lease, occupancyEpoch, expiresAt, requestId: options.requestId, owner: identity } };
+	}
+	async commitRestart(options: BrokerRestartCommitOptions): Promise<BrokerRestartResult> {
+		const current = this.#restart;
+		const identity = this.#restartIdentity();
+		if (
+			!current ||
+			!identity ||
+			current.lease !== options.lease ||
+			current.occupancyEpoch !== options.occupancyEpoch ||
+			current.options.requestId !== options.requestId ||
+			options.ownerId !== identity.ownerId ||
+			options.generation !== identity.generation ||
+			options.pid !== identity.pid ||
+			options.incarnation !== identity.incarnation ||
+			Date.now() >= current.expiresAt ||
+			this.#restartBusy()
+		)
+			return { ok: false, error: { code: "restart_commit_refused", message: "restart commit proof is invalid" } };
+		const publication = this.#publication;
+		const intent: NativeBrokerRestartIntent = {
+			requestId: options.requestId,
+			lease: current.lease,
+			expiresAt: current.expiresAt,
+		};
+		if (!publication || !(await publication.commitRestartIntent(intent)))
+			return {
+				ok: false,
+				error: { code: "restart_commit_refused", message: "restart intent could not be durably committed" },
+			};
+		clearTimeout(current.timer);
+		// The retained restart-intent slot (independent of `sdk/broker.lock/`)
+		// deliberately survives this owned-root exit: it is the durable proof a
+		// successor's ordinary startup consults, and clearing it here -- before
+		// this process has actually exited -- would let a racing ordinary
+		// `ensureBroker` treat the still-live old owner as idle and spawn early.
+		setTimeout(() => {
+			void this.#complete("owned-root").finally(() => {
+				if (this.#restart === current) this.#restart = undefined;
+			});
+		}, 0);
+		return { ok: true, result: { committed: true } };
+	}
+	async cancelRestart(requestId: string): Promise<BrokerRestartResult> {
+		const current = this.#restart;
+		if (!current) return { ok: true, result: { cancelled: true } };
+		if (current.options.requestId !== requestId)
+			return { ok: false, error: { code: "restart_request_mismatch", message: "restart request does not match" } };
+		const publication = this.#publication;
+		// Best-effort: the owner's own descriptor-bound cancel removes the intent
+		// it prepared. A publication that is no longer reachable (already fenced,
+		// already stopping) leaves the slot for lease-expiry discovery by the
+		// caller instead of retrying indefinitely inside this admission path.
+		if (publication) await publication.cancelRestartIntent().catch(() => undefined);
+		clearTimeout(current.timer);
+		this.#restart = undefined;
+		this.#startupAdmissions.reopen();
+		return { ok: true, result: { cancelled: true } };
+	}
 	status(): RedactedBrokerDiscovery | null {
 		return this.discovery ? redactBrokerDiscovery(this.discovery) : null;
 	}
@@ -3160,7 +3356,8 @@ export class Broker {
 		};
 		const sessions = snapshot.sessions.slice(snapshot.offset, snapshot.offset + snapshot.limit).map(session => {
 			const { lifecycleRequestId: _lifecycleRequestId, ...publicSession } = session;
-			return publicSession;
+			const incarnation = endpointIncarnation(session, session.sessionId);
+			return incarnation === undefined ? publicSession : { ...publicSession, endpointIncarnation: incarnation };
 		});
 		const offset = snapshot.offset + sessions.length;
 		if (offset >= snapshot.sessions.length && typeof cursor === "string") this.#sessionListCursors.delete(cursor);
@@ -3183,9 +3380,45 @@ export class Broker {
 			indexSeq: snapshot.indexSeq,
 		};
 	}
+	async #lookupLifecycle(
+		requestedOperation: string,
+		idempotencyKey: string | undefined,
+		requestedFingerprint: string,
+	): Promise<BrokerResponse> {
+		if (!idempotencyKey) return error("invalid_input", "operation, idempotencyKey, and fingerprint are required");
+		if (requestedOperation === "session.spawn")
+			return error("invalid_input", "session.spawn does not support lifecycle lookup");
+		if (!LIFECYCLE_OPERATIONS.has(requestedOperation)) return error("not_found", "lifecycle operation was not found");
+		const identity = await deriveIdempotencyIdentity(this.settings.agentDir, requestedOperation, idempotencyKey);
+		const entry = this.ledger.get(identity);
+		if (!entry) return error("not_found", "lifecycle operation was not found");
+		if (entry.fingerprint !== requestedFingerprint)
+			return error("idempotency_conflict", "lifecycle request fingerprint differs");
+		if (entry.state === "terminal_uncertain")
+			return error("terminal_uncertain", "lifecycle outcome is still uncertain");
+		if (entry.state !== "terminal_ok" && entry.state !== "terminal_error")
+			return error("lifecycle_pending", "lifecycle outcome is still pending");
+		return isBrokerResponse(entry.response)
+			? entry.response
+			: error("terminal_uncertain", "lifecycle outcome has no recorded response");
+	}
 	handleRequest(operation: string, input: Record<string, unknown>, idempotencyKey?: string): Promise<BrokerResponse> {
+		if (operation === "broker.status") return Promise.resolve({ ok: true, result: this.status() });
+		if (operation === "broker.prepare_restart")
+			return this.prepareRestart(input as unknown as BrokerRestartPrepareOptions).then(
+				result => result as BrokerResponse,
+			);
+		if (operation === "broker.commit_restart")
+			return this.commitRestart(input as unknown as BrokerRestartCommitOptions).then(
+				result => result as BrokerResponse,
+			);
+		if (operation === "broker.cancel_restart") {
+			const requestId = typeof input.requestId === "string" ? input.requestId : "";
+			return this.cancelRestart(requestId).then(result => result as BrokerResponse);
+		}
 		if (this.#stopping || (this.#publication !== null && this.#publicationState !== "healthy-owned"))
 			return Promise.resolve(error("unavailable", "broker publication is unavailable"));
+		if (this.#restart) return Promise.resolve(error("broker_restarting", "broker restart is prepared"));
 		let release!: () => void;
 		const admission = new Promise<void>(resolve => (release = resolve));
 		this.#admitted.add(admission);
@@ -3208,6 +3441,15 @@ export class Broker {
 			if (spawnClose) return spawnClose;
 		}
 		if (operation === "session.control") return this.#sessionControl(input, idempotencyKey);
+		if (operation === "session.lookup") {
+			const lookup = publicLifecycleLookupInput(input);
+			if (isBrokerResponse(lookup)) return lookup;
+			return await this.#lookupLifecycle(
+				lookup.operation,
+				idempotencyKey,
+				lifecycleFingerprint(lookup.operation, lookup.target),
+			);
+		}
 		const fingerprint = lifecycleFingerprint(operation, input);
 		const normalization = normalizeBrokerInput(operation, input);
 		if (isBrokerResponse(normalization)) return normalization;
@@ -3270,22 +3512,9 @@ export class Broker {
 		if (operation === "broker.lookup_lifecycle") {
 			const requestedOperation = typeof input.operation === "string" ? input.operation : undefined;
 			const requestedFingerprint = typeof input.fingerprint === "string" ? input.fingerprint : undefined;
-			if (!idempotencyKey || !requestedOperation || !requestedFingerprint)
+			if (!requestedOperation || !requestedFingerprint)
 				return error("invalid_input", "operation, idempotencyKey, and fingerprint are required");
-			if (requestedOperation === "session.spawn")
-				return error("invalid_input", "session.spawn does not support lifecycle lookup");
-			if (!LIFECYCLE_OPERATIONS.has(requestedOperation))
-				return error("not_found", "lifecycle operation was not found");
-			const identity = await deriveIdempotencyIdentity(this.settings.agentDir, requestedOperation, idempotencyKey);
-			const entry = this.ledger.get(identity);
-			if (!entry) return error("not_found", "lifecycle operation was not found");
-			if (entry.fingerprint !== requestedFingerprint)
-				return error("idempotency_conflict", "lifecycle request fingerprint differs");
-			if (entry.state === "terminal_uncertain")
-				return error("terminal_uncertain", "lifecycle outcome is still uncertain");
-			return isBrokerResponse(entry.response)
-				? entry.response
-				: error("terminal_uncertain", "lifecycle outcome has no recorded response");
+			return await this.#lookupLifecycle(requestedOperation, idempotencyKey, requestedFingerprint);
 		}
 
 		if (!idempotencyKey) return error("invalid_input", "idempotencyKey is required for lifecycle operations");

package/src/sdk/broker/daemon-entry.ts

@@ -0,0 +1,119 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import { type BrokerDiscovery, readBrokerDiscovery, readBrokerRestartIntent } from "./discovery";
+import { withBrokerStartupLock } from "./ensure";
+import { observeProcessIncarnation } from "./process-incarnation";
+import { resolveSdkInternalSpawnCommand } from "./runtime";
+
+export interface AuthorizedBrokerSuccessorOptions {
+	agentDir: string;
+	requestId: string;
+	deadlineAt: number;
+	packageGeneration: string;
+}
+
+/** Typed outcome of a successor-launch attempt; never an opaque thrown message. */
+export type AuthorizedBrokerSuccessorResult =
+	| { kind: "adopted"; discovery: BrokerDiscovery }
+	| { kind: "spawned"; discovery: BrokerDiscovery }
+	| {
+			kind: "refused";
+			reason:
+				| "deadline_elapsed"
+				| "intent_not_committed"
+				| "spawn_failed"
+				| "spawn_exited_before_publication"
+				| "publication_timeout";
+			detail?: string;
+	  };
+
+const SUCCESSOR_SPAWN_POLL_MS = 25;
+
+/**
+ * Launches (or adopts) exactly one authorized successor for `requestId`.
+ *
+ * Holds `withBrokerStartupLock` only around the decision to spawn and the
+ * detached `spawn()` call itself -- never across the successor's own
+ * publication wait. The successor process (`commands/sdk.ts`'s
+ * `broker-internal` branch) acquires that SAME lock during its own startup to
+ * serialize against ordinary concurrent starts; holding it here while
+ * blocking on that child's publication would deadlock the parent against its
+ * own child. The unguarded polling loop below runs strictly after the lock
+ * has been released.
+ */
+export async function launchAuthorizedBrokerSuccessor(
+	options: AuthorizedBrokerSuccessorOptions,
+): Promise<AuthorizedBrokerSuccessorResult> {
+	const spawnOutcome = await withBrokerStartupLock(options.agentDir, async deadline => {
+		if (Date.now() >= Math.min(deadline, options.deadlineAt))
+			return { kind: "refused" as const, reason: "deadline_elapsed" as const };
+		// Only a durably COMMITTED intent for this exact requestId authorizes a
+		// spawn. A prepared-but-not-committed or absent intent means the owner
+		// side of the protocol never reached its commit boundary, so no successor
+		// may exist yet -- spawning here would double-launch a broker the owner
+		// might still be about to retire cleanly on its own.
+		const intent = await readBrokerRestartIntent(options.agentDir);
+		if (intent?.phase !== "committed" || intent.requestId !== options.requestId)
+			return { kind: "refused" as const, reason: "intent_not_committed" as const };
+		const existing = await readBrokerDiscovery(options.agentDir);
+		if (
+			existing &&
+			existing.packageGeneration === options.packageGeneration &&
+			existing.restartRequestId === options.requestId
+		)
+			return { kind: "adopted" as const, discovery: existing };
+		const command = resolveSdkInternalSpawnCommand("broker-internal");
+		let child: ChildProcess;
+		try {
+			child = spawn(command.file, [...command.args, "--agent-dir", options.agentDir], {
+				detached: true,
+				stdio: "ignore",
+				env: { ...command.env, GJC_BROKER_RESTART_REQUEST: options.requestId },
+				...(command.kind === "bun-source" ? { cwd: command.cwd } : {}),
+			});
+		} catch (spawnError) {
+			return {
+				kind: "refused" as const,
+				reason: "spawn_failed" as const,
+				detail: spawnError instanceof Error ? spawnError.message : String(spawnError),
+			};
+		}
+		let spawnError: Error | undefined;
+		child.once("error", childError => {
+			spawnError = childError;
+		});
+		child.unref();
+		return { kind: "spawned" as const, child, spawnError: () => spawnError };
+	});
+	if (spawnOutcome.kind !== "spawned") return spawnOutcome;
+	const { child } = spawnOutcome;
+	const until = Math.min(Date.now() + Math.max(1, options.deadlineAt - Date.now()), options.deadlineAt);
+	for (;;) {
+		if (spawnOutcome.spawnError())
+			return {
+				kind: "refused",
+				reason: "spawn_failed",
+				detail: spawnOutcome.spawnError()?.message,
+			};
+		if (child.exitCode !== null || child.signalCode !== null)
+			return { kind: "refused", reason: "spawn_exited_before_publication" };
+		const discovered = await readBrokerDiscovery(options.agentDir);
+		if (
+			discovered &&
+			discovered.packageGeneration === options.packageGeneration &&
+			discovered.restartRequestId === options.requestId
+		)
+			return { kind: "spawned", discovery: discovered };
+		if (Date.now() >= until) return { kind: "refused", reason: "publication_timeout" };
+		await Bun.sleep(SUCCESSOR_SPAWN_POLL_MS);
+	}
+}
+
+/**
+ * Positive OS-confirmed absence of the exact prior owner, distinguished from
+ * every merely-inconclusive outcome (permission denial, PID reuse ambiguity,
+ * missing native addon). Never treats a null/changed incarnation read alone as
+ * death proof; only `observeProcessIncarnation`'s `"absent"` status counts.
+ */
+export function oldOwnerConfirmedExited(pid: number): boolean {
+	return observeProcessIncarnation(pid).status === "absent";
+}