@gajae-code/coding-agent 0.17.1 → 0.17.4

package/src/sdk/broker/ensure.ts

@@ -70,6 +70,72 @@ const SPAWN_LOCK_RETRY_DELAY_MS = 50;
 const SPAWN_LOCK_TARGET_NAME = "broker.spawn";
 const STARTUP_LOCK_TARGET_NAME = "broker.startup";
 
+export interface BrokerStartupLockTestHooks {
+	onAcquired?: () => void;
+	onContended?: () => void;
+}
+
+/**
+ * Test-only phase observation for detached broker startup regressions. The
+ * signal is opt-in through the child environment and never affects broker
+ * ownership or error handling when the test seam is absent.
+ */
+export async function emitBrokerStartupTestSignal(signal: string): Promise<void> {
+	const directory = process.env.GJC_SDK_TEST_BROKER_SIGNAL_DIR;
+	if (!directory || !/^[a-z0-9-]+$/.test(signal)) return;
+	try {
+		await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+		await fs.writeFile(path.join(directory, signal), `${process.pid}\n`);
+	} catch {
+		// Test observability must never change broker startup semantics.
+	}
+}
+
+/**
+ * The parent discovery budget published as a composition rather than a number.
+ * A test that stages a fence contention has to time itself against these legs,
+ * and retyping the sum makes it win or lose on scheduler noise while letting a
+ * change to any single leg silently re-tune it (#5604). This is the one source
+ * of truth for how the budget is built; nothing may restate the arithmetic.
+ */
+export const BROKER_DISCOVERY_BUDGET = {
+	staleRetirementMs: STALE_BROKER_RETIREMENT_TIMEOUT_MS,
+	startupLockWaitMs: STARTUP_LOCK_WAIT_MS,
+	publicationMs: BROKER_PUBLICATION_TIMEOUT_MS,
+	/** What the startup fence grants its holder: retirement plus one publication attempt. */
+	fenceOperationMs: STALE_BROKER_RETIREMENT_TIMEOUT_MS + BROKER_PUBLICATION_TIMEOUT_MS,
+	/**
+	 * When a child spawned under the parent's spawn lock gives up on the fence,
+	 * measured from that lock acquisition: the parent retires the stale incumbent
+	 * first, then the child exhausts its own fence wait. Not a production
+	 * constant -- an emergent property of the two legs that precede publication.
+	 */
+	childFenceWaitMs: STALE_BROKER_RETIREMENT_TIMEOUT_MS + STARTUP_LOCK_WAIT_MS,
+	discoveryMs: DISCOVERY_TIMEOUT_MS,
+} as const;
+
+const sleep = (ms: number): Promise<void> => new Promise(resolve => setTimeout(resolve, ms));
+
+/**
+ * Clock the discovery budget is measured on. The default is the real one; a test
+ * installs a virtual clock to assert the composition order -- stale retirement,
+ * then the child fence, then startup and publication -- in-process instead of
+ * racing three wall clocks against each other (#5604). Reaping keeps its own
+ * {@link ReapTiming} seam and is deliberately not driven from here.
+ */
+export interface EnsureBrokerTiming {
+	now(): number;
+	sleep(ms: number): Promise<void>;
+}
+
+const REAL_ENSURE_BROKER_TIMING: EnsureBrokerTiming = { now: Date.now, sleep };
+let ensureBrokerTiming: EnsureBrokerTiming = REAL_ENSURE_BROKER_TIMING;
+
+/** Test hook: drives the discovery budget on a controllable clock. */
+export function setEnsureBrokerTimingForTest(timing: EnsureBrokerTiming | undefined): void {
+	ensureBrokerTiming = timing ?? REAL_ENSURE_BROKER_TIMING;
+}
+
 type SpawnLockOptions = Pick<FileLockOptions, "retries" | "retryDelayMs" | "signal">;
 
 interface BrokerLockHostIdentity {
@@ -104,7 +170,7 @@ async function readBrokerDiscoveryBeforeDeadline(
 	heartbeatTtlMs: number | undefined,
 	deadline: number,
 ): Promise<BrokerDiscovery | null> {
-	const remainingMs = deadline - Date.now();
+	const remainingMs = deadline - ensureBrokerTiming.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);
@@ -151,14 +217,17 @@ async function acquireSpawnLock(agentDir: string, options: SpawnLockOptions = {}
 export async function withBrokerStartupLock<T>(
 	agentDir: string,
 	operation: (deadline: number) => Promise<T>,
+	testHooks: BrokerStartupLockTestHooks = {},
 ): 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),
+		() => operation(ensureBrokerTiming.now() + BROKER_DISCOVERY_BUDGET.fenceOperationMs),
 		{
 			retries: Math.ceil(STARTUP_LOCK_WAIT_MS / SPAWN_LOCK_RETRY_DELAY_MS),
 			retryDelayMs: SPAWN_LOCK_RETRY_DELAY_MS,
+			onAcquired: testHooks.onAcquired,
+			onContended: testHooks.onContended,
 			...hostIdentity,
 		},
 	);
@@ -275,7 +344,6 @@ const DEFAULT_REAP_TIMING: ReapTiming = {
 	gracefulMs: REAP_GRACEFUL_MS,
 	killVerifyMs: REAP_SIGKILL_CAP_MS,
 };
-const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
 
 /**
  * Terminate and reap a detached broker this process spawned, targeting the exact
@@ -410,9 +478,9 @@ export async function closeBrokerClientBeforeDeadline(
 ): Promise<void> {
 	const close = client.close();
 	void close.catch(() => undefined);
-	const remainingMs = deadline - Date.now();
+	const remainingMs = deadline - ensureBrokerTiming.now();
 	if (remainingMs <= 0) return;
-	await Promise.race([close, Bun.sleep(remainingMs)]);
+	await Promise.race([close, ensureBrokerTiming.sleep(remainingMs)]);
 }
 
 async function retireUnusableBroker(
@@ -420,7 +488,7 @@ async function retireUnusableBroker(
 	settings: EnsureBrokerSettings,
 	outerDeadline = Number.POSITIVE_INFINITY,
 ): Promise<void> {
-	const deadline = Math.min(outerDeadline, Date.now() + STALE_BROKER_RETIREMENT_TIMEOUT_MS);
+	const deadline = Math.min(outerDeadline, ensureBrokerTiming.now() + BROKER_DISCOVERY_BUDGET.staleRetirementMs);
 	let shutdownSucceeded = false;
 	try {
 		const current = await readBrokerDiscoveryBeforeDeadline(settings.agentDir, settings.heartbeatTtlMs, deadline);
@@ -443,10 +511,10 @@ async function retireUnusableBroker(
 		} catch {}
 	}
 	// Wait for the stale identity to disappear (owner-fenced: pid+incarnation).
-	while (Date.now() < deadline) {
+	while (ensureBrokerTiming.now() < deadline) {
 		const current = await readBrokerDiscoveryBeforeDeadline(settings.agentDir, settings.heartbeatTtlMs, deadline);
 		if (!sameBrokerOwner(current, stale)) break;
-		await sleep(STALE_BROKER_POLL_MS);
+		await ensureBrokerTiming.sleep(STALE_BROKER_POLL_MS);
 	}
 }
 
@@ -459,6 +527,7 @@ export async function reconcileBrokerGenerationForStartup(
 	if (!current) return undefined;
 	if (await isBrokerReusable(current)) return current;
 	await retireUnusableBroker(current, settings, deadline);
+	await emitBrokerStartupTestSignal("retirement-finished");
 	const replacement = await readBrokerDiscoveryBeforeDeadline(settings.agentDir, settings.heartbeatTtlMs, deadline);
 	return replacement && (await isBrokerReusable(replacement)) ? replacement : undefined;
 }
@@ -506,7 +575,7 @@ 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);
+		ensureBrokerTiming.now() + (initiator === "fixture-lease" ? FIXTURE_DISCOVERY_TIMEOUT_MS : DISCOVERY_TIMEOUT_MS);
 	const priorOwner = owners.get(settings.agentDir);
 	const existing = await readBrokerDiscoveryBeforeDeadline(
 		settings.agentDir,
@@ -514,7 +583,11 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 		initialDiscoveryDeadline,
 	);
 	const restartIntent = await readBrokerRestartIntent(settings.agentDir);
-	if (restartIntent && restartIntent.expiresAt > Date.now() && restartIntent.requestId !== settings.restartRequestId)
+	if (
+		restartIntent &&
+		restartIntent.expiresAt > ensureBrokerTiming.now() &&
+		restartIntent.requestId !== settings.restartRequestId
+	)
 		throw new Error("broker_restart_in_progress");
 	if (initiator === "fixture-lease" && (priorOwner || existing)) throw fixtureLeaseUnavailable();
 	if (priorOwner) {
@@ -543,9 +616,14 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 	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);
+			ensureBrokerTiming.now() +
+			(initiator === "fixture-lease" ? FIXTURE_DISCOVERY_TIMEOUT_MS : DISCOVERY_TIMEOUT_MS);
 		const lockedIntent = await readBrokerRestartIntent(settings.agentDir);
-		if (lockedIntent && lockedIntent.expiresAt > Date.now() && lockedIntent.requestId !== settings.restartRequestId)
+		if (
+			lockedIntent &&
+			lockedIntent.expiresAt > ensureBrokerTiming.now() &&
+			lockedIntent.requestId !== settings.restartRequestId
+		)
 			throw new Error("broker_restart_in_progress");
 		// The lock winner may still find a discovery published by an earlier winner
 		// that finished between our first read and the lock acquisition.
@@ -572,7 +650,7 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 		// 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) {
+		while (ensureBrokerTiming.now() < deadline) {
 			if (spawnError || child.exitCode !== null || child.signalCode !== null) break;
 			try {
 				const discovered = await readBrokerDiscoveryBeforeDeadline(
@@ -582,7 +660,7 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 				);
 				if (discovered) {
 					if (!(await isBrokerReusable(discovered))) {
-						await sleep(50);
+						await ensureBrokerTiming.sleep(50);
 						continue;
 					}
 					if (owner.markReady(discovered)) {
@@ -596,7 +674,7 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 			} catch (error) {
 				discoveryError = error;
 			}
-			await sleep(50);
+			await ensureBrokerTiming.sleep(50);
 		}
 		const exitedBeforeDiscovery = child.exitCode !== null || child.signalCode !== null;
 		if (exitedBeforeDiscovery && child.exitCode === 0) {
@@ -616,7 +694,7 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 						await owner.stop();
 						return { kind: "external-discovery", discovery: winner };
 					}
-					await sleep(50);
+					await ensureBrokerTiming.sleep(50);
 				}
 			} catch {
 				// fall through to cleanup + failure
@@ -649,8 +727,8 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 			// 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) {
+			const recoveryDeadline = Math.min(deadline, ensureBrokerTiming.now() + BROKER_DISCOVERY_BUDGET.publicationMs);
+			while (ensureBrokerTiming.now() < recoveryDeadline) {
 				try {
 					const incumbent = await readBrokerDiscoveryBeforeDeadline(
 						settings.agentDir,
@@ -665,7 +743,7 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 					// Keep the bounded retry alive; a transient read failure is not
 					// authority to classify the incumbent as failed.
 				}
-				await sleep(50);
+				await ensureBrokerTiming.sleep(50);
 			}
 		}
 		const spawnLogTail = exitedBeforeDiscovery && spawnLog ? await readBrokerSpawnLogTail(spawnLog.path) : "";

package/src/sdk/broker/identity.ts

@@ -43,8 +43,16 @@ export async function deriveIdempotencyIdentity(
 	agentDir: string,
 	operation: string,
 	callerKey: string,
-	_protocolVersionOrLegacyTargetHash?: string,
+	targetHash?: string,
 ): Promise<string> {
+	const key = await getBrokerIdentityKey(agentDir);
+	return createHmac("sha256", Buffer.from(key, "hex"))
+		.update(`4|${operation}|${callerKey}|${targetHash ?? ""}`)
+		.digest("hex");
+}
+
+/** Identity format used by lifecycle rows written before target binding. */
+export async function deriveLegacyIdentity(agentDir: string, operation: string, callerKey: string): Promise<string> {
 	const key = await getBrokerIdentityKey(agentDir);
 	return createHmac("sha256", Buffer.from(key, "hex")).update(`3|${operation}|${callerKey}`).digest("hex");
 }

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

@@ -100,6 +100,32 @@ export type BeginResult =
 	| { kind: "idempotency_conflict" }
 	| { kind: "terminal_uncertain"; entry: LifecycleLedgerEntry }
 	| { kind: "in_progress"; entry: LifecycleLedgerEntry };
+
+type BoundedSourceReadRejection = "not-regular-file" | "oversized-by-stat" | "oversized-by-read" | "read-error";
+
+/**
+ * Why a terminal read-back produced no entry. `absent` means nothing terminal is
+ * recorded for the request; `rejected` means the source or a row was refused, which
+ * is evidence of a damaged ledger rather than of an unpersisted operation. Collapsing
+ * the two lets a corrupt source or row read as "not yet written" and unfence the session.
+ */
+export type TerminalReadBackRejection =
+	| "bounds"
+	| "shape"
+	| "undecodable"
+	| "row-not-attributable"
+	| "partial-row"
+	| BoundedSourceReadRejection;
+export type TerminalReadBack =
+	| { kind: "terminal"; entry: LifecycleLedgerEntry }
+	| { kind: "absent" }
+	| { kind: "rejected"; reason: TerminalReadBackRejection };
+
+type BoundedSourceRead =
+	| { kind: "absent" }
+	| { kind: "source"; source: Buffer }
+	| { kind: "rejected"; reason: BoundedSourceReadRejection };
+
 const terminal = (s: LifecycleState) => s === "terminal_ok" || s === "terminal_error";
 const final = (s: LifecycleState) => terminal(s) || s === "terminal_uncertain";
 export interface LifecycleLedgerLimits {
@@ -117,6 +143,11 @@ function canonicalCleanupSessionId(value: unknown): value is string {
 }
 
 const DEFAULT_LIFECYCLE_LEDGER_LIMITS: Required<LifecycleLedgerLimits> = {
+	// Terminal evidence intentionally has no time-based expiry: forgetting a
+	// completed close would allow a delayed duplicate to reach a later host
+	// generation. The row/byte bounds below are storage limits; compaction keeps
+	// each identity's accepted anchor and latest terminal state instead of
+	// expiring replay authority.
 	maxBytes: 64 * 1024 * 1024,
 	maxLineBytes: 8 * 1024 * 1024,
 	maxRows: 10_000,
@@ -376,9 +407,11 @@ export class LifecycleLedger {
 	 * uncertainly persists that conclusion, and refusing to read it back would report a
 	 * synced row as unpersisted and replace its true reason with a generic one.
 	 */
-	async readTerminal(identity: string, requestHash: string): Promise<LifecycleLedgerEntry | undefined> {
-		const source = await this.#readBoundedSourceReadOnly();
-		if (!source) return undefined;
+	async readTerminal(identity: string, requestHash: string): Promise<TerminalReadBack> {
+		const sourceRead = await this.#readBoundedSourceReadOnly();
+		if (sourceRead.kind === "absent") return sourceRead;
+		if (sourceRead.kind === "rejected") return sourceRead;
+		const { source } = sourceRead;
 		let prior: LifecycleLedgerEntry | undefined;
 		let latest: LifecycleLedgerEntry | undefined;
 		let rows = 0;
@@ -391,15 +424,16 @@ export class LifecycleLedger {
 			lineStart = offset + 1;
 			if (line.length === 0) continue;
 			rows += 1;
-			if (rows > this.#limits.maxRows || line.length > this.#limits.maxLineBytes) return undefined;
+			if (rows > this.#limits.maxRows || line.length > this.#limits.maxLineBytes)
+				return { kind: "rejected", reason: "bounds" };
 			let entry: LifecycleLedgerEntry;
 			try {
 				const value = parseLifecycleJson(line);
 				assertSupportedStateVersion(this.#file, value);
-				if (!isLifecycleLedgerEntry(value)) return undefined;
+				if (!isLifecycleLedgerEntry(value)) return { kind: "rejected", reason: "shape" };
 				entry = value;
 			} catch {
-				return undefined;
+				return { kind: "rejected", reason: "undecodable" };
 			}
 			if (entry.identity !== identity) continue;
 			if (
@@ -407,7 +441,7 @@ export class LifecycleLedger {
 				!hasValidTerminalDigests(entry) ||
 				!this.#isValidHistoryContinuation(prior, entry)
 			)
-				return undefined;
+				return { kind: "rejected", reason: "row-not-attributable" };
 			prior = entry;
 			latest = entry;
 		}
@@ -417,9 +451,11 @@ export class LifecycleLedger {
 			// a partially persisted row from this identity without inspecting arbitrary
 			// malformed data as a valid record.
 			const identityMarker = Buffer.from(`"identity":${JSON.stringify(identity)}`);
-			if (tail.includes(identityMarker)) return undefined;
+			if (tail.includes(identityMarker)) return { kind: "rejected", reason: "partial-row" };
 		}
-		return latest && final(latest.state) ? latest : undefined;
+		// No matching row, or one that has not reached a terminal state yet, is genuine
+		// absence: nothing was rejected, there is simply nothing terminal to read back.
+		return latest && final(latest.state) ? { kind: "terminal", entry: latest } : { kind: "absent" };
 	}
 
 	/**
@@ -512,19 +548,21 @@ export class LifecycleLedger {
 			if (handle) await handle.close();
 		}
 	}
-	async #readBoundedSourceReadOnly(): Promise<Buffer | undefined> {
+	async #readBoundedSourceReadOnly(): Promise<BoundedSourceRead> {
 		let handle: fs.FileHandle | undefined;
 		try {
-			handle = await fs.open(this.#file, fsSync.constants.O_RDONLY | fsSync.constants.O_NOFOLLOW);
+			const nonBlocking = process.platform === "win32" ? 0 : fsSync.constants.O_NONBLOCK;
+			handle = await fs.open(this.#file, fsSync.constants.O_RDONLY | fsSync.constants.O_NOFOLLOW | nonBlocking);
 			const stat = await handle.stat({ bigint: true });
-			if (!stat.isFile() || stat.size > BigInt(this.#limits.maxBytes)) return undefined;
+			if (!stat.isFile()) return { kind: "rejected", reason: "not-regular-file" };
+			if (stat.size > BigInt(this.#limits.maxBytes)) return { kind: "rejected", reason: "oversized-by-stat" };
 			const bytes = Buffer.alloc(Number(stat.size) + 1);
 			const { bytesRead } = await handle.read(bytes, 0, bytes.length, 0);
-			if (bytesRead > this.#limits.maxBytes) return undefined;
-			return bytes.subarray(0, bytesRead);
+			if (bytesRead > this.#limits.maxBytes) return { kind: "rejected", reason: "oversized-by-read" };
+			return { kind: "source", source: bytes.subarray(0, bytesRead) };
 		} catch (error) {
-			if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
-			return undefined;
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return { kind: "absent" };
+			return { kind: "rejected", reason: "read-error" };
 		} finally {
 			if (handle) await handle.close();
 		}
@@ -621,7 +659,7 @@ export class LifecycleLedger {
 		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(anchor);
+			snapshot.push(replacement?.identity === identity && latest.state === "accepted" ? latest : anchor);
 			if (latest.state !== "accepted") snapshot.push(latest);
 		}
 		const contents = Buffer.from(snapshot.map(entry => `${JSON.stringify(entry)}\n`).join(""));
@@ -663,16 +701,24 @@ export class LifecycleLedger {
 		}
 		return replacement !== undefined;
 	}
-	findByOperationKey(operationKey: string): LifecycleLedgerEntry | undefined {
-		return [...this.#byIdentity.values()].find(entry => entry.operationKey === operationKey);
+	findByOperationKey(operationKey: string, fingerprint?: string): LifecycleLedgerEntry | undefined {
+		return [...this.#byIdentity.values()].findLast(
+			entry =>
+				entry.operationKey === operationKey && (fingerprint === undefined || entry.fingerprint === fingerprint),
+		);
+	}
+	findAnyByOperationKey(operationKey: string): LifecycleLedgerEntry | undefined {
+		return [...this.#byIdentity.values()].findLast(entry => entry.operationKey === operationKey);
 	}
 	/**
 	 * Legacy target-inclusive rows predate the operation/key index. Their opaque
 	 * identities cannot establish that a different target is safe, so callers
 	 * must reject rather than create a second admission.
 	 */
-	hasLegacyIdentity(): boolean {
-		return [...this.#byIdentity.values()].some(entry => entry.operationKey === undefined);
+	hasLegacyIdentity(excludedIdentities?: ReadonlySet<string>): boolean {
+		return [...this.#byIdentity.values()].some(
+			entry => entry.operationKey === undefined && !excludedIdentities?.has(entry.identity),
+		);
 	}
 	async migrateIdentity(
 		from: string,
@@ -680,15 +726,32 @@ export class LifecycleLedger {
 		metadata: { operationKey: string; fingerprint: string },
 	): Promise<LifecycleLedgerEntry | undefined> {
 		return this.#mutate(async () => {
-			if (this.#byIdentity.has(to)) return this.#byIdentity.get(to);
+			const existing = this.#byIdentity.get(to);
 			const entry = this.#byIdentity.get(from);
-			if (!entry) return undefined;
-			const migrated = await this.#append({ ...entry, identity: to, ...metadata, ts: Date.now() });
-			// Retire the legacy row so hasLegacyIdentity() returns false and future
-			// unrelated lifecycle requests are not globally blocked. The legacy
-			// identity gets a metadata-bearing replacement row in the append-only
-			// log, superseding the original metadata-free entry in #byIdentity.
-			if (entry.operationKey === undefined) await this.#append({ ...entry, ...metadata, ts: Date.now() });
+			if (!entry) return existing;
+			if (existing) {
+				if (entry.operationKey === undefined) {
+					await this.#compact({ ...entry, ...metadata, ts: Date.now() });
+				}
+				return existing;
+			}
+			// A migrated identity needs the same accepted anchor as a fresh request;
+			// appending only a terminal row would be quarantined on the next restart.
+			await this.#append({
+				version: SDK_STATE_VERSION,
+				identity: to,
+				requestHash: entry.requestHash,
+				...metadata,
+				state: "accepted",
+				ts: Date.now(),
+			});
+			const migrated =
+				entry.state === "accepted"
+					? this.#byIdentity.get(to)
+					: await this.#append({ ...entry, identity: to, ...metadata, ts: Date.now() });
+			// Retire metadata-free legacy rows by rewriting their latest row in place;
+			// appending a duplicate terminal row would violate the ledger history rules.
+			if (entry.operationKey === undefined) await this.#compact({ ...entry, ...metadata, ts: Date.now() });
 			return migrated;
 		});
 	}
@@ -723,7 +786,7 @@ export class LifecycleLedger {
 	async begin(
 		identity: string,
 		requestHash: string,
-		metadata: { operationKey?: string; fingerprint?: string } = {},
+		metadata: { operationKey?: string; fingerprint?: string; intendedSessionId?: string } = {},
 	): Promise<BeginResult> {
 		return this.#mutate(async () => this.#begin(identity, requestHash, metadata));
 	}
@@ -731,7 +794,7 @@ export class LifecycleLedger {
 	async #begin(
 		identity: string,
 		requestHash: string,
-		metadata: { operationKey?: string; fingerprint?: string },
+		metadata: { operationKey?: string; fingerprint?: string; intendedSessionId?: string },
 	): Promise<BeginResult> {
 		const prior = this.#byIdentity.get(identity);
 		if (!prior)
@@ -743,6 +806,7 @@ export class LifecycleLedger {
 					requestHash,
 					operationKey: metadata.operationKey,
 					fingerprint: metadata.fingerprint,
+					intendedSessionId: metadata.intendedSessionId,
 					state: "accepted",
 					ts: Date.now(),
 				}),