@gajae-code/coding-agent 0.11.2 → 0.11.4

package/src/modes/interactive-mode.ts

@@ -62,6 +62,7 @@ import {
 } from "./components/pet-capability";
 import type { ToolExecutionHandle } from "./components/tool-execution";
 import { StatusLineComponent } from "./components/tool-status-header";
+import { composeToolText } from "./components/tool-transcript-format";
 import {
 	WelcomeComponent,
 	type WelcomeLogoMode,
@@ -1817,17 +1818,27 @@ export class InteractiveMode implements InteractiveModeContext {
 						result?.content
 							.filter(part => part.type === "text")
 							.map(part => part.text)
-							.join("\n") ?? "";
+							.join("\n")
+							.trim() ?? "";
 					items.push({
 						kind: "tool",
 						source: { toolCallId: content.id, content, result },
 						getPayload: () => ({
-							text: resultText || JSON.stringify(content.arguments, null, 2),
+							text: composeToolText({
+								name: content.name,
+								args: content.arguments,
+								intent: content.intent,
+								resultText,
+								isError: result?.isError ?? false,
+								hasResult: toolResults.has(content.id),
+							}),
 							metadata: {
 								name: content.name,
 								arguments: content.arguments,
 								intent: content.intent,
 								isError: result?.isError ?? false,
+								resultText,
+								hasResult: toolResults.has(content.id),
 							},
 							source: { content, result },
 						}),

package/src/modes/prompt-action-autocomplete.ts

@@ -248,6 +248,13 @@ export class PromptActionAutocompleteProvider implements AutocompleteProvider {
 
 		return this.#baseProvider.getSuggestions(lines, cursorLine, cursorCol);
 	}
+	getForceFileSuggestions(
+		lines: string[],
+		cursorLine: number,
+		cursorCol: number,
+	): Promise<{ items: AutocompleteItem[]; prefix: string } | null> {
+		return this.#baseProvider.getForceFileSuggestions(lines, cursorLine, cursorCol);
+	}
 
 	applyCompletion(
 		lines: string[],

package/src/sdk/broker/broker.ts

@@ -12,12 +12,14 @@ import {
 	type BrokerDiscovery,
 	brokerDiscoveryPath,
 	brokerProcessIncarnation,
+	heartbeatBrokerDiscoveryRetained,
 	isPidAlive,
 	newBrokerToken,
+	publishBrokerDiscovery,
 	type RedactedBrokerDiscovery,
+	type RetainedBrokerDiscovery,
 	readBrokerDiscovery,
 	redactBrokerDiscovery,
-	writeBrokerDiscovery,
 } from "./discovery";
 import { deriveIdempotencyIdentity } from "./identity";
 import { executeLifecycle, isCanonicalSessionId } from "./lifecycle";
@@ -362,6 +364,17 @@ type BrokerLockSnapshot = {
 	identity: string;
 };
 
+const BROKER_PUBLICATION_CADENCE_MS = 5_000;
+const BROKER_PUBLICATION_GRACE_MS = 15_000;
+const BROKER_SETTLEMENT_MS = 2_000;
+type BrokerPublicationState =
+	| "healthy-owned"
+	| "suspect-unpublished"
+	| "observation-ambiguous"
+	| "heartbeat-ambiguous"
+	| "stopping";
+type BrokerStopMode = "owned-root" | "lost-root";
+
 const terminalPersistenceHooksForTest = new WeakMap<Broker, () => void>();
 
 export class Broker {
@@ -372,10 +385,17 @@ export class Broker {
 	#lock: string;
 	#owner = randomBytes(12).toString("hex");
 	#chains = new Map<string, Promise<void>>();
+	#admitted = new Set<Promise<void>>();
+	#publication: RetainedBrokerDiscovery | null = null;
+	#publicationState: BrokerPublicationState = "healthy-owned";
+	#lossAt: bigint | null = null;
 	#stopping = false;
 	#transport: BrokerTransport | null = null;
 	#heartbeatTimer: NodeJS.Timeout | null = null;
-	#heartbeatWrite: Promise<void> = Promise.resolve();
+	#completionTask: Promise<void> | null = null;
+	#completion!: Promise<void>;
+	#resolveCompletion!: () => void;
+	#rejectCompletion!: (error: unknown) => void;
 	constructor(settings: BrokerSettings) {
 		this.settings = {
 			agentDir: settings.agentDir,
@@ -387,6 +407,10 @@ export class Broker {
 		this.index = new SessionIndex(settings.agentDir);
 		this.ledger = new LifecycleLedger(settings.agentDir);
 		this.#lock = path.join(settings.agentDir, "sdk", "broker.lock");
+		const completion = Promise.withResolvers<void>();
+		this.#completion = completion.promise;
+		this.#resolveCompletion = completion.resolve;
+		this.#rejectCompletion = completion.reject;
 	}
 	#lockRecordPath(): string {
 		return path.join(this.#lock, BROKER_LOCK_RECORD);
@@ -490,7 +514,17 @@ export class Broker {
 	}
 
 	async start(): Promise<BrokerDiscovery> {
+		if (this.#completionTask) {
+			await this.#completionTask;
+			const completion = Promise.withResolvers<void>();
+			this.#completion = completion.promise;
+			this.#resolveCompletion = completion.resolve;
+			this.#rejectCompletion = completion.reject;
+			this.#completionTask = null;
+		}
 		this.#stopping = false;
+		this.#publicationState = "healthy-owned";
+		this.#lossAt = null;
 		await Promise.all([this.ledger.assertSupportedStateVersions(), readBrokerDiscovery(this.settings.agentDir)]);
 		await fs.mkdir(path.dirname(this.#lock), { recursive: true, mode: 0o700 });
 		for (;;) {
@@ -544,15 +578,19 @@ export class Broker {
 				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)),
+			this.#publication = await publishBrokerDiscovery(this.settings.agentDir, this.discovery);
+			this.#publicationState = "healthy-owned";
+			const cadenceMs = Math.max(
+				10,
+				Math.min(BROKER_PUBLICATION_CADENCE_MS, Math.floor(this.settings.heartbeatTtlMs / 3)),
 			);
+			this.#heartbeatTimer = setInterval(() => void this.#watchPublication(), cadenceMs);
 			return this.discovery;
 		} catch (error) {
 			await this.#transport?.stop();
 			this.#transport = null;
+			this.#publication?.close();
+			this.#publication = null;
 			this.discovery = null;
 			await this.#releaseOwnedLock();
 			throw error;
@@ -561,38 +599,96 @@ export class Broker {
 	get ownsDiscovery(): boolean {
 		return this.discovery?.ownerId === this.#owner;
 	}
+	get completion(): Promise<void> {
+		return this.#completion;
+	}
 	status(): RedactedBrokerDiscovery | null {
 		return this.discovery ? redactBrokerDiscovery(this.discovery) : null;
 	}
-	async heartbeat(): Promise<void> {
-		if (!this.discovery || this.discovery.ownerId !== this.#owner) return;
-		this.discovery = { ...this.discovery, heartbeatAt: Date.now() };
-		const discovery = this.discovery;
-		this.#heartbeatWrite = this.#heartbeatWrite.then(() => writeBrokerDiscovery(this.settings.agentDir, discovery));
-		await this.#heartbeatWrite;
+	#fence(kind: "suspect-unpublished" | "observation-ambiguous" | "heartbeat-ambiguous"): void {
+		if (this.#publicationState === "stopping") return;
+		this.#publicationState = kind;
+		if (kind === "suspect-unpublished") this.#lossAt ??= process.hrtime.bigint();
+		else this.#lossAt = null;
 	}
-	async stop(): Promise<void> {
-		this.#stopping = true;
-		if (this.#heartbeatTimer) {
-			clearInterval(this.#heartbeatTimer);
-			this.#heartbeatTimer = null;
+	async #watchPublication(writeHeartbeat = true): Promise<void> {
+		if (!this.#publication || this.#publicationState === "stopping") return;
+		let observation: ReturnType<RetainedBrokerDiscovery["observe"]>;
+		try {
+			observation = this.#publication.observe();
+		} catch {
+			this.#fence("observation-ambiguous");
+			return;
 		}
-		await this.#heartbeatWrite;
-		await Promise.allSettled(this.#chains.values());
-		await this.#transport?.stop();
-		this.#transport = null;
-		if (this.discovery?.ownerId === this.#owner) {
-			try {
-				const disk = JSON.parse(await fs.readFile(brokerDiscoveryPath(this.settings.agentDir), "utf8")) as {
-					ownerId?: string;
-				};
-				if (disk.ownerId === this.#owner) await fs.unlink(brokerDiscoveryPath(this.settings.agentDir));
-			} catch (e) {
-				if ((e as NodeJS.ErrnoException).code !== "ENOENT") throw e;
+		if (observation === "owned") {
+			if (this.#publicationState === "heartbeat-ambiguous") {
+				if (writeHeartbeat) await this.#writeHeartbeat();
+				return;
 			}
-			await this.#releaseOwnedLock();
+			this.#publicationState = "healthy-owned";
+			this.#lossAt = null;
+			if (writeHeartbeat) await this.#writeHeartbeat();
+			return;
+		}
+		this.#fence(observation === "ambiguous" ? "observation-ambiguous" : "suspect-unpublished");
+		if (
+			this.#lossAt !== null &&
+			process.hrtime.bigint() - this.#lossAt >= BigInt(BROKER_PUBLICATION_GRACE_MS) * 1_000_000n
+		)
+			void this.#complete("lost-root");
+	}
+	async #writeHeartbeat(): Promise<void> {
+		if (!this.discovery || !this.#publication || this.#publicationState === "stopping") return;
+		const heartbeatAt = Date.now();
+		try {
+			if (!(await heartbeatBrokerDiscoveryRetained(this.#publication, heartbeatAt))) {
+				this.#fence("heartbeat-ambiguous");
+				return;
+			}
+		} catch {
+			this.#fence("heartbeat-ambiguous");
+			return;
 		}
-		this.discovery = null;
+		this.#publicationState = "healthy-owned";
+		this.#lossAt = null;
+		this.discovery = { ...this.discovery, heartbeatAt };
+	}
+	async heartbeat(): Promise<void> {
+		if (this.#publicationState !== "healthy-owned") return;
+		await this.#writeHeartbeat();
+	}
+	async #complete(mode: BrokerStopMode): Promise<void> {
+		if (this.#completionTask) return this.#completionTask;
+		this.#stopping = true;
+		this.#publicationState = "stopping";
+		if (this.#heartbeatTimer) clearInterval(this.#heartbeatTimer);
+		this.#heartbeatTimer = null;
+		this.#completionTask = (async () => {
+			await this.#transport?.stop();
+			this.#transport = null;
+			if (mode === "lost-root")
+				await Promise.race([Promise.allSettled(this.#admitted), Bun.sleep(BROKER_SETTLEMENT_MS)]);
+			else await Promise.allSettled(this.#admitted);
+			this.#publication?.close();
+			this.#publication = null;
+			if (mode === "owned-root" && this.discovery?.ownerId === this.#owner) {
+				try {
+					const disk = JSON.parse(await fs.readFile(brokerDiscoveryPath(this.settings.agentDir), "utf8")) as {
+						ownerId?: string;
+					};
+					if (disk.ownerId === this.#owner) await fs.unlink(brokerDiscoveryPath(this.settings.agentDir));
+				} catch (e) {
+					if ((e as NodeJS.ErrnoException).code !== "ENOENT") throw e;
+				}
+				await this.#releaseOwnedLock();
+			}
+			this.discovery = null;
+		})();
+		void this.#completionTask.then(this.#resolveCompletion, this.#rejectCompletion);
+		return this.#completionTask;
+	}
+	async stop(): Promise<void> {
+		await this.#complete("owned-root");
 	}
 	async #endpoint(input: Record<string, unknown>): Promise<BrokerResponse> {
 		const sessionId = input.sessionId;
@@ -634,7 +730,18 @@ export class Broker {
 			throw e;
 		}
 	}
-	async handleRequest(
+	handleRequest(operation: string, input: Record<string, unknown>, idempotencyKey?: string): Promise<BrokerResponse> {
+		if (this.#stopping || (this.#publication !== null && this.#publicationState !== "healthy-owned"))
+			return Promise.resolve(error("unavailable", "broker publication is unavailable"));
+		let release!: () => void;
+		const admission = new Promise<void>(resolve => (release = resolve));
+		this.#admitted.add(admission);
+		return this.#handleRequest(operation, input, idempotencyKey).finally(() => {
+			release();
+			this.#admitted.delete(admission);
+		});
+	}
+	async #handleRequest(
 		operation: string,
 		input: Record<string, unknown>,
 		idempotencyKey?: string,

package/src/sdk/broker/discovery.ts

@@ -1,9 +1,97 @@
 import { randomBytes } from "node:crypto";
 import * as fs from "node:fs/promises";
 import path from "node:path";
+import { type NativeRetainedBrokerPublication, retainBrokerPublication } from "@gajae-code/natives";
 import { processIncarnation } from "./process-incarnation";
 import { assertSupportedStateVersion, SDK_STATE_VERSION } from "./state-version";
 
+export type BrokerPublicationObservation = "owned" | "absent" | "replaced" | "ambiguous";
+export interface RetainedBrokerDiscovery {
+	observe(): BrokerPublicationObservation;
+	heartbeat(heartbeatAt: number): Promise<boolean>;
+	close(): void;
+}
+
+function requireRetainedBrokerPublication(agentDir: string): NativeRetainedBrokerPublication {
+	if (typeof retainBrokerPublication !== "function") {
+		throw new Error("Loaded native bindings do not expose retained broker publication authority.");
+	}
+	return retainBrokerPublication(agentDir);
+}
+
+async function rollbackPublishedBrokerDiscovery(agentDir: string, discovery: BrokerDiscovery): Promise<void> {
+	const file = brokerDiscoveryPath(agentDir);
+	try {
+		const raw: unknown = JSON.parse(await fs.readFile(file, "utf8"));
+		if (
+			!raw ||
+			typeof raw !== "object" ||
+			(raw as BrokerDiscovery).ownerId !== discovery.ownerId ||
+			(raw as BrokerDiscovery).pid !== discovery.pid ||
+			(raw as BrokerDiscovery).incarnation !== discovery.incarnation ||
+			(raw as BrokerDiscovery).token !== discovery.token ||
+			(raw as BrokerDiscovery).startedAt !== discovery.startedAt ||
+			(raw as BrokerDiscovery).heartbeatAt !== discovery.heartbeatAt
+		)
+			return;
+		await fs.unlink(file);
+		await syncDirectory(path.dirname(file));
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+}
+
+class NativeRetainedBrokerDiscovery implements RetainedBrokerDiscovery {
+	#closed = false;
+	#publication: NativeRetainedBrokerPublication;
+	constructor(publication: NativeRetainedBrokerPublication) {
+		this.#publication = publication;
+	}
+	observe(): BrokerPublicationObservation {
+		if (this.#closed) return "ambiguous";
+		const kind = this.#publication.observe().kind;
+		return kind === "owned" || kind === "absent" || kind === "replaced" || kind === "ambiguous" ? kind : "ambiguous";
+	}
+	async heartbeat(heartbeatAt: number): Promise<boolean> {
+		if (this.#closed || !isFixedWidthHeartbeat(heartbeatAt)) return false;
+		const write = this.#publication.heartbeat(String(heartbeatAt));
+		if (write.kind !== "written") return false;
+		return this.#publication.sync().kind === "synced";
+	}
+	close(): void {
+		if (this.#closed) return;
+		this.#closed = true;
+		this.#publication.close();
+	}
+}
+
+class LegacyWindowsBrokerDiscovery implements RetainedBrokerDiscovery {
+	#closed = false;
+	#discovery: BrokerDiscovery;
+	#agentDir: string;
+	constructor(agentDir: string, discovery: BrokerDiscovery) {
+		this.#agentDir = agentDir;
+		this.#discovery = discovery;
+	}
+	observe(): BrokerPublicationObservation {
+		return this.#closed ? "ambiguous" : "owned";
+	}
+	async heartbeat(heartbeatAt: number): Promise<boolean> {
+		if (this.#closed || !isFixedWidthHeartbeat(heartbeatAt)) return false;
+		const next = { ...this.#discovery, heartbeatAt };
+		await writeBrokerDiscovery(this.#agentDir, next);
+		this.#discovery = next;
+		return true;
+	}
+	close(): void {
+		this.#closed = true;
+	}
+}
+
+function isFixedWidthHeartbeat(value: number): boolean {
+	return Number.isSafeInteger(value) && value >= 1_000_000_000_000 && value <= 9_999_999_999_999;
+}
+
 export const BROKER_HEARTBEAT_TTL_MS = 15_000;
 export interface BrokerDiscovery {
 	version: typeof SDK_STATE_VERSION;
@@ -63,6 +151,9 @@ export async function writeBrokerDiscovery(agentDir: string, discovery: BrokerDi
 	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.");
+	}
 	const file = brokerDiscoveryPath(agentDir);
 	const dir = path.dirname(file);
 	await fs.mkdir(dir, { recursive: true, mode: 0o700 });
@@ -78,6 +169,40 @@ export async function writeBrokerDiscovery(agentDir: string, discovery: BrokerDi
 		await fs.rm(temp, { force: true });
 	}
 }
+
+/** Publish once by name, then retain no-follow native authority for recurring heartbeats. */
+export async function publishBrokerDiscovery(
+	agentDir: string,
+	discovery: BrokerDiscoveryWrite,
+	platform: NodeJS.Platform = process.platform,
+): 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);
+	if (platform === "win32") return new LegacyWindowsBrokerDiscovery(agentDir, published);
+	try {
+		return new NativeRetainedBrokerDiscovery(requireRetainedBrokerPublication(agentDir));
+	} catch (error) {
+		try {
+			await rollbackPublishedBrokerDiscovery(agentDir, published);
+		} catch (rollbackError) {
+			throw new AggregateError(
+				[error, rollbackError],
+				"Broker publication authority acquisition and exact rollback both failed.",
+			);
+		}
+		throw error;
+	}
+}
+
+/** Heartbeat through retained authority, or the explicit Windows compatibility path. */
+export function heartbeatBrokerDiscoveryRetained(
+	publication: RetainedBrokerDiscovery,
+	heartbeatAt: number,
+): Promise<boolean> {
+	return publication.heartbeat(heartbeatAt);
+}
 export async function readBrokerDiscovery(
 	agentDir: string,
 	ttlMs = BROKER_HEARTBEAT_TTL_MS,

package/src/sdk/broker/ensure.ts

@@ -19,12 +19,32 @@ const FIXTURE_DISCOVERY_TIMEOUT_MS = 30_000;
 const REAP_GRACEFUL_MS = 2_000;
 const REAP_SIGKILL_CAP_MS = 2_000;
 export interface FixtureBrokerLease {
+	/** Backward-compatible fixture cleanup alias for exact child termination. */
 	close(): Promise<void>;
 }
 
+export interface ExactFixtureBrokerLease extends FixtureBrokerLease {
+	/** Observes the retained child only; it never signals a process. */
+	waitForExit(timeoutMs: number): Promise<boolean>;
+	/** Signals only the retained ChildProcess, never a discovery-derived PID. */
+	terminateExactChild(): Promise<void>;
+}
+
+export interface FixtureBrokerCommand {
+	file: string;
+	args: readonly string[];
+	cwd?: string;
+	env?: NodeJS.ProcessEnv;
+}
+
+export interface StartedFixtureBrokerCommand {
+	lease: ExactFixtureBrokerLease;
+	control: NodeJS.WritableStream;
+}
+
 export interface StartedFixtureBroker {
 	discovery: BrokerDiscovery;
-	lease: FixtureBrokerLease;
+	lease: ExactFixtureBrokerLease;
 }
 
 interface BrokerOwner {
@@ -37,7 +57,7 @@ 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 };
+	| { kind: "local-started-fixture"; discovery: BrokerDiscovery; owner: BrokerOwner; child: ChildProcess };
 interface EnsureInFlight {
 	initiator: EnsureInitiator;
 	promise: Promise<EnsureOutcome>;
@@ -167,27 +187,48 @@ function fixtureLeaseUnavailable(): Error {
 	return new Error("fixture_broker_lease_unavailable");
 }
 
-function createFixtureLease(owner: BrokerOwner): FixtureBrokerLease {
-	let closeAttempt: Promise<void> | undefined;
-	let closed = false;
+function createFixtureLeaseFromChild(child: ChildProcess, terminate: () => Promise<void>): ExactFixtureBrokerLease {
+	let termination: Promise<void> | undefined;
+	const hasExited = (): boolean => child.exitCode !== null || child.signalCode !== null || child.pid === undefined;
+	const waitForExit = (timeoutMs: number): Promise<boolean> => {
+		if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 0)
+			return Promise.reject(new Error("Invalid fixture broker exit timeout."));
+		if (hasExited()) return Promise.resolve(true);
+		return new Promise(resolve => {
+			let settled = false;
+			let timer: ReturnType<typeof setTimeout> | undefined;
+			const onExit = (): void => finish(true);
+			const finish = (exited: boolean): void => {
+				if (settled) return;
+				settled = true;
+				if (timer) clearTimeout(timer);
+				child.off("exit", onExit);
+				child.off("close", onExit);
+				resolve(exited && hasExited());
+			};
+			timer = setTimeout(() => finish(false), timeoutMs);
+			child.once("exit", onExit);
+			child.once("close", onExit);
+			if (hasExited()) finish(true);
+		});
+	};
 	return {
+		waitForExit,
+		terminateExactChild(): Promise<void> {
+			if (!termination) termination = terminate();
+			return termination;
+		},
 		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;
+			if (!termination) termination = terminate();
+			return termination;
 		},
 	};
 }
 
+function createFixtureLease(owner: BrokerOwner, child: ChildProcess): ExactFixtureBrokerLease {
+	return createFixtureLeaseFromChild(child, () => owner.stop());
+}
+
 async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: EnsureInitiator): Promise<EnsureOutcome> {
 	const priorOwner = owners.get(settings.agentDir);
 	const existing = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
@@ -226,7 +267,7 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 			if (discovered) {
 				if (owner.markReady(discovered)) {
 					return initiator === "fixture-lease"
-						? { kind: "local-started-fixture", discovery: discovered, owner }
+						? { kind: "local-started-fixture", discovery: discovered, owner, child }
 						: { kind: "local-started-discovery", discovery: discovered };
 				}
 				await owner.stop();
@@ -280,10 +321,53 @@ export function startFixtureBrokerWithLeaseForTest(settings: EnsureBrokerSetting
 	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) };
+		return { discovery: outcome.discovery, lease: createFixtureLease(outcome.owner, outcome.child) };
 	});
 }
 
+/**
+ * Test-only launch surface for topology fixtures. It accepts an already-resolved
+ * command and retains the exact spawned child; no production selection path
+ * reaches this function.
+ */
+export function startFixtureBrokerCommandWithLeaseForTest(command: FixtureBrokerCommand): StartedFixtureBrokerCommand {
+	if (!command.file || !Array.isArray(command.args)) throw new Error("Invalid fixture broker command.");
+	const child = spawn(command.file, [...command.args], {
+		cwd: command.cwd,
+		detached: true,
+		stdio: ["ignore", "ignore", "ignore", "pipe"],
+		env: command.env,
+	});
+	child.unref();
+	let spawnError: Error | undefined;
+	child.once("error", error => {
+		spawnError = error;
+	});
+	const control = child.stdio[3];
+	if (!control || typeof (control as NodeJS.WritableStream).write !== "function") {
+		try {
+			if (!child.kill("SIGKILL"))
+				throw new Error(
+					"Fixture broker fd 3 is unavailable and the exact child could not be synchronously terminated.",
+				);
+		} catch (reapError) {
+			throw new AggregateError(
+				[reapError],
+				"Fixture broker fd 3 is unavailable and the exact child could not be synchronously terminated.",
+			);
+		}
+		if (spawnError) throw new Error(`Failed to spawn fixture broker: ${spawnError.message}`);
+		throw new Error("Fixture broker fd 3 is unavailable.");
+	}
+	return {
+		lease: createFixtureLeaseFromChild(child, async () => {
+			await reapSpawnedBroker(child);
+			if (spawnError) throw new Error(`Failed to spawn fixture broker: ${spawnError.message}`);
+		}),
+		control: control as NodeJS.WritableStream,
+	};
+}
+
 /** Test hook: returns a stop handle for the detached broker this process spawned. */
 export function brokerOwnerForTest(agentDir: string): BrokerOwner | undefined {
 	return owners.get(agentDir);

package/src/sdk/broker/internal.ts

@@ -0,0 +1,10 @@
+import type { Broker } from "./broker";
+
+/** Wait for broker-local completion, then terminate only the current broker process. */
+export async function completeBrokerProcess(
+	broker: Broker,
+	exit: (code: number) => never = code => process.exit(code),
+): Promise<never> {
+	await broker.completion;
+	return exit(0);
+}