@gajae-code/coding-agent 0.15.5 → 0.16.0

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

@@ -3,14 +3,21 @@ 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";
 import { SdkClient, SdkClientError, type SdkDispatchContext, type SdkDispatchHandler } from "../client/client";
-import { readSdkBrokerDiscovery, readSdkSessionEndpoint, type SdkSessionEndpoint } from "../client/discovery";
+import {
+	endpointDirectory,
+	readSdkBrokerDiscovery,
+	readSdkSessionEndpoint,
+	type SdkSessionEndpoint,
+} from "../client/discovery";
 import {
 	type ActivatedPreparedSession,
 	type PreparedSessionActivationClient,
@@ -19,6 +26,14 @@ import {
 } from "../session-activation";
 import { ACP_SESSION_RECONNECT, SESSION_REQUEST_TIMEOUT_MS } from "../session-reconnect";
 
+export interface SessionEndpointIdentity {
+	readonly mtimeMs: number;
+	readonly mtimeNs: bigint;
+	readonly ctimeNs: bigint;
+	readonly size: bigint;
+	readonly ino: bigint;
+}
+
 /**
  * Exact identity of one attached SDK session endpoint. Providers persist it next to
  * their conversation state and re-prove it before every resume, so it must be derived
@@ -32,11 +47,22 @@ export function sessionAttachmentAuthorityId(input: {
 	endpointMtimeMs: number | undefined;
 	url: string;
 	token: string;
+	/** Proven no-follow endpoint identity, when the caller has one. */
+	endpointIdentity?: SessionEndpointIdentity;
 }): string {
 	const endpointAuthorityDigest = crypto
 		.createHash("sha256")
 		.update(JSON.stringify({ url: input.url, token: input.token }))
 		.digest("hex");
+	const endpointIdentity = input.endpointIdentity
+		? {
+				mtimeMs: input.endpointIdentity.mtimeMs,
+				mtimeNs: input.endpointIdentity.mtimeNs.toString(),
+				ctimeNs: input.endpointIdentity.ctimeNs.toString(),
+				size: input.endpointIdentity.size.toString(),
+				ino: input.endpointIdentity.ino.toString(),
+			}
+		: undefined;
 	return crypto
 		.createHash("sha256")
 		.update(
@@ -46,6 +72,7 @@ export function sessionAttachmentAuthorityId(input: {
 				pid: input.pid,
 				endpointMtimeMs: input.endpointMtimeMs,
 				endpointAuthorityDigest,
+				endpointIdentity,
 			}),
 		)
 		.digest("hex");
@@ -233,6 +260,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;
@@ -287,6 +316,8 @@ type AttachedSession = {
 	readonly generation: number;
 	readonly pid: number;
 	readonly endpointMtimeMs: number;
+	/** No-follow endpoint identity proven before this attachment became current. */
+	readonly endpointIdentity: SessionEndpointIdentity;
 	readonly runEpoch: number;
 	readonly client: SessionRouterClient;
 	readonly indexed: IndexedSession;
@@ -398,6 +429,60 @@ function readSequence(value: unknown): number | undefined {
 	return typeof value === "number" && Number.isSafeInteger(value) && value >= 1 ? value : undefined;
 }
 
+async function lstatEndpoint(file: string): Promise<SessionEndpointIdentity | undefined> {
+	const stat = await fs.lstat(file).catch(() => undefined);
+	if (!stat || !stat.isFile()) return undefined;
+	const identity = await fs.lstat(file, { bigint: true }).catch(() => undefined);
+	if (!identity || !identity.isFile()) return undefined;
+	if (
+		stat.size !== Number(identity.size) ||
+		stat.ino !== Number(identity.ino) ||
+		Math.abs(stat.mtimeMs - Number(identity.mtimeNs) / 1_000_000) > 0.0005 ||
+		Math.abs(stat.ctimeMs - Number(identity.ctimeNs) / 1_000_000) > 0.0005
+	)
+		return undefined;
+	return {
+		mtimeMs: stat.mtimeMs,
+		mtimeNs: identity.mtimeNs,
+		ctimeNs: identity.ctimeNs,
+		size: identity.size,
+		ino: identity.ino,
+	};
+}
+
+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 &&
+		expected.mtimeNs === current.mtimeNs &&
+		expected.ctimeNs === current.ctimeNs &&
+		expected.size === current.size &&
+		expected.ino === current.ino
+	);
+}
+
+function readFrameSequenceClaim(frame: Record<string, unknown>): {
+	claimed: boolean;
+	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] };
+}
+
 function fallbackCorrelation(frame: Record<string, unknown>): SessionRouterFrame | undefined {
 	const payload =
 		frame.type === "event" && frame.payload && typeof frame.payload === "object" && !Array.isArray(frame.payload)
@@ -488,6 +573,7 @@ type AdoptedSession = {
  */
 export class SessionRouter {
 	readonly #agentDir: string;
+	readonly #sessionIds: ReadonlySet<string> | undefined;
 	readonly #deps: SessionRouterDeps;
 	readonly #correlateFrame: SessionRouterFrameCorrelator;
 	readonly #index: SessionIndex;
@@ -503,16 +589,11 @@ export class SessionRouter {
 		{ generation: number; frames: Array<{ seq: number; frame: Record<string, unknown> }> }
 	>();
 	readonly #reviving = new Set<string>();
-	/**
-	 * Endpoint-file inode captured when each attachment was published (#4730
-	 * review). Maintenance renewal compares against this so a rename-replace that
-	 * preserves size, mtime and body cannot keep a superseded endpoint authorized.
-	 */
-	readonly #endpointInodes = new Map<string, bigint>();
 	readonly #notificationReceipts = new Map<string, NotificationCleanupReceipt>();
 	#stopTimer: (() => void) | undefined;
 	#reconcileTail: Promise<void> = Promise.resolve();
 	#reconcilePending: { readonly runEpoch: number; force: boolean } | undefined;
+	#attachmentTails = new Map<string, Promise<boolean>>();
 	/**
 	 * Set when a live indexed session failed to attach; keeps the idle gate
 	 * from parking retries until the 30s sweep (#4689 review).
@@ -524,11 +605,14 @@ export class SessionRouter {
 	#lastReconciledIndexSeq = -1;
 	#ready = false;
 	#started = false;
+	#startPromise: Promise<void> | undefined;
+	#stopPromise: Promise<void> | undefined;
 	#stopController = new AbortController();
 	#runEpoch = 0;
 
 	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);
@@ -545,14 +629,27 @@ export class SessionRouter {
 
 	/** Starts reconciliation and the index watcher. */
 	async start(): Promise<void> {
+		if (this.#stopPromise) await this.#stopPromise;
+		if (this.#startPromise) return await this.#startPromise;
 		if (this.#started) return;
 		this.#started = true;
+		const startup = this.#startImpl();
+		this.#startPromise = startup;
+		try {
+			await startup;
+		} finally {
+			if (this.#startPromise === startup) this.#startPromise = undefined;
+		}
+	}
+
+	async #startImpl(): Promise<void> {
 		const runEpoch = ++this.#runEpoch;
 		if (this.#stopController.signal.aborted) {
 			this.#stopController = new AbortController();
 			this.#reconcileTail = Promise.resolve();
 			this.#reconcilePending = undefined;
 			this.#frameTails.clear();
+			this.#attachmentTails.clear();
 			// A restart must re-run the full body on the first tick: reset the
 			// idle-gate markers so stale state cannot carry across run epochs.
 			this.#lastReconcileSweepAt = 0;
@@ -666,11 +763,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,
@@ -693,14 +790,29 @@ 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;
 	}
 
 	async stop(): Promise<void> {
+		if (this.#stopPromise) return await this.#stopPromise;
+		const stopping = this.#stopImpl();
+		this.#stopPromise = stopping;
+		try {
+			await stopping;
+		} finally {
+			if (this.#stopPromise === stopping) this.#stopPromise = undefined;
+		}
+	}
+
+	async #stopImpl(): Promise<void> {
+		// Detach the in-flight startup promise before invalidating its epoch. A
+		// later start must not return a promise owned by the stopped epoch.
+		this.#startPromise = undefined;
 		if (this.#stopTimer) this.#stopTimer();
 		this.#stopTimer = undefined;
 		this.#started = false;
@@ -720,7 +832,7 @@ export class SessionRouter {
 		this.#adopted.clear();
 		// Provider notification work is detached and bounded independently; core
 		// shutdown waits only for Router reconciliation and client close.
-		const pending = Promise.allSettled([this.#reconcileTail, ...shutdownTasks]);
+		const pending = Promise.allSettled([this.#reconcileTail, ...this.#attachmentTails.values(), ...shutdownTasks]);
 		// Cancelled once the race settles, so a completed shutdown does not hold the
 		// event loop open for the remainder of the timeout.
 		const shutdownCutoff = new AbortController();
@@ -790,14 +902,15 @@ export class SessionRouter {
 		if (expectedAttachment !== undefined && attached.capability !== expectedAttachment)
 			throw new SessionRouterError("pre_send", "SDK session attachment changed before command dispatch.");
 		if (attached.initializingPublication) {
-			const endpoint = await this.#readEndpoint(attached.indexed);
+			const proven = await this.#readProvenEndpoint(attached.indexed);
 			if (
-				!endpoint ||
-				endpoint.url !== attached.endpoint.url ||
-				endpoint.token !== attached.endpoint.token ||
-				endpoint.pid !== attached.pid
+				!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, endpoint ? "replaced_same_generation" : undefined);
+				await this.#retireAttachment(attached, proven ? "replaced_same_generation" : undefined);
 				throw new SessionRouterError("pre_send", "SDK session attachment changed during publication.");
 			}
 		}
@@ -851,7 +964,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;
@@ -865,8 +978,15 @@ export class SessionRouter {
 		)
 			return undefined;
 		if (!Number.isSafeInteger(indexed.pid) || indexed.pid <= 0) return undefined;
-		const endpoint = await this.#readEndpoint(indexed).catch(() => null);
-		if (!endpoint || endpoint.stale === true || endpoint.pid !== indexed.pid || !endpoint.token) return undefined;
+		const proven = await this.#readProvenEndpoint(indexed).catch(() => null);
+		if (
+			!proven ||
+			proven.endpoint.stale === true ||
+			proven.endpoint.pid !== indexed.pid ||
+			!proven.endpoint.token ||
+			!sameEndpointIdentity(attached.endpointIdentity, proven.identity)
+		)
+			return undefined;
 		if (this.#sessions.get(sessionId) !== attached || !this.#attachmentPublished(attached)) return undefined;
 		return { sessionId, endpointGeneration: attached.generation };
 	}
@@ -916,7 +1036,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.",
@@ -945,8 +1065,16 @@ export class SessionRouter {
 				"session_not_live",
 				"Session activation requires an exact live session endpoint.",
 			);
-		const endpoint = await this.#readEndpoint(indexed).catch(() => null);
-		if (!endpoint || endpoint.stale === true || !endpoint.url || !endpoint.token || endpoint.pid !== indexed.pid)
+		const provenEndpoint = await this.#readProvenEndpoint(indexed).catch(() => null);
+		const endpoint = provenEndpoint?.endpoint;
+		if (
+			!provenEndpoint ||
+			!endpoint ||
+			endpoint.stale === true ||
+			!endpoint.url ||
+			!endpoint.token ||
+			endpoint.pid !== indexed.pid
+		)
 			throw new SessionActivationError(
 				"session_not_live",
 				"Session activation requires a readable session discovery endpoint.",
@@ -966,12 +1094,15 @@ export class SessionRouter {
 			throw new SessionActivationError("activation_unavailable", "The session endpoint could not be reached.");
 		}
 		try {
-			const currentEndpoint = await this.#readEndpoint(indexed).catch(() => null);
+			const currentProvenEndpoint = await this.#readProvenEndpoint(indexed).catch(() => null);
+			const currentEndpoint = currentProvenEndpoint?.endpoint;
 			if (
+				!currentProvenEndpoint ||
 				!currentEndpoint ||
 				currentEndpoint.url !== endpoint.url ||
 				currentEndpoint.token !== endpoint.token ||
-				currentEndpoint.pid !== endpoint.pid
+				currentEndpoint.pid !== endpoint.pid ||
+				!sameEndpointIdentity(provenEndpoint.identity, currentProvenEndpoint.identity)
 			)
 				throw new SessionActivationError(
 					"session_not_live",
@@ -1083,50 +1214,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;
@@ -1200,15 +1332,9 @@ export class SessionRouter {
 		// attachment was PUBLISHED against is therefore the identity, and the
 		// generation is compared so a re-registration reusing the same url/token/pid
 		// cannot keep the old attachment authorized.
-		const publishedIno = this.#endpointInodes.get(attached.id);
-		if (publishedIno === undefined) return false;
-		const statBefore = await fs.stat(attached.endpoint.path).catch(() => undefined);
-		const inoBefore = await fs
-			.stat(attached.endpoint.path, { bigint: true })
-			.then(value => value.ino)
-			.catch(() => undefined);
-		if (!statBefore || inoBefore === undefined || inoBefore !== publishedIno) return false;
-		if (statBefore.mtimeMs !== indexed.endpointMtimeMs) return false;
+		const identityBefore = await lstatEndpoint(attached.endpoint.path);
+		if (!identityBefore || !sameEndpointIdentity(attached.endpointIdentity, identityBefore)) return false;
+		if (identityBefore.mtimeMs !== indexed.endpointMtimeMs) return false;
 		let raw: Record<string, unknown>;
 		try {
 			const parsed = JSON.parse(await Bun.file(attached.endpoint.path).text());
@@ -1229,36 +1355,29 @@ export class SessionRouter {
 		// comes from the indexed row this attachment was published against.
 		if (indexed.endpointGeneration !== attached.generation) return false;
 		if (raw.endpointGeneration !== undefined && raw.endpointGeneration !== attached.generation) return false;
-		const statAfter = await fs.stat(attached.endpoint.path).catch(() => undefined);
-		const inoAfter = await fs
-			.stat(attached.endpoint.path, { bigint: true })
-			.then(value => value.ino)
-			.catch(() => undefined);
+		const identityAfter = await lstatEndpoint(attached.endpoint.path);
 		return (
-			statAfter !== undefined &&
-			inoAfter !== undefined &&
-			statAfter.mtimeMs === indexed.endpointMtimeMs &&
-			inoAfter === publishedIno
+			identityAfter !== undefined &&
+			identityAfter.mtimeMs === indexed.endpointMtimeMs &&
+			sameEndpointIdentity(attached.endpointIdentity, identityAfter)
 		);
 	}
 
 	/**
-	 * Returns the endpoint together with the inode this read PROVED (#4730
+	 * Returns the endpoint together with the full identity this read PROVED (#4730
 	 * review). The identity travels with the value instead of living in a side
 	 * map, so every consumer decision compares the same proof and the two cannot
 	 * drift apart.
 	 */
-	async #readProvenEndpoint(indexed: IndexedSession): Promise<{ endpoint: SdkSessionEndpoint; ino: bigint } | null> {
+	async #readProvenEndpoint(
+		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)
@@ -1267,18 +1386,15 @@ export class SessionRouter {
 					? "chat"
 					: undefined;
 		if (!scope || indexed.endpointMtimeMs === undefined || !Number.isFinite(indexed.endpointMtimeMs)) return null;
-		const endpoint = await readSdkSessionEndpoint(repo, indexed.sessionId, scope);
+		const endpointPath = path.join(endpointDirectory(cwd, scope), `${indexed.sessionId}.json`);
+		const endpointIdentity = await lstatEndpoint(endpointPath);
+		const endpoint = await readSdkSessionEndpoint(cwd, indexed.sessionId, scope);
 		if (!endpoint || endpoint.stale || endpoint.pid !== indexed.pid) return null;
-		const endpointStat = await fs.stat(endpoint.path).catch(() => undefined);
-		const endpointIno = await fs
-			.stat(endpoint.path, { bigint: true })
-			.then(value => value.ino)
-			.catch(() => undefined);
-		if (!endpointStat || endpointIno === undefined || endpointStat.mtimeMs !== indexed.endpointMtimeMs) return null;
+		if (!endpointIdentity || endpointIdentity.mtimeMs !== indexed.endpointMtimeMs) return null;
 		// Identity is proven INSIDE this authority read (#4730 review): sampling it
 		// afterwards would let an identical rename between the read and the sample
 		// install the replacement's inode as the trusted baseline.
-		const provenIno = endpointIno;
+		const provenIdentity = endpointIdentity;
 		let raw: Record<string, unknown>;
 		try {
 			const parsed = JSON.parse(await Bun.file(endpoint.path).text());
@@ -1296,24 +1412,19 @@ export class SessionRouter {
 		)
 			return null;
 		// Fail CLOSED on stat error and on any identity change across the body read.
-		const endpointStatAfterRead = await fs.stat(endpoint.path).catch(() => undefined);
-		const inoAfterRead = await fs
-			.stat(endpoint.path, { bigint: true })
-			.then(value => value.ino)
-			.catch(() => undefined);
+		const endpointIdentityAfterRead = await lstatEndpoint(endpoint.path);
 		if (
-			!endpointStatAfterRead ||
-			inoAfterRead === undefined ||
-			endpointStatAfterRead.mtimeMs !== indexed.endpointMtimeMs ||
-			inoAfterRead !== provenIno
+			!endpointIdentityAfterRead ||
+			endpointIdentityAfterRead.mtimeMs !== indexed.endpointMtimeMs ||
+			!sameEndpointIdentity(endpointIdentity, endpointIdentityAfterRead)
 		)
 			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, ino: provenIno };
+		return { endpoint, identity: provenIdentity };
 	}
 
 	/** Endpoint-only view for callers that do not make an authority decision. */
@@ -1375,6 +1486,28 @@ export class SessionRouter {
 		skipReplay = false,
 		deferPublication = false,
 		deferReplay = false,
+	): Promise<boolean> {
+		const previous = this.#attachmentTails.get(indexed.sessionId) ?? Promise.resolve(true);
+		const task = previous
+			.catch(() => false)
+			.then(() =>
+				this.#attachUnserialized(indexed, runEpoch, resolvedEndpoint, skipReplay, deferPublication, deferReplay),
+			);
+		this.#attachmentTails.set(indexed.sessionId, task);
+		try {
+			return await task;
+		} finally {
+			if (this.#attachmentTails.get(indexed.sessionId) === task) this.#attachmentTails.delete(indexed.sessionId);
+		}
+	}
+
+	async #attachUnserialized(
+		indexed: IndexedSession,
+		runEpoch: number,
+		resolvedEndpoint?: SdkSessionEndpoint,
+		skipReplay = false,
+		deferPublication = false,
+		deferReplay = false,
 	): Promise<boolean> {
 		const retirementVersion = this.#retirementVersions.get(indexed.sessionId) ?? 0;
 		const retirement = this.#retirements.get(indexed.sessionId);
@@ -1386,18 +1519,14 @@ export class SessionRouter {
 		// authority read of its own, so it samples once here.
 		const proven = resolvedEndpoint === undefined ? await this.#readProvenEndpoint(indexed) : null;
 		const endpoint = resolvedEndpoint ?? proven?.endpoint ?? null;
-		let provenIno = proven?.ino;
-		if (resolvedEndpoint !== undefined)
-			provenIno = await fs
-				.stat(resolvedEndpoint.path, { bigint: true })
-				.then(value => value.ino)
-				.catch(() => undefined);
+		const endpointIdentity =
+			resolvedEndpoint === undefined ? proven?.identity : await lstatEndpoint(resolvedEndpoint.path);
 		const retirementAfterValidation = this.#retirements.get(indexed.sessionId);
 		if (retirementAfterValidation) await retirementAfterValidation;
 		if ((this.#retirementVersions.get(indexed.sessionId) ?? 0) !== retirementVersion)
-			return await this.#attach(indexed, runEpoch, undefined, skipReplay, deferPublication, deferReplay);
+			return await this.#attachUnserialized(indexed, runEpoch, undefined, skipReplay, deferPublication, deferReplay);
 		if (!this.#running(runEpoch)) return false;
-		if (!endpoint) return false;
+		if (!endpoint || !endpointIdentity) return false;
 		const existing = this.#sessions.get(indexed.sessionId);
 		const resumable =
 			existing !== undefined &&
@@ -1405,7 +1534,9 @@ export class SessionRouter {
 			existing.endpoint.token === endpoint.token &&
 			existing.generation === indexed.endpointGeneration &&
 			existing.pid === indexed.pid &&
-			existing.endpointMtimeMs === indexed.endpointMtimeMs;
+			existing.endpointMtimeMs === indexed.endpointMtimeMs &&
+			endpointIdentity !== undefined &&
+			sameEndpointIdentity(existing.endpointIdentity, endpointIdentity);
 		if (existing && resumable && !existing.barrier.failed) {
 			this.#reviveTransport(existing);
 			return true;
@@ -1434,7 +1565,9 @@ export class SessionRouter {
 						(existing.endpoint.url !== endpoint.url ||
 							existing.endpoint.token !== endpoint.token ||
 							existing.pid !== indexed.pid ||
-							existing.endpointMtimeMs !== indexed.endpointMtimeMs)
+							existing.endpointMtimeMs !== indexed.endpointMtimeMs ||
+							endpointIdentity === undefined ||
+							!sameEndpointIdentity(existing.endpointIdentity, endpointIdentity))
 						? "replaced_same_generation"
 						: "replaced",
 				),
@@ -1455,7 +1588,7 @@ export class SessionRouter {
 			await client.close().catch(() => undefined);
 			const currentRetirement = this.#retirements.get(indexed.sessionId);
 			if (currentRetirement) await currentRetirement;
-			return await this.#attach(indexed, runEpoch, undefined, skipReplay, deferPublication, deferReplay);
+			return await this.#attachUnserialized(indexed, runEpoch, undefined, skipReplay, deferPublication, deferReplay);
 		}
 		let attached: AttachedSession | undefined;
 		const barrier: ReplayBarrier = { held: undefined, detached: false, failed: false };
@@ -1469,6 +1602,7 @@ export class SessionRouter {
 				endpointMtimeMs: indexed.endpointMtimeMs,
 				url: endpoint.url,
 				token: endpoint.token,
+				endpointIdentity,
 			}),
 			sessionId: indexed.sessionId,
 			generation: indexed.endpointGeneration,
@@ -1480,14 +1614,15 @@ export class SessionRouter {
 				if (!attached || !this.#attachmentPublished(attached))
 					throw new SessionRouterError("pre_send", "SDK session attachment is stale.");
 				if (attached.initializingPublication) {
-					const endpoint = await this.#readEndpoint(attached.indexed);
+					const proven = await this.#readProvenEndpoint(attached.indexed);
 					if (
-						!endpoint ||
-						endpoint.url !== attached.endpoint.url ||
-						endpoint.token !== attached.endpoint.token ||
-						endpoint.pid !== attached.pid
+						!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, endpoint ? "replaced_same_generation" : undefined);
+						await this.#retireAttachment(attached, proven ? "replaced_same_generation" : undefined);
 						throw new SessionRouterError("pre_send", "SDK session attachment changed during publication.");
 					}
 				} else await this.#serialReconcile(runEpoch, true, true);
@@ -1569,6 +1704,7 @@ export class SessionRouter {
 			endpoint,
 			pid: indexed.pid,
 			endpointMtimeMs: indexed.endpointMtimeMs,
+			endpointIdentity,
 			generation: indexed.endpointGeneration,
 			runEpoch,
 			client,
@@ -1592,10 +1728,6 @@ export class SessionRouter {
 						new SessionRouterError("pre_send", "SDK session publication was detached before completion."),
 					);
 				barrier.held = undefined;
-				// Every teardown path (retirement, replacement, stop, failed
-				// publication) routes through dispose(), so the published-inode entry
-				// is dropped here rather than at one call site (#4730 review).
-				if (attached) this.#endpointInodes.delete(attached.id);
 			},
 		};
 		// Re-check at publication (#4730 review): the endpoint must STILL be the
@@ -1609,14 +1741,9 @@ export class SessionRouter {
 			await client.close().catch(() => undefined);
 			return false;
 		};
-		if (provenIno === undefined) return await rollback();
-		const publishIno = await fs
-			.stat(endpoint.path, { bigint: true })
-			.then(value => value.ino)
-			.catch(() => undefined);
-		if (publishIno === undefined || publishIno !== provenIno) return await rollback();
+		const publishIdentity = await lstatEndpoint(endpoint.path);
+		if (!publishIdentity || !sameEndpointIdentity(endpointIdentity, publishIdentity)) return await rollback();
 		this.#sessions.set(indexed.sessionId, attached);
-		this.#endpointInodes.set(attached.id, provenIno);
 		if (deferPublication)
 			this.#adopted.set(indexed.sessionId, {
 				generation: indexed.endpointGeneration,
@@ -1656,19 +1783,17 @@ export class SessionRouter {
 		if (!this.#attachmentLive(attached)) return false;
 		const proven = await this.#readProvenEndpoint(attached.indexed).catch(() => null);
 		if (!this.#attachmentLive(attached)) return false;
-		// The commit point compares the PROVEN inode alongside url/token/pid
+		// The commit point compares the PROVEN endpoint identity alongside url/token/pid
 		// (#4730 review): an identical-byte rename during the pre-publication
 		// hooks matches every other field, so identity is what rejects it. The
 		// value compared here is the one the authority read proved, not a later
 		// observation, so the proof and its consumer cannot drift apart.
-		const publishedIno = this.#endpointInodes.get(attached.id);
 		if (
 			!proven ||
 			proven.endpoint.url !== attached.endpoint.url ||
 			proven.endpoint.token !== attached.endpoint.token ||
 			proven.endpoint.pid !== attached.pid ||
-			publishedIno === undefined ||
-			proven.ino !== publishedIno
+			!sameEndpointIdentity(attached.endpointIdentity, proven.identity)
 		) {
 			await this.#retireAttachment(attached, proven ? "replaced_same_generation" : undefined);
 			return false;
@@ -1731,14 +1856,15 @@ export class SessionRouter {
 			.catch(() => undefined)
 			.then(async () => {
 				if (!this.#attachmentLive(attached)) return;
-				const endpoint = await this.#readEndpoint(attached.indexed);
+				const proven = await this.#readProvenEndpoint(attached.indexed);
 				if (
-					!endpoint ||
-					endpoint.url !== attached.endpoint.url ||
-					endpoint.token !== attached.endpoint.token ||
-					endpoint.pid !== attached.pid
+					!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, endpoint ? "replaced_same_generation" : undefined);
+					await this.#retireAttachment(attached, proven ? "replaced_same_generation" : undefined);
 					return;
 				}
 				attached.initializingPublication = true;
@@ -2031,7 +2157,21 @@ export class SessionRouter {
 				}
 				const correlated = this.#correlateFrame(frame);
 				if (!correlated) return;
-				const seq = typeof frame.seq === "number" && Number.isSafeInteger(frame.seq) ? frame.seq : undefined;
+				const sequenceClaim = readFrameSequenceClaim(frame);
+				if (!sequenceClaim.valid) {
+					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;
 				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;