@gajae-code/coding-agent 0.15.6 → 0.16.1

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

@@ -3,9 +3,11 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { logger, resolveEquivalentPath } from "@gajae-code/utils";
 import {
+	canonicalSessionCwd,
 	SessionIndex as DefaultSessionIndex,
 	type IndexedSession,
 	isSessionAuthorityEligible,
+	resolveSessionLocator,
 	type SessionIndex,
 } from "../broker/session-index";
 import { cancellableSleep, lifecycleRequestTimeoutMs } from "../broker/startup-budget";
@@ -190,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;
@@ -220,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,
@@ -258,6 +264,8 @@ export type SessionRouterProviderDeps = Pick<
 
 export interface SessionRouterOptions {
 	agentDir: string;
+	/** Limits attachment to exact ids selected by a Broker-scoped operation. */
+	sessionIds?: readonly string[];
 	deps?: SessionRouterDeps;
 	/** Runtime-specific identity validation; Router supplies a conservative fallback. */
 	correlateFrame?: SessionRouterFrameCorrelator;
@@ -327,6 +335,9 @@ type AttachedSession = {
 	readonly notificationCursor: { generation: number; seq: number };
 	published: boolean;
 	initializingPublication: boolean;
+	replayPending: boolean;
+	replayPendingSince?: number;
+	replayPendingToken?: object;
 	readyTail: Promise<void>;
 	readonly publication: { promise: Promise<void>; resolve: () => void; reject: (reason?: unknown) => void };
 	dispose: () => void;
@@ -346,6 +357,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;
@@ -425,11 +437,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) ||
@@ -446,6 +462,10 @@ async function lstatEndpoint(file: string): Promise<SessionEndpointIdentity | un
 	};
 }
 
+function warningAffectsSession(warning: string, sessionId: string): boolean {
+	return !warning.startsWith("Session ") || warning.includes(`Session ${sessionId} `);
+}
+
 function sameEndpointIdentity(expected: SessionEndpointIdentity, current: SessionEndpointIdentity): boolean {
 	return (
 		expected.mtimeMs === current.mtimeMs &&
@@ -461,18 +481,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 {
@@ -488,12 +499,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;
@@ -514,10 +522,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 }),
 	};
 }
 
@@ -565,6 +587,7 @@ type AdoptedSession = {
  */
 export class SessionRouter {
 	readonly #agentDir: string;
+	readonly #sessionIds: ReadonlySet<string> | undefined;
 	readonly #deps: SessionRouterDeps;
 	readonly #correlateFrame: SessionRouterFrameCorrelator;
 	readonly #index: SessionIndex;
@@ -603,6 +626,7 @@ export class SessionRouter {
 
 	constructor(options: SessionRouterOptions) {
 		this.#agentDir = options.agentDir;
+		this.#sessionIds = options.sessionIds === undefined ? undefined : new Set(options.sessionIds);
 		this.#deps = options.deps ?? {};
 		this.#correlateFrame = options.correlateFrame ?? fallbackCorrelation;
 		this.#index = this.#deps.createIndex?.(options.agentDir) ?? new DefaultSessionIndex(options.agentDir);
@@ -654,7 +678,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.
@@ -741,6 +765,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 ||
@@ -753,11 +778,11 @@ export class SessionRouter {
 				"pre_send",
 				"Broker lifecycle result omitted an exact session endpoint authority.",
 			);
-		const repo = path.resolve(fallback.cwd);
-		const stateRoot = path.join(repo, ".gjc", "state");
+		const cwd = await canonicalSessionCwd(fallback.cwd);
+		const stateRoot = path.join(cwd, ".gjc", "state");
 		const indexed: IndexedSession = {
 			sessionId,
-			locator: { repo, stateRoot },
+			locator: await resolveSessionLocator(cwd, stateRoot),
 			endpointGeneration,
 			pid,
 			endpointMtimeMs,
@@ -780,8 +805,9 @@ export class SessionRouter {
 		if (!attached || !current || !capability)
 			throw new SessionRouterError("pre_send", "Broker session endpoint could not be attached.");
 		const listing = this.#index.listSessions();
-		const indexedCurrent =
-			listing.warnings.length === 0 ? listing.sessions.find(item => item.sessionId === sessionId) : undefined;
+		const indexedCurrent = listing.warnings.some(warning => warningAffectsSession(warning, sessionId))
+			? undefined
+			: listing.sessions.find(item => item.sessionId === sessionId);
 		if (indexedCurrent && sameIndexedAuthority(indexed, indexedCurrent))
 			await this.#serialReconcile(this.#runEpoch, true, true);
 		return capability;
@@ -814,8 +840,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();
@@ -880,15 +909,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);
@@ -936,10 +969,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;
@@ -953,7 +988,7 @@ export class SessionRouter {
 		try {
 			await this.#index.refresh();
 			const listing = this.#index.listSessions();
-			if (listing.warnings.length > 0) return undefined;
+			if (listing.warnings.some(warning => warningAffectsSession(warning, sessionId))) return undefined;
 			indexed = listing.sessions.find(candidate => candidate.sessionId === sessionId);
 		} catch {
 			return undefined;
@@ -1025,7 +1060,7 @@ export class SessionRouter {
 			await this.#index.open();
 			await this.#index.refresh();
 			const listing = this.#index.listSessions();
-			if (listing.warnings.length > 0)
+			if (listing.warnings.some(warning => warningAffectsSession(warning, sessionId)))
 				throw new SessionActivationError(
 					"session_not_live",
 					"Session activation requires an intact session index.",
@@ -1203,50 +1238,51 @@ export class SessionRouter {
 			return;
 		}
 		const indexed = this.#index.listSessions();
-		const live =
-			indexed.warnings.length === 0
-				? indexed.sessions.filter(
-						session => session.live && isSessionAuthorityEligible(session) && !session.terminalUncertain,
-					)
-				: [];
+		const live = indexed.sessions.filter(
+			session =>
+				!indexed.warnings.some(warning => warningAffectsSession(warning, session.sessionId)) &&
+				session.live &&
+				isSessionAuthorityEligible(session) &&
+				!session.terminalUncertain &&
+				(this.#sessionIds === undefined || this.#sessionIds.has(session.sessionId)),
+		);
 		const liveIds = new Set(live.map(session => session.sessionId));
 		const attachedIds = new Set<string>();
-		if (indexed.warnings.length === 0) {
-			for (const [sessionId, adopted] of [...this.#adopted]) {
-				const attached = this.#sessions.get(sessionId);
-				const indexedSession = indexed.sessions.find(session => session.sessionId === sessionId);
-				if (!attached || attached.capability !== adopted.attachment) {
-					this.#adopted.delete(sessionId);
-					continue;
-				}
-				const exactIndex =
-					indexedSession?.live === true &&
-					isSessionAuthorityEligible(indexedSession) &&
-					!indexedSession.terminalUncertain &&
-					indexedSession.endpointGeneration === adopted.generation &&
-					indexedSession.pid === adopted.pid &&
-					indexedSession.endpointMtimeMs === adopted.endpointMtimeMs;
-				const endpoint = exactIndex ? await this.#readEndpoint(indexedSession).catch(() => null) : null;
-				if (
-					!exactIndex ||
-					!endpoint ||
-					endpoint.pid !== adopted.pid ||
-					endpoint.url !== attached.endpoint.url ||
-					endpoint.token !== attached.endpoint.token
-				) {
-					this.#adopted.delete(sessionId);
-					await this.#retireAttachment(attached);
-					continue;
-				}
-				try {
-					if (await this.#publishAttachment(attached, true)) {
-						this.#adopted.delete(sessionId);
-						attachedIds.add(sessionId);
-					}
-				} catch {
+		for (const [sessionId, adopted] of [...this.#adopted]) {
+			if (indexed.warnings.some(warning => warningAffectsSession(warning, sessionId))) continue;
+			const attached = this.#sessions.get(sessionId);
+			const indexedSession = indexed.sessions.find(session => session.sessionId === sessionId);
+			if (!attached || attached.capability !== adopted.attachment) {
+				this.#adopted.delete(sessionId);
+				continue;
+			}
+			const exactIndex =
+				indexedSession?.live === true &&
+				isSessionAuthorityEligible(indexedSession) &&
+				!indexedSession.terminalUncertain &&
+				indexedSession.endpointGeneration === adopted.generation &&
+				indexedSession.pid === adopted.pid &&
+				indexedSession.endpointMtimeMs === adopted.endpointMtimeMs;
+			const endpoint = exactIndex ? await this.#readEndpoint(indexedSession).catch(() => null) : null;
+			if (
+				!exactIndex ||
+				!endpoint ||
+				endpoint.pid !== adopted.pid ||
+				endpoint.url !== attached.endpoint.url ||
+				endpoint.token !== attached.endpoint.token
+			) {
+				this.#adopted.delete(sessionId);
+				await this.#retireAttachment(attached);
+				continue;
+			}
+			try {
+				if (await this.#publishAttachment(attached, true)) {
 					this.#adopted.delete(sessionId);
-					await this.#retireAttachment(attached);
+					attachedIds.add(sessionId);
 				}
+			} catch {
+				this.#adopted.delete(sessionId);
+				await this.#retireAttachment(attached);
 			}
 		}
 		let nextAttachment = 0;
@@ -1361,15 +1397,11 @@ export class SessionRouter {
 		indexed: IndexedSession,
 	): Promise<{ endpoint: SdkSessionEndpoint; identity: SessionEndpointIdentity } | null> {
 		if (!isSessionAuthorityEligible(indexed)) return null;
-		const repo = path.resolve(indexed.locator.repo);
-		const defaultStateRoot = path.join(repo, ".gjc", "state");
-		// The session index stores the lifecycle caller's lexical cwd in `locator.repo`
-		// (reconcileReadyScope re-scopes only that field) while `locator.stateRoot` is
-		// the host process's physical path, because process.cwd() resolves symlinks.
-		// The scope test therefore compares path identity, not spelling: a lexical
-		// match fails for every symlinked cwd (macOS /var -> /private/var,
-		// /home/jun/desk -> /data/Lina-Desk), the adopted attachment is retired on
-		// reconcile, and session/new surfaces "lost exact Router authority".
+		const cwd = indexed.locator.cwd;
+		const defaultStateRoot = path.join(cwd, ".gjc", "state");
+		// Locator cwd is already canonical. `stateRoot` remains the host-provided
+		// authority path, so this comparison resolves equivalent paths only for the
+		// state-root identity boundary; cwd never retains lexical symlink spellings.
 		const indexedStateRoot = resolveEquivalentPath(indexed.locator.stateRoot);
 		const scope =
 			indexedStateRoot === resolveEquivalentPath(defaultStateRoot)
@@ -1378,9 +1410,9 @@ export class SessionRouter {
 					? "chat"
 					: undefined;
 		if (!scope || indexed.endpointMtimeMs === undefined || !Number.isFinite(indexed.endpointMtimeMs)) return null;
-		const endpointPath = path.join(endpointDirectory(repo, scope), `${indexed.sessionId}.json`);
+		const endpointPath = path.join(endpointDirectory(cwd, scope), `${indexed.sessionId}.json`);
 		const endpointIdentity = await lstatEndpoint(endpointPath);
-		const endpoint = await readSdkSessionEndpoint(repo, indexed.sessionId, scope);
+		const endpoint = await readSdkSessionEndpoint(cwd, indexed.sessionId, scope);
 		if (!endpoint || endpoint.stale || endpoint.pid !== indexed.pid) return null;
 		if (!endpointIdentity || endpointIdentity.mtimeMs !== indexed.endpointMtimeMs) return null;
 		// Identity is proven INSIDE this authority read (#4730 review): sampling it
@@ -1413,7 +1445,7 @@ export class SessionRouter {
 			return null;
 		await this.#index.refresh();
 		const listing = this.#index.listSessions();
-		if (listing.warnings.length > 0) return null;
+		if (listing.warnings.some(warning => warningAffectsSession(warning, indexed.sessionId))) return null;
 		const current = listing.sessions.find(session => session.sessionId === indexed.sessionId);
 		if (!current || !sameIndexedAuthority(indexed, current)) return null;
 		return { endpoint, identity: provenIdentity };
@@ -1529,7 +1561,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;
 		}
@@ -1691,6 +1728,7 @@ export class SessionRouter {
 		});
 		attached = {
 			initializingPublication: false,
+			replayPending: false,
 			id: crypto.randomUUID(),
 			sessionId: indexed.sessionId,
 			endpoint,
@@ -1828,15 +1866,33 @@ 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;
@@ -1844,6 +1900,10 @@ export class SessionRouter {
 
 	async #reinitializeAttachment(attached: AttachedSession): Promise<void> {
 		const previous = attached.readyTail;
+		const replayToken = {};
+		attached.replayPending = true;
+		attached.replayPendingSince = Date.now();
+		attached.replayPendingToken = replayToken;
 		const current = previous
 			.catch(() => undefined)
 			.then(async () => {
@@ -1868,6 +1928,7 @@ export class SessionRouter {
 							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;
@@ -1876,8 +1937,14 @@ export class SessionRouter {
 				}
 				if (this.#attachmentLive(attached)) await this.#replayAttachment(attached, attached.cursor.seq);
 			});
-		attached.readyTail = current;
-		await current;
+		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);
@@ -1899,7 +1966,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;
 	}
@@ -2131,9 +2205,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)}`),
 		);
 	}
@@ -2150,26 +2224,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;
@@ -2184,16 +2250,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;
@@ -2285,12 +2354,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 = sinceSeq;
+			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) {
@@ -2308,6 +2405,10 @@ 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);