@gajae-code/coding-agent 0.18.5 → 0.18.7

package/src/sdk/broker/ensure.ts

@@ -14,6 +14,7 @@ import {
 	readBrokerDiscovery,
 	readBrokerRestartIntent,
 } from "./discovery";
+import { isProcessIncarnation, observeProcessIncarnation } from "./process-incarnation";
 import {
 	isSdkInternalRuntimeImagePresent,
 	resolveSdkInternalSpawnCommand,
@@ -369,6 +370,7 @@ interface BrokerOwner {
 	stop(): Promise<void>;
 	canReuse(discovery: BrokerDiscovery | null): boolean;
 	markReady(discovery: BrokerDiscovery): boolean;
+	setTarget(pid: number, incarnation: string): void;
 }
 type EnsureInitiator = "discovery" | "fixture-lease";
 type EnsureOutcome =
@@ -453,25 +455,60 @@ async function reapSpawnedBroker(child: ChildProcess, timing: ReapTiming = DEFAU
 	throw new Error(`Detached SDK broker (pid ${child.pid}) did not exit after SIGKILL during reap.`);
 }
 
+async function reapSpawnedBrokerIdentity(
+	pid: number,
+	incarnation: string,
+	timing: ReapTiming = DEFAULT_REAP_TIMING,
+): Promise<void> {
+	const matches = (): boolean => {
+		const observed = observeProcessIncarnation(pid);
+		return observed.status === "present" && observed.incarnation === incarnation;
+	};
+	const gone = (): boolean => observeProcessIncarnation(pid).status === "absent";
+	const signal = (sig: NodeJS.Signals): void => {
+		if (!matches()) return;
+		try {
+			process.kill(pid, sig);
+		} catch {
+			// already exited between identity check and signal delivery
+		}
+	};
+	if (gone() || !matches()) return;
+	// A reported trampoline has already detached this broker from the retained
+	// child handle, so graceful shutdown cannot be observed or reaped reliably.
+	// Force termination keeps discovery-timeout cleanup within its caller's
+	// bounded deadline while the identity check still prevents PID reuse.
+	signal("SIGKILL");
+	await Promise.race([waitForProcessAbsence(pid), sleep(timing.killVerifyMs)]);
+	if (!gone()) throw new Error(`Detached SDK broker (pid ${pid}) did not exit after SIGKILL during reap.`);
+}
+
+async function waitForProcessAbsence(pid: number): Promise<void> {
+	while (observeProcessIncarnation(pid).status !== "absent") await Bun.sleep(10);
+}
+
 function registerBrokerOwner(
 	agentDir: string,
 	child: ChildProcess,
 	timing: ReapTiming = DEFAULT_REAP_TIMING,
 ): BrokerOwner {
-	const incarnation = child.pid === undefined ? undefined : brokerProcessIncarnation(child.pid);
+	let targetPid = child.pid;
+	let targetIncarnation = child.pid === undefined ? undefined : brokerProcessIncarnation(child.pid);
 	let state: "starting" | "ready" | "cleanup-unverified" = "starting";
 	const matches = (discovery: BrokerDiscovery | null): boolean =>
 		Boolean(
 			discovery &&
-				child.pid !== undefined &&
-				incarnation &&
-				discovery.pid === child.pid &&
-				discovery.incarnation === incarnation,
+				targetPid !== undefined &&
+				targetIncarnation !== undefined &&
+				discovery.pid === targetPid &&
+				discovery.incarnation === targetIncarnation,
 		);
 	const owner: BrokerOwner = {
 		async stop(): Promise<void> {
 			try {
-				await reapSpawnedBroker(child, timing);
+				if (targetPid !== undefined && targetIncarnation !== undefined && targetPid !== child.pid)
+					await reapSpawnedBrokerIdentity(targetPid, targetIncarnation, timing);
+				else await reapSpawnedBroker(child, timing);
 			} catch (error) {
 				state = "cleanup-unverified";
 				throw error;
@@ -486,6 +523,10 @@ function registerBrokerOwner(
 			state = "ready";
 			return true;
 		},
+		setTarget(pid, incarnation): void {
+			targetPid = pid;
+			targetIncarnation = incarnation;
+		},
 	};
 	owners.set(agentDir, owner);
 	return owner;
@@ -688,7 +729,11 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 		// that finished between our first read and the lock acquisition.
 		const discoveredUnderLock = await reconcileBrokerGenerationForStartup(settings, deadline);
 		if (discoveredUnderLock) return { kind: "external-discovery", discovery: discoveredUnderLock };
-		const command = resolveSdkInternalSpawnCommand("broker-internal");
+		const command = resolveSdkInternalSpawnCommand(
+			process.platform === "win32" || initiator === "fixture-lease"
+				? "broker-internal"
+				: "broker-trampoline-internal",
+		);
 		spawnLog = await openBrokerSpawnLog(settings.agentDir);
 		// A stale marker must never be misattributed to this spawn; clear it first.
 		await clearBrokerStartupExitRecord(settings.agentDir);
@@ -696,23 +741,83 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 		const childSpawnedAt = Date.now();
 		const child = spawn(command.file, [...command.args, "--agent-dir", settings.agentDir], {
 			detached: true,
-			stdio: ["ignore", "ignore", spawnLog ? spawnLog.handle.fd : "ignore"],
+			stdio: ["ignore", process.platform === "win32" ? "ignore" : "pipe", spawnLog ? spawnLog.handle.fd : "ignore"],
 			env: brokerSpawnEnvironment(command, settings.env),
 			...(command.kind === "bun-source" ? { cwd: command.cwd } : {}),
 		});
+		const isTrampoline = process.platform !== "win32" && initiator !== "fixture-lease";
 		let spawnError: Error | undefined;
+		let childExited = false;
+		let childExitCode: number | null = null;
+		let childSignalCode: NodeJS.Signals | null = null;
+		let brokerDeathObserved = false;
 		child.once("error", error => {
 			spawnError = error;
 		});
-		const childIncarnation = child.pid === undefined ? undefined : brokerProcessIncarnation(child.pid);
+		child.once("close", (code, signal) => {
+			childExited = true;
+			childExitCode = code;
+			childSignalCode = signal;
+		});
+		let trampolineReported = !isTrampoline;
+		let spawnedBrokerPid = isTrampoline ? undefined : child.pid;
+		let spawnedBrokerIncarnation =
+			isTrampoline || child.pid === undefined ? undefined : brokerProcessIncarnation(child.pid);
 		const owner = registerBrokerOwner(settings.agentDir, child);
+		if (isTrampoline && child.stdout) {
+			let output = "";
+			child.stdout.on("data", chunk => {
+				output += Buffer.from(chunk).toString("utf8");
+				const newline = output.indexOf("\n");
+				if (newline < 0) return;
+				const line = output.slice(0, newline).trim();
+				const [rawPid, rawIncarnation] = line?.split("\t") ?? [];
+				const pid = rawPid ? Number(rawPid) : NaN;
+				if (!Number.isSafeInteger(pid) || pid <= 0) return;
+				if (isProcessIncarnation(rawIncarnation)) {
+					const incarnation = rawIncarnation;
+					trampolineReported = true;
+					spawnedBrokerPid = pid;
+					spawnedBrokerIncarnation = incarnation;
+					owner.setTarget(pid, incarnation);
+				}
+			});
+		}
 		child.unref();
 		// The child holds its own duplicate of the descriptor. Failure to close the
 		// parent's diagnostic handle must not discard exact ownership of a live child.
 		await spawnLog?.handle.close().catch(() => undefined);
 		let discoveryError: unknown;
 		while (ensureBrokerTiming.now() < deadline) {
-			if (spawnError || child.exitCode !== null || child.signalCode !== null) break;
+			if (
+				spawnError ||
+				(isTrampoline && childExited && (!trampolineReported || childExitCode !== 0 || childSignalCode !== null)) ||
+				(!isTrampoline && process.platform === "win32" && (child.exitCode !== null || child.signalCode !== null))
+			)
+				break;
+			if (
+				isTrampoline &&
+				trampolineReported &&
+				spawnedBrokerPid !== undefined &&
+				spawnedBrokerIncarnation !== undefined
+			) {
+				const observed = observeProcessIncarnation(spawnedBrokerPid);
+				if (observed.status === "present" && observed.incarnation !== spawnedBrokerIncarnation) {
+					brokerDeathObserved = true;
+					break;
+				}
+				if (observed.status === "absent") {
+					brokerDeathObserved = true;
+					break;
+				}
+			}
+			// The trampoline's stdout line identifies the real broker. Do not read
+			// discovery until that line has been parsed, or a marker from the
+			// trampoline could be trusted as the broker's own startup evidence.
+			if (isTrampoline && !trampolineReported) {
+				await ensureBrokerTiming.sleep(50);
+				continue;
+			}
 			try {
 				const discovered = await readBrokerDiscoveryBeforeDeadline(
 					settings.agentDir,
@@ -724,6 +829,20 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 						await ensureBrokerTiming.sleep(50);
 						continue;
 					}
+					if (isTrampoline && !childExited) {
+						await ensureBrokerTiming.sleep(50);
+						continue;
+					}
+					if (isTrampoline && spawnedBrokerPid !== undefined && spawnedBrokerIncarnation !== undefined) {
+						const observed = observeProcessIncarnation(spawnedBrokerPid);
+						if (
+							observed.status === "absent" ||
+							(observed.status === "present" && observed.incarnation !== spawnedBrokerIncarnation)
+						) {
+							brokerDeathObserved = true;
+							break;
+						}
+					}
 					if (owner.markReady(discovered)) {
 						return initiator === "fixture-lease"
 							? { kind: "local-started-fixture", discovery: discovered, owner, child }
@@ -737,8 +856,13 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 			}
 			await ensureBrokerTiming.sleep(50);
 		}
-		const exitedBeforeDiscovery = child.exitCode !== null || child.signalCode !== null;
-		if (exitedBeforeDiscovery && child.exitCode === 0) {
+		const exitedBeforeDiscovery =
+			(isTrampoline &&
+				(!trampolineReported ||
+					(childExited && (childExitCode !== 0 || childSignalCode !== null)) ||
+					brokerDeathObserved)) ||
+			(!isTrampoline && process.platform === "win32" && (child.exitCode !== null || child.signalCode !== null));
+		if (!isTrampoline && exitedBeforeDiscovery && childExitCode === 0) {
 			// A clean exit means another broker won the ownership lock (two ACP
 			// processes racing a cold broker state, e.g. a provider probe and an
 			// agent launch). The winner may publish its discovery right after our
@@ -765,16 +889,16 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 		const startupExitRecord = await readBrokerStartupExitRecord(settings.agentDir);
 		const trustedMarker =
 			marker &&
-			child.pid !== undefined &&
-			childIncarnation !== undefined &&
-			marker.pid === child.pid &&
-			marker.incarnation === childIncarnation
+			spawnedBrokerPid !== undefined &&
+			spawnedBrokerIncarnation !== undefined &&
+			marker.pid === spawnedBrokerPid &&
+			marker.incarnation === spawnedBrokerIncarnation
 				? marker
 				: undefined;
 		const trustedStartupExitRecord =
 			startupExitRecord &&
-			child.pid !== undefined &&
-			startupExitRecord.pid === child.pid &&
+			spawnedBrokerPid !== undefined &&
+			startupExitRecord.pid === spawnedBrokerPid &&
 			startupExitRecord.writtenAt >= childSpawnedAt
 				? startupExitRecord
 				: undefined;
@@ -828,8 +952,20 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 			? new Error(`Failed to spawn detached SDK broker: ${spawnError.message}`)
 			: exitedBeforeDiscovery
 				? new BrokerStartupError({
-						exitCode: child.exitCode ?? trustedStartupExitRecord?.exitCode ?? null,
-						signal: child.signalCode ?? trustedStartupExitRecord?.signal ?? null,
+						exitCode: isTrampoline
+							? (trustedStartupExitRecord?.exitCode ??
+								trustedMarker?.exitCode ??
+								childExitCode ??
+								child.exitCode ??
+								null)
+							: (childExitCode ?? child.exitCode ?? trustedStartupExitRecord?.exitCode ?? null),
+						signal: isTrampoline
+							? (trustedStartupExitRecord?.signal ??
+								trustedMarker?.signal ??
+								childSignalCode ??
+								child.signalCode ??
+								null)
+							: (childSignalCode ?? child.signalCode ?? trustedStartupExitRecord?.signal ?? null),
 						reason:
 							brokerStartupExitReason(trustedStartupExitRecord) ?? brokerStartupFailureReason(trustedMarker),
 						stderrExcerpt: spawnLogTail.length > 0 ? spawnLogTail : undefined,

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

@@ -74,6 +74,8 @@ export interface LifecycleDurableEffectsReceipt {
 export interface LifecycleLedgerEntry {
 	operationKey?: string;
 	fingerprint?: string;
+	/** True only when a session.close request supplied immutable generation authority. */
+	closeAuthorityBound?: boolean;
 	version: typeof SDK_STATE_VERSION;
 	identity: string;
 	requestHash: string;
@@ -213,6 +215,20 @@ function pendingCleanupSessionId(response: unknown): string | undefined {
 	return canonicalCleanupSessionId(cleanup?.sessionId) ? cleanup.sessionId : undefined;
 }
 
+function retirementCreateIdentity(response: unknown): string | undefined {
+	if (!response || typeof response !== "object") return undefined;
+	const error = (response as { error?: unknown }).error;
+	if (!error || typeof error !== "object") return undefined;
+	const cleanup = (error as { cleanup?: unknown }).cleanup;
+	if (!cleanup || typeof cleanup !== "object") return undefined;
+	const receipt = (cleanup as { uncertainRetirement?: unknown }).uncertainRetirement;
+	if (!receipt || typeof receipt !== "object") return undefined;
+	const identity = (receipt as { identity?: unknown }).identity;
+	if (!identity || typeof identity !== "object") return undefined;
+	const createIdentity = (identity as { createIdentity?: unknown }).createIdentity;
+	return typeof createIdentity === "string" && createIdentity.length > 0 ? createIdentity : undefined;
+}
+
 function hasValidTerminalDigests(entry: LifecycleLedgerEntry): boolean {
 	const response = entry.response as { ok?: unknown; error?: { code?: unknown; cleanup?: unknown } } | undefined;
 	const cleanupPendingResponse =
@@ -646,23 +662,91 @@ export class LifecycleLedger {
 			await directory.close();
 		}
 	}
-	async #compact(replacement?: LifecycleLedgerEntry): Promise<boolean> {
+	async #compact(
+		replacement?: LifecycleLedgerEntry,
+		incoming?: { readonly bytes: number; readonly rows: number },
+	): Promise<boolean> {
 		const anchors = new Map<string, LifecycleLedgerEntry>();
 		for (const entry of this.#entries) {
 			const latest = replacement?.identity === entry.identity ? replacement : this.#byIdentity.get(entry.identity);
 			if (entry.state === "accepted" && !anchors.has(entry.identity) && entry.requestHash === latest?.requestHash)
 				anchors.set(entry.identity, entry);
 		}
-		const snapshot: LifecycleLedgerEntry[] = [];
 		const compacted = new Map(this.#byIdentity);
 		if (replacement) compacted.set(replacement.identity, replacement);
-		for (const [identity, latest] of compacted) {
-			const anchor = anchors.get(identity);
-			if (!anchor) throw new Error("Lifecycle ledger compaction requires an accepted identity anchor.");
-			snapshot.push(replacement?.identity === identity && latest.state === "accepted" ? latest : anchor);
-			if (latest.state !== "accepted") snapshot.push(latest);
+		const buildSnapshot = (): LifecycleLedgerEntry[] => {
+			const next: LifecycleLedgerEntry[] = [];
+			for (const [identity, latest] of compacted) {
+				const anchor = anchors.get(identity);
+				if (!anchor) throw new Error("Lifecycle ledger compaction requires an accepted identity anchor.");
+				next.push(replacement?.identity === identity && latest.state === "accepted" ? latest : anchor);
+				if (latest.state !== "accepted") next.push(latest);
+			}
+			return next;
+		};
+		let snapshot = buildSnapshot();
+		let contents = Buffer.from(snapshot.map(entry => `${JSON.stringify(entry)}\n`).join(""));
+		const needsEviction = incoming
+			? snapshot.length + incoming.rows > this.#limits.maxRows ||
+				contents.length + incoming.bytes > this.#limits.maxBytes
+			: replacement === undefined
+				? snapshot.length >= this.#limits.maxRows || contents.length >= this.#limits.maxBytes
+				: snapshot.length > this.#limits.maxRows || contents.length > this.#limits.maxBytes;
+		if (needsEviction) {
+			const protectedCreateIdentities = new Set<string>();
+			for (const entry of compacted.values()) {
+				const createIdentity =
+					retirementCreateIdentity(entry.response) ?? retirementCreateIdentity(entry.unresolvedCleanupResponse);
+				if (createIdentity !== undefined) protectedCreateIdentities.add(createIdentity);
+			}
+			const evictable = [...compacted.values()]
+				.filter(
+					latest =>
+						latest.identity !== replacement?.identity &&
+						terminal(latest.state) &&
+						latest.operationKey !== undefined &&
+						latest.fingerprint !== undefined &&
+						(!latest.operationKey.startsWith("session.close\u0000") || latest.closeAuthorityBound === true) &&
+						!protectedCreateIdentities.has(latest.identity) &&
+						pendingCleanupSessionId(latest.response) === undefined &&
+						pendingCleanupSessionId(latest.unresolvedCleanupResponse) === undefined,
+				)
+				.sort((left, right) => left.ts - right.ts);
+			const rowsByIdentity = new Map<string, number>();
+			const bytesByIdentity = new Map<string, number>();
+			for (const entry of snapshot) {
+				rowsByIdentity.set(entry.identity, (rowsByIdentity.get(entry.identity) ?? 0) + 1);
+				bytesByIdentity.set(
+					entry.identity,
+					(bytesByIdentity.get(entry.identity) ?? 0) + Buffer.byteLength(`${JSON.stringify(entry)}\n`),
+				);
+			}
+			let remainingRows = snapshot.length;
+			let remainingBytes = contents.length;
+			const evicted = new Set<string>();
+			for (const latest of evictable) {
+				if (
+					remainingRows <= this.#limits.maxRows / 2 &&
+					remainingBytes <= this.#limits.maxBytes / 2 &&
+					remainingRows + (incoming?.rows ?? 0) <= this.#limits.maxRows &&
+					remainingBytes + (incoming?.bytes ?? 0) <= this.#limits.maxBytes
+				)
+					break;
+				evicted.add(latest.identity);
+				remainingRows -= rowsByIdentity.get(latest.identity) ?? 0;
+				remainingBytes -= bytesByIdentity.get(latest.identity) ?? 0;
+			}
+			for (const identity of evicted) compacted.delete(identity);
+			snapshot = buildSnapshot();
+			contents = Buffer.from(snapshot.map(entry => `${JSON.stringify(entry)}\n`).join(""));
+			// Replay is guaranteed only for identities retained in the compacted ledger.
 		}
-		const contents = Buffer.from(snapshot.map(entry => `${JSON.stringify(entry)}\n`).join(""));
+		if (
+			incoming &&
+			(snapshot.length + incoming.rows > this.#limits.maxRows ||
+				contents.length + incoming.bytes > this.#limits.maxBytes)
+		)
+			throw new Error("Lifecycle ledger append exceeds configured bounds.");
 		if (
 			snapshot.length > this.#limits.maxRows ||
 			contents.length > this.#limits.maxBytes ||
@@ -735,7 +819,7 @@ export class LifecycleLedger {
 	async migrateIdentity(
 		from: string,
 		to: string,
-		metadata: { operationKey: string; fingerprint: string },
+		metadata: { operationKey: string; fingerprint: string; closeAuthorityBound?: boolean },
 	): Promise<LifecycleLedgerEntry | undefined> {
 		return this.#mutate(async () => {
 			const existing = this.#byIdentity.get(to);
@@ -776,9 +860,12 @@ export class LifecycleLedger {
 		);
 		if (line.length - 1 > this.#limits.maxLineBytes)
 			throw new Error("Lifecycle ledger row exceeds the maximum byte length.");
+		if (line.length > this.#limits.maxBytes) throw new Error("Lifecycle ledger append exceeds configured bounds.");
 		let replacementCompacted = false;
 		if (this.#rowCount + 1 > this.#limits.maxRows || this.#byteCount + line.length > this.#limits.maxBytes)
-			replacementCompacted = await this.#compact(this.#byIdentity.has(entry.identity) ? entry : undefined);
+			replacementCompacted = this.#byIdentity.has(entry.identity)
+				? await this.#compact(entry)
+				: await this.#compact(undefined, { bytes: line.length, rows: 1 });
 		if (replacementCompacted) return entry;
 		if (this.#rowCount + 1 > this.#limits.maxRows || this.#byteCount + line.length > this.#limits.maxBytes)
 			throw new Error("Lifecycle ledger append exceeds configured bounds.");
@@ -798,7 +885,12 @@ export class LifecycleLedger {
 	async begin(
 		identity: string,
 		requestHash: string,
-		metadata: { operationKey?: string; fingerprint?: string; intendedSessionId?: string } = {},
+		metadata: {
+			operationKey?: string;
+			fingerprint?: string;
+			intendedSessionId?: string;
+			closeAuthorityBound?: boolean;
+		} = {},
 	): Promise<BeginResult> {
 		return this.#mutate(async () => this.#begin(identity, requestHash, metadata));
 	}
@@ -806,7 +898,12 @@ export class LifecycleLedger {
 	async #begin(
 		identity: string,
 		requestHash: string,
-		metadata: { operationKey?: string; fingerprint?: string; intendedSessionId?: string },
+		metadata: {
+			operationKey?: string;
+			fingerprint?: string;
+			intendedSessionId?: string;
+			closeAuthorityBound?: boolean;
+		},
 	): Promise<BeginResult> {
 		const prior = this.#byIdentity.get(identity);
 		if (!prior)
@@ -819,6 +916,7 @@ export class LifecycleLedger {
 					operationKey: metadata.operationKey,
 					fingerprint: metadata.fingerprint,
 					intendedSessionId: metadata.intendedSessionId,
+					closeAuthorityBound: metadata.closeAuthorityBound,
 					state: "accepted",
 					ts: Date.now(),
 				}),