@gajae-code/coding-agent 0.16.3 → 0.16.6

package/src/sdk/broker/ensure.ts

@@ -4,6 +4,8 @@ import type { FileHandle } from "node:fs/promises";
 import * as fs from "node:fs/promises";
 import path from "node:path";
 import packageJson from "../../../package.json" with { type: "json" };
+import { acquireFileLock, type FileLockOptions, withFileLock } from "../../config/file-lock";
+import { loadInstallationHostId, loadLegacyInstallationHostId } from "../../config/machine-identity";
 import { SdkClient } from "../client/client";
 import { type BrokerDiscovery, brokerProcessIncarnation, readBrokerDiscovery } from "./discovery";
 import { resolveSdkInternalSpawnCommand, type SdkInternalSpawnCommand } from "./runtime";
@@ -14,7 +16,7 @@ function resolveExpectedBrokerGeneration(): string {
 	return typeof v === "string" && v.length > 0 ? v : "unknown";
 }
 
-function isBrokerGenerationCompatible(discovery: BrokerDiscovery | null): boolean {
+export function isBrokerGenerationCompatible(discovery: BrokerDiscovery | null): boolean {
 	if (!discovery) return false;
 	return discovery.packageGeneration === resolveExpectedBrokerGeneration();
 }
@@ -29,7 +31,110 @@ export interface EnsureBrokerSettings {
 	env?: NodeJS.ProcessEnv;
 }
 
-const DISCOVERY_TIMEOUT_MS = 10_000;
+const BROKER_PUBLICATION_TIMEOUT_MS = 15_000;
+const STARTUP_LOCK_WAIT_MS = 9_000;
+const STALE_BROKER_RETIREMENT_TIMEOUT_MS = 5_000;
+/** Parent budget covers stale retirement, a full child-fence wait, and one publication attempt. */
+const DISCOVERY_TIMEOUT_MS = STALE_BROKER_RETIREMENT_TIMEOUT_MS + STARTUP_LOCK_WAIT_MS + BROKER_PUBLICATION_TIMEOUT_MS;
+/** A process that loses the spawn lock waits this long for the winner's discovery before giving up. */
+const SPAWN_LOCK_WAIT_MS = STALE_BROKER_RETIREMENT_TIMEOUT_MS + DISCOVERY_TIMEOUT_MS + 5_000;
+const SPAWN_LOCK_RETRY_DELAY_MS = 50;
+const SPAWN_LOCK_TARGET_NAME = "broker.spawn";
+const STARTUP_LOCK_TARGET_NAME = "broker.startup";
+
+type SpawnLockOptions = Pick<FileLockOptions, "retries" | "retryDelayMs" | "signal">;
+
+interface BrokerLockHostIdentity {
+	ownerHostId: string;
+	previousOwnerHostIds: readonly string[];
+}
+
+const brokerLockHostIdentityPromises = new Map<string, Promise<BrokerLockHostIdentity>>();
+
+async function brokerLockHostIdentity(agentDir: string): Promise<BrokerLockHostIdentity> {
+	const coordinationRoot = path.resolve(agentDir, "sdk");
+	const pending =
+		brokerLockHostIdentityPromises.get(coordinationRoot) ??
+		Promise.all([loadInstallationHostId({ configRootDir: coordinationRoot }), loadLegacyInstallationHostId()]).then(
+			([ownerHostId, legacyHostId]) => ({
+				ownerHostId,
+				previousOwnerHostIds: legacyHostId === ownerHostId ? [] : [legacyHostId],
+			}),
+		);
+	brokerLockHostIdentityPromises.set(coordinationRoot, pending);
+	try {
+		return await pending;
+	} catch (error) {
+		if (brokerLockHostIdentityPromises.get(coordinationRoot) === pending)
+			brokerLockHostIdentityPromises.delete(coordinationRoot);
+		throw error;
+	}
+}
+
+async function readBrokerDiscoveryBeforeDeadline(
+	agentDir: string,
+	heartbeatTtlMs: number | undefined,
+	deadline: number,
+): Promise<BrokerDiscovery | null> {
+	const remainingMs = deadline - Date.now();
+	if (!Number.isFinite(remainingMs)) return await readBrokerDiscovery(agentDir, heartbeatTtlMs);
+	if (remainingMs <= 0) throw new Error("Timed out reading SDK broker discovery.");
+	const read = readBrokerDiscovery(agentDir, heartbeatTtlMs);
+	void read.catch(() => undefined);
+	const timeout = Promise.withResolvers<BrokerDiscovery | null>();
+	const timer: NodeJS.Timeout = setTimeout(
+		() => timeout.reject(new Error("Timed out reading SDK broker discovery.")),
+		remainingMs,
+	);
+	try {
+		return await Promise.race([read, timeout.promise]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+/**
+ * Cross-process single-flight for the detached broker spawn (#5198).
+ *
+ * `ensureInFlight` only dedupes within one process. Every CLI invocation is
+ * its own process, so N concurrent invocations that all miss discovery each
+ * spawn a broker; the losers of the runtime's ownership lock then leave
+ * quarantine tombstones behind and the next start fails with
+ * `quarantine_collision`. The spawn itself must be exclusive across process
+ * death and PID reuse, so it uses the shared identity-bound file-lock protocol:
+ * complete owner metadata is published atomically, stale removal is bound to
+ * the exact directory generation, and ownership includes the OS incarnation.
+ */
+async function acquireSpawnLock(agentDir: string, options: SpawnLockOptions = {}): Promise<() => Promise<void>> {
+	const hostIdentity = await brokerLockHostIdentity(agentDir);
+	return acquireFileLock(path.join(agentDir, "sdk", SPAWN_LOCK_TARGET_NAME), {
+		retries: Math.ceil(SPAWN_LOCK_WAIT_MS / SPAWN_LOCK_RETRY_DELAY_MS),
+		retryDelayMs: SPAWN_LOCK_RETRY_DELAY_MS,
+		...hostIdentity,
+		...options,
+	});
+}
+
+/**
+ * Child-owned fence for the interval from bootstrap through discovery publication.
+ * The parent-held spawn lock prevents ordinary stampedes; this second fence keeps
+ * startup single-flight if that detached child's launcher dies and its lock is reclaimed.
+ */
+export async function withBrokerStartupLock<T>(
+	agentDir: string,
+	operation: (deadline: number) => Promise<T>,
+): Promise<T> {
+	const hostIdentity = await brokerLockHostIdentity(agentDir);
+	return withFileLock(
+		path.join(agentDir, "sdk", STARTUP_LOCK_TARGET_NAME),
+		() => operation(Date.now() + STALE_BROKER_RETIREMENT_TIMEOUT_MS + BROKER_PUBLICATION_TIMEOUT_MS),
+		{
+			retries: Math.ceil(STARTUP_LOCK_WAIT_MS / SPAWN_LOCK_RETRY_DELAY_MS),
+			retryDelayMs: SPAWN_LOCK_RETRY_DELAY_MS,
+			...hostIdentity,
+		},
+	);
+}
 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).
@@ -260,7 +365,6 @@ function fixtureLeaseUnavailable(): Error {
 	return new Error("fixture_broker_lease_unavailable");
 }
 
-const STALE_BROKER_SHUTDOWN_TIMEOUT_MS = 5_000;
 const STALE_BROKER_POLL_MS = 50;
 
 type BrokerOwnerIdentity = Pick<BrokerDiscovery, "ownerId" | "pid" | "incarnation">;
@@ -271,17 +375,34 @@ function sameBrokerOwner(left: BrokerOwnerIdentity | null, right: BrokerOwnerIde
 	);
 }
 
-async function retireStaleBrokerGeneration(stale: BrokerDiscovery, settings: EnsureBrokerSettings): Promise<void> {
+/** Start client teardown, but never await it past the retirement operation's absolute deadline. */
+export async function closeBrokerClientBeforeDeadline(
+	client: { close(): Promise<void> },
+	deadline: number,
+): Promise<void> {
+	const close = client.close();
+	void close.catch(() => undefined);
+	const remainingMs = deadline - Date.now();
+	if (remainingMs <= 0) return;
+	await Promise.race([close, Bun.sleep(remainingMs)]);
+}
+
+async function retireStaleBrokerGeneration(
+	stale: BrokerDiscovery,
+	settings: EnsureBrokerSettings,
+	outerDeadline = Number.POSITIVE_INFINITY,
+): Promise<void> {
+	const deadline = Math.min(outerDeadline, Date.now() + STALE_BROKER_RETIREMENT_TIMEOUT_MS);
 	let shutdownSucceeded = false;
 	try {
-		const current = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
+		const current = await readBrokerDiscoveryBeforeDeadline(settings.agentDir, settings.heartbeatTtlMs, deadline);
 		if (!current || !sameBrokerOwner(current, stale)) return;
-		const client = await SdkClient.connect(current.url, current.token, { timeoutMs: 2_000 });
+		const client = await SdkClient.connect(current.url, current.token, { timeoutMs: 2_000, deadline });
 		try {
 			await client.global("broker.shutdown", {});
 			shutdownSucceeded = true;
 		} finally {
-			await client.close().catch(() => {});
+			await closeBrokerClientBeforeDeadline(client, deadline).catch(() => undefined);
 		}
 	} catch {}
 	if (!shutdownSucceeded) {
@@ -294,13 +415,25 @@ async function retireStaleBrokerGeneration(stale: BrokerDiscovery, settings: Ens
 		} catch {}
 	}
 	// Wait for the stale identity to disappear (owner-fenced: pid+incarnation).
-	const deadline = Date.now() + STALE_BROKER_SHUTDOWN_TIMEOUT_MS;
 	while (Date.now() < deadline) {
-		const current = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
+		const current = await readBrokerDiscoveryBeforeDeadline(settings.agentDir, settings.heartbeatTtlMs, deadline);
 		if (!sameBrokerOwner(current, stale)) break;
 		await sleep(STALE_BROKER_POLL_MS);
 	}
 }
+
+/** Reconcile an observed broker generation before entering a startup critical section. */
+export async function reconcileBrokerGenerationForStartup(
+	settings: EnsureBrokerSettings,
+	deadline = Number.POSITIVE_INFINITY,
+): Promise<BrokerDiscovery | undefined> {
+	const current = await readBrokerDiscoveryBeforeDeadline(settings.agentDir, settings.heartbeatTtlMs, deadline);
+	if (!current) return undefined;
+	if (isBrokerGenerationCompatible(current)) return current;
+	await retireStaleBrokerGeneration(current, settings, deadline);
+	const replacement = await readBrokerDiscoveryBeforeDeadline(settings.agentDir, settings.heartbeatTtlMs, deadline);
+	return replacement && isBrokerGenerationCompatible(replacement) ? replacement : undefined;
+}
 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;
@@ -344,60 +477,79 @@ function createFixtureLease(owner: BrokerOwner, child: ChildProcess): ExactFixtu
 }
 
 async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: EnsureInitiator): Promise<EnsureOutcome> {
+	const initialDiscoveryDeadline =
+		Date.now() + (initiator === "fixture-lease" ? FIXTURE_DISCOVERY_TIMEOUT_MS : DISCOVERY_TIMEOUT_MS);
 	const priorOwner = owners.get(settings.agentDir);
-	const existing = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
+	const existing = await readBrokerDiscoveryBeforeDeadline(
+		settings.agentDir,
+		settings.heartbeatTtlMs,
+		initialDiscoveryDeadline,
+	);
 	if (initiator === "fixture-lease" && (priorOwner || existing)) throw fixtureLeaseUnavailable();
 	if (priorOwner) {
 		// A retained cleanup failure fences every discovery record. Only a ready
 		// record bound to this exact child incarnation may be reused.
 		if (priorOwner.canReuse(existing)) return { kind: "prior-local-owner", discovery: existing!, owner: priorOwner };
 		await priorOwner.stop();
-		const discoveredAfterCleanup = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
+		const discoveredAfterCleanup = await readBrokerDiscoveryBeforeDeadline(
+			settings.agentDir,
+			settings.heartbeatTtlMs,
+			initialDiscoveryDeadline,
+		);
 		if (discoveredAfterCleanup && isBrokerGenerationCompatible(discoveredAfterCleanup))
 			return { kind: "external-discovery", discovery: discoveredAfterCleanup };
-		// A stale-generation discovery after cleanup must not be reused — fall through to replacement.
-		if (!discoveredAfterCleanup) {
-			// no discovery left after cleanup — fall through to spawn
-		} else {
-			await retireStaleBrokerGeneration(discoveredAfterCleanup, settings);
-			const afterRetire = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
-			if (afterRetire && isBrokerGenerationCompatible(afterRetire))
-				return { kind: "external-discovery", discovery: afterRetire };
-		}
+		// Stale-generation retirement is serialized under the spawn lock below.
 	} else if (existing) {
 		if (isBrokerGenerationCompatible(existing)) return { kind: "external-discovery", discovery: existing };
-		await retireStaleBrokerGeneration(existing, settings);
-		const afterRetire = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
-		if (afterRetire && isBrokerGenerationCompatible(afterRetire))
-			return { kind: "external-discovery", discovery: afterRetire };
+		// Stale-generation retirement is serialized under the spawn lock below.
 	}
-	const command = resolveSdkInternalSpawnCommand("broker-internal");
-	const spawnLog = await openBrokerSpawnLog(settings.agentDir);
-	// A stale marker must never be misattributed to this spawn; clear it first.
-	await clearBrokerStartupFailureMarker(settings.agentDir);
+
+	// Only one process may spawn for this agent dir at a time; everyone else
+	// waits for the exact lock generation to release, then rechecks discovery.
+	// Fixture leases always spawn their own.
+	let spawnLog: BrokerSpawnLog | undefined;
+	const releaseSpawnLock = initiator === "fixture-lease" ? async () => {} : await acquireSpawnLock(settings.agentDir);
 	try {
+		const deadline =
+			Date.now() + (initiator === "fixture-lease" ? FIXTURE_DISCOVERY_TIMEOUT_MS : DISCOVERY_TIMEOUT_MS);
+		// The lock winner may still find a discovery published by an earlier winner
+		// that finished between our first read and the lock acquisition.
+		const discoveredUnderLock = await reconcileBrokerGenerationForStartup(settings, deadline);
+		if (discoveredUnderLock) return { kind: "external-discovery", discovery: discoveredUnderLock };
+		const command = resolveSdkInternalSpawnCommand("broker-internal");
+		spawnLog = await openBrokerSpawnLog(settings.agentDir);
+		// A stale marker must never be misattributed to this spawn; clear it first.
+		await clearBrokerStartupFailureMarker(settings.agentDir);
 		const child = spawn(command.file, [...command.args, "--agent-dir", settings.agentDir], {
 			detached: true,
 			stdio: ["ignore", "ignore", spawnLog ? spawnLog.handle.fd : "ignore"],
 			env: brokerSpawnEnvironment(command, settings.env),
 			...(command.kind === "bun-source" ? { cwd: command.cwd } : {}),
 		});
-		// The child holds its own duplicate of the descriptor; this one is done.
-		await spawnLog?.handle.close();
-		child.unref();
 		let spawnError: Error | undefined;
 		child.once("error", error => {
 			spawnError = error;
 		});
+		const childIncarnation = child.pid === undefined ? undefined : brokerProcessIncarnation(child.pid);
 		const owner = registerBrokerOwner(settings.agentDir, child);
-		const discoveryTimeoutMs = initiator === "fixture-lease" ? FIXTURE_DISCOVERY_TIMEOUT_MS : DISCOVERY_TIMEOUT_MS;
-		const deadline = Date.now() + discoveryTimeoutMs;
+		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 (Date.now() < deadline) {
 			if (spawnError || child.exitCode !== null || child.signalCode !== null) break;
 			try {
-				const discovered = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
+				const discovered = await readBrokerDiscoveryBeforeDeadline(
+					settings.agentDir,
+					settings.heartbeatTtlMs,
+					deadline,
+				);
 				if (discovered) {
+					if (!isBrokerGenerationCompatible(discovered)) {
+						await sleep(50);
+						continue;
+					}
 					if (owner.markReady(discovered)) {
 						return initiator === "fixture-lease"
 							? { kind: "local-started-fixture", discovery: discovered, owner, child }
@@ -420,8 +572,12 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 			// read failures fall through to the common cleanup + failure path below.
 			try {
 				for (let retry = 0; retry < 20; retry++) {
-					const winner = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
-					if (winner) {
+					const winner = await readBrokerDiscoveryBeforeDeadline(
+						settings.agentDir,
+						settings.heartbeatTtlMs,
+						deadline,
+					);
+					if (winner && isBrokerGenerationCompatible(winner)) {
 						await owner.stop();
 						return { kind: "external-discovery", discovery: winner };
 					}
@@ -431,8 +587,53 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 				// fall through to cleanup + failure
 			}
 		}
-		const spawnLogTail = exitedBeforeDiscovery && spawnLog ? await readBrokerSpawnLogTail(spawnLog.path) : "";
 		const marker = await readBrokerStartupFailureMarker(settings.agentDir);
+		const trustedMarker =
+			marker &&
+			child.pid !== undefined &&
+			childIncarnation !== undefined &&
+			marker.pid === child.pid &&
+			marker.incarnation === childIncarnation
+				? marker
+				: undefined;
+		const startupLockPath = path.join(settings.agentDir, "sdk", STARTUP_LOCK_TARGET_NAME);
+		let startupFenceContention =
+			exitedBeforeDiscovery &&
+			trustedMarker?.reason.startsWith(`Failed to acquire lock for ${startupLockPath} after `) === true;
+		if (!startupFenceContention && exitedBeforeDiscovery && child.exitCode !== 0) {
+			try {
+				startupFenceContention = (await fs.stat(`${startupLockPath}.lock`)).isDirectory();
+			} catch {
+				// The marker is best-effort and the fence may have been released
+				// between the child exit and this observation.
+			}
+		}
+		if (startupFenceContention) {
+			// A launcher can die after its detached child acquires the startup fence.
+			// The replacement child may exhaust its own fence wait before the incumbent
+			// reaches the end of its publication allowance, so keep the parent attached
+			// to the exact agent dir and give that incumbent one final bounded chance to
+			// publish before treating the replacement failure as terminal.
+			const recoveryDeadline = Math.min(deadline, Date.now() + BROKER_PUBLICATION_TIMEOUT_MS);
+			while (Date.now() < recoveryDeadline) {
+				try {
+					const incumbent = await readBrokerDiscoveryBeforeDeadline(
+						settings.agentDir,
+						settings.heartbeatTtlMs,
+						recoveryDeadline,
+					);
+					if (incumbent && isBrokerGenerationCompatible(incumbent)) {
+						await owner.stop();
+						return { kind: "external-discovery", discovery: incumbent };
+					}
+				} catch {
+					// Keep the bounded retry alive; a transient read failure is not
+					// authority to classify the incumbent as failed.
+				}
+				await sleep(50);
+			}
+		}
+		const spawnLogTail = exitedBeforeDiscovery && spawnLog ? await readBrokerSpawnLogTail(spawnLog.path) : "";
 		// A marker only wins over the generic fallback when it was written by the
 		// exact child this call just spawned and reaped. The pre-spawn clear
 		// already prevents an old marker from surviving to this point, but a
@@ -440,7 +641,6 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 		// still write a marker between the clear and this read; the pid binding
 		// rejects that marker instead of misattributing a foreign failure to this
 		// spawn's caller.
-		const trustedMarker = marker && child.pid !== undefined && marker.pid === child.pid ? marker : undefined;
 		const failure = spawnError
 			? new Error(`Failed to spawn detached SDK broker: ${spawnError.message}`)
 			: exitedBeforeDiscovery
@@ -464,6 +664,7 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 		throw failure;
 	} finally {
 		if (spawnLog) await removeBrokerSpawnLog(spawnLog.path);
+		await releaseSpawnLock();
 	}
 }
 
@@ -482,14 +683,16 @@ function startEnsure(settings: EnsureBrokerSettings, initiator: EnsureInitiator)
 
 /** 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");
+	const resolvedSettings = { ...settings, agentDir: path.resolve(settings.agentDir) };
+	const inFlight = ensureInFlight.get(resolvedSettings.agentDir) ?? startEnsure(resolvedSettings, "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");
+	const resolvedSettings = { ...settings, agentDir: path.resolve(settings.agentDir) };
+	if (ensureInFlight.has(resolvedSettings.agentDir)) return Promise.reject(fixtureLeaseUnavailable());
+	const inFlight = startEnsure(resolvedSettings, "fixture-lease");
 	return inFlight.promise.then(outcome => {
 		if (outcome.kind !== "local-started-fixture") throw fixtureLeaseUnavailable();
 		return { discovery: outcome.discovery, lease: createFixtureLease(outcome.owner, outcome.child) };
@@ -540,6 +743,10 @@ export function startFixtureBrokerCommandWithLeaseForTest(command: FixtureBroker
 }
 
 /** Test hook: returns a stop handle for the detached broker this process spawned. */
+export const acquireSpawnLockForTest = acquireSpawnLock;
+/** Test hook: proves discovery reads honor their enclosing absolute deadline. */
+export const readBrokerDiscoveryBeforeDeadlineForTest = readBrokerDiscoveryBeforeDeadline;
+
 export function brokerOwnerForTest(agentDir: string): BrokerOwner | undefined {
 	return owners.get(agentDir);
 }

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

@@ -92,7 +92,6 @@ export interface LifecycleLedgerEntry {
 	unresolvedCleanupResponseDigest?: string;
 	uncertainCleanupSessionId?: string;
 	uncertainCleanupSessionIds?: string[];
-	uncertainCleanupAllSessions?: true;
 	ts: number;
 }
 export type BeginResult =
@@ -183,12 +182,6 @@ function pendingCleanupSessionId(response: unknown): string | undefined {
 	return canonicalCleanupSessionId(cleanup?.sessionId) ? cleanup.sessionId : undefined;
 }
 
-function hasCleanupAuthorityShape(response: unknown): boolean {
-	if (!response || typeof response !== "object") return false;
-	const error = (response as { error?: unknown }).error;
-	return Boolean(error && typeof error === "object" && "cleanup" in error);
-}
-
 function hasValidTerminalDigests(entry: LifecycleLedgerEntry): boolean {
 	const response = entry.response as { ok?: unknown; error?: { code?: unknown; cleanup?: unknown } } | undefined;
 	const cleanupPendingResponse =
@@ -335,12 +328,10 @@ export class LifecycleLedger {
 								(candidate, index, candidates): candidate is string =>
 									canonicalCleanupSessionId(candidate) && candidates.indexOf(candidate) === index,
 							);
-							if (
-								hasCleanupAuthorityShape(entry.response) ||
-								hasCleanupAuthorityShape(entry.unresolvedCleanupResponse) ||
-								(entry.state === "terminal_uncertain" && entry.response === undefined)
-							)
-								uncertain.uncertainCleanupAllSessions = true;
+							// No blanket fence: the synthetic marker stays scoped to the
+							// session ids the quarantined row actually named (#5364).
+							// Rows that named nothing fence nothing; resurrecting a
+							// maximally-destructive flag here is the poison shape.
 							syntheticUncertain.set(entry.identity, uncertain);
 						}
 						continue;
@@ -895,8 +886,6 @@ export class LifecycleLedger {
 	hasUncertainCleanupForSession(sessionId: string, excludingIdentity: string): boolean {
 		for (const current of this.#byIdentity.values()) {
 			if (current.state !== "terminal_uncertain") continue;
-			if (current.uncertainCleanupAllSessions === true) return true;
-			if (current.response === undefined) return true;
 			if (current.identity === excludingIdentity) continue;
 			const fencedSessions = [
 				current.uncertainCleanupSessionId,
@@ -905,8 +894,9 @@ export class LifecycleLedger {
 				pendingCleanupSessionId(current.unresolvedCleanupResponse),
 				...(current.uncertainCleanupSessionIds ?? []),
 			];
-			const boundSessions = fencedSessions.filter((value): value is string => typeof value === "string");
-			if (boundSessions.length === 0) return true;
+			// An unbound uncertain entry names no session: it fences nothing.
+			// Fencing all ids on zero evidence is what made one refusal
+			// self-amplify into a permanent blanket fence (#5364).
 			if (fencedSessions.includes(sessionId)) return true;
 		}
 		return false;

package/src/sdk/broker/lifecycle.ts

@@ -812,6 +812,20 @@ function sameResumeSessionIdentity(left: ResumeScope, right: ResumeScope): boole
 		left.sessionIdentity.sha256 === right.sessionIdentity.sha256
 	);
 }
+function sameSavedTranscriptIdentity(
+	actual: { dev: bigint; ino: bigint; size: number; mtimeMs: number; mtimeNs: bigint; sha256: string },
+	expected: unknown,
+): boolean {
+	return (
+		isSessionLifecycleTranscriptIdentity(expected) &&
+		actual.dev.toString() === expected.dev &&
+		actual.ino.toString() === expected.ino &&
+		actual.size === expected.size &&
+		actual.mtimeMs === expected.mtimeMs &&
+		actual.mtimeNs.toString() === expected.mtimeNs &&
+		actual.sha256 === expected.sha256
+	);
+}
 function sameLiveResumeRecord(expected: LiveResumeRecord, current: LiveResumeRecord): boolean {
 	return (
 		current.live &&
@@ -890,6 +904,7 @@ async function validateSavedTranscript(
 	suppliedPath: string | undefined,
 	expectedSessionId: string | undefined,
 	label: "Saved" | "Source",
+	expectedIdentity?: unknown,
 ): Promise<ValidatedTranscript | BrokerResponse> {
 	const inventory = await managedCandidates(broker, cwd, label);
 	if ("ok" in inventory) return inventory;
@@ -902,6 +917,11 @@ async function validateSavedTranscript(
 	if (matches.length !== 1 || !isCanonicalSessionId(matches[0]!.sessionId))
 		return fail("invalid_input", `${label} saved session does not match the requested workspace and session id.`);
 	const match = matches[0]!;
+	if (expectedIdentity !== undefined && !sameSavedTranscriptIdentity(match.identity, expectedIdentity))
+		return fail(
+			"invalid_input",
+			`${label} saved session does not match the requested workspace, session id, and transcript identity.`,
+		);
 	if (inventory.migrationPolicy === "disabled" && match.provenance === "legacy")
 		return fail("legacy_migration_disabled", `${label} legacy session migration is disabled for this workspace.`);
 	return { path: match.path, id: match.sessionId, identity: serializeTranscriptIdentity(match.identity) };
@@ -959,6 +979,8 @@ async function validateLiveResumeScope(
 	if (matches.length !== 1)
 		return fail("endpoint_stale", "Requested saved session does not match the live session scope.");
 	const session = matches[0]!;
+	if (input.sessionIdentity !== undefined && !sameSavedTranscriptIdentity(session.identity, input.sessionIdentity))
+		return fail("invalid_input", "Saved session transcript identity does not match the requested snapshot.");
 	if (inventory.migrationPolicy === "disabled" && matches[0]!.provenance === "legacy")
 		return fail("legacy_migration_disabled", "Saved legacy session migration is disabled for this workspace.");
 	return {
@@ -1375,7 +1397,7 @@ export async function reapDeadLifecycleMarkers(
 	return reaped;
 }
 
-async function writeEffectMarker(root: string, id: string, marker: EffectMarker): Promise<void> {
+export async function writeEffectMarker(root: string, id: string, marker: EffectMarker): Promise<void> {
 	const directory = path.join(root, "sdk");
 	await fs.mkdir(directory, { recursive: true, mode: 0o700 });
 	const temporary = path.join(directory, `.${id}.lifecycle.${randomUUID()}.tmp`);
@@ -2994,7 +3016,7 @@ async function reconcileLifecycleCleanup(
 	return completion;
 }
 
-async function readSessionLifecycleFailure(
+export async function readSessionLifecycleFailure(
 	root: string,
 	id: string,
 	expected: EffectMarker,
@@ -4031,10 +4053,16 @@ async function currentReadyAuthority(
 			"alive"
 		)
 			return undefined;
+		// Every other field of this authority comes from the indexed record, and
+		// `matchesIndexedEndpointFile` above already proved the on-disk file is
+		// that record's endpoint. Re-deriving the mtime from a fresh `stat` made
+		// the tuple internally inconsistent: the float differed from the indexed
+		// value in its last digits (…272.1147 vs …272.1145), and replay hashing
+		// then read the same endpoint as replaced. Prefer the validated value.
 		return {
 			endpoint: endpoint as Record<string, unknown>,
 			endpointSource,
-			endpointMtimeMs: endpointFile.mtimeMs,
+			endpointMtimeMs: record.endpointMtimeMs ?? endpointFile.mtimeMs,
 			...(record.endpointFileId === undefined ? {} : { endpointFileId: record.endpointFileId }),
 			endpointGeneration: record.endpointGeneration,
 		};
@@ -4392,7 +4420,7 @@ async function launchInput(
 		if (!requested) return fail("invalid_input", "sessionId is required to resume a saved session.");
 		const savedPath = text(input.sessionPath);
 		if (!savedPath) return fail("invalid_input", "sessionPath is required to resume a saved session.");
-		const saved = await validateSavedTranscript(broker, cwd, savedPath, requested, "Saved");
+		const saved = await validateSavedTranscript(broker, cwd, savedPath, requested, "Saved", input.sessionIdentity);
 		if ("ok" in saved) return saved;
 		return {
 			id: requested,
@@ -4417,7 +4445,14 @@ async function launchInput(
 	const sourceSessionPath = text(input.sourceSessionPath) ?? text(input.sourcePath) ?? text(input.sessionPath);
 	if (!sourceSessionId && !sourceSessionPath)
 		return fail("invalid_input", "sourceSessionId or sourceSessionPath is required to fork a session.");
-	const source = await validateSavedTranscript(broker, sourceCwd, sourceSessionPath, sourceSessionId, "Source");
+	const source = await validateSavedTranscript(
+		broker,
+		sourceCwd,
+		sourceSessionPath,
+		sourceSessionId,
+		"Source",
+		input.sourceSessionIdentity,
+	);
 	if ("ok" in source) return source;
 	return {
 		id: randomUUID(),
@@ -4797,7 +4832,10 @@ type CloseRecord = {
 	processIncarnation?: string;
 };
 
-function endpointIncarnation(record: CloseRecord, sessionId: string): string | undefined {
+function endpointIncarnation(
+	record: Pick<CloseRecord, "endpointGeneration" | "endpointMtimeMs" | "pid">,
+	sessionId: string,
+): string | undefined {
 	if (
 		!Number.isSafeInteger(record.endpointGeneration) ||
 		record.endpointGeneration <= 0 ||
@@ -4996,6 +5034,7 @@ async function executeLifecycleResponse(
 						sessionId: requestedSessionId,
 						cwd: finalScope.cwd,
 						endpointGeneration: current.endpointGeneration,
+						endpointIncarnation: initialIncarnation,
 						pid: current.pid,
 						endpointMtimeMs: current.endpointMtimeMs,
 						endpoint: endpoint.result,
@@ -5470,12 +5509,23 @@ async function executeLifecycleResponse(
 						"Session readiness authority changed and its spawned process could not be verified dead.",
 					);
 		}
+		if (!spawnedAuthority) return fail("endpoint_stale", "Session endpoint authority is unavailable.");
+		const replayIncarnation = endpointIncarnation(
+			{
+				endpointGeneration: verified.endpointGeneration,
+				endpointMtimeMs: verified.endpointMtimeMs,
+				pid: spawnedAuthority.pid,
+			},
+			launch.id,
+		);
+		if (!replayIncarnation) return fail("endpoint_stale", "Session endpoint incarnation is unavailable.");
 		return {
 			ok: true,
 			result: {
 				sessionId: launch.id,
 				cwd: launch.cwd,
 				endpointGeneration: verified.endpointGeneration,
+				endpointIncarnation: replayIncarnation,
 				pid: verified.endpoint.pid,
 				endpointMtimeMs: verified.endpointMtimeMs,
 				endpoint: verified.endpoint,