@gajae-code/coding-agent 0.16.0 → 0.16.3

package/src/sdk/router/session-router.ts

@@ -192,11 +192,13 @@ export interface SessionRouterClient {
 	send(frame: Record<string, unknown>): void;
 }
 
+/** One frame after the caller's envelope/payload identity correlation. */
 /** One frame after the caller's envelope/payload identity correlation. */
 export interface SessionRouterFrame {
 	readonly body: Record<string, unknown>;
 	readonly name: string | undefined;
 	readonly sessionId: string | undefined;
+	readonly revision?: number;
 	readonly generation: number | undefined;
 	readonly commandId?: string;
 	readonly turnId?: string;
@@ -222,6 +224,8 @@ export interface SessionRouterDeps {
 	onAttachment?: (attachment: SessionAttachment) => Promise<void> | void;
 	/** Called only after the opaque capability becomes externally current. */
 	onAttachmentReady?: (attachment: SessionAttachment) => Promise<void> | void;
+	/** Called before deferred replay may perform provider-facing mutations. */
+	onReplayReady?: () => Promise<void> | void;
 	/** Called when the Broker index no longer reports an attached session as live. */
 	onSessionRemoved?: (
 		attachment: SessionAttachment,
@@ -331,6 +335,11 @@ type AttachedSession = {
 	readonly notificationCursor: { generation: number; seq: number };
 	published: boolean;
 	initializingPublication: boolean;
+	replayPending: boolean;
+	replayPendingSince?: number;
+	replayPendingToken?: object;
+	drainingHeldSeq?: number;
+	drainingHeldBatch?: HeldFrame[];
 	readyTail: Promise<void>;
 	readonly publication: { promise: Promise<void>; resolve: () => void; reject: (reason?: unknown) => void };
 	dispose: () => void;
@@ -350,6 +359,7 @@ function isUnansweredAfterDispatch(error: unknown): boolean {
 }
 
 const REPLAY_BARRIER_LIMIT = 1_024;
+const REPLAY_PENDING_STALL_MS = 10_000;
 const REPLAY_RETRY_ATTEMPTS = 3;
 const REPLAY_RETRY_BACKOFF_MS = 100;
 const DELIVERY_ATTEMPT_LIMIT = 3;
@@ -429,11 +439,15 @@ function readSequence(value: unknown): number | undefined {
 	return typeof value === "number" && Number.isSafeInteger(value) && value >= 1 ? value : undefined;
 }
 
+function readNonnegativeSequence(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
 async function lstatEndpoint(file: string): Promise<SessionEndpointIdentity | undefined> {
 	const stat = await fs.lstat(file).catch(() => undefined);
-	if (!stat || !stat.isFile()) return undefined;
+	if (!stat?.isFile()) return undefined;
 	const identity = await fs.lstat(file, { bigint: true }).catch(() => undefined);
-	if (!identity || !identity.isFile()) return undefined;
+	if (!identity?.isFile()) return undefined;
 	if (
 		stat.size !== Number(identity.size) ||
 		stat.ino !== Number(identity.ino) ||
@@ -469,18 +483,9 @@ function readFrameSequenceClaim(frame: Record<string, unknown>): {
 	valid: boolean;
 	seq?: number;
 } {
-	const payload =
-		frame.type === "event" && frame.payload && typeof frame.payload === "object" && !Array.isArray(frame.payload)
-			? (frame.payload as Record<string, unknown>)
-			: undefined;
-	const claims: unknown[] = [];
-	if (Object.hasOwn(frame, "seq")) claims.push(frame.seq);
-	if (payload && Object.hasOwn(payload, "seq")) claims.push(payload.seq);
-	if (claims.length === 0) return { claimed: false, valid: true };
-	const sequences = claims.map(readSequence);
-	if (sequences.some(sequence => sequence === undefined)) return { claimed: true, valid: false };
-	if (new Set(sequences).size !== 1) return { claimed: true, valid: false };
-	return { claimed: true, valid: true, seq: sequences[0] };
+	if (!Object.hasOwn(frame, "seq")) return { claimed: false, valid: true };
+	const seq = readSequence(frame.seq);
+	return seq === undefined ? { claimed: true, valid: false } : { claimed: true, valid: true, seq };
 }
 
 function fallbackCorrelation(frame: Record<string, unknown>): SessionRouterFrame | undefined {
@@ -496,12 +501,9 @@ function fallbackCorrelation(frame: Record<string, unknown>): SessionRouterFrame
 	const outerSession = frame.sessionId;
 	const innerSession = payload?.sessionId;
 	const outerGeneration = frame.generation;
-	const innerGeneration = payload?.generation;
 	if (outerSession !== undefined && innerSession !== undefined && outerSession !== innerSession) return undefined;
-	if (outerGeneration !== undefined && innerGeneration !== undefined && outerGeneration !== innerGeneration)
-		return undefined;
 	const sessionClaim = outerSession !== undefined ? outerSession : innerSession;
-	const generationClaim = outerGeneration !== undefined ? outerGeneration : innerGeneration;
+	const generationClaim = outerGeneration;
 	const sessionId = readSession(sessionClaim);
 	const generation = readGeneration(generationClaim);
 	if (sessionClaim !== undefined && sessionId === undefined) return undefined;
@@ -522,10 +524,24 @@ function fallbackCorrelation(frame: Record<string, unknown>): SessionRouterFrame
 		body,
 		name: readName(frame.name) ?? readName(frame.kind) ?? readName(body.type),
 		sessionId,
+		revision: typeof frame.revision === "number" ? frame.revision : undefined,
 		generation,
 		commandId,
 		turnId,
-		seq: readSequence(frame.seq) ?? readSequence(payload?.seq),
+		seq: readSequence(frame.seq),
+	};
+}
+
+function coordinateFreeRouterFrame(correlated: SessionRouterFrame): SessionRouterFrame {
+	return {
+		body: correlated.body,
+		name: correlated.name,
+		sessionId: correlated.sessionId,
+		...(correlated.revision === undefined ? {} : { revision: correlated.revision }),
+		generation: undefined,
+		seq: undefined,
+		...(correlated.commandId === undefined ? {} : { commandId: correlated.commandId }),
+		...(correlated.turnId === undefined ? {} : { turnId: correlated.turnId }),
 	};
 }
 
@@ -664,7 +680,7 @@ export class SessionRouter {
 			// STARTUP_ATTACH_BUDGET_MS: those attachments are published with their
 			// initial replay delivered. Past that budget the pass continues in the
 			// background instead of owning the caller's deadline.
-			const initialPass = this.#serialReconcile(runEpoch, false, true);
+			const initialPass = this.#serialReconcile(runEpoch, true, true);
 			// Cancelled as soon as the race settles. Promise.race leaves the loser pending,
 			// and a pending Bun.sleep keeps the event loop alive, so a startup that settled
 			// in milliseconds still owed the rest of the budget before the process could exit.
@@ -751,6 +767,7 @@ export class SessionRouter {
 		const endpointMtimeMs = readEndpointMtime(result.endpointMtimeMs);
 		if (
 			sessionId !== fallback.sessionId ||
+			(this.#sessionIds !== undefined && !this.#sessionIds.has(sessionId ?? "")) ||
 			endpointGeneration === undefined ||
 			pid === undefined ||
 			endpointMtimeMs === undefined ||
@@ -825,8 +842,11 @@ export class SessionRouter {
 			attached.dispose();
 			this.#detachNotification(attached, "removed");
 			shutdownTasks.push((async () => await attached.client.close())());
-			void Promise.resolve(this.#deps.onSessionRemoved?.(attached.capability)).catch(error =>
-				logger.warn(`SDK provider cleanup failed during router stop: ${String(error)}`),
+			shutdownTasks.push(
+				Promise.resolve(this.#deps.onSessionRemoved?.(attached.capability)).catch(error => {
+					logger.warn(`SDK provider cleanup failed during router stop: ${String(error)}`);
+					throw error;
+				}),
 			);
 		}
 		this.#adopted.clear();
@@ -891,15 +911,19 @@ export class SessionRouter {
 			onDispatch?: SdkDispatchHandler;
 		},
 	): Promise<Record<string, unknown>> {
+		const matchesExpectedAuthority = (attachment: SessionAttachment): boolean =>
+			expectedAttachment === undefined ||
+			attachment === expectedAttachment ||
+			(expectedAttachment.authorityId !== undefined && attachment.authorityId === expectedAttachment.authorityId);
 		const publishing = this.#sessions.get(sessionId);
-		if (!expectedAttachment || publishing?.capability !== expectedAttachment || !publishing.initializingPublication)
+		if (!publishing || !matchesExpectedAuthority(publishing.capability) || !publishing.initializingPublication)
 			await this.#serialReconcile(this.#runEpoch, true, true);
 		const attached = this.#sessions.get(sessionId);
 		if (!attached || !this.#attachmentPublished(attached))
 			throw new SessionRouterError("pre_send", "SDK session attachment is unavailable: session not published.");
 		if (expectedGeneration !== undefined && expectedGeneration !== attached.generation)
 			throw new SessionRouterError("pre_send", "SDK session endpoint changed before command dispatch.");
-		if (expectedAttachment !== undefined && attached.capability !== expectedAttachment)
+		if (!matchesExpectedAuthority(attached.capability))
 			throw new SessionRouterError("pre_send", "SDK session attachment changed before command dispatch.");
 		if (attached.initializingPublication) {
 			const proven = await this.#readProvenEndpoint(attached.indexed);
@@ -947,10 +971,12 @@ export class SessionRouter {
 					}
 				: {}),
 		});
+		const settled = this.#sessions.get(sessionId);
 		if (
-			!this.#attachmentPublished(attached) ||
-			(expectedGeneration !== undefined && attached.generation !== expectedGeneration) ||
-			(expectedAttachment !== undefined && attached.capability !== expectedAttachment)
+			!settled ||
+			!this.#attachmentPublished(settled) ||
+			(expectedGeneration !== undefined && settled.generation !== expectedGeneration) ||
+			!matchesExpectedAuthority(settled.capability)
 		)
 			throw new SessionRouterError("ambiguous", "SDK session attachment changed while awaiting command response.");
 		return response;
@@ -1537,7 +1563,12 @@ export class SessionRouter {
 			existing.endpointMtimeMs === indexed.endpointMtimeMs &&
 			endpointIdentity !== undefined &&
 			sameEndpointIdentity(existing.endpointIdentity, endpointIdentity);
-		if (existing && resumable && !existing.barrier.failed) {
+		if (
+			existing &&
+			resumable &&
+			!existing.barrier.failed &&
+			(!existing.replayPending || Date.now() - (existing.replayPendingSince ?? Date.now()) < REPLAY_PENDING_STALL_MS)
+		) {
 			this.#reviveTransport(existing);
 			return true;
 		}
@@ -1699,6 +1730,7 @@ export class SessionRouter {
 		});
 		attached = {
 			initializingPublication: false,
+			replayPending: false,
 			id: crypto.randomUUID(),
 			sessionId: indexed.sessionId,
 			endpoint,
@@ -1836,56 +1868,94 @@ export class SessionRouter {
 		// generation fences are unchanged; replay just runs on the attachment's
 		// ready tail like the reconnect path (#4527).
 		if (deferReplay) {
+			const replayToken = {};
+			attached.replayPending = true;
+			attached.replayPendingSince = Date.now();
+			attached.replayPendingToken = replayToken;
 			attached.readyTail = attached.readyTail
 				.catch(() => undefined)
 				.then(async () => {
+					if (!this.#attachmentLive(attached)) return;
+					await this.#deps.onReplayReady?.();
 					if (!this.#attachmentLive(attached)) return;
 					if (!(await this.#deliverRecoveredFrames(attached))) return;
 					await this.#replayAttachment(attached, attached.cursor.seq);
+				})
+				.catch(error => {
+					attached.barrier.failed = true;
+					logger.warn(`SDK deferred replay failed for ${attached.sessionId}: ${String(error)}`);
+				})
+				.finally(() => {
+					if (attached.replayPendingToken === replayToken) {
+						attached.replayPending = false;
+						attached.replayPendingSince = undefined;
+						attached.replayPendingToken = undefined;
+					}
 				});
 			return true;
 		}
+		await this.#deps.onReplayReady?.();
 		if (!(await this.#deliverRecoveredFrames(attached))) return false;
 		await this.#replayAttachment(attached, attached.cursor.seq);
 		return true;
 	}
 
 	async #reinitializeAttachment(attached: AttachedSession): Promise<void> {
-		const previous = attached.readyTail;
-		const current = previous
-			.catch(() => undefined)
-			.then(async () => {
-				if (!this.#attachmentLive(attached)) return;
-				const proven = await this.#readProvenEndpoint(attached.indexed);
-				if (
-					!proven ||
-					proven.endpoint.url !== attached.endpoint.url ||
-					proven.endpoint.token !== attached.endpoint.token ||
-					proven.endpoint.pid !== attached.pid ||
-					!sameEndpointIdentity(attached.endpointIdentity, proven.identity)
-				) {
-					await this.#retireAttachment(attached, proven ? "replaced_same_generation" : undefined);
-					return;
-				}
-				attached.initializingPublication = true;
-				try {
-					void Promise.resolve()
-						.then(() => this.#deps.onNotificationSubscriptionReady?.(attached.notificationSubscription))
-						.catch(error => {
-							this.#detachNotification(attached, "cancelled");
-							logger.warn(`SDK notification subscription reconnect hook failed locally: ${String(error)}`);
-						});
-					await this.#deps.onAttachmentReady?.(attached.capability);
-				} catch {
-					await this.#retireAttachment(attached);
-					return;
-				} finally {
-					attached.initializingPublication = false;
-				}
-				if (this.#attachmentLive(attached)) await this.#replayAttachment(attached, attached.cursor.seq);
-			});
-		attached.readyTail = current;
-		await current;
+		// A prior ready tail may be waiting for publication work carried by the dead
+		// socket. Chaining the reconnect behind it prevents the replacement from even
+		// issuing replay. Replace its hold-array identity to fence that tail, but carry
+		// forward frames it had not started draining; the active draining sequence is
+		// already represented by the independent frame tail.
+		if (attached.barrier.held) {
+			const carried = [...(attached.drainingHeldBatch ?? []), ...attached.barrier.held];
+			attached.drainingHeldBatch = undefined;
+			attached.barrier.held = carried
+				.filter(entry => entry.seq !== attached.drainingHeldSeq)
+				.filter((entry, index, entries) => entries.findIndex(candidate => candidate.seq === entry.seq) === index);
+		}
+		const replayToken = {};
+		attached.replayPending = true;
+		attached.replayPendingSince = Date.now();
+		attached.replayPendingToken = replayToken;
+		const current = Promise.resolve().then(async () => {
+			if (!this.#attachmentLive(attached)) return;
+			const proven = await this.#readProvenEndpoint(attached.indexed);
+			if (
+				!proven ||
+				proven.endpoint.url !== attached.endpoint.url ||
+				proven.endpoint.token !== attached.endpoint.token ||
+				proven.endpoint.pid !== attached.pid ||
+				!sameEndpointIdentity(attached.endpointIdentity, proven.identity)
+			) {
+				await this.#retireAttachment(attached, proven ? "replaced_same_generation" : undefined);
+				return;
+			}
+			attached.initializingPublication = true;
+			try {
+				void Promise.resolve()
+					.then(() => this.#deps.onNotificationSubscriptionReady?.(attached.notificationSubscription))
+					.catch(error => {
+						this.#detachNotification(attached, "cancelled");
+						logger.warn(`SDK notification subscription reconnect hook failed locally: ${String(error)}`);
+					});
+				await this.#deps.onAttachmentReady?.(attached.capability);
+				await this.#deps.onReplayReady?.();
+			} catch {
+				await this.#retireAttachment(attached);
+				return;
+			} finally {
+				attached.initializingPublication = false;
+			}
+			if (this.#attachmentLive(attached)) await this.#replayAttachment(attached, attached.cursor.seq);
+		});
+		attached.readyTail = current.finally(() => {
+			if (attached.replayPendingToken === replayToken) {
+				attached.replayPending = false;
+				attached.replayPendingSince = undefined;
+				attached.replayPendingToken = undefined;
+			}
+		});
+		await attached.readyTail;
 	}
 	#reviveTransport(attached: AttachedSession): void {
 		const connect = attached.client.connect?.bind(attached.client);
@@ -1907,7 +1977,14 @@ export class SessionRouter {
 	 */
 	#hasUnhealthyAttachment(): boolean {
 		for (const attached of this.#sessions.values()) {
-			if (attached.barrier.failed || attached.barrier.detached || !attached.published) return true;
+			if (
+				attached.barrier.failed ||
+				attached.barrier.detached ||
+				!attached.published ||
+				(attached.replayPending &&
+					Date.now() - (attached.replayPendingSince ?? Date.now()) >= REPLAY_PENDING_STALL_MS)
+			)
+				return true;
 		}
 		return false;
 	}
@@ -2139,9 +2216,9 @@ export class SessionRouter {
 		const correlated = this.#correlateFrame(frame);
 		if (!correlated) return;
 		if (correlated.sessionId !== undefined && correlated.sessionId !== attached.sessionId) return;
-		if (correlated.generation !== undefined && correlated.generation !== attached.generation) return;
-		this.#dispatchNotificationFrame(attached, correlated);
-		void Promise.resolve(this.#deps.onFrame?.(attached.capability, correlated)).catch(error =>
+		const notificationFrame = coordinateFreeRouterFrame(correlated);
+		this.#dispatchNotificationFrame(attached, notificationFrame);
+		void Promise.resolve(this.#deps.onFrame?.(attached.capability, notificationFrame)).catch(error =>
 			logger.warn(`SDK provider frame hook failed: ${String(error)}`),
 		);
 	}
@@ -2158,26 +2235,18 @@ export class SessionRouter {
 				const correlated = this.#correlateFrame(frame);
 				if (!correlated) return;
 				const sequenceClaim = readFrameSequenceClaim(frame);
-				if (!sequenceClaim.valid) {
+				const ringFrame = frame.type === "event";
+				const generationClaim = Object.hasOwn(frame, "generation");
+				const outerGeneration = generationClaim ? readGeneration(frame.generation) : undefined;
+				const partialCoordinate = ringFrame && sequenceClaim.claimed !== generationClaim;
+				if (!sequenceClaim.valid || partialCoordinate || (generationClaim && outerGeneration === undefined)) {
 					this.#failBarrier(attached, "protocol error: malformed sequence coordinate");
 					return;
 				}
-				const correlatedSeq = correlated.seq === undefined ? undefined : readSequence(correlated.seq);
-				if (correlated.seq !== undefined && correlatedSeq === undefined) {
-					this.#failBarrier(attached, "protocol error: malformed correlated sequence coordinate");
-					return;
-				}
-				if (sequenceClaim.claimed && correlatedSeq !== undefined && correlatedSeq !== sequenceClaim.seq) {
-					this.#failBarrier(attached, "protocol error: inconsistent sequence coordinate");
-					return;
-				}
-				const seq = sequenceClaim.seq ?? correlatedSeq;
+				const seq = ringFrame ? sequenceClaim.seq : undefined;
 				if (correlated.sessionId !== undefined && correlated.sessionId !== attached.sessionId) return;
-				if (correlated.generation !== undefined && correlated.generation !== attached.generation) return;
-				if (seq !== undefined && correlated.generation === undefined) return;
-				const ownsSequence =
-					correlated.generation === attached.generation &&
-					(correlated.sessionId === undefined || correlated.sessionId === attached.sessionId);
+				if (outerGeneration !== undefined && outerGeneration !== attached.generation) return;
+				const ownsSequence = seq !== undefined && outerGeneration === attached.generation;
 				if (seq !== undefined && ownsSequence) {
 					if (seq <= attached.cursor.seq) return;
 					const held = attached.barrier.held;
@@ -2192,16 +2261,19 @@ export class SessionRouter {
 				}
 				const publicationId =
 					seq !== undefined && ownsSequence ? `${attached.sessionId}:${attached.generation}:${seq}` : undefined;
-				let notificationFrame: SessionRouterFrame;
+				const coordinateFree = coordinateFreeRouterFrame(correlated);
+				const notificationFrame: SessionRouterFrame =
+					publicationId === undefined
+						? coordinateFree
+						: { ...coordinateFree, generation: outerGeneration, publicationId, seq };
 				try {
-					notificationFrame = publicationId === undefined ? correlated : { ...correlated, publicationId };
 					this.#dispatchNotificationFrame(attached, notificationFrame);
 					await this.#deps.onFrame?.(attached.capability, notificationFrame);
 				} catch (error) {
 					if (!this.#attachmentLive(attached)) return;
 					if (seq === undefined || !ownsSequence) throw error;
 					this.#failDelivery(attached, seq, error);
-					this.#deps.onFrameSettled?.(attached.capability, { ...correlated, seq });
+					this.#deps.onFrameSettled?.(attached.capability, notificationFrame);
 					return;
 				}
 				if (!this.#attachmentLive(attached)) return;
@@ -2233,7 +2305,19 @@ export class SessionRouter {
 				return;
 			}
 			const batch = held.splice(0, held.length).sort((left, right) => left.seq - right.seq);
-			for (const entry of batch) await this.#enqueueFrame(attached, entry.frame, "ordered");
+			attached.drainingHeldBatch = batch;
+			for (;;) {
+				const entry = batch.shift();
+				if (!entry) break;
+				attached.drainingHeldSeq = entry.seq;
+				try {
+					await this.#enqueueFrame(attached, entry.frame, "ordered");
+				} finally {
+					if (attached.drainingHeldSeq === entry.seq) attached.drainingHeldSeq = undefined;
+				}
+				if (attached.barrier.held !== held) return;
+			}
+			if (attached.drainingHeldBatch === batch) attached.drainingHeldBatch = undefined;
 		}
 	}
 
@@ -2293,12 +2377,40 @@ export class SessionRouter {
 			if (attached.barrier.held !== held || !this.#attachmentLive(attached)) return;
 			await this.#frameTails.get(attached.id)?.catch(() => undefined);
 			if (attached.barrier.held !== held || !this.#attachmentLive(attached)) return;
-			const events = Array.isArray(replay.events)
-				? replay.events.filter(
-						(event): event is Record<string, unknown> =>
-							!!event && typeof event === "object" && !Array.isArray(event),
-					)
-				: [];
+			if (!Array.isArray(replay.events)) {
+				this.#failBarrier(attached, "replay response omitted an events array");
+				return;
+			}
+			if (replay.ok !== true || readGeneration(replay.generation) !== attached.generation) {
+				this.#failBarrier(attached, "replay response failed or crossed generations");
+				return;
+			}
+			const lastSeq = readNonnegativeSequence(replay.lastSeq);
+			if (lastSeq === undefined || lastSeq < sinceSeq) {
+				this.#failBarrier(attached, "replay response omitted a coherent high-watermark");
+				return;
+			}
+			const events = replay.events.filter(
+				(event): event is Record<string, unknown> => !!event && typeof event === "object" && !Array.isArray(event),
+			);
+			if (events.length !== replay.events.length) {
+				this.#failBarrier(attached, "replay response contained a malformed event");
+				return;
+			}
+			let previousSeq = -1;
+			for (const event of events) {
+				if (event.type !== "event") {
+					this.#failBarrier(attached, "replay response contained a non-event frame");
+					return;
+				}
+				const generation = readGeneration(event.generation);
+				const seq = readSequence(event.seq);
+				if (generation !== attached.generation || seq === undefined || seq <= previousSeq || seq > lastSeq) {
+					this.#failBarrier(attached, "replay response contained invalid or unordered coordinates");
+					return;
+				}
+				previousSeq = seq;
+			}
 			if (replay.gap !== undefined) {
 				const gap = readReplayGap(replay.gap);
 				if (!gap) {
@@ -2316,9 +2428,13 @@ export class SessionRouter {
 					);
 					return;
 				}
+				if (gap.toSeq > lastSeq) {
+					this.#failBarrier(attached, "replay gap exceeded the reported high-watermark");
+					return;
+				}
 				const retained = events
 					.map(event => readSequence(event.seq))
-					.find(seq => seq !== undefined && seq <= gap.toSeq);
+					.find(seq => seq !== undefined && seq >= gap.fromSeq && seq <= gap.toSeq);
 				if (retained !== undefined) {
 					this.#failBarrier(
 						attached,