@gajae-code/coding-agent 0.11.0 → 0.11.2

package/src/sdk/broker/broker.ts

@@ -1,7 +1,12 @@
 import { createHash, randomBytes } from "node:crypto";
 import * as fs from "node:fs/promises";
 import path from "node:path";
-import { resolveResumableSession, SessionManager } from "../../session/session-manager";
+import type { NativeDirectoryTreeSnapshot } from "@gajae-code/natives";
+import {
+	type DirectoryMigrationPolicy,
+	listManagedSessionCandidates,
+	resolveManagedSessionScope,
+} from "../session-directory";
 import {
 	BROKER_HEARTBEAT_TTL_MS,
 	type BrokerDiscovery,
@@ -9,6 +14,7 @@ import {
 	brokerProcessIncarnation,
 	isPidAlive,
 	newBrokerToken,
+	type RedactedBrokerDiscovery,
 	readBrokerDiscovery,
 	redactBrokerDiscovery,
 	writeBrokerDiscovery,
@@ -20,6 +26,7 @@ import {
 	type LifecycleDurableEffectsReceipt,
 	LifecycleLedger,
 	type LifecycleStartupFailureReceipt,
+	type LifecycleState,
 } from "./lifecycle-ledger";
 import { type IndexedSession, SessionIndex } from "./session-index";
 import { BrokerTransport } from "./transport";
@@ -29,7 +36,18 @@ export interface BrokerSettings {
 	packageGeneration?: string;
 	port?: number;
 	heartbeatTtlMs?: number;
+	/** Broker-owned migration policy. Client lifecycle frames cannot select it. */
+	resolveDirectoryMigration?: (_cwd: string) => Promise<DirectoryMigrationPolicy>;
 }
+
+type ResolvedBrokerSettings = {
+	agentDir: string;
+	packageGeneration: string;
+	port: number;
+	heartbeatTtlMs: number;
+	resolveDirectoryMigration: (_cwd: string) => Promise<DirectoryMigrationPolicy>;
+};
+
 export type BrokerErrorCode =
 	| "idempotency_conflict"
 	| "terminal_uncertain"
@@ -46,10 +64,73 @@ export type BrokerErrorCode =
 	| "cleanup_pending"
 	| (string & {});
 
+export type BrokerCleanupIdentity = {
+	dev: string;
+	ino: string;
+	size: number;
+	mtimeNs: string;
+	sha256: string;
+};
+
+/** Exact retry evidence; detached paths are managed-receipt references, never caller authority. */
+export type BrokerLifecycleCleanupFile = {
+	/** Original lifecycle-owned path, retained only for exact identity validation. */
+	path: string;
+	identity: BrokerCleanupIdentity;
+	/** Monotonic append-only cleanup attempt. */
+	attempt?: number;
+	/** Immutable no-replace quarantine destination persisted before native detach. */
+	plannedPath: string;
+	/** Native-returned detached path, persisted after a failed post-detach cleanup. */
+	detachedPath?: string;
+	/** Append-only terminal proof for this exact artifact; completed entries are never retried. */
+	completed?: true;
+};
+
+/** Durable root-tree authority for broker artifact cleanup. */
+export type BrokerArtifactTree = {
+	identity: BrokerCleanupIdentity;
+	snapshot: NativeDirectoryTreeSnapshot;
+	plannedPath: string;
+	detachedPath?: string;
+	completed?: true;
+};
+
 export type BrokerCleanupEvidence = {
-	phase: "artifacts" | "transcript" | "metadata";
-	artifactsIdentity?: { dev: string; ino: string };
-	transcriptIdentity?: { dev: string; ino: string };
+	phase: "artifacts" | "transcript" | "metadata" | "lifecycle";
+	/** Ledger-bound deletion target; never reconstructed from a retry request. */
+	sessionsRoot?: string;
+	transcriptPath?: string;
+	cwd?: string;
+	metadataRoot?: string;
+	sessionId?: string;
+	artifactsIdentity?: BrokerCleanupIdentity;
+	transcriptIdentity?: BrokerCleanupIdentity;
+	/** Identity-bound lifecycle metadata marker retained when exact cleanup is deferred. */
+	metadataIdentity?: BrokerCleanupIdentity;
+	metadataPath?: string;
+	/** Monotonic append-only cleanup attempt. */
+	metadataAttempt?: number;
+	/** No-replace quarantine destination persisted before lifecycle metadata detach. */
+	plannedMetadataPath?: string;
+	/** Native-returned metadata quarantine path retained until identity-bound reconciliation succeeds. */
+	detachedMetadataPath?: string;
+	/** Append-only terminal proof for lifecycle metadata cleanup. */
+	metadataCompleted?: true;
+	detachedArtifactsPath?: string;
+	detachedTranscriptPath?: string;
+	/** Durable proof that artifact cleanup completed before transcript mutation. */
+	artifactsRemoved?: boolean;
+	/** Preauthorized no-replace artifact quarantine path persisted before detach. */
+	plannedArtifactsPath?: string;
+	/** Identity-bound artifact tree authority persisted before broker detach and replayed exactly. */
+	artifactTree?: BrokerArtifactTree;
+	/** Preauthorized no-replace transcript quarantine path persisted before detach. */
+	plannedTranscriptPath?: string;
+	/** Fully identity-bound startup-failure cleanup plan, persisted before any detach. */
+	lifecycleFiles?: BrokerLifecycleCleanupFile[];
+	/** Delete metadata receipts authorize only the canonical marker/ready sibling pair. */
+	lifecycleDeleteMetadata?: true;
 };
 export type BrokerResponse =
 	| { ok: true; result?: unknown; indexSeq?: number }
@@ -67,6 +148,16 @@ export type BrokerResponse =
 	  };
 const error = (code: BrokerErrorCode, message: string): BrokerResponse => ({ ok: false, error: { code, message } });
 
+function isCleanupPending(response: BrokerResponse): boolean {
+	return !response.ok && response.error.code === "cleanup_pending" && response.error.cleanup !== undefined;
+}
+
+function lifecycleResponseState(response: BrokerResponse): LifecycleState {
+	if (response.ok) return "terminal_ok";
+	if (isCleanupPending(response)) return "effect_started";
+	return response.error.code === "terminal_uncertain" ? "terminal_uncertain" : "terminal_error";
+}
+
 type InputNormalization = { input: Record<string, unknown> } | BrokerResponse;
 
 function isBrokerResponse(value: InputNormalization): value is BrokerResponse {
@@ -106,6 +197,8 @@ function normalizeBrokerInput(operation: string, input: Record<string, unknown>)
 		normalized.sourceSessionId = source.value;
 		delete normalized.sourceId;
 	}
+	if (input.directoryMigration !== undefined)
+		return error("invalid_input", "directoryMigration is broker-managed and cannot be selected by clients.");
 
 	if (operation === "session.list") {
 		const resolved = input.resolveSessionId;
@@ -272,7 +365,7 @@ type BrokerLockSnapshot = {
 const terminalPersistenceHooksForTest = new WeakMap<Broker, () => void>();
 
 export class Broker {
-	readonly settings: Required<BrokerSettings>;
+	readonly settings: ResolvedBrokerSettings;
 	readonly index: SessionIndex;
 	readonly ledger: LifecycleLedger;
 	discovery: BrokerDiscovery | null = null;
@@ -281,10 +374,16 @@ export class Broker {
 	#chains = new Map<string, Promise<void>>();
 	#stopping = false;
 	#transport: BrokerTransport | null = null;
-	#heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+	#heartbeatTimer: NodeJS.Timeout | null = null;
 	#heartbeatWrite: Promise<void> = Promise.resolve();
 	constructor(settings: BrokerSettings) {
-		this.settings = { packageGeneration: "unknown", port: 0, heartbeatTtlMs: BROKER_HEARTBEAT_TTL_MS, ...settings };
+		this.settings = {
+			agentDir: settings.agentDir,
+			packageGeneration: settings.packageGeneration ?? "unknown",
+			port: settings.port ?? 0,
+			heartbeatTtlMs: settings.heartbeatTtlMs ?? BROKER_HEARTBEAT_TTL_MS,
+			resolveDirectoryMigration: settings.resolveDirectoryMigration ?? (async () => "copy-retain"),
+		};
 		this.index = new SessionIndex(settings.agentDir);
 		this.ledger = new LifecycleLedger(settings.agentDir);
 		this.#lock = path.join(settings.agentDir, "sdk", "broker.lock");
@@ -379,13 +478,20 @@ export class Broker {
 			throw e;
 		}
 	}
+	async #releaseOwnedLock(): Promise<void> {
+		try {
+			const lock = await this.#readLock();
+			if (lock?.ownerId !== this.#owner) return;
+			await fs.unlink(this.#lockRecordPath());
+			await fs.rmdir(this.#lock);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		}
+	}
+
 	async start(): Promise<BrokerDiscovery> {
 		this.#stopping = false;
-		await Promise.all([
-			this.index.assertSupportedStateVersions(),
-			this.ledger.assertSupportedStateVersions(),
-			readBrokerDiscovery(this.settings.agentDir),
-		]);
+		await Promise.all([this.ledger.assertSupportedStateVersions(), readBrokerDiscovery(this.settings.agentDir)]);
 		await fs.mkdir(path.dirname(this.#lock), { recursive: true, mode: 0o700 });
 		for (;;) {
 			try {
@@ -415,39 +521,47 @@ export class Broker {
 			}
 			await this.#reclaimStaleLock(snapshot);
 		}
-		await this.index.open();
-		await this.ledger.open();
-		const now = Date.now();
-		const incarnation = brokerProcessIncarnation(process.pid);
-		if (!incarnation) throw new Error("Broker process incarnation is unavailable.");
-		const token = newBrokerToken();
-		this.#transport = new BrokerTransport(this, token, this.settings.port);
-		const port = await this.#transport.start();
-		this.discovery = {
-			version: 1,
-			protocolVersion: 3,
-			packageGeneration: this.settings.packageGeneration,
-			ownerId: this.#owner,
-			pid: process.pid,
-			incarnation,
-			host: "127.0.0.1",
-			port,
-			url: `ws://127.0.0.1:${port}`,
-			token,
-			startedAt: now,
-			heartbeatAt: now,
-		};
-		await writeBrokerDiscovery(this.settings.agentDir, this.discovery);
-		this.#heartbeatTimer = setInterval(
-			() => void this.heartbeat(),
-			Math.max(1, Math.floor(this.settings.heartbeatTtlMs / 3)),
-		);
-		return this.discovery;
+		try {
+			await this.index.open();
+			await this.ledger.open();
+			const now = Date.now();
+			const incarnation = brokerProcessIncarnation(process.pid);
+			if (!incarnation) throw new Error("Broker process incarnation is unavailable.");
+			const token = newBrokerToken();
+			this.#transport = new BrokerTransport(this, token, this.settings.port);
+			const port = await this.#transport.start();
+			this.discovery = {
+				version: 1,
+				protocolVersion: 3,
+				packageGeneration: this.settings.packageGeneration,
+				ownerId: this.#owner,
+				pid: process.pid,
+				incarnation,
+				host: "127.0.0.1",
+				port,
+				url: `ws://127.0.0.1:${port}`,
+				token,
+				startedAt: now,
+				heartbeatAt: now,
+			};
+			await writeBrokerDiscovery(this.settings.agentDir, this.discovery);
+			this.#heartbeatTimer = setInterval(
+				() => void this.heartbeat(),
+				Math.max(1, Math.floor(this.settings.heartbeatTtlMs / 3)),
+			);
+			return this.discovery;
+		} catch (error) {
+			await this.#transport?.stop();
+			this.#transport = null;
+			this.discovery = null;
+			await this.#releaseOwnedLock();
+			throw error;
+		}
 	}
 	get ownsDiscovery(): boolean {
 		return this.discovery?.ownerId === this.#owner;
 	}
-	status(): ReturnType<typeof redactBrokerDiscovery> | null {
+	status(): RedactedBrokerDiscovery | null {
 		return this.discovery ? redactBrokerDiscovery(this.discovery) : null;
 	}
 	async heartbeat(): Promise<void> {
@@ -476,15 +590,7 @@ export class Broker {
 			} catch (e) {
 				if ((e as NodeJS.ErrnoException).code !== "ENOENT") throw e;
 			}
-			try {
-				const lock = await this.#readLock();
-				if (lock?.ownerId === this.#owner) {
-					await fs.unlink(this.#lockRecordPath());
-					await fs.rmdir(this.#lock);
-				}
-			} catch (e) {
-				if ((e as NodeJS.ErrnoException).code !== "ENOENT") throw e;
-			}
+			await this.#releaseOwnedLock();
 		}
 		this.discovery = null;
 	}
@@ -543,15 +649,21 @@ export class Broker {
 			const resolveSessionId = typeof input.resolveSessionId === "string" ? input.resolveSessionId : undefined;
 			const cwd = typeof input.cwd === "string" ? input.cwd : undefined;
 			if (resolveSessionId && cwd) {
-				const sessionDir = SessionManager.getDefaultSessionDir(cwd, this.settings.agentDir);
-				const match = await resolveResumableSession(resolveSessionId, cwd, sessionDir);
+				const scope = await resolveManagedSessionScope({ cwd, agentDir: this.settings.agentDir });
+				const listed =
+					scope.kind === "resolved" ? await listManagedSessionCandidates({ scope: scope.scope }) : undefined;
+				const matches =
+					listed?.kind === "complete"
+						? listed.owned.filter(candidate => candidate.sessionId === resolveSessionId)
+						: [];
+				const match = matches.length === 1 ? matches[0] : undefined;
 				return {
 					ok: true,
 					result: {
 						...result,
 						savedSession:
-							match && match.session.id === resolveSessionId
-								? { id: match.session.id, path: match.session.path }
+							match && match.sessionId === resolveSessionId
+								? { id: match.sessionId, path: match.path }
 								: undefined,
 					},
 					indexSeq: result.indexSeq,
@@ -575,37 +687,53 @@ export class Broker {
 		);
 		await prev;
 		try {
+			const beforeBegin = this.ledger.get(identity);
 			const begun = await this.ledger.begin(identity, requestHash);
-			if (begun.kind === "replay") return begun.entry.response as BrokerResponse;
+			if (begun.kind === "replay") {
+				const replay = begun.entry.response as BrokerResponse;
+				if (!(!replay.ok && replay.error.cleanup)) return replay;
+				const cleanup = replay.error.cleanup;
+				const outcome = await executeLifecycle(this, operation, input, identity, cleanup);
+				const response = outcome.response;
+				await this.ledger.transition(identity, lifecycleResponseState(response), {
+					response,
+					responseDigest: createHash("sha256").update(canonicalJson(response)).digest("hex"),
+					...(outcome.durableEffects ? { durableEffects: outcome.durableEffects } : {}),
+					...(outcome.startupFailure ? { startupFailure: outcome.startupFailure } : {}),
+				});
+				return response;
+			}
 			if (begun.kind === "idempotency_conflict")
 				return error("idempotency_conflict", "idempotency key was used with a different request");
-			if (begun.kind === "terminal_uncertain")
-				return begun.entry.response
-					? (begun.entry.response as BrokerResponse)
-					: error("terminal_uncertain", "prior lifecycle operation outcome is uncertain");
-			if (begun.kind === "in_progress") return error("broker_restarting", "lifecycle operation is in progress");
-			const outcome = await executeLifecycle(this, operation, input, identity);
-			const response = outcome.response;
-			await this.ledger.transition(
-				identity,
-				response.ok
-					? "terminal_ok"
-					: response.error.code === "terminal_uncertain"
-						? "terminal_uncertain"
-						: "terminal_error",
-				{
-					resultSessionId:
-						response.ok && typeof (response.result as { sessionId?: unknown } | undefined)?.sessionId === "string"
-							? (response.result as { sessionId: string }).sessionId
-							: undefined,
+			if (begun.kind === "terminal_uncertain") {
+				const replay = (begun.entry.response ?? beforeBegin?.response) as BrokerResponse | undefined;
+				if (!replay || replay.ok || !replay.error.cleanup)
+					return replay ?? error("terminal_uncertain", "prior lifecycle operation outcome is uncertain");
+				const outcome = await executeLifecycle(this, operation, input, identity, replay.error.cleanup);
+				const response = outcome.response;
+				await this.ledger.transition(identity, lifecycleResponseState(response), {
 					response,
 					responseDigest: createHash("sha256").update(canonicalJson(response)).digest("hex"),
 					...(outcome.durableEffects ? { durableEffects: outcome.durableEffects } : {}),
 					...(outcome.startupFailure ? { startupFailure: outcome.startupFailure } : {}),
-				},
-			);
-			const reopenedLedger = await new LifecycleLedger(this.settings.agentDir).open();
-			const persisted = reopenedLedger.get(identity);
+				});
+				return response;
+			}
+			if (begun.kind === "in_progress") return error("broker_restarting", "lifecycle operation is in progress");
+			const outcome = await executeLifecycle(this, operation, input, identity);
+			const response = outcome.response;
+			await this.ledger.transition(identity, lifecycleResponseState(response), {
+				resultSessionId:
+					response.ok && typeof (response.result as { sessionId?: unknown } | undefined)?.sessionId === "string"
+						? (response.result as { sessionId: string }).sessionId
+						: undefined,
+				response,
+				responseDigest: createHash("sha256").update(canonicalJson(response)).digest("hex"),
+				...(outcome.durableEffects ? { durableEffects: outcome.durableEffects } : {}),
+				...(outcome.startupFailure ? { startupFailure: outcome.startupFailure } : {}),
+			});
+			if (isCleanupPending(response)) return response;
+			const persisted = await this.ledger.readTerminal(identity, requestHash);
 			const expectedResponseDigest = createHash("sha256").update(canonicalJson(response)).digest("hex");
 			const persistenceVerified =
 				persisted?.responseDigest === expectedResponseDigest &&

package/src/sdk/broker/discovery.ts

@@ -33,13 +33,32 @@ export function isPidAlive(pid: number): boolean {
 	}
 }
 async function syncFile(file: string): Promise<void> {
-	const handle = await fs.open(file, "r");
+	const handle = await fs.open(file, "r+");
 	try {
 		await handle.sync();
 	} finally {
 		await handle.close();
 	}
 }
+
+async function syncDirectory(directory: string): Promise<void> {
+	let handle: fs.FileHandle;
+	try {
+		handle = await fs.open(directory, "r");
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (process.platform === "win32" && (code === "EPERM" || code === "EACCES")) return;
+		throw error;
+	}
+	try {
+		await handle.sync();
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (process.platform !== "win32" || (code !== "EPERM" && code !== "EACCES")) throw error;
+	} finally {
+		await handle.close();
+	}
+}
 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}.`);
@@ -54,7 +73,7 @@ export async function writeBrokerDiscovery(agentDir: string, discovery: BrokerDi
 		await fs.chmod(temp, 0o600);
 		await syncFile(temp);
 		await fs.rename(temp, file);
-		await syncFile(dir);
+		await syncDirectory(dir);
 	} finally {
 		await fs.rm(temp, { force: true });
 	}

package/src/sdk/broker/ensure.ts

@@ -13,17 +13,38 @@ export interface EnsureBrokerSettings {
 }
 
 const DISCOVERY_TIMEOUT_MS = 10_000;
+const FIXTURE_DISCOVERY_TIMEOUT_MS = 30_000;
 // Bounded grace windows for reaping a spawned broker on failure, mirroring the
 // owned-process teardown convention (SIGTERM -> grace -> SIGKILL -> hard cap).
 const REAP_GRACEFUL_MS = 2_000;
 const REAP_SIGKILL_CAP_MS = 2_000;
+export interface FixtureBrokerLease {
+	close(): Promise<void>;
+}
+
+export interface StartedFixtureBroker {
+	discovery: BrokerDiscovery;
+	lease: FixtureBrokerLease;
+}
+
 interface BrokerOwner {
 	stop(): Promise<void>;
 	canReuse(discovery: BrokerDiscovery | null): boolean;
 	markReady(discovery: BrokerDiscovery): boolean;
 }
+type EnsureInitiator = "discovery" | "fixture-lease";
+type EnsureOutcome =
+	| { kind: "external-discovery"; discovery: BrokerDiscovery }
+	| { kind: "prior-local-owner"; discovery: BrokerDiscovery; owner: BrokerOwner }
+	| { kind: "local-started-discovery"; discovery: BrokerDiscovery }
+	| { kind: "local-started-fixture"; discovery: BrokerDiscovery; owner: BrokerOwner };
+interface EnsureInFlight {
+	initiator: EnsureInitiator;
+	promise: Promise<EnsureOutcome>;
+	discovery: Promise<BrokerDiscovery>;
+}
 const owners = new Map<string, BrokerOwner>();
-const ensureInFlight = new Map<string, Promise<BrokerDiscovery>>();
+const ensureInFlight = new Map<string, EnsureInFlight>();
 const reapErrorGuards = new WeakSet<ChildProcess>();
 interface ReapTiming {
 	gracefulMs: number;
@@ -142,18 +163,44 @@ function brokerSpawnEnvironment(command: SdkInternalSpawnCommand, override?: Nod
 	return environment;
 }
 
-async function ensureBrokerOnce(settings: EnsureBrokerSettings): Promise<BrokerDiscovery> {
+function fixtureLeaseUnavailable(): Error {
+	return new Error("fixture_broker_lease_unavailable");
+}
+
+function createFixtureLease(owner: BrokerOwner): FixtureBrokerLease {
+	let closeAttempt: Promise<void> | undefined;
+	let closed = false;
+	return {
+		close(): Promise<void> {
+			if (closed) return Promise.resolve();
+			if (closeAttempt) return closeAttempt;
+			closeAttempt = owner.stop().then(
+				() => {
+					closed = true;
+				},
+				(error: unknown) => {
+					closeAttempt = undefined;
+					throw error;
+				},
+			);
+			return closeAttempt;
+		},
+	};
+}
+
+async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: EnsureInitiator): Promise<EnsureOutcome> {
 	const priorOwner = owners.get(settings.agentDir);
 	const existing = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
+	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 existing!;
+		if (priorOwner.canReuse(existing)) return { kind: "prior-local-owner", discovery: existing!, owner: priorOwner };
 		await priorOwner.stop();
 		const discoveredAfterCleanup = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
-		if (discoveredAfterCleanup) return discoveredAfterCleanup;
+		if (discoveredAfterCleanup) return { kind: "external-discovery", discovery: discoveredAfterCleanup };
 	} else if (existing) {
-		return existing;
+		return { kind: "external-discovery", discovery: existing };
 	}
 
 	const command = resolveSdkInternalSpawnCommand("broker-internal");
@@ -169,30 +216,27 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings): Promise<BrokerD
 		spawnError = error;
 	});
 	const owner = registerBrokerOwner(settings.agentDir, child);
-	const deadline = Date.now() + DISCOVERY_TIMEOUT_MS;
+	const discoveryTimeoutMs = initiator === "fixture-lease" ? FIXTURE_DISCOVERY_TIMEOUT_MS : DISCOVERY_TIMEOUT_MS;
+	const deadline = Date.now() + discoveryTimeoutMs;
 	let discoveryError: unknown;
 	while (Date.now() < deadline) {
-		// Fail fast: if the spawn failed or the child already exited, discovery can
-		// never succeed — stop (a no-op once dead) and surface the failure instead
-		// of running out the discovery timeout with an orphaned child.
 		if (spawnError || child.exitCode !== null || child.signalCode !== null) break;
 		try {
 			const discovered = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
 			if (discovered) {
-				if (owner.markReady(discovered)) return discovered;
+				if (owner.markReady(discovered)) {
+					return initiator === "fixture-lease"
+						? { kind: "local-started-fixture", discovery: discovered, owner }
+						: { kind: "local-started-discovery", discovery: discovered };
+				}
 				await owner.stop();
-				return discovered;
+				return { kind: "external-discovery", discovery: discovered };
 			}
 		} catch (error) {
-			// A transient read failure (e.g. a half-written record) must not orphan the
-			// child; remember it and keep polling. It is surfaced if discovery fails.
 			discoveryError = error;
 		}
 		await sleep(50);
 	}
-	// Discovery failed (timeout, early child exit, spawn error, or unreadable
-	// discovery): the spawned broker never became reachable. Terminate and reap it
-	// so the failure cannot leave a detached orphan behind, then surface why.
 	const exitedBeforeDiscovery = child.exitCode !== null || child.signalCode !== null;
 	const failure = spawnError
 		? new Error(`Failed to spawn detached SDK broker: ${spawnError.message}`)
@@ -211,17 +255,33 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings): Promise<BrokerD
 	throw failure;
 }
 
-/** Starts the detached broker entrypoint when discovery has no live owner. */
-export function ensureBroker(settings: EnsureBrokerSettings): Promise<BrokerDiscovery> {
-	const existing = ensureInFlight.get(settings.agentDir);
-	if (existing) return existing;
-	const pending = ensureBrokerOnce(settings);
-	ensureInFlight.set(settings.agentDir, pending);
+function startEnsure(settings: EnsureBrokerSettings, initiator: EnsureInitiator): EnsureInFlight {
+	const promise = ensureBrokerOnce(settings, initiator);
+	const discovery = promise.then(outcome => outcome.discovery);
+	void discovery.catch(() => {});
+	const entry = { initiator, promise, discovery };
+	ensureInFlight.set(settings.agentDir, entry);
 	const clear = (): void => {
-		if (ensureInFlight.get(settings.agentDir) === pending) ensureInFlight.delete(settings.agentDir);
+		if (ensureInFlight.get(settings.agentDir) === entry) ensureInFlight.delete(settings.agentDir);
 	};
-	void pending.then(clear, clear);
-	return pending;
+	void promise.then(clear, clear);
+	return entry;
+}
+
+/** Starts the detached broker entrypoint when discovery has no live owner. */
+export function ensureBroker(settings: EnsureBrokerSettings): Promise<BrokerDiscovery> {
+	const inFlight = ensureInFlight.get(settings.agentDir) ?? startEnsure(settings, "discovery");
+	return inFlight.discovery;
+}
+
+/** Starts one fresh fixture broker and returns its sole exact-child close lease. */
+export function startFixtureBrokerWithLeaseForTest(settings: EnsureBrokerSettings): Promise<StartedFixtureBroker> {
+	if (ensureInFlight.has(settings.agentDir)) return Promise.reject(fixtureLeaseUnavailable());
+	const inFlight = startEnsure(settings, "fixture-lease");
+	return inFlight.promise.then(outcome => {
+		if (outcome.kind !== "local-started-fixture") throw fixtureLeaseUnavailable();
+		return { discovery: outcome.discovery, lease: createFixtureLease(outcome.owner) };
+	});
 }
 
 /** Test hook: returns a stop handle for the detached broker this process spawned. */

package/src/sdk/broker/lifecycle-codec.ts

@@ -0,0 +1,11 @@
+const lifecycleUtf8Decoder = new TextDecoder("utf-8", { fatal: true });
+
+/** Decodes persisted lifecycle bytes without replacement characters before JSON parsing. */
+export function decodeLifecycleUtf8(bytes: Uint8Array): string {
+	return lifecycleUtf8Decoder.decode(bytes);
+}
+
+/** Parses persisted lifecycle JSON only after fatal UTF-8 decoding. */
+export function parseLifecycleJson(bytes: Uint8Array): unknown {
+	return JSON.parse(decodeLifecycleUtf8(bytes));
+}