@gajae-code/coding-agent 0.17.2 → 0.17.5

package/src/sdk/broker/session-index.ts

@@ -5,6 +5,7 @@ import { logger, resolveEquivalentPath } from "@gajae-code/utils";
 import { nativeProcessBindings } from "@gajae-code/utils/native-process";
 import { withFileLock } from "../../config/file-lock";
 import { repo } from "../../utils/git";
+import { endpointIncarnation } from "./endpoint-authority";
 import { processIncarnation } from "./process-incarnation";
 import {
 	assertSupportedSessionIndexEventVersion,
@@ -26,7 +27,7 @@ export type SessionIndexEventType =
 	| "record_reconciled";
 
 export type SessionActivityState = "active" | "idle";
-/** Coalesced broker-owned heartbeat checkpoint (C2): state plus the observation time. */
+/** Host-reported or broker-coalesced heartbeat: state plus the observation time. */
 export interface SessionActivity {
 	state: SessionActivityState;
 	at: number;
@@ -34,6 +35,8 @@ export interface SessionActivity {
 /** Events persisted without an OS process incarnation (v1/v2 era) are legacy provenance. */
 export type SessionIdentityProvenance = "composite" | "legacy";
 export type SessionTombstoneRule = "retain" | "expire";
+/** Durable provenance for a retired host registration. */
+export type HostUnregisteredReason = "process_exited" | "detached_idle";
 /**
  * Injected retention policy (C3). The broker schedules compaction independently of
  * rotation; settings apply at the next scheduled compaction. `clock` drives both
@@ -141,6 +144,7 @@ export interface SessionIndexEvent {
 	/** Immutable endpoint file identity captured by the broker at registration. */
 	endpointFileId?: string;
 	lifecycleRequestId?: string;
+	hostUnregisteredReason?: HostUnregisteredReason;
 	terminalUncertain?: boolean;
 	/**
 	 * Distinguishes the terminal-uncertain claim written by a forced stop of a
@@ -170,6 +174,7 @@ export interface IndexedSession {
 	live: boolean;
 	indexSeq: number;
 	lifecycleRequestId?: string;
+	hostUnregisteredReason?: HostUnregisteredReason;
 	terminalUncertain?: boolean;
 	/** True only for a terminal-uncertain claim written by a forced stale-worktree release. */
 	forcedStaleRelease?: boolean;
@@ -345,6 +350,8 @@ function sameIndexChangeStamp(a: SessionIndexChangeStamp, b: SessionIndexChangeS
 const ROTATE_BYTES = 4 * 1024 * 1024;
 /** Coalesced heartbeat checkpoint rate cap (C2): at most one per session per minute. */
 export const SESSION_HEARTBEAT_INTERVAL_MS = 60_000;
+/** A stale-host retirement requires silence well beyond the broker freshness window. */
+export const DEAD_HOST_HEARTBEAT_SILENCE_MS = 10 * SESSION_HEARTBEAT_INTERVAL_MS;
 export const DEFAULT_SESSION_RETENTION_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
 export const DEFAULT_SESSION_RETENTION_MAX_ROWS = 25_000;
 
@@ -571,6 +578,10 @@ function projectIdentity(
 	const { latest, heartbeat } = state;
 	const terminal = isTerminalEvent(latest);
 	const terminalUncertain = latest.type === "lifecycle_terminal" || latest.terminalUncertain === true;
+	const hostUnregisteredReason =
+		latest.hostUnregisteredReason === "process_exited" || latest.hostUnregisteredReason === "detached_idle"
+			? latest.hostUnregisteredReason
+			: undefined;
 	const pidAlive = alive(latest.pid);
 	// Liveness evidence is host-written: a checkpointed heartbeat, or the
 	// `host_registered` event the host appended itself. Counting registration
@@ -606,6 +617,7 @@ function projectIdentity(
 		endpointMtimeMs: latest.endpointMtimeMs,
 		endpointFileId: latest.endpointFileId,
 		lifecycleRequestId: latest.lifecycleRequestId,
+		...(hostUnregisteredReason === undefined ? {} : { hostUnregisteredReason }),
 		terminalUncertain,
 		...(latest.forcedStaleRelease === true ? { forcedStaleRelease: true } : {}),
 		indexSeq: latest.indexSeq,
@@ -1687,6 +1699,82 @@ export class SessionIndex {
 			});
 		});
 	}
+
+	/**
+	 * Atomically fence an exact, long-silent dead-host authority before a caller
+	 * removes state outside the broker index. The comparison and terminal event
+	 * append share the machine-global index lock, so a heartbeat, successor
+	 * registration, or unresolved-authority update that wins the lock prevents
+	 * destructive coordinator cleanup.
+	 */
+	async retireStaleIfCurrent(expected: {
+		sessionId: string;
+		workspace: string;
+		endpointGeneration: number;
+		endpointIncarnation: string;
+	}): Promise<"retired" | "already_retired" | "not_found" | "stale"> {
+		const indexPath = path.resolve(logFor(this.#agentDir));
+		// Process-incarnation observations are gathered before the lock. The locked
+		// projection then uses this fixed batch, avoiding an unbounded OS probe while
+		// holding the machine-global index lock.
+		const probed = new Map<string, string | undefined>();
+		for (const row of reduceEvents(this.#events, this.#policy.clock(), this.#agentDir).identities) {
+			const recordedIncarnation = row.hostIncarnation ?? row.processIncarnation;
+			if (recordedIncarnation === undefined || !alive(row.pid)) continue;
+			probed.set(`${row.sessionId}\u0000${row.endpointGeneration}\u0000${row.pid}`, processIncarnation(row.pid));
+		}
+		return await SessionIndex.#enqueue(indexPath, async () => {
+			try {
+				await fs.stat(dirFor(this.#agentDir));
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code === "ENOENT") return "not_found";
+				throw error;
+			}
+			return await withSessionIndexLock("stale session retirement", this.#agentDir, async () => {
+				await this.#replayUnderLock();
+				if (this.#corruptSuffix) throw new Error("Cannot retire a session from a corrupt session index");
+				const current = this.listSessions(probed).sessions.find(
+					session => session.sessionId === expected.sessionId,
+				);
+				if (!current) return "not_found";
+				if (
+					resolveEquivalentPath(current.locator.cwd) !== resolveEquivalentPath(expected.workspace) ||
+					current.endpointGeneration !== expected.endpointGeneration ||
+					endpointIncarnation(current, expected.sessionId) !== expected.endpointIncarnation
+				)
+					return "stale";
+				if (current.ambiguous || current.terminalUncertain) return "stale";
+				if (current.terminal) return "already_retired";
+				if (
+					current.live !== false ||
+					current.lastHeartbeatAt === undefined ||
+					this.#policy.clock() - current.lastHeartbeatAt < DEAD_HOST_HEARTBEAT_SILENCE_MS
+				)
+					return "stale";
+				const unsigned: Omit<SessionIndexEvent, "checksum"> = {
+					version: SESSION_INDEX_EVENT_VERSION,
+					indexSeq: this.indexSeq + 1,
+					ts: Date.now(),
+					type: "session_closed",
+					sessionId: current.sessionId,
+					locator: current.locator,
+					endpointGeneration: current.endpointGeneration,
+					pid: current.pid,
+					...(current.processIncarnation === undefined ? {} : { processIncarnation: current.processIncarnation }),
+					...(current.hostIncarnation === undefined ? {} : { hostIncarnation: current.hostIncarnation }),
+					...(current.endpointMtimeMs === undefined ? {} : { endpointMtimeMs: current.endpointMtimeMs }),
+					...(current.endpointFileId === undefined ? {} : { endpointFileId: current.endpointFileId }),
+					...(current.lifecycleRequestId === undefined ? {} : { lifecycleRequestId: current.lifecycleRequestId }),
+				};
+				const event: SessionIndexEvent = { ...unsigned, checksum: sessionIndexChecksum(unsigned) };
+				await appendSync(logFor(this.#agentDir), JSON.stringify(event));
+				await this.#refreshUnderLock();
+				if ((await fs.stat(logFor(this.#agentDir))).size >= ROTATE_BYTES) await this.#rotate();
+				return "retired";
+			});
+		});
+	}
+
 	async unregisterIfCurrent(
 		expected: Pick<
 			SessionIndexEvent,
@@ -1701,6 +1789,7 @@ export class SessionIndex {
 			| "processIncarnation"
 			| "hostIncarnation"
 		>,
+		reason?: HostUnregisteredReason,
 	): Promise<boolean> {
 		const indexPath = path.resolve(logFor(this.#agentDir));
 		return await SessionIndex.#enqueue(indexPath, async () => {
@@ -1781,6 +1870,7 @@ export class SessionIndex {
 					...(expected.lifecycleRequestId === undefined
 						? {}
 						: { lifecycleRequestId: expected.lifecycleRequestId }),
+					...(reason === undefined ? {} : { hostUnregisteredReason: reason }),
 				};
 				const event: SessionIndexEvent = { ...unsigned, checksum: sessionIndexChecksum(unsigned) };
 				await appendSync(logFor(this.#agentDir), JSON.stringify(event));
@@ -1866,10 +1956,10 @@ export class SessionIndex {
 		this.#changeStamp = await readIndexChangeStamp(this.#agentDir);
 	}
 
-	listSessions(): SessionList {
+	listSessions(probedIncarnations?: ReadonlyMap<string, string | undefined>): SessionList {
 		return {
 			indexSeq: this.indexSeq,
-			sessions: reduceEvents(this.#events, this.#policy.clock(), this.#agentDir).sessions,
+			sessions: reduceEvents(this.#events, this.#policy.clock(), this.#agentDir, probedIncarnations).sessions,
 			warnings: this.#warnings,
 		};
 	}
@@ -2323,7 +2413,10 @@ export class SessionIndex {
 						...(row.processIncarnation === undefined ? {} : { processIncarnation: row.processIncarnation }),
 						...(row.hostIncarnation === undefined ? {} : { hostIncarnation: row.hostIncarnation }),
 						...(row.masterRole === undefined ? {} : { masterRole: row.masterRole }),
-						activity: { state: "active", at: now },
+						// Preserve the host's last observed activity state while this
+						// broker-owned heartbeat only renews liveness. A live idle host
+						// must not be rewritten as active merely because its pid is alive.
+						activity: row.activity ?? { state: "active", at: now },
 						ts: now,
 					};
 					events.push({ ...unsigned, checksum: sessionIndexChecksum(unsigned) });

package/src/sdk/broker/spawn-authority.ts

@@ -23,6 +23,8 @@ export type SpawnClaimV2 = {
 	failure?: SpawnSubstrateFailure;
 	preSendLease?: { epoch: string; status: "owned" | "consumed" };
 	childId?: string;
+	/** Launch proof retained while registration is still unbound so a later retry can re-prove or close it. */
+	substrateProof?: SpawnSubstrateProof;
 	seed?: SeedDeliveryV2;
 	authorityRef?: string;
 	createdAt: number;
@@ -139,6 +141,8 @@ export type SpawnClaimTransition = {
 	leaseEpoch?: string;
 	/** The fresh child ID is committed before substrate launch. */
 	childId?: string;
+	/** Launch proof may be appended to the pre-registration state for later reconciliation. */
+	substrateProof?: SpawnSubstrateProof;
 	/** Required for seed and terminal state transitions that carry Q26 facts. */
 	seed?: SeedDeliveryV2;
 	failure?: SpawnSubstrateFailure;
@@ -166,7 +170,8 @@ export type SpawnClaimDecision =
 	| { kind: "replay"; claim: SpawnClaimV2 }
 	| { kind: "terminal"; claim: SpawnClaimV2 }
 	| { kind: "terminal_uncertain"; claim: SpawnClaimV2 }
-	| { kind: "idempotency_conflict"; claim: SpawnClaimV2 };
+	| { kind: "idempotency_conflict"; claim: SpawnClaimV2 }
+	| { kind: "managed_key_conflict" };
 
 type StoredClaim = {
 	version: 1;
@@ -175,6 +180,15 @@ type StoredClaim = {
 	integrity: string;
 };
 
+type ManagedKeyReservation = {
+	version: 1;
+	kind: "managed_key_reservation";
+	aliasIdentities: string[];
+	managedIdentity: string;
+	controlRoot: string;
+	integrity: string;
+};
+
 type SpawnAuthorityDurableWrite = {
 	claim: SpawnClaimV2;
 	authority?: SpawnAuthorityV1;
@@ -225,6 +239,7 @@ const CLAIM_KEYS = new Set([
 	"failure",
 	"preSendLease",
 	"childId",
+	"substrateProof",
 	"seed",
 	"authorityRef",
 	"createdAt",
@@ -272,13 +287,13 @@ const FORBIDDEN_FIELD =
 	/(?:task|prompt|capability|idempotency|fingerprint|requesthash|digest|credential|token|secret|password|stderr)/i;
 const TRANSITION_EDGES: Readonly<Record<SpawnClaimV2["state"], readonly SpawnClaimV2["state"][]>> = {
 	prepared: ["substrate_starting", "pre_send_rejected", "uncertain", "closed"],
-	substrate_starting: ["authority_active", "pre_send_rejected", "uncertain", "closed"],
+	substrate_starting: ["substrate_starting", "authority_active", "pre_send_rejected", "uncertain", "closed"],
 	authority_active: ["seed_prepared", "pre_send_rejected", "uncertain", "closed"],
 	seed_prepared: ["dispatching", "pre_send_rejected", "uncertain", "closed"],
 	dispatching: ["accepted", "pre_send_rejected", "uncertain", "closed"],
 	accepted: ["uncertain", "closed"],
 	pre_send_rejected: ["uncertain", "closed"],
-	uncertain: ["closed"],
+	uncertain: ["pre_send_rejected", "closed"],
 	closed: [],
 };
 
@@ -476,6 +491,7 @@ export function isSpawnClaimV2(value: unknown): value is SpawnClaimV2 {
 				((lease as { status?: unknown }).status === "owned" ||
 					(lease as { status?: unknown }).status === "consumed"))) &&
 		(claim.childId === undefined || isOpaque(claim.childId)) &&
+		(claim.substrateProof === undefined || isSpawnSubstrateProof(claim.substrateProof)) &&
 		(claim.seed === undefined || isSeed(claim.seed)) &&
 		(claim.authorityRef === undefined || isOpaque(claim.authorityRef)) &&
 		(claim.failure === undefined || isSpawnSubstrateFailure(claim.failure)) &&
@@ -554,6 +570,8 @@ export class SpawnAuthorityStore {
 	readonly #options: SpawnAuthorityStoreOptions;
 	readonly #latest = new Map<string, SpawnClaimV2>();
 	readonly #authorities = new Map<string, SpawnAuthorityV1>();
+	readonly #managedKeyAliases = new Map<string, Map<string, string>>();
+	readonly #managedIdentityBindings = new Map<string, { aliasIdentities: string[]; controlRoot: string }>();
 	readonly #active = new Set<string>();
 	#tail: Promise<void> = Promise.resolve();
 
@@ -586,6 +604,8 @@ export class SpawnAuthorityStore {
 			await fs.mkdir(path.dirname(this.#file), { recursive: true, mode: 0o700 });
 			this.#latest.clear();
 			this.#authorities.clear();
+			this.#managedKeyAliases.clear();
+			this.#managedIdentityBindings.clear();
 			let source = "";
 			try {
 				source = await Bun.file(this.#file).text();
@@ -600,6 +620,12 @@ export class SpawnAuthorityStore {
 				} catch {
 					throw new Error("Spawn authority journal contains malformed durable evidence.");
 				}
+				if (this.#isManagedKeyReservation(row)) {
+					const reservation = row as ManagedKeyReservation;
+					if (!this.#rememberManagedKeyReservation(reservation))
+						throw new Error("Spawn authority journal managed key history is invalid.");
+					continue;
+				}
 				if (!this.#isStoredClaim(row))
 					throw new Error("Spawn authority journal contains invalid durable evidence.");
 				const stored = row as StoredClaim;
@@ -610,6 +636,52 @@ export class SpawnAuthorityStore {
 				if (stored.authority) this.#authorities.set(stored.claim.lifecycleIdentity, stored.authority);
 				else this.#authorities.delete(stored.claim.lifecycleIdentity);
 			}
+			for (const alias of this.#managedKeyAliases.keys())
+				if (this.#latest.has(alias)) throw new Error("Spawn authority journal aliases an ordinary claim.");
+		});
+	}
+
+	/**
+	 * Durably reserves an ordinary session.spawn idempotency identity for one
+	 * managed native identity. Multiple managed roots may share the alias, but an
+	 * ordinary claim and a managed reservation can never both win.
+	 */
+	async reserveManagedKeyAliases(
+		aliasIdentities: readonly string[],
+		managedIdentity: string,
+		controlRoot: string,
+	): Promise<boolean> {
+		const aliases = [...new Set(aliasIdentities)].sort();
+		if (
+			aliases.length === 0 ||
+			aliases.some(identity => !/^[0-9a-f]{64}$/i.test(identity)) ||
+			!/^[0-9a-f]{64}$/i.test(managedIdentity) ||
+			!path.isAbsolute(controlRoot) ||
+			path.normalize(controlRoot) !== controlRoot
+		)
+			throw new Error("Invalid managed spawn key reservation.");
+		return await this.#serial(async () => {
+			if (aliases.some(alias => this.#latest.has(alias))) return false;
+			const prior = this.#managedIdentityBindings.get(managedIdentity);
+			if (prior)
+				return prior.controlRoot === controlRoot && canonicalJson(prior.aliasIdentities) === canonicalJson(aliases);
+			for (const alias of aliases) {
+				const roots = this.#managedKeyAliases.get(alias);
+				const existingRoot = roots?.get(managedIdentity);
+				if (existingRoot !== undefined && existingRoot !== controlRoot) return false;
+			}
+			const reservation: ManagedKeyReservation = {
+				version: 1,
+				kind: "managed_key_reservation",
+				aliasIdentities: aliases,
+				managedIdentity,
+				controlRoot,
+				integrity: "",
+			};
+			reservation.integrity = this.#managedKeyReservationIntegrity(reservation);
+			await this.#appendRow(reservation);
+			this.#rememberManagedKeyReservation(reservation);
+			return true;
 		});
 	}
 
@@ -626,6 +698,7 @@ export class SpawnAuthorityStore {
 		)
 			throw new Error("Invalid opaque spawn claim key.");
 		return await this.#serial(async () => {
+			if (this.#managedKeyAliases.has(lifecycleIdentity)) return { kind: "managed_key_conflict" };
 			const current = this.#latest.get(lifecycleIdentity);
 			if (!current) {
 				if (bindingMac === undefined) throw new Error("A canonical spawn binding is required for a new claim.");
@@ -698,10 +771,19 @@ export class SpawnAuthorityStore {
 						!isOpaque(transition.childId) ||
 						transition.seed !== undefined ||
 						transition.authority !== undefined ||
-						transition.failure !== undefined
+						transition.failure !== undefined ||
+						(transition.substrateProof !== undefined && !isSpawnSubstrateProof(transition.substrateProof)) ||
+						(current.state === "prepared" && transition.substrateProof !== undefined) ||
+						(current.state === "substrate_starting" && transition.substrateProof === undefined) ||
+						(current.state === "substrate_starting" && transition.childId !== current.childId)
 					)
 						throw new SpawnAuthorityTransitionError("invalid_transition");
-					next = { ...current, state: "substrate_starting", childId: transition.childId };
+					next = {
+						...current,
+						state: "substrate_starting",
+						childId: transition.childId,
+						...(transition.substrateProof === undefined ? {} : { substrateProof: transition.substrateProof }),
+					};
 					break;
 				}
 				case "authority_active": {
@@ -804,7 +886,11 @@ export class SpawnAuthorityStore {
 					break;
 				}
 				case "uncertain": {
-					if (transition.childId !== undefined || transition.authority !== undefined)
+					if (
+						transition.childId !== undefined ||
+						transition.authority !== undefined ||
+						(transition.failure !== undefined && !isSpawnSubstrateFailure(transition.failure))
+					)
 						throw new SpawnAuthorityTransitionError("invalid_transition");
 					if (current.seed) {
 						if (
@@ -813,10 +899,19 @@ export class SpawnAuthorityStore {
 							!sameSeedIdentity(current.seed, transition.seed)
 						)
 							throw new SpawnAuthorityTransitionError("invalid_transition");
-						next = { ...current, state: "uncertain", seed: transition.seed };
+						next = {
+							...current,
+							state: "uncertain",
+							seed: transition.seed,
+							...(transition.failure === undefined ? {} : { failure: transition.failure }),
+						};
 					} else {
 						if (transition.seed !== undefined) throw new SpawnAuthorityTransitionError("invalid_transition");
-						next = { ...current, state: "uncertain" };
+						next = {
+							...current,
+							state: "uncertain",
+							...(transition.failure === undefined ? {} : { failure: transition.failure }),
+						};
 					}
 					break;
 				}
@@ -936,6 +1031,68 @@ export class SpawnAuthorityStore {
 			.digest("hex");
 	}
 
+	#managedKeyReservationIntegrity(reservation: ManagedKeyReservation): string {
+		const { integrity: _integrity, ...facts } = reservation;
+		return createHmac("sha256", this.#identityKey).update(canonicalJson(facts)).digest("hex");
+	}
+
+	#isManagedKeyReservation(value: unknown): value is ManagedKeyReservation {
+		if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+		const row = value as Partial<ManagedKeyReservation>;
+		return (
+			Object.keys(row).every(
+				key =>
+					key === "version" ||
+					key === "kind" ||
+					key === "aliasIdentities" ||
+					key === "managedIdentity" ||
+					key === "controlRoot" ||
+					key === "integrity",
+			) &&
+			row.version === 1 &&
+			row.kind === "managed_key_reservation" &&
+			Array.isArray(row.aliasIdentities) &&
+			row.aliasIdentities.length > 0 &&
+			row.aliasIdentities.every(identity => typeof identity === "string" && /^[0-9a-f]{64}$/i.test(identity)) &&
+			new Set(row.aliasIdentities).size === row.aliasIdentities.length &&
+			canonicalJson(row.aliasIdentities) === canonicalJson([...row.aliasIdentities].sort()) &&
+			typeof row.managedIdentity === "string" &&
+			/^[0-9a-f]{64}$/i.test(row.managedIdentity) &&
+			typeof row.controlRoot === "string" &&
+			path.isAbsolute(row.controlRoot) &&
+			path.normalize(row.controlRoot) === row.controlRoot &&
+			typeof row.integrity === "string" &&
+			/^[0-9a-f]{64}$/i.test(row.integrity) &&
+			timingSafeEqual(
+				Buffer.from(row.integrity, "hex"),
+				Buffer.from(this.#managedKeyReservationIntegrity(row as ManagedKeyReservation), "hex"),
+			)
+		);
+	}
+
+	#rememberManagedKeyReservation(reservation: ManagedKeyReservation): boolean {
+		const prior = this.#managedIdentityBindings.get(reservation.managedIdentity);
+		if (
+			prior &&
+			(prior.controlRoot !== reservation.controlRoot ||
+				canonicalJson(prior.aliasIdentities) !== canonicalJson(reservation.aliasIdentities))
+		)
+			return false;
+		if (prior) return false;
+		this.#managedIdentityBindings.set(reservation.managedIdentity, {
+			aliasIdentities: [...reservation.aliasIdentities],
+			controlRoot: reservation.controlRoot,
+		});
+		for (const alias of reservation.aliasIdentities) {
+			const roots = this.#managedKeyAliases.get(alias) ?? new Map<string, string>();
+			const existingRoot = roots.get(reservation.managedIdentity);
+			if (existingRoot !== undefined && existingRoot !== reservation.controlRoot) return false;
+			roots.set(reservation.managedIdentity, reservation.controlRoot);
+			this.#managedKeyAliases.set(alias, roots);
+		}
+		return true;
+	}
+
 	#isStoredClaim(value: unknown): value is StoredClaim {
 		if (!value || typeof value !== "object" || Array.isArray(value)) return false;
 		const row = value as Partial<StoredClaim>;
@@ -961,6 +1118,13 @@ export class SpawnAuthorityStore {
 			throw new Error("Refusing to persist invalid spawn authority evidence.");
 		const write: SpawnAuthorityDurableWrite = { claim, ...(authority === undefined ? {} : { authority }) };
 		const row: StoredClaim = { version: 1, ...write, integrity: this.#integrity(claim, authority) };
+		await this.#appendRow(row, write);
+		this.#latest.set(claim.lifecycleIdentity, claim);
+		if (authority) this.#authorities.set(claim.lifecycleIdentity, authority);
+		else this.#authorities.delete(claim.lifecycleIdentity);
+	}
+
+	async #appendRow(row: unknown, write?: SpawnAuthorityDurableWrite): Promise<void> {
 		// The row is appended before the durability barrier, so a barrier failure
 		// can leave a physically written line that in-memory state never accepted.
 		// A retry would then append a second row for the same claim and reopen
@@ -981,13 +1145,13 @@ export class SpawnAuthorityStore {
 		try {
 			try {
 				await handle.writeFile(`${canonicalJson(row)}\n`);
-				await this.#options.beforeSyncForTest?.(write);
+				if (write) await this.#options.beforeSyncForTest?.(write);
 				await handle.sync();
 				// The parent-directory barrier belongs INSIDE the rolled-back region:
 				// a throw here would otherwise leave a durable row that in-memory
 				// state never accepted, and the retry would append a duplicate that
 				// makes the journal unreopenable.
-				await this.#options.beforeDirectorySyncForTest?.(write);
+				if (write) await this.#options.beforeDirectorySyncForTest?.(write);
 				const directory = await fs.open(path.dirname(this.#file), fsSync.constants.O_RDONLY);
 				try {
 					await directory.sync();
@@ -1011,10 +1175,7 @@ export class SpawnAuthorityStore {
 		} finally {
 			await handle.close();
 		}
-		this.#latest.set(claim.lifecycleIdentity, claim);
-		if (authority) this.#authorities.set(claim.lifecycleIdentity, authority);
-		else this.#authorities.delete(claim.lifecycleIdentity);
-		await this.#options.afterSyncForTest?.(write);
+		if (write) await this.#options.afterSyncForTest?.(write);
 	}
 
 	async #serial<T>(operation: () => Promise<T>): Promise<T> {

package/src/sdk/broker/startup-failure.ts

@@ -5,6 +5,8 @@ import { processIncarnation } from "./process-incarnation";
 export interface BrokerStartupFailureMarker {
 	version: 2;
 	reason: string;
+	/** Validated manual lock cleanup command, stored separately when it cannot fit in `reason`. */
+	cleanupCommand?: string;
 	exitCode: number | null;
 	signal: string | null;
 	writtenAt: number;
@@ -23,11 +25,82 @@ export interface BrokerStartupFailureMarker {
 
 const BROKER_STARTUP_FAILURE_FILE = "broker.startup-failure.json";
 const MAX_BROKER_STARTUP_FAILURE_REASON = 512;
+// Windows extended paths can be 32,767 UTF-16 code units and PowerShell quoting
+// can double every apostrophe; this also comfortably covers POSIX PATH_MAX paths.
+const MAX_BROKER_STARTUP_FAILURE_CLEANUP_COMMAND = 66_000;
+const FILE_LOCK_CLEANUP_GUIDANCE =
+	"; manual cleanup is appropriate only after independently verifying this exact directory still belongs to the dead owner and no successor has taken it: ";
+const FILE_LOCK_OWNER_GUIDANCE =
+	"; a live owner is never displaced — if this is an SDK broker (gjc sdk session list), it must finish or be stopped before retrying";
+const COMPACT_FILE_LOCK_CLEANUP_GUIDANCE =
+	"Manual cleanup is appropriate only after independently verifying this exact directory still belongs to the dead owner and no successor has taken it: ";
+
+function decodeFileLockCleanupCommand(command: string): string | undefined {
+	if (command.length === 0 || command.length > MAX_BROKER_STARTUP_FAILURE_CLEANUP_COMMAND) return undefined;
+	const prefix = process.platform === "win32" ? "Remove-Item -LiteralPath '" : "rm -rf -- '";
+	const suffix = process.platform === "win32" ? "' -Recurse -Force" : "'";
+	if (!command.startsWith(prefix) || !command.endsWith(suffix)) return undefined;
+
+	const encodedPath = command.slice(prefix.length, -suffix.length);
+	const quoteEscape = process.platform === "win32" ? "''" : "'\\''";
+	const decodedPath = encodedPath.replaceAll(quoteEscape, "'");
+	if (!decodedPath || decodedPath.replaceAll("'", quoteEscape) !== encodedPath) return undefined;
+	return decodedPath;
+}
+
+function validatedFileLockCleanupCommand(reason: string): string | undefined {
+	let guidanceIndex = reason.indexOf(FILE_LOCK_CLEANUP_GUIDANCE);
+	while (guidanceIndex >= 0) {
+		const command = reason.slice(guidanceIndex + FILE_LOCK_CLEANUP_GUIDANCE.length);
+		const lockPath = decodeFileLockCleanupCommand(command);
+		if (lockPath) {
+			const beforeCleanup = reason.slice(0, guidanceIndex);
+			const lockAndOwnerGuidance = ` (${lockPath})${FILE_LOCK_OWNER_GUIDANCE}`;
+			const acquisition = beforeCleanup.endsWith(lockAndOwnerGuidance)
+				? beforeCleanup.slice(0, -lockAndOwnerGuidance.length)
+				: "";
+			if (/^Failed to acquire lock for [\s\S]+ after \d+ attempts: [\s\S]+$/.test(acquisition)) {
+				return command;
+			}
+		}
+		guidanceIndex = reason.indexOf(FILE_LOCK_CLEANUP_GUIDANCE, guidanceIndex + 1);
+	}
+	return undefined;
+}
+
+function boundedFailureDetails(reason: string): { reason: string; cleanupCommand?: string } {
+	if (reason.length <= MAX_BROKER_STARTUP_FAILURE_REASON) return { reason };
+
+	const cleanupCommand = validatedFileLockCleanupCommand(reason);
+	if (cleanupCommand) {
+		const compactReason = `${COMPACT_FILE_LOCK_CLEANUP_GUIDANCE}${cleanupCommand}`;
+		if (compactReason.length <= MAX_BROKER_STARTUP_FAILURE_REASON) return { reason: compactReason };
+		return { reason: COMPACT_FILE_LOCK_CLEANUP_GUIDANCE, cleanupCommand };
+	}
+
+	return { reason: reason.slice(0, MAX_BROKER_STARTUP_FAILURE_REASON) };
+}
 
 export function brokerStartupFailurePath(agentDir: string): string {
 	return path.join(agentDir, "sdk", BROKER_STARTUP_FAILURE_FILE);
 }
 
+/** Whether validated compact cleanup guidance targets the exact lock path. */
+export function brokerStartupFailureCleanupTargetsLock(
+	marker: BrokerStartupFailureMarker | undefined,
+	lockPath: string,
+): boolean {
+	if (!marker) return false;
+	if (marker.cleanupCommand !== undefined) {
+		return (
+			marker.reason === COMPACT_FILE_LOCK_CLEANUP_GUIDANCE &&
+			decodeFileLockCleanupCommand(marker.cleanupCommand) === lockPath
+		);
+	}
+	if (!marker.reason.startsWith(COMPACT_FILE_LOCK_CLEANUP_GUIDANCE)) return false;
+	return decodeFileLockCleanupCommand(marker.reason.slice(COMPACT_FILE_LOCK_CLEANUP_GUIDANCE.length)) === lockPath;
+}
+
 function boundedMarker(
 	reason: string,
 	exitCode: number | null,
@@ -35,9 +108,10 @@ function boundedMarker(
 	pid: number,
 	incarnation: string,
 ): BrokerStartupFailureMarker {
+	const boundedFailure = boundedFailureDetails(reason);
 	return {
 		version: 2,
-		reason: reason.slice(0, MAX_BROKER_STARTUP_FAILURE_REASON),
+		...boundedFailure,
 		exitCode,
 		signal,
 		writtenAt: Date.now(),
@@ -84,6 +158,11 @@ export async function readBrokerStartupFailureMarker(
 			marker.version !== 2 ||
 			typeof marker.reason !== "string" ||
 			marker.reason.length === 0 ||
+			marker.reason.length > MAX_BROKER_STARTUP_FAILURE_REASON ||
+			(marker.cleanupCommand !== undefined &&
+				(typeof marker.cleanupCommand !== "string" ||
+					marker.reason !== COMPACT_FILE_LOCK_CLEANUP_GUIDANCE ||
+					decodeFileLockCleanupCommand(marker.cleanupCommand) === undefined)) ||
 			(marker.exitCode !== null && typeof marker.exitCode !== "number") ||
 			(marker.signal !== null && typeof marker.signal !== "string") ||
 			typeof marker.writtenAt !== "number" ||