@gajae-code/coding-agent 0.13.2 → 0.14.0

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

@@ -1,12 +1,13 @@
 import { randomUUID } from "node:crypto";
 /**
- * Per-session forum-topic registry for the threaded session surface.
+ * Forum-topic registry for eligible orchestration sessions on the threaded
+ * Telegram surface.
  *
- * Each GJC session owns one active Telegram forum topic. Remote archive closes
- * daemon-created topics without deleting their durable records; rotated
- * successors move inactive records into retained history before creating a new
- * active authority. The registry also tracks whether the one-time identity
- * header has already been pinned.
+ * Each eligible orchestration session owns one active Telegram forum topic.
+ * Remote archive closes daemon-created topics without deleting their durable
+ * records; rotated successors move inactive records into retained history before
+ * creating a new active authority. The registry also tracks whether the one-time
+ * identity header has already been pinned.
  *
  * State is a plain serialisable map persisted beside the daemon state files;
  * topic creation is injected so this module is pure and unit-testable without a
@@ -60,6 +61,10 @@ export interface TopicRecord {
 	authorityState?: TopicLifecycleState;
 	/** Telegram chat and endpoint authority last proven to use this topic. */
 	chatId?: string;
+	/** Stable provider binding; never contains SDK endpoint or attachment identity. */
+	telegramBinding?: TelegramTopicBinding;
+	/** Why this record is archive-fenced; absence means no remote archive is authorized. */
+	archiveReason?: "session_closed" | "notification_subscription_removed" | "create_compensation";
 	/** Canonical endpoint tuple (URL + token) that currently holds the lease. */
 	endpointKey?: string;
 	/** Authenticated endpoint authority digest, excluding transport presentation. */
@@ -87,6 +92,8 @@ export interface TopicCreateClaim {
 	leaseOwner?: string;
 	authorityEpoch: number;
 	createdAt: number;
+	telegramBinding?: TelegramTopicBinding;
+	/** Legacy v2 input only; never emitted by serialize(). */
 	binding?: TopicEndpointBinding;
 }
 
@@ -114,8 +121,8 @@ export interface TopicRegistryState {
 	topics: Record<string, TopicRecord>;
 	/** Durable lifecycle epochs retained after an archive starts. */
 	fences?: Record<string, number>;
-	/** Closed transport endpoint leases; unchanged endpoint discovery remains fenced across restart. */
-	closedEndpoints?: Record<string, TopicEndpointBinding>;
+	/** Closed durable Telegram bindings; values intentionally contain no SDK endpoint identity. */
+	closedEndpoints?: Record<string, TelegramTopicBinding>;
 	/** Persistent host identity used to distinguish concurrent installations. */
 	installationHostId?: string;
 	/** Bounded durable archive work; no topic record is physically deleted. */
@@ -134,11 +141,22 @@ export interface TopicRegistryCasAuthority {
 	compareAndSet(expectedGeneration: number, next: TopicRegistryState): Promise<boolean>;
 }
 
+/** Durable Telegram authority. This is the only binding shape writers persist. */
+export interface TelegramTopicBinding {
+	chatId: string;
+	transport: "telegram";
+}
+
+export type TopicArchiveReason = NonNullable<TopicRecord["archiveReason"]>;
+
 /** Authenticated runtime binding for a durable topic lease. */
 export interface TopicEndpointBinding {
 	chatId: string;
-	endpointKey: string;
-	endpointDigest: string;
+	transport?: "telegram";
+	logicalSessionId?: string;
+	/** Legacy input-only fields. They are never authority or persistence fields. */
+	endpointKey?: string;
+	endpointDigest?: string;
 	endpointGeneration?: number;
 }
 
@@ -159,6 +177,12 @@ export interface TopicArchiveAuthoritySnapshot {
 	record?: TopicRecord;
 }
 
+function isTopicArchiveReason(value: unknown): value is TopicArchiveReason {
+	return (
+		value === "session_closed" || value === "notification_subscription_removed" || value === "create_compensation"
+	);
+}
+
 function isValidBindingString(value: unknown): value is string {
 	return typeof value === "string" && value.trim().length > 0;
 }
@@ -168,6 +192,7 @@ function isValidBindingGeneration(value: unknown): value is number {
 }
 function hasAnyBinding(record: TopicRecord): boolean {
 	return (
+		record.telegramBinding !== undefined ||
 		record.chatId !== undefined ||
 		record.endpointKey !== undefined ||
 		record.endpointDigest !== undefined ||
@@ -176,22 +201,23 @@ function hasAnyBinding(record: TopicRecord): boolean {
 	);
 }
 
-function hasCompleteBinding(record: TopicRecord): boolean {
+function hasStableTelegramBinding(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))
+		record.telegramBinding !== undefined &&
+		isValidBindingString(record.telegramBinding.chatId) &&
+		record.telegramBinding.transport === "telegram"
 	);
 }
 
+function hasCompleteBinding(record: TopicRecord): boolean {
+	return hasStableTelegramBinding(record);
+}
+
 function hasValidBinding(binding: TopicEndpointBinding): boolean {
 	return (
 		isValidBindingString(binding.chatId) &&
-		isValidBindingString(binding.endpointKey) &&
-		isValidBindingString(binding.endpointDigest) &&
-		(binding.endpointGeneration === undefined || isValidBindingGeneration(binding.endpointGeneration))
+		(binding.transport === undefined || binding.transport === "telegram") &&
+		(binding.logicalSessionId === undefined || isValidBindingString(binding.logicalSessionId))
 	);
 }
 
@@ -207,15 +233,38 @@ function nextAuthorityEpoch(current: number): number {
 export function emptyTopicRegistryState(): TopicRegistryState {
 	return { version: 2, topics: {} };
 }
+
+/** Strip SDK endpoint authority from legacy v2 records without archiving them. */
+function migrateLegacyTopicBinding(record: Record<string, unknown>): Record<string, unknown> {
+	const migrated = { ...record };
+	const chatId =
+		isObjectLike(migrated.telegramBinding) && isValidBindingString(migrated.telegramBinding.chatId)
+			? migrated.telegramBinding.chatId
+			: migrated.chatId;
+	if (isValidBindingString(chatId)) {
+		migrated.telegramBinding = { chatId, transport: "telegram" };
+		delete migrated.endpointKey;
+		delete migrated.endpointDigest;
+		delete migrated.endpointGeneration;
+		delete migrated.endpointIncarnation;
+	}
+	return migrated;
+}
+
+function isObjectLike(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
 /**
  * Reject snapshots written by a newer daemon. Missing versions are preserved as
  * evidence but quarantined: legacy records must never route or mutate remotely.
  */
 export function parseTopicRegistryState(value: unknown): TopicRegistryState | undefined {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	if (value === undefined) return undefined;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("malformed Telegram topic state");
 	let state = value as TopicRegistryState;
 	if (state.version !== undefined && state.version !== 2) throw new Error("unsupported future Telegram topic state");
-	if (!state.topics || typeof state.topics !== "object" || Array.isArray(state.topics)) return undefined;
+	if (!state.topics || typeof state.topics !== "object" || Array.isArray(state.topics))
+		throw new Error("malformed Telegram topic state");
 	if (state.version === undefined) {
 		if (state.registryGeneration !== undefined) throw new Error("malformed Telegram topic state");
 		return parseTopicRegistryState({
@@ -228,6 +277,7 @@ export function parseTopicRegistryState(value: unknown): TopicRegistryState | un
 					record && typeof record === "object"
 						? {
 								...record,
+								...migrateLegacyTopicBinding(record as unknown as Record<string, unknown>),
 								topicOrigin: (record as TopicRecord).topicOrigin ?? "daemon_created",
 								authorityState: "legacy_quarantined",
 							}
@@ -258,7 +308,40 @@ export function parseTopicRegistryState(value: unknown): TopicRegistryState | un
 								: records,
 						]),
 					),
+		// Pre-#4401 writers persisted closed-endpoint bindings without the
+		// `transport` discriminator. Rejecting them would permanently brick an
+		// otherwise-healthy shared registry (the same class as the
+		// disconnectGraceExpiresAt artifact below): the CAS authority refuses
+		// every read and write forever. The transport can only be "telegram" in
+		// those snapshots, so heal the in-memory record; the serializer no
+		// longer persists closed endpoints at all. Only heal records that match
+		// the complete pre-#4401 shape (chatId + endpointKey + endpointDigest +
+		// endpointGeneration): partial records are corruption, not legacy data.
+		closedEndpoints:
+			state.closedEndpoints === undefined
+				? undefined
+				: isObject(state.closedEndpoints)
+					? Object.fromEntries(
+							Object.entries(state.closedEndpoints).map(([sessionId, binding]) => [
+								sessionId,
+								isObject(binding) &&
+								binding.transport === undefined &&
+								isValidBindingString(binding.chatId) &&
+								isValidBindingString(binding.endpointKey) &&
+								isValidBindingString(binding.endpointDigest) &&
+								isValidBindingGeneration(binding.endpointGeneration)
+									? ({ chatId: binding.chatId, transport: "telegram" } as TelegramTopicBinding)
+									: binding,
+							]),
+						)
+					: state.closedEndpoints,
 	};
+	state.topics = Object.fromEntries(
+		Object.entries(state.topics).map(([sessionId, record]) => [
+			sessionId,
+			isObject(record) ? (migrateLegacyTopicBinding(record) as unknown as TopicRecord) : record,
+		]),
+	);
 	const validTimestamp = (candidate: unknown): candidate is number =>
 		typeof candidate === "number" && Number.isFinite(candidate) && candidate >= 0;
 	const validEpoch = (candidate: unknown): candidate is number =>
@@ -268,12 +351,13 @@ export function parseTopicRegistryState(value: unknown): TopicRegistryState | un
 	const validBinding = (candidate: unknown): candidate is TopicEndpointBinding =>
 		isObject(candidate) &&
 		isValidBindingString(candidate.chatId) &&
-		isValidBindingString(candidate.endpointKey) &&
-		isValidBindingString(candidate.endpointDigest) &&
-		(candidate.endpointGeneration === undefined || isValidBindingGeneration(candidate.endpointGeneration));
+		(candidate.transport === undefined || candidate.transport === "telegram") &&
+		(candidate.logicalSessionId === undefined || isValidBindingString(candidate.logicalSessionId));
 	const malformed = (): never => {
 		throw new Error("malformed Telegram topic state");
 	};
+	const validTelegramBinding = (candidate: unknown): candidate is TelegramTopicBinding =>
+		isObject(candidate) && isValidBindingString(candidate.chatId) && candidate.transport === "telegram";
 
 	if (
 		(state.registryGeneration !== undefined && !validEpoch(state.registryGeneration)) ||
@@ -286,6 +370,13 @@ export function parseTopicRegistryState(value: unknown): TopicRegistryState | un
 	for (const [sessionId, raw] of Object.entries(state.topics)) {
 		if (!isValidBindingString(sessionId) || !isObject(raw) || !isValidTopicId(raw.topicId)) malformed();
 		if (typeof raw.identitySent !== "boolean" || !validTimestamp(raw.createdAt)) malformed();
+		if (
+			raw.telegramBinding !== undefined &&
+			(!isObject(raw.telegramBinding) ||
+				!isValidBindingString(raw.telegramBinding.chatId) ||
+				raw.telegramBinding.transport !== "telegram")
+		)
+			malformed();
 		if (
 			!validOptionalString(raw.sessionUuid) ||
 			(raw.orphanedAt !== undefined && !validTimestamp(raw.orphanedAt)) ||
@@ -332,8 +423,13 @@ export function parseTopicRegistryState(value: unknown): TopicRegistryState | un
 				raw.authorityState !== "inactive"
 			)
 				malformed();
-			// Older archive transitions retained the expired disconnect-grace marker,
-			// making the entire shared registry unreadable on the next daemon start.
+			// A grace deadline on a non-grace record is a known artifact of the
+			// v0.12.12–v0.12.17 archive writers, which moved disconnect_grace records
+			// to archive_pending without clearing disconnectGraceExpiresAt (fixed by
+			// #4054). Rejecting it here permanently bricked otherwise-healthy shared
+			// registries: the CAS authority refused every read and write forever.
+			// The field is inert outside disconnect_grace, so drop it here to heal
+			// the in-memory state; the next serialize no longer persists it.
 			delete raw.disconnectGraceExpiresAt;
 		}
 		const hasBinding = hasAnyBinding(raw);
@@ -346,15 +442,12 @@ export function parseTopicRegistryState(value: unknown): TopicRegistryState | un
 			raw.endpointDigest === undefined &&
 			raw.endpointGeneration === undefined &&
 			raw.endpointIncarnation === undefined;
-		if (
-			hasBinding &&
-			!hasArchiveOnlyChatIdentity &&
-			(!isValidBindingString(raw.chatId) ||
-				!isValidBindingString(raw.endpointKey) ||
-				!isValidBindingString(raw.endpointDigest) ||
-				(raw.endpointGeneration !== undefined && !isValidBindingGeneration(raw.endpointGeneration)) ||
-				(raw.endpointIncarnation !== undefined && !isValidBindingGeneration(raw.endpointIncarnation)))
-		)
+		const hasStableTelegramBinding =
+			raw.telegramBinding !== undefined &&
+			isObjectLike(raw.telegramBinding) &&
+			isValidBindingString(raw.telegramBinding.chatId) &&
+			raw.telegramBinding.transport === "telegram";
+		if (hasBinding && !hasStableTelegramBinding && !hasArchiveOnlyChatIdentity && !isValidBindingString(raw.chatId))
 			malformed();
 	}
 	for (const [sessionId, records] of Object.entries(state.retiredTopics ?? {})) {
@@ -380,7 +473,11 @@ export function parseTopicRegistryState(value: unknown): TopicRegistryState | un
 			!validTimestamp(claim.createdAt) ||
 			!validOptionalString(claim.hostId) ||
 			!validOptionalString(claim.leaseOwner) ||
-			(claim.binding !== undefined && !validBinding(claim.binding))
+			(claim.binding !== undefined && !validBinding(claim.binding)) ||
+			(claim.telegramBinding !== undefined &&
+				(!isObject(claim.telegramBinding) ||
+					!isValidBindingString(claim.telegramBinding.chatId) ||
+					claim.telegramBinding.transport !== "telegram"))
 		)
 			malformed();
 	}
@@ -400,7 +497,7 @@ export function parseTopicRegistryState(value: unknown): TopicRegistryState | un
 			malformed();
 	}
 	for (const [sessionId, binding] of Object.entries(state.closedEndpoints ?? {}))
-		if (!isValidBindingString(sessionId) || !validBinding(binding)) malformed();
+		if (!isValidBindingString(sessionId) || !validTelegramBinding(binding)) malformed();
 	return state;
 }
 
@@ -457,7 +554,7 @@ export class TopicRegistry {
 			if (Array.isArray(records))
 				this.retiredTopics.set(
 					sessionId,
-					records.map(record => ({ ...record })),
+					records.map(record => this.#normalizeLoadedRecord(record)),
 				);
 		for (const [sessionId, job] of Object.entries(state.archiveJobs ?? {})) {
 			const attempt =
@@ -513,6 +610,9 @@ export class TopicRegistry {
 					...(isValidBindingString(claim.hostId) ? { hostId: claim.hostId } : {}),
 					...(isValidBindingString(claim.leaseOwner) ? { leaseOwner: claim.leaseOwner } : {}),
 					...(claim.binding ? { binding: claim.binding } : {}),
+					...(isObjectLike(claim.telegramBinding) && isValidBindingString(claim.telegramBinding.chatId)
+						? { telegramBinding: { chatId: claim.telegramBinding.chatId, transport: "telegram" } }
+						: {}),
 				});
 		}
 
@@ -554,6 +654,9 @@ export class TopicRegistry {
 					typeof raw.sessionUuid === "string" && raw.sessionUuid.length > 0 ? raw.sessionUuid : randomUUID(),
 				identitySent: raw.identitySent === true,
 				createdAt: typeof raw.createdAt === "number" ? raw.createdAt : 0,
+				...(isObjectLike(raw.telegramBinding) && isValidBindingString(raw.telegramBinding.chatId)
+					? { telegramBinding: { chatId: raw.telegramBinding.chatId, transport: "telegram" as const } }
+					: {}),
 				...(typeof raw.name === "string" ? { name: raw.name } : {}),
 				...(typeof raw.orphanedAt === "number" && Number.isFinite(raw.orphanedAt) && raw.orphanedAt >= 0
 					? { orphanedAt: raw.orphanedAt }
@@ -564,6 +667,11 @@ export class TopicRegistry {
 					? { userNameUpdateId: raw.userNameUpdateId }
 					: {}),
 				...(typeof raw.identityKey === "string" ? { identityKey: raw.identityKey } : {}),
+				...(raw.archiveReason === "session_closed" ||
+				raw.archiveReason === "notification_subscription_removed" ||
+				raw.archiveReason === "create_compensation"
+					? { archiveReason: raw.archiveReason }
+					: {}),
 				...(typeof raw.creationLeaseEpoch === "number" &&
 				Number.isSafeInteger(raw.creationLeaseEpoch) &&
 				raw.creationLeaseEpoch >= 0
@@ -592,12 +700,6 @@ export class TopicRegistry {
 						}
 					: { authorityState: "active" 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 }
-					: {}),
 				...(isValidBindingString(raw.leaseOwner) ? { leaseOwner: raw.leaseOwner } : {}),
 				...(typeof raw.leaseHeartbeatAt === "number" && Number.isFinite(raw.leaseHeartbeatAt)
 					? { leaseHeartbeatAt: raw.leaseHeartbeatAt }
@@ -615,16 +717,37 @@ export class TopicRegistry {
 					: {}),
 				...(bindingMalformed ? { bindingMalformed: true as const } : {}),
 			};
-			this.epochs.set(sessionId, Math.max(fenceEpoch, record.authorityEpoch ?? 0));
+			const normalizedRecord = this.#normalizeLoadedRecord(record);
+			this.epochs.set(sessionId, Math.max(fenceEpoch, normalizedRecord.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);
+			this.topics.set(sessionId, normalizedRecord);
 		}
 		this.rebuildInboundRoutes();
 	}
 
+	/** Keep durable topic authority at stable logical session + Telegram binding. */
+	#normalizeLoadedRecord(raw: TopicRecord): TopicRecord {
+		const normalized = { ...raw };
+		const chatId =
+			isObjectLike(raw.telegramBinding) && isValidBindingString(raw.telegramBinding.chatId)
+				? raw.telegramBinding.chatId
+				: isValidBindingString(raw.chatId)
+					? raw.chatId
+					: undefined;
+		if (chatId !== undefined) {
+			normalized.chatId = chatId;
+			normalized.telegramBinding = { chatId, transport: "telegram" };
+		}
+		delete normalized.endpointKey;
+		delete normalized.endpointDigest;
+		delete normalized.endpointGeneration;
+		delete normalized.endpointIncarnation;
+		return normalized;
+	}
+
 	private rebuildInboundRoutes(): void {
 		this.byTopic.clear();
 		this.#ambiguousTopicIds.clear();
@@ -680,12 +803,7 @@ export class TopicRegistry {
 		if (topic.authorityEpoch !== claim.authorityEpoch) return false;
 		if (
 			claim.binding &&
-			(!hasCompleteBinding(topic) ||
-				!hasValidBinding(claim.binding) ||
-				topic.chatId !== claim.binding.chatId ||
-				topic.endpointKey !== claim.binding.endpointKey ||
-				topic.endpointDigest !== claim.binding.endpointDigest ||
-				topic.endpointGeneration !== claim.binding.endpointGeneration)
+			(!hasCompleteBinding(topic) || !hasValidBinding(claim.binding) || topic.chatId !== claim.binding.chatId)
 		)
 			return false;
 		this.topics.set(sessionId, { ...topic });
@@ -735,31 +853,29 @@ export class TopicRegistry {
 	 */
 	endpointAuthority(binding: TopicEndpointBinding, excludedTransientClaimant?: object): TopicEndpointAuthority {
 		if (!hasValidBinding(binding)) return { state: "ambiguous" };
-		const canClaim = (record: Pick<TopicRecord, "chatId" | "endpointKey" | "endpointDigest">): boolean =>
+		const canClaim = (sessionId: string, record: Pick<TopicRecord, "chatId">): 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));
+			(binding.logicalSessionId === undefined || sessionId === binding.logicalSessionId);
+		const committed = [...this.topics].filter(([sessionId, record]) => canClaim(sessionId, 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 staged = [...this.staged].filter(
+			([sessionId, record]) => canClaim(sessionId, record) && !excludesClaimant(sessionId),
+		);
 		const creating = [...this.creatingBindings].filter(
-			([sessionId, claim]) => canClaim(claim) && !excludesClaimant(sessionId),
+			([sessionId, claim]) => canClaim(sessionId, claim) && !excludesClaimant(sessionId),
 		);
 		const durableClaims = [...this.createClaims].filter(
-			([sessionId, claim]) => claim.binding !== undefined && canClaim(claim.binding) && !excludesClaimant(sessionId),
+			([sessionId, claim]) =>
+				claim.binding !== undefined && canClaim(sessionId, claim.binding) && !excludesClaimant(sessionId),
 		);
 		if (committed.length === 0 && staged.length === 0 && creating.length === 0 && durableClaims.length === 0)
 			return { state: "none" };
 		if (committed.length !== 1 || staged.length !== 0 || creating.length !== 0 || durableClaims.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
+		return record.chatId === binding.chatId && this.isActiveUnambiguous(sessionId) && !record.bindingMalformed
 			? { state: "unique", sessionId }
 			: { state: "ambiguous" };
 	}
@@ -773,13 +889,7 @@ export class TopicRegistry {
 	/** 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
-		);
+		return this.isActiveUnambiguous(sessionId) && !record?.bindingMalformed && record?.chatId === binding.chatId;
 	}
 
 	/**
@@ -794,7 +904,7 @@ export class TopicRegistry {
 			record.bindingMalformed ||
 			!hasCompleteBinding(record) ||
 			!hasValidBinding(binding) ||
-			(record.endpointKey === binding.endpointKey && record.endpointDigest === binding.endpointDigest)
+			false
 		)
 			return false;
 		const history = this.retiredTopics.get(sessionId) ?? [];
@@ -816,8 +926,8 @@ export class TopicRegistry {
 	bindEndpoint(
 		sessionId: string,
 		binding: TopicEndpointBinding,
-		activeEndpointKeys: ReadonlySet<string> = new Set(),
-		allowEndpointRotation = false,
+		_activeEndpointKeys: ReadonlySet<string> = new Set(),
+		_allowEndpointRotation = false,
 	): "bound" | "unchanged" | "rejected" {
 		const record = this.topics.get(sessionId);
 		if (
@@ -833,33 +943,10 @@ export class TopicRegistry {
 		// 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;
+		const changed = false;
 		if (!changed && record.authorityState === "active") 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;
+		record.telegramBinding = { chatId: binding.chatId, transport: "telegram" };
 		if (record.authorityState === "disconnect_grace") {
 			record.authorityState = "active";
 			delete record.orphanedAt;
@@ -873,27 +960,13 @@ export class TopicRegistry {
 	restoreEndpointBinding(
 		sessionId: string,
 		expected: TopicEndpointBinding,
-		previous: Pick<
-			TopicRecord,
-			"chatId" | "endpointKey" | "endpointDigest" | "endpointGeneration" | "endpointIncarnation"
-		>,
+		previous: Pick<TopicRecord, "chatId">,
 	): 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;
+		if (!record || record.chatId !== expected.chatId) 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;
+		if (previous.chatId === undefined) delete record.telegramBinding;
+		else record.telegramBinding = { chatId: previous.chatId, transport: "telegram" };
 		return true;
 	}
 
@@ -950,15 +1023,11 @@ export class TopicRegistry {
 				authorityEpoch: revoked ? (this.epochs.get(sessionId) ?? 0) : epoch,
 				creationLeaseEpoch: epoch,
 				authorityState: revoked ? "archive_pending" : "active",
+				...(revoked ? { archiveReason: "create_compensation" as const } : {}),
 				...(binding
 					? {
 							chatId: binding.chatId,
-							endpointKey: binding.endpointKey,
-							endpointDigest: binding.endpointDigest,
-							endpointIncarnation: 0,
-							...(binding.endpointGeneration === undefined
-								? {}
-								: { endpointGeneration: binding.endpointGeneration }),
+							telegramBinding: { chatId: binding.chatId, transport: "telegram" },
 						}
 					: {}),
 			};
@@ -978,6 +1047,7 @@ export class TopicRegistry {
 			if ((this.epochs.get(sessionId) ?? 0) !== epoch) {
 				record.authorityEpoch = this.epochs.get(sessionId) ?? 0;
 				record.authorityState = "archive_pending";
+				record.archiveReason = "create_compensation";
 				this.topics.set(sessionId, record);
 				throw new Error("topic authority was revoked during creation");
 			}
@@ -1236,6 +1306,7 @@ export class TopicRegistry {
 				...snapshot.record,
 				authorityEpoch: deleteEpoch,
 				authorityState: "archive_pending",
+				archiveReason: snapshot.record.archiveReason ?? "create_compensation",
 			});
 			const restored = this.topics.get(snapshot.sessionId);
 			if (restored) delete restored.disconnectGraceExpiresAt;
@@ -1244,6 +1315,7 @@ export class TopicRegistry {
 		} else {
 			record.authorityEpoch = deleteEpoch;
 			record.authorityState = "archive_pending";
+			record.archiveReason = snapshot.record?.archiveReason ?? record.archiveReason ?? "create_compensation";
 			delete record.disconnectGraceExpiresAt;
 			if (this.byTopic.get(record.topicId) === snapshot.sessionId) this.byTopic.delete(record.topicId);
 		}
@@ -1252,7 +1324,13 @@ export class TopicRegistry {
 	}
 
 	/** Fence new work before the remote archive starts, including an absent in-flight create. */
-	beginArchive(sessionId: string, hostId?: string, now = Date.now()): TopicRecord | undefined {
+	beginArchive(
+		sessionId: string,
+		hostId: string | undefined,
+		now: number,
+		reason: TopicArchiveReason,
+	): TopicRecord | undefined {
+		if (!isTopicArchiveReason(reason)) return undefined;
 		const record = this.topics.get(sessionId);
 		if (
 			record?.topicOrigin === "user_created" ||
@@ -1278,6 +1356,7 @@ export class TopicRegistry {
 		if (!record) return undefined;
 		record.authorityEpoch = epoch;
 		record.authorityState = "archive_pending";
+		record.archiveReason = reason;
 		delete record.disconnectGraceExpiresAt;
 		if (hostId) record.archiveHostId = hostId;
 		record.archiveLeaseEpoch = epoch;
@@ -1318,7 +1397,9 @@ export class TopicRegistry {
 		binding?: TopicEndpointBinding,
 		topicOrigin?: TopicRecord["topicOrigin"],
 		archiveChatId?: string,
+		reason: TopicArchiveReason = "create_compensation",
 	): TopicRecord {
+		if (!isTopicArchiveReason(reason)) throw new Error("archive reason is required");
 		const epoch = Math.max(this.epochs.get(sessionId) ?? 0, this.topics.get(sessionId)?.authorityEpoch ?? 0);
 		const record: TopicRecord = {
 			topicId,
@@ -1329,15 +1410,11 @@ export class TopicRegistry {
 			createdAt: now(),
 			authorityEpoch: epoch,
 			authorityState: "archive_pending",
+			archiveReason: reason,
 			...(binding
 				? {
 						chatId: binding.chatId,
-						endpointKey: binding.endpointKey,
-						endpointDigest: binding.endpointDigest,
-						endpointIncarnation: 0,
-						...(binding.endpointGeneration === undefined
-							? {}
-							: { endpointGeneration: binding.endpointGeneration }),
+						telegramBinding: { chatId: binding.chatId, transport: "telegram" },
 					}
 				: archiveChatId
 					? { chatId: archiveChatId }
@@ -1360,22 +1437,28 @@ export class TopicRegistry {
 		binding?: TopicEndpointBinding,
 		topicOrigin?: TopicRecord["topicOrigin"],
 		archiveChatId?: string,
+		reason: TopicArchiveReason = "create_compensation",
 	): 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;
+		const matchesBinding = record?.chatId === binding?.chatId;
 		if (
 			record
 				? record.topicId !== topicId || record.creationLeaseEpoch !== creationLeaseEpoch || !matchesBinding
 				: (this.epochs.get(sessionId) ?? 0) !== creationLeaseEpoch
 		)
 			return undefined;
-		const archiveFence = this.beginArchive(sessionId, hostId, now());
+		const archiveFence = this.beginArchive(sessionId, hostId, now(), reason);
 		if (record && !archiveFence) return undefined;
-		const fenced = this.fenceAcceptedCreate(sessionId, topicId, now, name, binding, topicOrigin, archiveChatId);
+		const fenced = this.fenceAcceptedCreate(
+			sessionId,
+			topicId,
+			now,
+			name,
+			binding,
+			topicOrigin,
+			archiveChatId,
+			reason,
+		);
 		fenced.creationLeaseEpoch = creationLeaseEpoch;
 		fenced.archiveHostId = hostId;
 		fenced.archiveLeaseEpoch = fenced.authorityEpoch;
@@ -1391,7 +1474,12 @@ export class TopicRegistry {
 	 * Retain a topic record after a definite remote archive only while the exact
 	 * dispatched authority epoch is still current.
 	 */
-	settleArchive(sessionId: string, topicId: string, dispatchedAuthorityEpoch: number): boolean {
+	settleArchive(
+		sessionId: string,
+		topicId: string,
+		dispatchedAuthorityEpoch: number,
+		reason: TopicArchiveReason,
+	): boolean {
 		if (
 			!Number.isSafeInteger(dispatchedAuthorityEpoch) ||
 			dispatchedAuthorityEpoch < 0 ||
@@ -1401,6 +1489,8 @@ export class TopicRegistry {
 		const record = this.topics.get(sessionId);
 		if (
 			!record ||
+			!isTopicArchiveReason(reason) ||
+			record.archiveReason !== reason ||
 			record.topicId !== topicId ||
 			record.authorityState !== "archive_pending" ||
 			record.authorityEpoch !== dispatchedAuthorityEpoch ||
@@ -1417,7 +1507,7 @@ export class TopicRegistry {
 	/** Durable archive jobs that are eligible for a retry at `now`. */
 	archivePendingSessionIds(now = Date.now()): string[] {
 		return [...this.topics].flatMap(([sessionId, record]) => {
-			if (record.authorityState === "archive_exhausted") {
+			if (record.authorityState === "archive_exhausted" && record.topicOrigin === "daemon_created") {
 				const currentEpoch = Math.max(this.epochs.get(sessionId) ?? 0, record.authorityEpoch ?? 0);
 				if (currentEpoch < Number.MAX_SAFE_INTEGER) {
 					const epoch = Math.min(currentEpoch + 1, Number.MAX_SAFE_INTEGER - 1);
@@ -1427,7 +1517,8 @@ export class TopicRegistry {
 					delete record.disconnectGraceExpiresAt;
 				}
 			}
-			return (record.authorityState === "archive_pending" || record.authorityState === "archive_exhausted") &&
+			return isTopicArchiveReason(record.archiveReason) &&
+				(record.authorityState === "archive_pending" || record.authorityState === "archive_exhausted") &&
 				(this.archiveJobs.get(sessionId)?.nextAttemptAt ?? 0) <= now
 				? [sessionId]
 				: [];
@@ -1441,16 +1532,29 @@ export class TopicRegistry {
 	}
 
 	/** Persist an indefinitely discoverable retry after an ambiguous archive result. */
-	scheduleArchiveRetry(sessionId: string, now: number, diagnostic?: string): ArchiveJob | undefined {
+	scheduleArchiveRetry(
+		sessionId: string,
+		now: number,
+		reason: TopicArchiveReason,
+		diagnostic?: string,
+	): ArchiveJob | undefined {
 		const record = this.topics.get(sessionId);
-		if (record?.authorityState !== "archive_pending" && record?.authorityState !== "archive_exhausted")
+		if (
+			!record ||
+			!isTopicArchiveReason(reason) ||
+			record.archiveReason !== reason ||
+			(record.authorityState !== "archive_pending" && record.authorityState !== "archive_exhausted")
+		)
 			return undefined;
 		const previous = this.archiveJobs.get(sessionId);
 		const firstAttemptAt = previous?.firstAttemptAt ?? now;
 		const attempt = (previous?.attempt ?? 0) + 1;
 		const exhausted = attempt > 8 || now - firstAttemptAt > 24 * 60 * 60 * 1000;
 		const effectiveAttempt = Math.min(attempt, 8);
-		const backoffMs = exhausted ? 1_000 : Math.min(60_000, 250 * 2 ** effectiveAttempt);
+		// Post-budget retries stay discoverable but are paced: a permanently
+		// ambiguous archive drained by a periodic sweep must not redispatch (and
+		// bump the authority epoch) every sweep tick forever.
+		const backoffMs = exhausted ? 15 * 60_000 : Math.min(60_000, 250 * 2 ** effectiveAttempt);
 		const job = {
 			sessionId,
 			topicId: record.topicId,
@@ -1469,14 +1573,43 @@ export class TopicRegistry {
 
 	/** Serialise active records plus unpublished staged creates for atomic commit. */
 	serialize(): TopicRegistryState {
+		const stripSdkAuthority = (record: TopicRecord): TopicRecord => {
+			const next = { ...record };
+			if (next.chatId) next.telegramBinding = { chatId: next.chatId, transport: "telegram" };
+			if (!next.chatId && next.telegramBinding) next.chatId = next.telegramBinding.chatId;
+			delete next.endpointKey;
+			delete next.endpointDigest;
+			delete next.endpointGeneration;
+			delete next.endpointIncarnation;
+			return next;
+		};
+		const topics = Object.fromEntries(
+			[...this.topics, ...this.staged].map(([id, record]) => [id, stripSdkAuthority(record)]),
+		);
+		const claims = Object.fromEntries(
+			[...this.createClaims].map(([id, claim]) => [
+				id,
+				{
+					...claim,
+					...(claim.binding
+						? { telegramBinding: { chatId: claim.binding.chatId, transport: "telegram" as const } }
+						: {}),
+					binding: undefined,
+				},
+			]),
+		);
+		const closedEndpoints: Record<string, TelegramTopicBinding> = {};
 		return {
 			version: 2,
 			registryGeneration: this.registryGeneration,
-			topics: Object.fromEntries([...this.topics, ...this.staged]),
+			topics,
 			fences: Object.fromEntries(this.epochs),
+			closedEndpoints,
 			archiveJobs: Object.fromEntries(this.archiveJobs),
-			createClaims: Object.fromEntries(this.createClaims),
-			retiredTopics: Object.fromEntries(this.retiredTopics),
+			createClaims: claims,
+			retiredTopics: Object.fromEntries(
+				[...this.retiredTopics].map(([id, records]) => [id, records.map(stripSdkAuthority)]),
+			),
 		};
 	}
 }