@gajae-code/coding-agent 0.11.6 → 0.11.7

package/src/sdk/bus/topic-registry.ts

@@ -39,8 +39,22 @@ export interface TopicRecord {
 	replaySeq?: number;
 	/** Serialized authority epoch; a late create may commit only in its starting epoch. */
 	authorityEpoch?: number;
+	/** Immutable authority epoch held when this remote topic create began. */
+	creationLeaseEpoch?: number;
 	/** An uncertain delete fences future creation and inbound routing. */
 	authorityState?: "active" | "delete_pending";
+	/** Telegram chat and endpoint authority last proven to use this topic. */
+	chatId?: string;
+	/** Canonical endpoint tuple (URL + token) that currently holds the lease. */
+	endpointKey?: string;
+	/** Authenticated endpoint authority digest, excluding transport presentation. */
+	endpointDigest?: string;
+	/** SDK event generation associated with the current endpoint lease. */
+	endpointGeneration?: number;
+	/** Monotonic authenticated endpoint handoffs; legacy bindings begin at zero. */
+	endpointIncarnation?: number;
+	/** True when persisted binding fields were present but malformed; recovery must fail closed. */
+	bindingMalformed?: true;
 }
 
 /** Serialisable shape persisted to disk. */
@@ -49,6 +63,69 @@ export interface TopicRegistryState {
 	topics: Record<string, TopicRecord>;
 	/** Durable deletion epochs retained after a definite delete. */
 	fences?: Record<string, number>;
+	/** Closed transport endpoint leases; unchanged endpoint discovery remains fenced across restart. */
+	closedEndpoints?: Record<string, TopicEndpointBinding>;
+}
+
+/** Authenticated runtime binding for a durable topic lease. */
+export interface TopicEndpointBinding {
+	chatId: string;
+	endpointKey: string;
+	endpointDigest: string;
+	endpointGeneration?: number;
+}
+
+/** Discriminated durable endpoint authority for identity-less replay admission. */
+export type TopicEndpointAuthority =
+	| { state: "none" }
+	| { state: "unique"; sessionId: string }
+	| { state: "ambiguous" };
+
+/** Conditional rollback token for a delete fence publication. */
+export interface TopicDeleteAuthoritySnapshot {
+	sessionId: string;
+	topicId?: string;
+	authorityEpoch?: number;
+	authorityState?: TopicRecord["authorityState"];
+	fenceEpoch?: number;
+	/** Exact fenced record, retained to restore an in-memory tombstone after a failed clear publication. */
+	record?: TopicRecord;
+}
+
+function isValidBindingString(value: unknown): value is string {
+	return typeof value === "string" && value.trim().length > 0;
+}
+
+function isValidBindingGeneration(value: unknown): value is number {
+	return Number.isSafeInteger(value) && (value as number) >= 0;
+}
+function hasAnyBinding(record: TopicRecord): boolean {
+	return (
+		record.chatId !== undefined ||
+		record.endpointKey !== undefined ||
+		record.endpointDigest !== undefined ||
+		record.endpointGeneration !== undefined ||
+		record.endpointIncarnation !== undefined
+	);
+}
+
+function hasCompleteBinding(record: TopicRecord): boolean {
+	return (
+		isValidBindingString(record.chatId) &&
+		isValidBindingString(record.endpointKey) &&
+		isValidBindingString(record.endpointDigest) &&
+		(record.endpointGeneration === undefined || isValidBindingGeneration(record.endpointGeneration)) &&
+		(record.endpointIncarnation === undefined || isValidBindingGeneration(record.endpointIncarnation))
+	);
+}
+
+function hasValidBinding(binding: TopicEndpointBinding): boolean {
+	return (
+		isValidBindingString(binding.chatId) &&
+		isValidBindingString(binding.endpointKey) &&
+		isValidBindingString(binding.endpointDigest) &&
+		(binding.endpointGeneration === undefined || isValidBindingGeneration(binding.endpointGeneration))
+	);
 }
 
 function isValidTopicId(value: unknown): value is string {
@@ -74,6 +151,12 @@ export class TopicRegistry {
 	readonly #ambiguousTopicIds = new Set<string>();
 	/** In-flight create promises, keyed by session, to dedupe concurrent creates. */
 	private readonly inflight = new Map<string, Promise<TopicRecord>>();
+	/** Newly-created records being durably published; never routable until committed. */
+	private readonly staged = new Map<string, TopicRecord>();
+	/** Socket-specific provenance for transient endpoint claims. */
+	private readonly transientClaimants = new Map<string, object | undefined>();
+	/** Endpoint claims registered before a remote topic create can publish a record. */
+	private readonly creatingBindings = new Map<string, TopicEndpointBinding>();
 	/** Monotonic authority epochs, including deletion fences for absent records. */
 	private readonly epochs = new Map<string, number>();
 
@@ -82,6 +165,15 @@ export class TopicRegistry {
 		this.load(state);
 	}
 
+	/** Replace all runtime state after a successfully persisted staged publication. */
+	replace(state: TopicRegistryState): void {
+		this.topics.clear();
+		this.byTopic.clear();
+		this.#ambiguousTopicIds.clear();
+		this.epochs.clear();
+		this.load(state);
+	}
+
 	/** Merge serialized state and normalize authority fields from older releases. */
 	load(state: TopicRegistryState): void {
 		for (const [sessionId, epoch] of Object.entries(state.fences ?? {})) {
@@ -94,9 +186,10 @@ export class TopicRegistry {
 				raw.nameOwner === "user" &&
 				typeof raw.name === "string" &&
 				raw.name.trim().length > 0 &&
-				typeof raw.userNameUpdateId === "number" &&
-				Number.isSafeInteger(raw.userNameUpdateId) &&
-				raw.userNameUpdateId >= 0;
+				(raw.userNameUpdateId === undefined ||
+					(typeof raw.userNameUpdateId === "number" &&
+						Number.isSafeInteger(raw.userNameUpdateId) &&
+						raw.userNameUpdateId >= 0));
 			const hasValidReplayCursor =
 				typeof raw.replayGeneration === "number" &&
 				Number.isSafeInteger(raw.replayGeneration) &&
@@ -104,6 +197,19 @@ export class TopicRegistry {
 				typeof raw.replaySeq === "number" &&
 				Number.isSafeInteger(raw.replaySeq) &&
 				raw.replaySeq >= 0;
+			const legacyUnbound = !hasAnyBinding(raw);
+			const bindingMalformed = raw.bindingMalformed === true || (!legacyUnbound && !hasCompleteBinding(raw));
+			const candidateAuthorityEpoch = raw.authorityEpoch;
+			const rawAuthorityEpoch: number =
+				typeof candidateAuthorityEpoch === "number" &&
+				Number.isSafeInteger(candidateAuthorityEpoch) &&
+				candidateAuthorityEpoch >= 0
+					? candidateAuthorityEpoch
+					: 0;
+			// A fence is the durable authority source. A mixed snapshot can contain an
+			// older active record alongside a newer fence; never rebuild its inbound route.
+			const fenceEpoch = this.epochs.get(sessionId) ?? 0;
+			const fenceSupersedesRecord = fenceEpoch > rawAuthorityEpoch;
 			const record: TopicRecord = {
 				topicId: raw.topicId,
 				identitySent: raw.identitySent === true,
@@ -114,15 +220,33 @@ export class TopicRegistry {
 					: {}),
 				...(hasValidUserAuthority ? { nameOwner: "user" as const } : {}),
 				...(hasValidUserAuthority && raw.nameReconcilePending === true ? { nameReconcilePending: true } : {}),
-				...(hasValidUserAuthority ? { userNameUpdateId: raw.userNameUpdateId } : {}),
+				...(hasValidUserAuthority && typeof raw.userNameUpdateId === "number"
+					? { userNameUpdateId: raw.userNameUpdateId }
+					: {}),
 				...(typeof raw.identityKey === "string" ? { identityKey: raw.identityKey } : {}),
+				...(typeof raw.creationLeaseEpoch === "number" &&
+				Number.isSafeInteger(raw.creationLeaseEpoch) &&
+				raw.creationLeaseEpoch >= 0
+					? { creationLeaseEpoch: raw.creationLeaseEpoch }
+					: {}),
 				...(hasValidReplayCursor ? { replayGeneration: raw.replayGeneration, replaySeq: raw.replaySeq } : {}),
-				...(Number.isSafeInteger(raw.authorityEpoch) && raw.authorityEpoch! >= 0
-					? { authorityEpoch: raw.authorityEpoch }
+				authorityEpoch: Math.max(rawAuthorityEpoch, fenceEpoch),
+				...(raw.authorityState === "delete_pending" || fenceSupersedesRecord
+					? { authorityState: "delete_pending" as const }
+					: {}),
+				...(isValidBindingString(raw.chatId) ? { chatId: raw.chatId } : {}),
+				...(isValidBindingString(raw.endpointKey) ? { endpointKey: raw.endpointKey } : {}),
+				...(isValidBindingString(raw.endpointDigest) ? { endpointDigest: raw.endpointDigest } : {}),
+				...(isValidBindingGeneration(raw.endpointGeneration) ? { endpointGeneration: raw.endpointGeneration } : {}),
+				...(isValidBindingGeneration(raw.endpointIncarnation)
+					? { endpointIncarnation: raw.endpointIncarnation }
 					: {}),
-				...(raw.authorityState === "delete_pending" ? { authorityState: "delete_pending" as const } : {}),
+				...(bindingMalformed ? { bindingMalformed: true as const } : {}),
 			};
-			this.epochs.set(sessionId, Math.max(this.epochs.get(sessionId) ?? 0, record.authorityEpoch ?? 0));
+			this.epochs.set(sessionId, Math.max(fenceEpoch, record.authorityEpoch ?? 0));
+			// Pre-generation-17 records have no endpoint authority. Retire them locally:
+			// their unknown remote topic must neither be rebound nor deleted cross-chat.
+			if (legacyUnbound) continue;
 
 			this.topics.set(sessionId, record);
 		}
@@ -135,7 +259,7 @@ export class TopicRegistry {
 		const activeByTopic = new Map<string, string>();
 
 		for (const [sessionId, record] of this.topics) {
-			if (record.authorityState === "delete_pending") {
+			if (record.authorityState === "delete_pending" || record.bindingMalformed) {
 				this.#ambiguousTopicIds.add(record.topicId);
 				continue;
 			}
@@ -161,11 +285,164 @@ export class TopicRegistry {
 		return [...this.topics.keys()];
 	}
 
+	/** Persisted remote deletes that must be reconciled before recovery can proceed. */
+	deletePendingSessionIds(): string[] {
+		return [...this.topics].flatMap(([sessionId, record]) =>
+			record.authorityState === "delete_pending" ? [sessionId] : [],
+		);
+	}
+
 	/** The existing topic record for a session, if any. */
 	get(sessionId: string): TopicRecord | undefined {
 		return this.topics.get(sessionId);
 	}
 
+	/** Current immutable authority epoch for a creation lease. */
+	authorityEpoch(sessionId: string): number {
+		return Math.max(this.epochs.get(sessionId) ?? 0, this.topics.get(sessionId)?.authorityEpoch ?? 0);
+	}
+
+	/** Whether this session has an active, unambiguous topic authority. */
+	isActiveUnambiguous(sessionId: string): boolean {
+		const record = this.topics.get(sessionId);
+		return record?.authorityState !== "delete_pending" && this.byTopic.get(record?.topicId ?? "") === sessionId;
+	}
+
+	/**
+	 * Resolve endpoint authority for identity-less replay. An endpoint may bootstrap
+	 * only when no committed, staged, or pre-create claim can own it; malformed
+	 * partial bindings and deletion fences deliberately fail closed.
+	 */
+	endpointAuthority(binding: TopicEndpointBinding, excludedTransientClaimant?: object): TopicEndpointAuthority {
+		if (!hasValidBinding(binding)) return { state: "ambiguous" };
+		const canClaim = (record: Pick<TopicRecord, "chatId" | "endpointKey" | "endpointDigest">): boolean =>
+			(record.chatId === undefined || record.chatId === binding.chatId) &&
+			(record.endpointKey === undefined || record.endpointKey === binding.endpointKey) &&
+			(record.endpointDigest === undefined || record.endpointDigest === binding.endpointDigest);
+		const committed = [...this.topics].filter(([, record]) => canClaim(record));
+		const excludesClaimant = (sessionId: string): boolean =>
+			excludedTransientClaimant !== undefined &&
+			this.transientClaimants.get(sessionId) === excludedTransientClaimant;
+		const staged = [...this.staged].filter(([sessionId, record]) => canClaim(record) && !excludesClaimant(sessionId));
+		const creating = [...this.creatingBindings].filter(
+			([sessionId, claim]) => canClaim(claim) && !excludesClaimant(sessionId),
+		);
+		if (committed.length === 0 && staged.length === 0 && creating.length === 0) return { state: "none" };
+		if (committed.length !== 1 || staged.length !== 0 || creating.length !== 0) return { state: "ambiguous" };
+		const [sessionId, record] = committed[0]!;
+		return record.chatId === binding.chatId &&
+			record.endpointKey === binding.endpointKey &&
+			record.endpointDigest === binding.endpointDigest &&
+			this.isActiveUnambiguous(sessionId) &&
+			!record.bindingMalformed
+			? { state: "unique", sessionId }
+			: { state: "ambiguous" };
+	}
+
+	/** Resolve a uniquely bound logical owner for callers that only need the owner. */
+	uniqueSessionForEndpoint(binding: TopicEndpointBinding): string | undefined {
+		const authority = this.endpointAuthority(binding);
+		return authority.state === "unique" ? authority.sessionId : undefined;
+	}
+
+	/** Whether this exact session owns the complete durable endpoint binding. */
+	matchesEndpoint(sessionId: string, binding: TopicEndpointBinding): boolean {
+		const record = this.topics.get(sessionId);
+		return (
+			this.isActiveUnambiguous(sessionId) &&
+			!record?.bindingMalformed &&
+			record?.chatId === binding.chatId &&
+			record.endpointKey === binding.endpointKey &&
+			record.endpointDigest === binding.endpointDigest
+		);
+	}
+
+	/**
+	 * Rebind an existing topic to an authenticated successor endpoint. The exact
+	 * logical session id is proved by replay before this method is called. A
+	 * rotated credential may replace only an inactive incumbent; concurrent
+	 * incumbents, cross-chat records, malformed evidence, collisions, and delete
+	 * fences remain fail-closed.
+	 */
+	bindEndpoint(
+		sessionId: string,
+		binding: TopicEndpointBinding,
+		activeEndpointKeys: ReadonlySet<string> = new Set(),
+		allowEndpointRotation = false,
+	): "bound" | "unchanged" | "rejected" {
+		const record = this.topics.get(sessionId);
+		if (
+			!record ||
+			record.authorityState === "delete_pending" ||
+			record.bindingMalformed ||
+			!hasValidBinding(binding) ||
+			!this.isActiveUnambiguous(sessionId)
+		)
+			return "rejected";
+		if (hasAnyBinding(record) && !hasCompleteBinding(record)) return "rejected";
+		// A topic id without chat affinity may belong to any prior paired chat.
+		// Do not bind it to the current chat merely because a resumed endpoint
+		// authenticated its logical session id.
+		if (record.chatId === undefined || record.chatId !== binding.chatId) return "rejected";
+
+		const sameEndpoint =
+			record.endpointKey === binding.endpointKey && record.endpointDigest === binding.endpointDigest;
+		if (
+			sameEndpoint &&
+			record.endpointGeneration !== undefined &&
+			binding.endpointGeneration !== undefined &&
+			binding.endpointGeneration < record.endpointGeneration
+		)
+			return "rejected";
+		if (
+			!sameEndpoint &&
+			hasAnyBinding(record) &&
+			(!allowEndpointRotation || (record.endpointKey !== undefined && activeEndpointKeys.has(record.endpointKey)))
+		)
+			return "rejected";
+
+		const changed =
+			record.chatId !== binding.chatId ||
+			record.endpointKey !== binding.endpointKey ||
+			record.endpointDigest !== binding.endpointDigest ||
+			record.endpointGeneration !== binding.endpointGeneration;
+		if (!changed) return "unchanged";
+		record.chatId = binding.chatId;
+		record.endpointKey = binding.endpointKey;
+		record.endpointDigest = binding.endpointDigest;
+		record.endpointGeneration = binding.endpointGeneration;
+		if (!sameEndpoint) record.endpointIncarnation = (record.endpointIncarnation ?? 0) + 1;
+		return "bound";
+	}
+
+	/** Undo a failed durable endpoint migration without disturbing concurrent metadata writers. */
+	restoreEndpointBinding(
+		sessionId: string,
+		expected: TopicEndpointBinding,
+		previous: Pick<
+			TopicRecord,
+			"chatId" | "endpointKey" | "endpointDigest" | "endpointGeneration" | "endpointIncarnation"
+		>,
+	): boolean {
+		const record = this.topics.get(sessionId);
+		if (
+			!record ||
+			record.chatId !== expected.chatId ||
+			record.endpointKey !== expected.endpointKey ||
+			record.endpointDigest !== expected.endpointDigest ||
+			record.endpointGeneration !== expected.endpointGeneration
+		)
+			return false;
+		record.chatId = previous.chatId;
+		record.endpointKey = previous.endpointKey;
+		record.endpointDigest = previous.endpointDigest;
+		if (previous.endpointGeneration === undefined) delete record.endpointGeneration;
+		else record.endpointGeneration = previous.endpointGeneration;
+		if (previous.endpointIncarnation === undefined) delete record.endpointIncarnation;
+		else record.endpointIncarnation = previous.endpointIncarnation;
+		return true;
+	}
+
 	/**
 	 * Return the existing active topic for `sessionId`, or create one via
 	 * `create` (called only on first use).
@@ -175,13 +452,22 @@ export class TopicRegistry {
 		create: () => Promise<unknown>,
 		now: () => number = Date.now,
 		name?: string,
+		binding?: TopicEndpointBinding,
+		commit?: () => Promise<void>,
+		transientClaimant?: object,
 	): Promise<TopicRecord> {
 		const existing = this.topics.get(sessionId);
 		if (existing?.authorityState === "delete_pending") throw new Error("topic authority is deletion-fenced");
+		if (existing?.bindingMalformed) throw new Error("topic authority binding is quarantined");
 		if (existing) return existing;
 		const pending = this.inflight.get(sessionId);
 		if (pending) return pending;
 		const epoch = this.epochs.get(sessionId) ?? 0;
+		// Publish the compatible endpoint claim before invoking `create`: the callback
+		// may immediately begin a remote create and identity-less recovery must never
+		// observe a false absence during that await.
+		if (binding) this.creatingBindings.set(sessionId, binding);
+		this.transientClaimants.set(sessionId, transientClaimant);
 		const promise = (async () => {
 			const topicId = await create();
 			if (!isValidTopicId(topicId)) throw new Error("createForumTopic: invalid message_thread_id");
@@ -192,10 +478,39 @@ export class TopicRegistry {
 				identitySent: false,
 				createdAt: now(),
 				authorityEpoch: revoked ? (this.epochs.get(sessionId) ?? 0) : epoch,
+				creationLeaseEpoch: epoch,
+				...(binding
+					? {
+							chatId: binding.chatId,
+							endpointKey: binding.endpointKey,
+							endpointDigest: binding.endpointDigest,
+							endpointIncarnation: 0,
+							...(binding.endpointGeneration === undefined
+								? {}
+								: { endpointGeneration: binding.endpointGeneration }),
+						}
+					: {}),
 				...(revoked ? { authorityState: "delete_pending" as const } : {}),
 			};
+			if (revoked) {
+				this.topics.set(sessionId, record);
+				throw new Error("topic authority was revoked during creation");
+			}
+			this.staged.set(sessionId, record);
+			try {
+				await commit?.();
+			} catch (error) {
+				this.staged.delete(sessionId);
+				throw error;
+			}
+			this.staged.delete(sessionId);
+			if ((this.epochs.get(sessionId) ?? 0) !== epoch) {
+				record.authorityEpoch = this.epochs.get(sessionId) ?? 0;
+				record.authorityState = "delete_pending";
+				this.topics.set(sessionId, record);
+				throw new Error("topic authority was revoked during creation");
+			}
 			this.topics.set(sessionId, record);
-			if (revoked) throw new Error("topic authority was revoked during creation");
 			if (this.#ambiguousTopicIds.has(topicId)) return record;
 			if (this.byTopic.has(topicId)) {
 				this.byTopic.delete(topicId);
@@ -210,6 +525,8 @@ export class TopicRegistry {
 			return await promise;
 		} finally {
 			this.inflight.delete(sessionId);
+			this.creatingBindings.delete(sessionId);
+			this.transientClaimants.delete(sessionId);
 		}
 	}
 
@@ -323,6 +640,67 @@ export class TopicRegistry {
 		record.nameReconcilePending = false;
 	}
 
+	/** Capture only authority fields that a failed delete publication may restore. */
+	captureDeleteAuthority(sessionId: string): TopicDeleteAuthoritySnapshot {
+		const record = this.topics.get(sessionId);
+		return {
+			sessionId,
+			topicId: record?.topicId,
+			authorityEpoch: record?.authorityEpoch,
+			authorityState: record?.authorityState,
+			fenceEpoch: this.epochs.get(sessionId),
+			...(record ? { record: { ...record } } : {}),
+		};
+	}
+
+	/** Restore a failed delete fence only while its exact authority mutation remains current. */
+	restoreDeleteAuthority(snapshot: TopicDeleteAuthoritySnapshot): boolean {
+		const record = this.topics.get(snapshot.sessionId);
+		const deleteEpoch = Math.max(snapshot.fenceEpoch ?? 0, snapshot.authorityEpoch ?? 0) + 1;
+		if (this.epochs.get(snapshot.sessionId) !== deleteEpoch) return false;
+		if (snapshot.topicId === undefined) {
+			if (record) return false;
+		} else if (
+			!record ||
+			record.topicId !== snapshot.topicId ||
+			record.authorityState !== "delete_pending" ||
+			record.authorityEpoch !== deleteEpoch
+		) {
+			return false;
+		} else {
+			record.authorityEpoch = snapshot.authorityEpoch;
+			record.authorityState = snapshot.authorityState;
+			this.rebuildInboundRoutes();
+		}
+		if (snapshot.fenceEpoch === undefined) this.epochs.delete(snapshot.sessionId);
+		else this.epochs.set(snapshot.sessionId, snapshot.fenceEpoch);
+		return true;
+	}
+
+	/** Restore the exact delete fence after a failed compensation publication. */
+	restoreDeleteFence(snapshot: TopicDeleteAuthoritySnapshot): boolean {
+		const record = this.topics.get(snapshot.sessionId);
+		const deleteEpoch = Math.max(snapshot.fenceEpoch ?? 0, snapshot.authorityEpoch ?? 0) + 1;
+		if (snapshot.topicId === undefined) {
+			if (record) return false;
+		} else if (!record) {
+			if (!snapshot.record) return false;
+			this.topics.set(snapshot.sessionId, {
+				...snapshot.record,
+				authorityEpoch: deleteEpoch,
+				authorityState: "delete_pending",
+			});
+		} else if (record.topicId !== snapshot.topicId) {
+			return false;
+		} else {
+			record.authorityEpoch = deleteEpoch;
+			record.authorityState = "delete_pending";
+			if (this.byTopic.get(record.topicId) === snapshot.sessionId) this.byTopic.delete(record.topicId);
+		}
+		this.epochs.set(snapshot.sessionId, deleteEpoch);
+		return true;
+	}
+
 	/** Fence new work before the remote delete starts, including an absent in-flight create. */
 	beginDelete(sessionId: string): TopicRecord | undefined {
 		const record = this.topics.get(sessionId);
@@ -335,6 +713,67 @@ export class TopicRegistry {
 		return record;
 	}
 
+	/** Retain an accepted create as deletion-fenced before remote compensation can begin. */
+	fenceAcceptedCreate(
+		sessionId: string,
+		topicId: string,
+		now: () => number = Date.now,
+		name?: string,
+		binding?: TopicEndpointBinding,
+	): TopicRecord {
+		const epoch = Math.max(this.epochs.get(sessionId) ?? 0, this.topics.get(sessionId)?.authorityEpoch ?? 0);
+		const record: TopicRecord = {
+			topicId,
+			name,
+			identitySent: false,
+			createdAt: now(),
+			authorityEpoch: epoch,
+			authorityState: "delete_pending",
+			...(binding
+				? {
+						chatId: binding.chatId,
+						endpointKey: binding.endpointKey,
+						endpointDigest: binding.endpointDigest,
+						endpointIncarnation: 0,
+						...(binding.endpointGeneration === undefined
+							? {}
+							: { endpointGeneration: binding.endpointGeneration }),
+					}
+				: {}),
+		};
+		this.topics.set(sessionId, record);
+		if (this.byTopic.get(topicId) === sessionId) this.byTopic.delete(topicId);
+		this.#ambiguousTopicIds.add(topicId);
+		return record;
+	}
+
+	/** Fence an accepted create only when its exact creator lease still owns the record. */
+	fenceAcceptedCreateForLease(
+		sessionId: string,
+		topicId: string,
+		creationLeaseEpoch: number,
+		now: () => number = Date.now,
+		name?: string,
+		binding?: TopicEndpointBinding,
+	): TopicRecord | undefined {
+		const record = this.topics.get(sessionId);
+		const matchesBinding =
+			record?.chatId === binding?.chatId &&
+			record?.endpointKey === binding?.endpointKey &&
+			record?.endpointDigest === binding?.endpointDigest &&
+			record?.endpointGeneration === binding?.endpointGeneration;
+		if (
+			record
+				? record.topicId !== topicId || record.creationLeaseEpoch !== creationLeaseEpoch || !matchesBinding
+				: (this.epochs.get(sessionId) ?? 0) !== creationLeaseEpoch
+		)
+			return undefined;
+		this.beginDelete(sessionId);
+		const fenced = this.fenceAcceptedCreate(sessionId, topicId, now, name, binding);
+		fenced.creationLeaseEpoch = creationLeaseEpoch;
+		return fenced;
+	}
+
 	/** Wait for a revoked create to settle before admitting a later lifecycle epoch. */
 	async awaitInflight(sessionId: string): Promise<void> {
 		await this.inflight.get(sessionId)?.catch(() => undefined);
@@ -357,8 +796,8 @@ export class TopicRegistry {
 		return this.topics.delete(sessionId);
 	}
 
-	/** Serialise for atomic persistence beside the daemon state. */
+	/** Serialise active records plus unpublished staged creates for atomic commit. */
 	serialize(): TopicRegistryState {
-		return { topics: Object.fromEntries(this.topics), fences: Object.fromEntries(this.epochs) };
+		return { topics: Object.fromEntries([...this.topics, ...this.staged]), fences: Object.fromEntries(this.epochs) };
 	}
 }

package/src/sdk/client/discovery.ts

@@ -6,6 +6,8 @@ export interface SdkSessionEndpoint {
 	sessionId: string;
 	url: string;
 	token: string;
+	pid?: number;
+	stale?: boolean;
 	path: string;
 }
 
@@ -38,12 +40,26 @@ function endpointDirectory(repo: string): string {
 function parseEndpoint(sessionId: string, file: string, value: unknown): SdkSessionEndpoint {
 	if (!value || typeof value !== "object")
 		throw new SdkDiscoveryError(file, "SDK endpoint discovery record must be an object.");
-	const endpoint = value as { version?: unknown; url?: unknown; token?: unknown };
+	const endpoint = value as { version?: unknown; url?: unknown; token?: unknown; pid?: unknown; stale?: unknown };
 	if (typeof endpoint.version === "number" && endpoint.version > 1)
 		throw new SdkDiscoveryError(file, "Unsupported SDK endpoint discovery state version.");
-	if (typeof endpoint.url !== "string" || typeof endpoint.token !== "string" || !endpoint.url || !endpoint.token)
+	if (typeof endpoint.url !== "string" || !endpoint.url)
 		throw new SdkDiscoveryError(file, "SDK endpoint discovery record is invalid.");
-	return { sessionId, url: endpoint.url, token: endpoint.token, path: file };
+	const stale = typeof endpoint.stale === "boolean" ? endpoint.stale : undefined;
+	const pid =
+		typeof endpoint.pid === "number" && Number.isInteger(endpoint.pid) && endpoint.pid > 0 ? endpoint.pid : undefined;
+	if (endpoint.token !== undefined && typeof endpoint.token !== "string")
+		throw new SdkDiscoveryError(file, "SDK endpoint discovery record is invalid.");
+	const token = endpoint.token ?? "";
+	if (!token && stale !== true) throw new SdkDiscoveryError(file, "SDK endpoint discovery record is invalid.");
+	return {
+		sessionId,
+		url: endpoint.url,
+		token,
+		...(pid === undefined ? {} : { pid }),
+		...(stale === undefined ? {} : { stale }),
+		path: file,
+	};
 }
 
 function discoveryError(file: string, error: unknown): SdkDiscoveryError {

package/src/sdk/client/liveness.ts

@@ -0,0 +1,49 @@
+import type { SdkSessionEndpoint } from "./discovery";
+
+export type SdkEndpointLiveness = "live" | "stale" | "dead" | "unknown";
+
+export interface SdkEndpointSelectionError {
+	code:
+		| "endpoint_stale"
+		| "endpoint_dead"
+		| "endpoint_unknown"
+		| "no_live_endpoint"
+		| "multiple_live_endpoints"
+		| "not_found";
+}
+
+export function classifyEndpoint(endpoint: SdkSessionEndpoint): SdkEndpointLiveness {
+	if (endpoint.stale === true) return "stale";
+	if (!Number.isInteger(endpoint.pid) || endpoint.pid === undefined || endpoint.pid <= 0) return "unknown";
+	try {
+		process.kill(endpoint.pid, 0);
+		return "live";
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code === "ESRCH") return "dead";
+		return code === "EPERM" ? "live" : "unknown";
+	}
+}
+
+export function selectLiveEndpoint(
+	records: readonly SdkSessionEndpoint[],
+	explicitSessionId?: string,
+): SdkSessionEndpoint | SdkEndpointSelectionError {
+	if (explicitSessionId !== undefined) {
+		const endpoint = records.find(record => record.sessionId === explicitSessionId);
+		if (!endpoint) return { code: "not_found" };
+		switch (classifyEndpoint(endpoint)) {
+			case "live":
+				return endpoint;
+			case "stale":
+				return { code: "endpoint_stale" };
+			case "dead":
+				return { code: "endpoint_dead" };
+			case "unknown":
+				return { code: "endpoint_unknown" };
+		}
+	}
+	const live = records.filter(record => classifyEndpoint(record) === "live");
+	if (live.length === 1) return live[0]!;
+	return { code: live.length === 0 ? "no_live_endpoint" : "multiple_live_endpoints" };
+}

package/src/sdk/protocol/operation-inventory.generated.json

@@ -4430,6 +4430,17 @@
 			"testIds": "not_applicable"
 		}
 	},
+	{
+		"sourceId": "agent_session:createBtwConversationScope",
+		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",
+		"sourceKind": "agent_session",
+		"decision": "exclude",
+		"rationale": "internal privacy-scoped side-chat snapshot factory, not a user-facing SDK control seam",
+		"exclusionMetadata": {
+			"adapterMappings": "not_applicable",
+			"testIds": "not_applicable"
+		}
+	},
 	{
 		"sourceId": "agent_session:runEphemeralTurn",
 		"sourceFile": "packages/coding-agent/src/session/agent-session.ts",