@gajae-code/coding-agent 0.13.3 → 0.14.0

package/src/sdk/bus/telegram-adoption-intent.ts

@@ -1,49 +1,27 @@
 /**
- * Durable, non-routable sidecar store for "adopt a user-created Telegram forum
- * topic into a preallocated session" intents.
+ * Durable provider-local reservations for Telegram topic adoption.
  *
- * When a user creates a new forum topic, the daemon first records durable
- * pending-topic authorization. After folder selection it preallocates an
- * `intendedSessionId` and records an adoption intent here *before* spawning.
- * Later, the authenticated `ensureTopic` create callback reads that intent and
- * returns the user's existing topicId to `TopicRegistry.getOrCreateTopic`, which
- * is the only authority that commits a topic binding. This keeps the intent out
- * of routing/endpoint authority until commit, so a failed spawn or a late socket
- * never deletes the user's topic and never strands a duplicate.
- *
- * Invariants (see `pending-approval.md`):
- * - One file per intent, named `<intendedSessionId>.adoption-intent.json` under
- *   the daemon notifications dir. Sweep touches files only; never the Telegram API.
- * - Only `{ intendedSessionId, topicId, chatId, target, createdAt, expiresAt }`
- *   is persisted. Bot/control tokens and endpoint digests are never stored.
- * - Owner-only dir (0o700) and 0o600 files; atomic temp→fsync→chmod→rename→parent sync.
- * - `tryClaim` is a synchronous, in-memory claim keyed by topicId; it excludes a
- *   second `intendedSessionId` from winning the same topic across awaits. It
- *   does not delete the sidecar; `releaseClaim` re-enables retry on commit failure.
+ * A reservation is keyed by the stable provider request identity, never by a
+ * preallocated Broker SessionId.  Broker allocates the SessionId; the daemon
+ * CAS-binds that opaque value only after the lifecycle service returns it.
+ * This store owns only presentation mappings and pending-topic authorization.
  */
 
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { logger } from "@gajae-code/utils";
 import { daemonPaths } from "./daemon-paths";
 import type { SessionCreateTarget } from "./index";
 
-/** Persisted document version. */
-export const TELEGRAM_ADOPTION_INTENT_VERSION = 1;
+export const TELEGRAM_ADOPTION_INTENT_VERSION = 2;
+const LEGACY_TELEGRAM_ADOPTION_INTENT_VERSION = 1 as const;
 export type TelegramAdoptionTarget = Extract<SessionCreateTarget, { kind: "existing_path" }>;
-/** Default intent TTL (configurable at write time). Plan starts at 10 minutes. */
 export const DEFAULT_ADOPTION_INTENT_TTL_MS = 10 * 60 * 1000;
-/** Per-intent filename prefix/suffix under the notifications dir. */
 const INTENT_FILE_SUFFIX = ".adoption-intent.json";
 const PENDING_TOPIC_FILE_SUFFIX = ".pending-topic.json";
+const MIGRATION_DIAGNOSTIC_MAX_LENGTH = 256;
 
-/**
- * Minimal async filesystem surface the store needs. Structurally a subset of the
- * daemon's `TelegramDaemonFs` / `ConversationStoreFs`, so the daemon can pass its
- * own `fs` straight through and tests can inject a fake. `open`/`sync`/`close`
- * mirror `ConversationStoreFileHandle` so the atomic fsync path reuses the same
- * shape as the conversation store.
- */
 export interface AdoptionIntentFs {
 	mkdir(directory: string, options: { recursive: true; mode: number }): Promise<unknown>;
 	chmod(target: string, mode: number): Promise<void>;
@@ -71,14 +49,15 @@ const nodeFs: AdoptionIntentFs = {
 	open: async (file, flags) => fs.promises.open(file, flags),
 };
 
-/** What gets persisted per intent. No tokens, no digests. */
+/** Persisted before create; `sessionId` is added only by bindSession. */
 export interface TelegramAdoptionIntent {
-	intendedSessionId: string;
-	topicId: number;
-	chatId: string;
-	target: TelegramAdoptionTarget;
-	createdAt: number;
-	expiresAt: number;
+	readonly providerRequestKey: string;
+	readonly topicId: number;
+	readonly chatId: string;
+	readonly target: TelegramAdoptionTarget;
+	readonly createdAt: number;
+	readonly expiresAt: number;
+	readonly sessionId?: string;
 }
 
 interface PersistedIntent {
@@ -86,12 +65,27 @@ interface PersistedIntent {
 	intent: TelegramAdoptionIntent;
 }
 
-/** Durable authorization that a topic was observed through forum_topic_created. */
+interface LegacyTelegramAdoptionIntent {
+	readonly intendedSessionId: string;
+	readonly topicId: number;
+	readonly chatId: string;
+	readonly target: TelegramAdoptionTarget;
+	readonly createdAt: number;
+	readonly expiresAt: number;
+}
+
+interface LegacyPersistedIntent {
+	version: typeof LEGACY_TELEGRAM_ADOPTION_INTENT_VERSION;
+	intent: LegacyTelegramAdoptionIntent;
+}
+
+type PersistedIntentRecord = PersistedIntent | LegacyPersistedIntent;
+
 export interface TelegramPendingTopic {
-	topicId: number;
-	chatId: string;
-	createdAt: number;
-	expiresAt: number;
+	readonly topicId: number;
+	readonly chatId: string;
+	readonly createdAt: number;
+	readonly expiresAt: number;
 }
 
 interface PersistedPendingTopic {
@@ -99,6 +93,13 @@ interface PersistedPendingTopic {
 	pendingTopic: TelegramPendingTopic;
 }
 
+interface LegacyPersistedPendingTopic {
+	version: typeof LEGACY_TELEGRAM_ADOPTION_INTENT_VERSION;
+	pendingTopic: TelegramPendingTopic;
+}
+
+type PersistedPendingTopicRecord = PersistedPendingTopic | LegacyPersistedPendingTopic;
+
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -107,11 +108,28 @@ function isSessionCreateTarget(value: unknown): value is TelegramAdoptionTarget
 	return isRecord(value) && value.kind === "existing_path" && typeof value.path === "string";
 }
 
-function isPersistedIntent(value: unknown): value is PersistedIntent {
-	if (!isRecord(value)) return false;
-	if (value.version !== TELEGRAM_ADOPTION_INTENT_VERSION) return false;
+function isPersistedIntent(value: unknown): value is PersistedIntentRecord {
+	if (!isRecord(value) || !isRecord(value.intent)) return false;
+	if (value.version === TELEGRAM_ADOPTION_INTENT_VERSION) {
+		const intent = value.intent;
+		return (
+			typeof intent.providerRequestKey === "string" &&
+			intent.providerRequestKey.length > 0 &&
+			typeof intent.topicId === "number" &&
+			Number.isSafeInteger(intent.topicId) &&
+			intent.topicId > 0 &&
+			typeof intent.chatId === "string" &&
+			typeof intent.createdAt === "number" &&
+			Number.isFinite(intent.createdAt) &&
+			typeof intent.expiresAt === "number" &&
+			Number.isFinite(intent.expiresAt) &&
+			intent.expiresAt > intent.createdAt &&
+			(intent.sessionId === undefined || (typeof intent.sessionId === "string" && intent.sessionId.length > 0)) &&
+			isSessionCreateTarget(intent.target)
+		);
+	}
+	if (value.version !== LEGACY_TELEGRAM_ADOPTION_INTENT_VERSION) return false;
 	const intent = value.intent;
-	if (!isRecord(intent)) return false;
 	return (
 		typeof intent.intendedSessionId === "string" &&
 		intent.intendedSessionId.length > 0 &&
@@ -128,11 +146,28 @@ function isPersistedIntent(value: unknown): value is PersistedIntent {
 	);
 }
 
-function isPersistedPendingTopic(value: unknown): value is PersistedPendingTopic {
-	if (!isRecord(value) || value.version !== TELEGRAM_ADOPTION_INTENT_VERSION) return false;
+function normalizePersistedIntent(value: unknown): { intent: TelegramAdoptionIntent; legacy: boolean } | undefined {
+	if (!isPersistedIntent(value)) return undefined;
+	if (value.version === TELEGRAM_ADOPTION_INTENT_VERSION) return { intent: value.intent, legacy: false };
+	return {
+		legacy: true,
+		intent: {
+			providerRequestKey: `legacy:v1:${value.intent.intendedSessionId}`,
+			topicId: value.intent.topicId,
+			chatId: value.intent.chatId,
+			target: value.intent.target,
+			createdAt: value.intent.createdAt,
+			expiresAt: value.intent.expiresAt,
+		},
+	};
+}
+
+function isPersistedPendingTopic(value: unknown): value is PersistedPendingTopicRecord {
+	if (!isRecord(value) || !isRecord(value.pendingTopic)) return false;
+	if (value.version !== TELEGRAM_ADOPTION_INTENT_VERSION && value.version !== LEGACY_TELEGRAM_ADOPTION_INTENT_VERSION)
+		return false;
 	const pending = value.pendingTopic;
 	return (
-		isRecord(pending) &&
 		typeof pending.topicId === "number" &&
 		Number.isSafeInteger(pending.topicId) &&
 		pending.topicId > 0 &&
@@ -145,19 +180,29 @@ function isPersistedPendingTopic(value: unknown): value is PersistedPendingTopic
 	);
 }
 
-/** Compose the per-intent sidecar path. Public so callers/tests can inspect it. */
-export function adoptionIntentFilePath(agentDir: string, intendedSessionId: string): string {
-	return path.join(daemonPaths(agentDir).dir, `${intendedSessionId}${INTENT_FILE_SUFFIX}`);
+/** Sidecar names are opaque, deterministic encodings of provider request keys. */
+function encodeProviderRequestKey(providerRequestKey: string): string {
+	return Buffer.from(providerRequestKey, "utf8").toString("base64url");
+}
+
+function decodeProviderRequestKey(value: string): string | undefined {
+	try {
+		return Buffer.from(value, "base64url").toString("utf8");
+	} catch {
+		return undefined;
+	}
+}
+
+export function adoptionIntentFilePath(agentDir: string, providerRequestKey: string): string {
+	return path.join(daemonPaths(agentDir).dir, `${encodeProviderRequestKey(providerRequestKey)}${INTENT_FILE_SUFFIX}`);
 }
 
-/** Compose the sidecar path for a user-created topic awaiting a folder choice. */
 export function pendingTopicFilePath(agentDir: string, topicId: number): string {
 	return path.join(daemonPaths(agentDir).dir, `${topicId}${PENDING_TOPIC_FILE_SUFFIX}`);
 }
 
-/** Build a fresh intent with `createdAt`/`expiresAt` derived from `now`/`ttlMs`. */
 export function buildAdoptionIntent(input: {
-	intendedSessionId: string;
+	providerRequestKey: string;
 	topicId: number;
 	chatId: string;
 	target: TelegramAdoptionTarget;
@@ -165,45 +210,31 @@ export function buildAdoptionIntent(input: {
 	ttlMs?: number;
 }): TelegramAdoptionIntent {
 	const createdAt = input.now ?? Date.now();
-	const ttl = input.ttlMs ?? DEFAULT_ADOPTION_INTENT_TTL_MS;
 	return {
-		intendedSessionId: input.intendedSessionId,
+		providerRequestKey: input.providerRequestKey,
 		topicId: input.topicId,
 		chatId: input.chatId,
 		target: input.target,
 		createdAt,
-		expiresAt: createdAt + ttl,
+		expiresAt: createdAt + (input.ttlMs ?? DEFAULT_ADOPTION_INTENT_TTL_MS),
 	};
 }
 
-/** Test-only: filename suffix used to recognize intent sidecars in a directory listing. */
 export const ADOPTION_INTENT_FILENAME_SUFFIX = INTENT_FILE_SUFFIX;
 export const PENDING_TOPIC_FILENAME_SUFFIX = PENDING_TOPIC_FILE_SUFFIX;
 
-/**
- * Durable, non-routable adoption-intent store. Owns durable sidecar files and
- * the synchronous in-memory topicId claim table. The daemon owns Telegram and
- * lifecycle wiring; this store never calls the Telegram API.
- */
 export class TelegramAdoptionIntentStore {
 	readonly #agentDir: string;
 	readonly #dir: string;
 	readonly #fsImpl: AdoptionIntentFs;
 	readonly #now: () => number;
 	readonly #platform: NodeJS.Platform;
-	/** intendedSessionId -> intent, rehydrated from disk. */
 	readonly #intents = new Map<string, TelegramAdoptionIntent>();
-	/** topicId -> intendedSessionId currently holding the synchronous claim. */
 	readonly #claims = new Map<number, string>();
-	/** topicId -> durable authorization observed from forum_topic_created. */
 	readonly #pendingTopics = new Map<number, TelegramPendingTopic>();
+	readonly #bindingKeys = new Set<string>();
 
-	constructor(input: {
-		agentDir: string;
-		fs?: AdoptionIntentFs;
-		now?: () => number;
-		platform?: NodeJS.Platform;
-	}) {
+	constructor(input: { agentDir: string; fs?: AdoptionIntentFs; now?: () => number; platform?: NodeJS.Platform }) {
 		this.#agentDir = input.agentDir;
 		this.#dir = daemonPaths(input.agentDir).dir;
 		this.#fsImpl = input.fs ?? nodeFs;
@@ -211,113 +242,117 @@ export class TelegramAdoptionIntentStore {
 		this.#platform = input.platform ?? process.platform;
 	}
 
-	/** Directory holding the sidecar files. */
 	get directory(): string {
 		return this.#dir;
 	}
 
-	/** In-memory lookup by intendedSessionId (no disk read). undefined if absent/expired. */
-	bySession(intendedSessionId: string): TelegramAdoptionIntent | undefined {
-		const intent = this.#intents.get(intendedSessionId);
-		if (intent === undefined) return undefined;
-		return this.#now() < intent.expiresAt ? intent : undefined;
+	byProviderRequestKey(providerRequestKey: string): TelegramAdoptionIntent | undefined {
+		const intent = this.#intents.get(providerRequestKey);
+		return intent && this.#now() < intent.expiresAt ? intent : undefined;
+	}
+
+	/** Only a post-create CAS binding makes a reservation visible by SessionId. */
+	bySession(sessionId: string): TelegramAdoptionIntent | undefined {
+		for (const intent of this.#intents.values()) {
+			if (intent.sessionId === sessionId && this.#now() < intent.expiresAt) return intent;
+		}
+		return undefined;
 	}
 
-	/** In-memory lookup of the (single) non-expired intent for a topicId. */
 	byTopic(topicId: number): TelegramAdoptionIntent | undefined {
 		for (const intent of this.#intents.values()) {
-			if (intent.topicId !== topicId) continue;
-			if (this.#now() >= intent.expiresAt) continue;
-			return intent;
+			if (intent.topicId === topicId && this.#now() < intent.expiresAt) return intent;
 		}
 		return undefined;
 	}
 
-	/** `true` if a non-expired intent already references `topicId`. */
 	hasNonExpiredTopic(topicId: number): boolean {
 		return this.byTopic(topicId) !== undefined;
 	}
 
-	/** Durable authorization for an observed user-created topic, if still live. */
 	pendingTopic(topicId: number): TelegramPendingTopic | undefined {
 		const pending = this.#pendingTopics.get(topicId);
-		return pending !== undefined && this.#now() < pending.expiresAt ? pending : undefined;
+		return pending && this.#now() < pending.expiresAt ? pending : undefined;
 	}
 
 	hasPendingTopic(topicId: number, chatId: string): boolean {
 		return this.pendingTopic(topicId)?.chatId === chatId;
 	}
 
-	/**
-	 * Synchronously claim `topicId` for `intendedSessionId`. Returns false if a
-	 * *different* non-expired intendedSessionId already holds the claim (or has a
-	 * non-expired intent for the topic). Same intendedSessionId re-claiming its
-	 * own topic is idempotent and succeeds. The claim is in-memory only; it never
-	 * deletes the sidecar, so a commit failure can `releaseClaim` and retry.
-	 */
-	tryClaim(topicId: number, intendedSessionId: string): boolean {
+	/** Synchronous fail-closed topic claim keyed by provider request identity. */
+	tryClaim(topicId: number, providerRequestKey: string): boolean {
 		const holder = this.#claims.get(topicId);
-		if (holder !== undefined) return holder === intendedSessionId;
-		// No live claim yet: refuse if a *different* non-expired intent already
-		// targets this topic (race between two pre-spawn intents on one topic).
+		if (holder !== undefined) return holder === providerRequestKey;
 		const existing = this.byTopic(topicId);
-		if (existing !== undefined && existing.intendedSessionId !== intendedSessionId) return false;
-		this.#claims.set(topicId, intendedSessionId);
+		if (existing !== undefined && existing.providerRequestKey !== providerRequestKey) return false;
+		this.#claims.set(topicId, providerRequestKey);
 		return true;
 	}
 
-	/** Release a claim held by `intendedSessionId` on `topicId`. No-op otherwise. */
-	releaseClaim(topicId: number, intendedSessionId: string): void {
-		if (this.#claims.get(topicId) === intendedSessionId) this.#claims.delete(topicId);
+	releaseClaim(topicId: number, providerRequestKey: string): void {
+		if (this.#claims.get(topicId) === providerRequestKey) this.#claims.delete(topicId);
 	}
 
-	/**
-	 * Durable write of one intent: temp→write→fsync→chmod(0600)→atomic rename→
-	 * chmod(final, 0600)→parent-dir fsync, then track it in memory. The dir is
-	 * created owner-only (0700). chmod-ing the final path after the rename makes
-	 * the 0600 contract durable regardless of whether the platform's rename
-	 * preserves the source mode (POSIX does; some test/network filesystems and
-	 * the in-memory test double model rename as copy+delete and would otherwise
-	 * drop it). The rename is still the atomic commit point; the final chmod only
-	 * tightens permissions on the already-durable file. The in-memory map is only
-	 * mutated after the atomic persist succeeds. Rejects (does not swallow) so the
-	 * daemon can decide fail-closed behavior.
-	 */
 	async put(intent: TelegramAdoptionIntent): Promise<void> {
+		const current =
+			this.#intents.get(intent.providerRequestKey) ?? (await this.readIntent(intent.providerRequestKey));
+		if (
+			current &&
+			(current.topicId !== intent.topicId ||
+				current.chatId !== intent.chatId ||
+				current.target.path !== intent.target.path)
+		)
+			throw new Error("provider request key is already reserved for a different topic or target");
 		const stored: TelegramAdoptionIntent = {
-			intendedSessionId: intent.intendedSessionId,
+			providerRequestKey: intent.providerRequestKey,
 			topicId: intent.topicId,
 			chatId: intent.chatId,
 			target: { kind: "existing_path", path: intent.target.path },
 			createdAt: intent.createdAt,
 			expiresAt: intent.expiresAt,
+			...((intent.sessionId ?? current?.sessionId) ? { sessionId: intent.sessionId ?? current?.sessionId } : {}),
 		};
-		const file = adoptionIntentFilePath(this.#agentDir, stored.intendedSessionId);
-		const payload: PersistedIntent = { version: TELEGRAM_ADOPTION_INTENT_VERSION, intent: stored };
-		if (!isPersistedIntent(payload)) throw new Error("invalid Telegram adoption intent");
-		await this.#writeSidecar(file, payload);
-		this.#intents.set(stored.intendedSessionId, stored);
+		const file = adoptionIntentFilePath(this.#agentDir, stored.providerRequestKey);
+		await this.#writeSidecar(file, { version: TELEGRAM_ADOPTION_INTENT_VERSION, intent: stored });
+		this.#intents.set(stored.providerRequestKey, stored);
+	}
+
+	/** CAS-bind the Broker-returned opaque SessionId exactly once. */
+	async bindSession(providerRequestKey: string, sessionId: string): Promise<boolean> {
+		if (!sessionId || this.#bindingKeys.has(providerRequestKey)) return false;
+		const current = this.byProviderRequestKey(providerRequestKey);
+		if (!current) return false;
+		if (current.sessionId !== undefined) return current.sessionId === sessionId;
+		this.#bindingKeys.add(providerRequestKey);
+		try {
+			const onDisk = await this.readIntent(providerRequestKey);
+			if (!onDisk || (onDisk.sessionId !== undefined && onDisk.sessionId !== sessionId)) return false;
+			const bound: TelegramAdoptionIntent = { ...current, sessionId };
+			await this.#writeSidecar(adoptionIntentFilePath(this.#agentDir, providerRequestKey), {
+				version: TELEGRAM_ADOPTION_INTENT_VERSION,
+				intent: bound,
+			});
+			this.#intents.set(providerRequestKey, bound);
+			return true;
+		} finally {
+			this.#bindingKeys.delete(providerRequestKey);
+		}
 	}
 
-	/** Persist authorization for a topic observed through forum_topic_created. */
 	async putPendingTopic(pendingTopic: TelegramPendingTopic): Promise<void> {
-		const stored: TelegramPendingTopic = {
-			topicId: pendingTopic.topicId,
-			chatId: pendingTopic.chatId,
-			createdAt: pendingTopic.createdAt,
-			expiresAt: pendingTopic.expiresAt,
-		};
-		const file = pendingTopicFilePath(this.#agentDir, stored.topicId);
-		const payload: PersistedPendingTopic = {
+		const stored = { ...pendingTopic };
+		await this.#writeSidecar(pendingTopicFilePath(this.#agentDir, stored.topicId), {
 			version: TELEGRAM_ADOPTION_INTENT_VERSION,
 			pendingTopic: stored,
-		};
-		if (!isPersistedPendingTopic(payload)) throw new Error("invalid Telegram pending topic");
-		await this.#writeSidecar(file, payload);
+		});
 		this.#pendingTopics.set(stored.topicId, stored);
 	}
 
-	async #writeSidecar(file: string, payload: PersistedIntent | PersistedPendingTopic): Promise<void> {
+	async #writeSidecar(
+		file: string,
+		payload: PersistedIntent | PersistedPendingTopic,
+		retainRenamedFileOnFailure = false,
+	): Promise<void> {
 		await this.#fsImpl.mkdir(this.#dir, { recursive: true, mode: 0o700 });
 		await this.#fsImpl.chmod(this.#dir, 0o700);
 		const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
@@ -336,6 +371,7 @@ export class TelegramAdoptionIntentStore {
 			await this.#fsImpl.chmod(file, 0o600);
 			await this.#syncParentDirectory();
 		} catch (error) {
+			if (renamed && retainRenamedFileOnFailure) throw new SidecarDurabilityUncertainError(error);
 			const cleanupTarget = renamed ? file : temporary;
 			let cleanupError: unknown;
 			try {
@@ -349,45 +385,27 @@ export class TelegramAdoptionIntentStore {
 		}
 	}
 
-	/**
-	 * Read a single intent sidecar from disk and track it if it is non-expired
-	 * and well-formed. Returns the parsed intent (or undefined). Used by
-	 * `rehydrate`; callers normally use `rehydrate` / `bySession`.
-	 */
-	async readIntent(intendedSessionId: string): Promise<TelegramAdoptionIntent | undefined> {
-		const file = adoptionIntentFilePath(this.#agentDir, intendedSessionId);
-		let raw: string;
-		try {
-			raw = await this.#fsImpl.readFile(file, "utf8");
-		} catch (error) {
-			if (isMissing(error)) return undefined;
-			throw error;
-		}
-		let parsed: unknown;
-		try {
-			parsed = JSON.parse(raw);
-		} catch {
+	async readIntent(providerRequestKey: string): Promise<TelegramAdoptionIntent | undefined> {
+		const file = adoptionIntentFilePath(this.#agentDir, providerRequestKey);
+		const record = await this.#readSidecarRecord(file);
+		const parsed = record?.intent;
+		if (!record || !parsed || parsed.providerRequestKey !== providerRequestKey || this.#now() >= parsed.expiresAt)
 			return undefined;
-		}
-		if (!isPersistedIntent(parsed) || parsed.intent.intendedSessionId !== intendedSessionId) return undefined;
-		if (this.#now() >= parsed.intent.expiresAt) return undefined;
-		this.#intents.set(intendedSessionId, parsed.intent);
-		return parsed.intent;
+		this.#intents.set(providerRequestKey, parsed);
+		if (record.legacy) await this.#migrateIntentSidecar(file, parsed);
+		return parsed;
 	}
 
 	async readPendingTopic(topicId: number): Promise<TelegramPendingTopic | undefined> {
 		const file = pendingTopicFilePath(this.#agentDir, topicId);
-		const pending = await this.#readPendingSidecar(file);
-		if (!pending || pending.topicId !== topicId || this.#now() >= pending.expiresAt) return undefined;
+		const record = await this.#readPendingSidecarRecord(file);
+		const pending = record?.pendingTopic;
+		if (!record || !pending || pending.topicId !== topicId || this.#now() >= pending.expiresAt) return undefined;
 		this.#pendingTopics.set(topicId, pending);
+		if (record.legacy) await this.#migratePendingTopicSidecar(file, pending);
 		return pending;
 	}
 
-	/**
-	 * Rehydrate all non-expired intents from the notifications dir. Files are the
-	 * only source: missing/corrupt/expired entries are skipped (never thrown).
-	 * Returns the count of live intents loaded.
-	 */
 	async rehydrate(): Promise<number> {
 		let names: readonly string[];
 		try {
@@ -398,55 +416,52 @@ export class TelegramAdoptionIntentStore {
 		}
 		let loaded = 0;
 		for (const name of names) {
+			const file = path.join(this.#dir, name);
 			if (name.endsWith(INTENT_FILE_SUFFIX)) {
-				const intendedSessionId = name.slice(0, -INTENT_FILE_SUFFIX.length);
-				if (!intendedSessionId) continue;
-				const intent = await this.readIntent(intendedSessionId);
-				if (intent) loaded++;
+				const encoded = name.slice(0, -INTENT_FILE_SUFFIX.length);
+				const key = decodeProviderRequestKey(encoded);
+				const record = await this.#readSidecarRecord(file);
+				const intent = record?.intent;
+				if (!intent || this.#now() >= intent.expiresAt) continue;
+				if (!record.legacy && (!key || intent.providerRequestKey !== key)) continue;
+				this.#intents.set(intent.providerRequestKey, intent);
+				if (record.legacy) await this.#migrateIntentSidecar(file, intent);
+				loaded++;
 				continue;
 			}
 			if (!name.endsWith(PENDING_TOPIC_FILE_SUFFIX)) continue;
-			const rawTopicId = name.slice(0, -PENDING_TOPIC_FILE_SUFFIX.length);
-			const topicId = Number(rawTopicId);
+			const topicId = Number(name.slice(0, -PENDING_TOPIC_FILE_SUFFIX.length));
 			if (!Number.isSafeInteger(topicId) || topicId <= 0) continue;
-			const pending = await this.readPendingTopic(topicId);
-			if (pending) loaded++;
+			const record = await this.#readPendingSidecarRecord(file);
+			const pending = record?.pendingTopic;
+			if (!pending || pending.topicId !== topicId || this.#now() >= pending.expiresAt) continue;
+			this.#pendingTopics.set(topicId, pending);
+			if (record.legacy) await this.#migratePendingTopicSidecar(file, pending);
+			loaded++;
 		}
 		return loaded;
 	}
 
-	/**
-	 * Remove a single intent sidecar and drop its in-memory entry. Safe to call
-	 * after a successful registry commit or a definite spawn failure. Missing
-	 * files are not an error. Never calls the Telegram API.
-	 */
-	async remove(intendedSessionId: string): Promise<void> {
-		const file = adoptionIntentFilePath(this.#agentDir, intendedSessionId);
+	async remove(providerRequestKey: string): Promise<void> {
 		try {
-			await this.#fsImpl.unlink(file);
+			await this.#fsImpl.unlink(adoptionIntentFilePath(this.#agentDir, providerRequestKey));
 		} catch (error) {
 			if (!isMissing(error)) throw error;
 		}
-		const intent = this.#intents.get(intendedSessionId);
-		this.#intents.delete(intendedSessionId);
-		if (intent) this.releaseClaim(intent.topicId, intendedSessionId);
+		const intent = this.#intents.get(providerRequestKey);
+		this.#intents.delete(providerRequestKey);
+		if (intent) this.releaseClaim(intent.topicId, providerRequestKey);
 	}
 
-	/** Remove a pending-topic authorization after an adoption intent is durable. */
 	async removePendingTopic(topicId: number): Promise<void> {
-		const file = pendingTopicFilePath(this.#agentDir, topicId);
 		try {
-			await this.#fsImpl.unlink(file);
+			await this.#fsImpl.unlink(pendingTopicFilePath(this.#agentDir, topicId));
 		} catch (error) {
 			if (!isMissing(error)) throw error;
 		}
 		this.#pendingTopics.delete(topicId);
 	}
 
-	/**
-	 * Sweep expired intent sidecars from disk. Touches files only. Returns the
-	 * count of expired sidecars removed. Safe to run at startup and periodically.
-	 */
 	async sweepExpired(): Promise<number> {
 		let names: readonly string[];
 		try {
@@ -460,10 +475,9 @@ export class TelegramAdoptionIntentStore {
 		for (const name of names) {
 			const file = path.join(this.#dir, name);
 			if (name.endsWith(INTENT_FILE_SUFFIX)) {
-				const intendedSessionId = name.slice(0, -INTENT_FILE_SUFFIX.length);
-				if (!intendedSessionId) continue;
-				const intent = await this.#readSidecar(file);
-				if (intent && intent.intendedSessionId === intendedSessionId && now < intent.expiresAt) continue;
+				const record = await this.#readSidecarRecord(file);
+				const intent = record?.intent;
+				if (intent && now < intent.expiresAt) continue;
 				try {
 					await this.#fsImpl.unlink(file);
 					removed++;
@@ -471,15 +485,14 @@ export class TelegramAdoptionIntentStore {
 					if (!isMissing(error)) throw error;
 				}
 				if (intent) {
-					this.#intents.delete(intent.intendedSessionId);
-					this.releaseClaim(intent.topicId, intent.intendedSessionId);
+					this.#intents.delete(intent.providerRequestKey);
+					this.releaseClaim(intent.topicId, intent.providerRequestKey);
 				}
 				continue;
 			}
 			if (!name.endsWith(PENDING_TOPIC_FILE_SUFFIX)) continue;
-			const rawTopicId = name.slice(0, -PENDING_TOPIC_FILE_SUFFIX.length);
-			const topicId = Number(rawTopicId);
-			const pending = await this.#readPendingSidecar(file);
+			const topicId = Number(name.slice(0, -PENDING_TOPIC_FILE_SUFFIX.length));
+			const pending = (await this.#readPendingSidecarRecord(file))?.pendingTopic;
 			if (Number.isSafeInteger(topicId) && topicId > 0 && pending?.topicId === topicId && now < pending.expiresAt)
 				continue;
 			try {
@@ -493,8 +506,7 @@ export class TelegramAdoptionIntentStore {
 		return removed;
 	}
 
-	/** Read and validate a sidecar at an arbitrary path (used by sweep). */
-	async #readSidecar(file: string): Promise<TelegramAdoptionIntent | undefined> {
+	async #readSidecarRecord(file: string): Promise<{ intent: TelegramAdoptionIntent; legacy: boolean } | undefined> {
 		let raw: string;
 		try {
 			raw = await this.#fsImpl.readFile(file, "utf8");
@@ -502,16 +514,16 @@ export class TelegramAdoptionIntentStore {
 			if (isMissing(error)) return undefined;
 			throw error;
 		}
-		let parsed: unknown;
 		try {
-			parsed = JSON.parse(raw);
+			return normalizePersistedIntent(JSON.parse(raw) as unknown);
 		} catch {
 			return undefined;
 		}
-		return isPersistedIntent(parsed) ? parsed.intent : undefined;
 	}
 
-	async #readPendingSidecar(file: string): Promise<TelegramPendingTopic | undefined> {
+	async #readPendingSidecarRecord(
+		file: string,
+	): Promise<{ pendingTopic: TelegramPendingTopic; legacy: boolean } | undefined> {
 		let raw: string;
 		try {
 			raw = await this.#fsImpl.readFile(file, "utf8");
@@ -519,16 +531,60 @@ export class TelegramAdoptionIntentStore {
 			if (isMissing(error)) return undefined;
 			throw error;
 		}
-		let parsed: unknown;
 		try {
-			parsed = JSON.parse(raw);
+			const parsed: unknown = JSON.parse(raw);
+			if (!isPersistedPendingTopic(parsed)) return undefined;
+			return {
+				pendingTopic: parsed.pendingTopic,
+				legacy: parsed.version === LEGACY_TELEGRAM_ADOPTION_INTENT_VERSION,
+			};
 		} catch {
 			return undefined;
 		}
-		return isPersistedPendingTopic(parsed) ? parsed.pendingTopic : undefined;
 	}
 
-	/** fsync the parent dir so the rename survives a crash; best-effort on win32. */
+	async #migrateIntentSidecar(file: string, intent: TelegramAdoptionIntent): Promise<void> {
+		const destination = adoptionIntentFilePath(this.#agentDir, intent.providerRequestKey);
+		try {
+			await this.#writeSidecar(
+				destination,
+				{ version: TELEGRAM_ADOPTION_INTENT_VERSION, intent },
+				destination === file,
+			);
+		} catch (error) {
+			if (error instanceof SidecarDurabilityUncertainError) logMigrationDurabilityUncertain("intent", error);
+			else logMigrationFailure("intent", "write", error);
+			return;
+		}
+		if (destination === file) return;
+		try {
+			await this.#fsImpl.unlink(file);
+		} catch (error) {
+			logMigrationFailure("intent", "unlink", error);
+		}
+	}
+
+	async #migratePendingTopicSidecar(file: string, pendingTopic: TelegramPendingTopic): Promise<void> {
+		const destination = pendingTopicFilePath(this.#agentDir, pendingTopic.topicId);
+		try {
+			await this.#writeSidecar(
+				destination,
+				{ version: TELEGRAM_ADOPTION_INTENT_VERSION, pendingTopic },
+				destination === file,
+			);
+		} catch (error) {
+			if (error instanceof SidecarDurabilityUncertainError) logMigrationDurabilityUncertain("pending_topic", error);
+			else logMigrationFailure("pending_topic", "write", error);
+			return;
+		}
+		if (destination === file) return;
+		try {
+			await this.#fsImpl.unlink(file);
+		} catch (error) {
+			logMigrationFailure("pending_topic", "unlink", error);
+		}
+	}
+
 	async #syncParentDirectory(): Promise<void> {
 		let handle: AdoptionIntentFileHandle;
 		try {
@@ -556,6 +612,40 @@ export class TelegramAdoptionIntentStore {
 	}
 }
 
+function migrationFailureMessage(error: unknown): string {
+	const message =
+		error instanceof Error ? error.message : typeof error === "string" ? error : "non-error migration failure";
+	return message.length <= MIGRATION_DIAGNOSTIC_MAX_LENGTH
+		? message
+		: `${message.slice(0, MIGRATION_DIAGNOSTIC_MAX_LENGTH - 1)}…`;
+}
+
+class SidecarDurabilityUncertainError extends Error {
+	constructor(error: unknown) {
+		super(migrationFailureMessage(error));
+		this.name = "SidecarDurabilityUncertainError";
+	}
+}
+
+function logMigrationDurabilityUncertain(sidecar: "intent" | "pending_topic", error: unknown): void {
+	logger.warn(
+		"notifications: Telegram adoption sidecar migration durability is uncertain; retained migrated v2 sidecar",
+		{
+			sidecar,
+			stage: "durability",
+			error: migrationFailureMessage(error),
+		},
+	);
+}
+
+function logMigrationFailure(sidecar: "intent" | "pending_topic", stage: "write" | "unlink", error: unknown): void {
+	logger.warn("notifications: Telegram adoption sidecar migration failed; retaining legacy sidecar", {
+		sidecar,
+		stage,
+		error: migrationFailureMessage(error),
+	});
+}
+
 async function syncRequired(handle: AdoptionIntentFileHandle): Promise<void> {
 	if (typeof handle.sync !== "function")
 		throw new Error("adoption sidecar durability requires filesystem sync support");