@gajae-code/coding-agent 0.7.2 → 0.7.3

package/src/notifications/telegram-daemon.ts

@@ -11,6 +11,7 @@ import { resolveGjcRuntimeSpawnInfo } from "../daemon/runtime";
 import { getNotificationConfig, isGloballyConfigured, tokenFingerprint } from "./config";
 import { parseInThreadConfigCommand } from "./config-commands";
 import { buildButtonGrid, TELEGRAM_PARSE_MODE } from "./html-format";
+import { NotificationOperatorRuntime, OperatorBackoffPolicy, OperatorEventRouter } from "./operator-runtime";
 import { RateLimitPool } from "./rate-limit-pool";
 import {
 	type AliasTable,
@@ -104,6 +105,7 @@ const TYPING_REFRESH_INTERVAL_MS = 4_000;
 // Native reactions used as a two-stage delivery double-check on inbound thread
 // messages: queued on receipt, consumed once a turn picks the message up.
 const QUEUED_REACTION = "👀";
+const PENDING_TOPIC_FRAME_LIMIT = 20;
 const CONSUMED_REACTION = "✅";
 
 /**
@@ -527,6 +529,154 @@ export interface BotApi {
 	call(method: string, body: unknown, opts?: { signal?: AbortSignal }): Promise<unknown>;
 }
 
+export interface TelegramTransportOptions {
+	botToken: string;
+	apiBase?: string;
+	fetchImpl?: typeof fetch;
+	setTimeoutImpl?: typeof setTimeout;
+}
+
+/** Telegram Bot API transport: HTTP JSON/multipart details stay out of daemon orchestration. */
+export class TelegramBotTransport implements BotApi {
+	#opts: TelegramTransportOptions;
+
+	constructor(opts: TelegramTransportOptions) {
+		this.#opts = opts;
+	}
+
+	async call(method: string, body: unknown, opts?: { signal?: AbortSignal }): Promise<unknown> {
+		const apiBase = this.#opts.apiBase ?? "https://api.telegram.org";
+		const url = `${apiBase}/bot${this.#opts.botToken}/${method}`;
+		const fetchImpl = this.#opts.fetchImpl ?? fetch;
+		const setTimeoutImpl = this.#opts.setTimeoutImpl ?? setTimeout;
+		const sleep = (ms: number) => new Promise<void>(resolve => setTimeoutImpl(resolve, ms));
+		// sendPhoto with base64 bytes must be a multipart upload (Telegram does
+		// not accept base64 in JSON). Other methods stay JSON.
+		const photoBody = body as { photo?: unknown; mime?: unknown } | null;
+		if (method === "sendPhoto" && photoBody && typeof photoBody.photo === "string") {
+			const b = body as {
+				chat_id: unknown;
+				message_thread_id?: unknown;
+				photo: string;
+				mime?: string;
+				caption?: string;
+				parse_mode?: string;
+			};
+			const form = new FormData();
+			form.set("chat_id", String(b.chat_id));
+			if (b.message_thread_id !== undefined) form.set("message_thread_id", String(b.message_thread_id));
+			if (b.caption) form.set("caption", b.caption);
+			if (b.parse_mode) form.set("parse_mode", String(b.parse_mode));
+			form.set("photo", new Blob([Buffer.from(b.photo, "base64")], { type: b.mime ?? "image/png" }), "image");
+			const res = await fetchWithRetry(fetchImpl, url, { method: "POST", body: form, signal: opts?.signal }, sleep);
+			return res.json();
+		}
+		const docBody = body as { document?: unknown } | null;
+		if (method === "sendDocument" && docBody && typeof docBody.document === "string") {
+			const b = body as {
+				chat_id: unknown;
+				message_thread_id?: unknown;
+				document: string;
+				mime?: string;
+				fileName?: string;
+				caption?: string;
+				parse_mode?: string;
+			};
+			const form = new FormData();
+			form.set("chat_id", String(b.chat_id));
+			if (b.message_thread_id !== undefined) form.set("message_thread_id", String(b.message_thread_id));
+			if (b.caption) form.set("caption", b.caption);
+			if (b.parse_mode) form.set("parse_mode", String(b.parse_mode));
+			form.set(
+				"document",
+				new Blob([Buffer.from(b.document, "base64")], { type: b.mime ?? "application/octet-stream" }),
+				b.fileName ?? "file",
+			);
+			const res = await fetchWithRetry(fetchImpl, url, { method: "POST", body: form, signal: opts?.signal }, sleep);
+			return res.json();
+		}
+		const res = await fetchWithRetry(
+			fetchImpl,
+			url,
+			{
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify(body),
+				signal: opts?.signal,
+			},
+			sleep,
+		);
+		return res.json();
+	}
+}
+
+export interface TelegramUpdatePollerOptions {
+	botApi: BotApi;
+	runtime: NotificationOperatorRuntime;
+	backoff: OperatorBackoffPolicy;
+	processUpdate: (update: unknown) => Promise<void>;
+}
+
+/** Owns getUpdates offset, conflict backoff, and per-update error isolation. */
+export class TelegramUpdatePoller {
+	#offset = 0;
+	#opts: TelegramUpdatePollerOptions;
+
+	constructor(opts: TelegramUpdatePollerOptions) {
+		this.#opts = opts;
+	}
+
+	async pollOnce(signal?: AbortSignal): Promise<number> {
+		let body: {
+			ok?: boolean;
+			error_code?: number;
+			description?: string;
+			result?: Array<{ update_id: number } & Record<string, unknown>>;
+		};
+		try {
+			body = (await this.#opts.botApi.call(
+				"getUpdates",
+				{ offset: this.#offset, timeout: 25, allowed_updates: ["message", "callback_query"] },
+				{ signal },
+			)) as typeof body;
+		} catch (err) {
+			// A cooperative stop aborts the in-flight long poll; treat as a clean wake.
+			if (isAbortError(err)) return 0;
+			// A transient Telegram API failure must never crash the daemon.
+			logger.error("notifications daemon: getUpdates failed", { error: String(err) });
+			await this.#opts.runtime.sleep(POLL_BACKOFF_MS, signal);
+			return 0;
+		}
+		// Telegram allows only one active getUpdates poller per bot. A 409 means
+		// another poller is live; back off boundedly instead of hot-looping.
+		if (body && body.ok === false && (body.error_code === 409 || /409|conflict/i.test(body.description ?? ""))) {
+			const backoffMs = this.#opts.backoff.next();
+			logger.error(
+				`notifications daemon: Telegram getUpdates 409 conflict (${body.description ?? "no description"}); backing off ${backoffMs}ms`,
+			);
+			await this.#opts.runtime.sleep(backoffMs, signal);
+			return 0;
+		}
+		this.#opts.backoff.reset();
+		for (const update of body.result ?? []) {
+			this.#offset = update.update_id + 1;
+			try {
+				await this.#opts.processUpdate(update);
+			} catch (err) {
+				logger.error("notifications daemon: handleTelegramUpdate failed", { error: String(err) });
+			}
+		}
+		return body.result?.length ?? 0;
+	}
+}
+
+/** Mutable dispatch state shared by session frames and inbound Telegram updates. */
+export class TelegramEventDispatchState {
+	readonly busy = new Set<string>();
+	readonly inboundReactions = new Map<number, { messageId: number }>();
+	readonly seenUpdateIds = new Set<number>();
+}
+
 /**
  * Cooperative control seam for the daemon run loop. Implemented by the
  * daemon-internal CLI / controller against the owner-scoped control-request
@@ -575,37 +725,44 @@ interface SessionSocket {
 	pingTimer: ReturnType<typeof setInterval> | undefined;
 }
 
+interface PendingThreadedFrame {
+	send: ThreadedSend;
+	msg: Record<string, unknown>;
+}
+
 export class TelegramNotificationDaemon {
 	readonly aliasTable: AliasTable;
 	readonly messageRoutes = new Map<string | number, CallbackRoute | Omit<CallbackRoute, "answer">>();
 	readonly sessions = new Map<string, SessionSocket>();
+	private readonly runtime: NotificationOperatorRuntime;
+	private readonly sessionRouter: OperatorEventRouter<SessionSocket>;
+	private readonly pollConflictBackoff = new OperatorBackoffPolicy({ initialMs: 500, maxMs: 5_000 });
+	private readonly loopBackoff = new OperatorBackoffPolicy({ initialMs: 250, maxMs: 4_000 });
 	private running = false;
-	private offset = 0;
 	private readonly fsImpl: TelegramDaemonFs;
 	private readonly botApi: BotApi;
 	private readonly topics = new TopicRegistry();
 	private readonly pool: RateLimitPool<{ send: ThreadedSend; topicId?: string }>;
-	private readonly seenUpdateIds = new Set<number>();
+	private readonly poller: TelegramUpdatePoller;
+	private readonly dispatchState = new TelegramEventDispatchState();
+	/** Identity-bearing sessions by repo/branch surface, used to avoid transient duplicate topics. */
+	private readonly topicOwnerByIdentity = new Map<string, string>();
+	/** Non-identity frames held until identity creates the correct thread. */
+	private readonly pendingThreadedFrames = new Map<string, PendingThreadedFrame[]>();
 	/** True once the daemon has nudged the user to enable Threaded Mode. */
 	private threadedFallbackNoticeSent = false;
 	/** Sessions whose identity header was already sent flat (Threaded Mode off). */
 	private readonly flatIdentitySent = new Set<string>();
 	/** Cached result of whether the paired chat is a private chat (flat-fallback gate). */
 	private pairedChatPrivate: boolean | undefined;
-	private flushTimer: ReturnType<typeof setInterval> | undefined;
-	private scanTimer: ReturnType<typeof setInterval> | undefined;
-	private scanning = false;
-	private typingTimer: ReturnType<typeof setInterval> | undefined;
 	/** Sessions whose agent loop is currently busy (drives the typing indicator). */
-	private readonly busy = new Set<string>();
+	private get busy(): Set<string> {
+		return this.dispatchState.busy;
+	}
 	/** Inbound update id → originating Telegram message, for delivery reactions. */
-	private readonly inboundReactions = new Map<number, { messageId: number }>();
-	/** AbortController for the in-flight long poll; aborted by requestStop() to wake the loop. */
-	private activePoll: AbortController | undefined;
-	/** Set when a cooperative stop has been requested (signal or control request). */
-	private stopRequested = false;
-	/** Current bounded backoff after a Telegram getUpdates 409 conflict (0 when healthy). */
-	private pollConflictBackoffMs = 0;
+	private get inboundReactions(): Map<number, { messageId: number }> {
+		return this.dispatchState.inboundReactions;
+	}
 
 	/**
 	 * Cooperatively stop the daemon: set the stop flag and abort the in-flight
@@ -613,91 +770,84 @@ export class TelegramNotificationDaemon {
 	 * ~25s getUpdates timeout. Safe to call from a signal handler.
 	 */
 	requestStop(_reason?: "reload" | "stop" | "signal"): void {
-		this.stopRequested = true;
+		this.runtime.requestStop();
 		this.running = false;
-		this.activePoll?.abort();
 	}
 
 	constructor(private readonly opts: TelegramDaemonOptions) {
 		this.fsImpl = opts.fs ?? nodeFs;
 		this.aliasTable = createAliasTable();
-		this.botApi = opts.botApi ?? {
-			call: async (method, body, callOpts) => {
-				const apiBase = opts.apiBase ?? "https://api.telegram.org";
-				const url = `${apiBase}/bot${opts.botToken}/${method}`;
-				const fetchImpl = opts.fetchImpl ?? fetch;
-				const setTimeoutImpl = opts.setTimeoutImpl ?? setTimeout;
-				const sleep = (ms: number) => new Promise<void>(resolve => setTimeoutImpl(resolve, ms));
-				// sendPhoto with base64 bytes must be a multipart upload (Telegram does
-				// not accept base64 in JSON). Other methods stay JSON.
-				const photoBody = body as { photo?: unknown; mime?: unknown } | null;
-				if (method === "sendPhoto" && photoBody && typeof photoBody.photo === "string") {
-					const b = body as {
-						chat_id: unknown;
-						message_thread_id?: unknown;
-						photo: string;
-						mime?: string;
-						caption?: string;
-						parse_mode?: string;
-					};
-					const form = new FormData();
-					form.set("chat_id", String(b.chat_id));
-					if (b.message_thread_id !== undefined) form.set("message_thread_id", String(b.message_thread_id));
-					if (b.caption) form.set("caption", b.caption);
-					if (b.parse_mode) form.set("parse_mode", String(b.parse_mode));
-					form.set("photo", new Blob([Buffer.from(b.photo, "base64")], { type: b.mime ?? "image/png" }), "image");
-					const res = await fetchWithRetry(
-						fetchImpl,
-						url,
-						{ method: "POST", body: form, signal: callOpts?.signal },
-						sleep,
-					);
-					return res.json();
-				}
-				const docBody = body as { document?: unknown } | null;
-				if (method === "sendDocument" && docBody && typeof docBody.document === "string") {
-					const b = body as {
-						chat_id: unknown;
-						message_thread_id?: unknown;
-						document: string;
-						mime?: string;
-						fileName?: string;
-						caption?: string;
-						parse_mode?: string;
-					};
-					const form = new FormData();
-					form.set("chat_id", String(b.chat_id));
-					if (b.message_thread_id !== undefined) form.set("message_thread_id", String(b.message_thread_id));
-					if (b.caption) form.set("caption", b.caption);
-					if (b.parse_mode) form.set("parse_mode", String(b.parse_mode));
-					form.set(
-						"document",
-						new Blob([Buffer.from(b.document, "base64")], { type: b.mime ?? "application/octet-stream" }),
-						b.fileName ?? "file",
-					);
-					const res = await fetchWithRetry(
-						fetchImpl,
-						url,
-						{ method: "POST", body: form, signal: callOpts?.signal },
-						sleep,
-					);
-					return res.json();
-				}
-				const res = await fetchWithRetry(
-					fetchImpl,
-					url,
-					{
-						method: "POST",
-						headers: { "content-type": "application/json" },
-						body: JSON.stringify(body),
-						signal: callOpts?.signal,
-					},
-					sleep,
-				);
-				return res.json();
-			},
-		};
+		this.botApi =
+			opts.botApi ??
+			new TelegramBotTransport({
+				botToken: opts.botToken,
+				apiBase: opts.apiBase,
+				fetchImpl: opts.fetchImpl,
+				setTimeoutImpl: opts.setTimeoutImpl,
+			});
+		this.runtime = new NotificationOperatorRuntime({
+			now: opts.now,
+			setTimeoutImpl: opts.setTimeoutImpl,
+			clearTimeoutImpl: opts.clearTimeoutImpl,
+			setIntervalImpl: opts.setIntervalImpl,
+			clearIntervalImpl: opts.clearIntervalImpl,
+		});
+		this.sessionRouter = this.createSessionRouter();
 		this.pool = new RateLimitPool<{ send: ThreadedSend; topicId?: string }>({ now: opts.now });
+		this.poller = new TelegramUpdatePoller({
+			botApi: this.botApi,
+			runtime: this.runtime,
+			backoff: this.pollConflictBackoff,
+			processUpdate: update => this.handleTelegramUpdate(update),
+		});
+	}
+
+	private createSessionRouter(): OperatorEventRouter<SessionSocket> {
+		return new OperatorEventRouter<SessionSocket>()
+			.add({
+				name: "hello",
+				matches: msg => msg.type === "hello",
+				handle: (session, msg) => {
+					const caps = Array.isArray(msg.capabilities) ? msg.capabilities : [];
+					if (caps.includes(CLIENT_PING_PONG_CAPABILITY)) {
+						session.capable = true;
+						this.startLiveness(session);
+					}
+				},
+			})
+			.add({
+				name: "pong",
+				matches: msg => msg.type === "pong",
+				handle: (session, msg) => {
+					if (typeof msg.nonce === "string" && msg.nonce === session.awaitingNonce) {
+						session.awaitingNonce = undefined;
+						session.lastPongAt = this.runtime.now();
+					}
+				},
+			})
+			.add({
+				name: "activity",
+				matches: msg => msg.type === "activity",
+				handle: async (session, msg) => {
+					if (msg.state === "busy") {
+						this.busy.add(session.sessionId);
+						await this.sendTyping(session.sessionId);
+					} else {
+						this.busy.delete(session.sessionId);
+					}
+				},
+			})
+			.add({
+				name: "inbound_ack",
+				matches: msg => msg.type === "inbound_ack" && typeof msg.updateId === "number",
+				handle: async (_session, msg) => {
+					const target = this.inboundReactions.get(msg.updateId as number);
+					if (target && msg.state === "consumed") {
+						this.inboundReactions.delete(msg.updateId as number);
+						await this.setReaction(target.messageId, CONSUMED_REACTION);
+					}
+				},
+			});
 	}
 
 	async loadAliases(): Promise<void> {
@@ -770,7 +920,7 @@ export class TelegramNotificationDaemon {
 			void this.handleSessionMessage(session, JSON.parse(String(ev.data))).catch(err => {
 				// Surface frame-handling failures (e.g. a rejected ask sendMessage) to
 				// the daemon log instead of an invisible unhandled rejection.
-				console.error("notifications daemon: handleSessionMessage failed:", err);
+				logger.error("notifications daemon: handleSessionMessage failed", { error: String(err) });
 			});
 		});
 		ws.addEventListener("close", () => {
@@ -788,7 +938,7 @@ export class TelegramNotificationDaemon {
 	private startLiveness(session: SessionSocket): void {
 		if (session.pingTimer) return;
 		const setIntervalImpl = this.opts.setIntervalImpl ?? setInterval;
-		const now = () => (this.opts.now ?? Date.now)();
+		const now = () => this.runtime.now();
 		session.lastPongAt = now();
 		session.pingTimer = setIntervalImpl(() => {
 			if (this.sessions.get(session.sessionId) !== session) return;
@@ -851,6 +1001,60 @@ export class TelegramNotificationDaemon {
 		return `GJC ${sessionId.slice(-6)}`;
 	}
 
+	private topicIdentityKey(msg: { repo?: unknown; branch?: unknown }): string | undefined {
+		const repo = typeof msg?.repo === "string" && msg.repo.trim() ? msg.repo.trim() : undefined;
+		if (!repo) return undefined;
+		const branch = typeof msg?.branch === "string" && msg.branch.trim() ? msg.branch.trim() : "";
+		return `${repo}\0${branch}`;
+	}
+
+	private topicIdentityBase(msg: { repo?: unknown; branch?: unknown }): string | undefined {
+		const repo = typeof msg?.repo === "string" && msg.repo.trim() ? msg.repo.trim() : undefined;
+		if (!repo) return undefined;
+		const branch = typeof msg?.branch === "string" && msg.branch.trim() ? msg.branch.trim() : undefined;
+		return branch ? `${repo}/${branch}` : repo;
+	}
+
+	private topicOwnerForIdentity(msg: { repo?: unknown; branch?: unknown }): string | undefined {
+		const identityKey = this.topicIdentityKey(msg);
+		const remembered = identityKey ? this.topicOwnerByIdentity.get(identityKey) : undefined;
+		if (remembered && this.topics.get(remembered)) return remembered;
+		const base = this.topicIdentityBase(msg);
+		if (!identityKey || !base) return undefined;
+		for (const sessionId of this.topics.sessionIds()) {
+			const name = this.topics.get(sessionId)?.name;
+			if (name === base || name?.startsWith(`${base} - `)) {
+				this.topicOwnerByIdentity.set(identityKey, sessionId);
+				return sessionId;
+			}
+		}
+		return undefined;
+	}
+
+	private async submitThreadedFrame(sessionId: string, send: ThreadedSend, topicId: string): Promise<void> {
+		this.pool.submit({
+			sessionId,
+			lane: send.lane,
+			coalesceKey: send.coalesceKey,
+			payload: { send, topicId },
+		});
+		await this.flushPool();
+	}
+
+	private rememberPendingThreadedFrame(sessionId: string, send: ThreadedSend, msg: Record<string, unknown>): void {
+		const frames = this.pendingThreadedFrames.get(sessionId) ?? [];
+		frames.push({ send, msg });
+		if (frames.length > PENDING_TOPIC_FRAME_LIMIT) frames.shift();
+		this.pendingThreadedFrames.set(sessionId, frames);
+	}
+
+	private async flushPendingThreadedFrames(sessionId: string, topicId: string): Promise<void> {
+		const frames = this.pendingThreadedFrames.get(sessionId);
+		if (!frames || frames.length === 0) return;
+		this.pendingThreadedFrames.delete(sessionId);
+		for (const frame of frames) await this.submitThreadedFrame(sessionId, frame.send, topicId);
+	}
+
 	/**
 	 * Resolve (creating once via `createForumTopic`) the forum topic for a
 	 * session. On capability failure (e.g. Threaded Mode off) this returns
@@ -1092,46 +1296,32 @@ export class TelegramNotificationDaemon {
 	}
 
 	private startFlushTimer(): void {
-		if (this.flushTimer) return;
-		const setIntervalImpl = this.opts.setIntervalImpl ?? setInterval;
-		this.flushTimer = setIntervalImpl(() => {
+		this.runtime.startInterval("telegram-flush", RATE_LIMIT_FLUSH_INTERVAL_MS, () => {
 			if (!this.running || this.pool.pending === 0) return;
 			void this.flushPool();
-		}, RATE_LIMIT_FLUSH_INTERVAL_MS);
+		});
 	}
 
 	private stopFlushTimer(): void {
-		if (!this.flushTimer) return;
-		const clearIntervalImpl = this.opts.clearIntervalImpl ?? clearInterval;
-		clearIntervalImpl(this.flushTimer);
-		this.flushTimer = undefined;
+		this.runtime.stopInterval("telegram-flush");
 	}
 
 	/** Run a root scan, guarding against overlapping scans from the timer + loop. */
 	private async runScan(): Promise<void> {
-		if (this.scanning) return;
-		this.scanning = true;
-		try {
+		await this.runtime.runExclusive("telegram-scan", async () => {
 			await this.scanRoots();
-		} finally {
-			this.scanning = false;
-		}
+		});
 	}
 
 	private startScanTimer(): void {
-		if (this.scanTimer) return;
-		const setIntervalImpl = this.opts.setIntervalImpl ?? setInterval;
-		this.scanTimer = setIntervalImpl(() => {
+		this.runtime.startInterval("telegram-scan", this.opts.scanIntervalMs ?? SESSION_SCAN_INTERVAL_MS, () => {
 			if (!this.running) return;
 			void this.runScan();
-		}, this.opts.scanIntervalMs ?? SESSION_SCAN_INTERVAL_MS);
+		});
 	}
 
 	private stopScanTimer(): void {
-		if (!this.scanTimer) return;
-		const clearIntervalImpl = this.opts.clearIntervalImpl ?? clearInterval;
-		clearIntervalImpl(this.scanTimer);
-		this.scanTimer = undefined;
+		this.runtime.stopInterval("telegram-scan");
 	}
 
 	/** Send a single `typing` chat action into a busy session's topic (best-effort). */
@@ -1163,67 +1353,43 @@ export class TelegramNotificationDaemon {
 	}
 
 	private startTypingTimer(): void {
-		if (this.typingTimer) return;
-		const setIntervalImpl = this.opts.setIntervalImpl ?? setInterval;
-		this.typingTimer = setIntervalImpl(() => {
+		this.runtime.startInterval("telegram-typing", TYPING_REFRESH_INTERVAL_MS, () => {
 			if (!this.running || this.busy.size === 0) return;
 			for (const sessionId of this.busy) void this.sendTyping(sessionId);
-		}, TYPING_REFRESH_INTERVAL_MS);
+		});
 	}
 
 	private stopTypingTimer(): void {
-		if (!this.typingTimer) return;
-		const clearIntervalImpl = this.opts.clearIntervalImpl ?? clearInterval;
-		clearIntervalImpl(this.typingTimer);
-		this.typingTimer = undefined;
+		this.runtime.stopInterval("telegram-typing");
 	}
 
 	async handleSessionMessage(session: SessionSocket, msg: any): Promise<void> {
-		if (msg?.type === "hello") {
-			const caps = Array.isArray(msg.capabilities) ? msg.capabilities : [];
-			if (caps.includes(CLIENT_PING_PONG_CAPABILITY)) {
-				session.capable = true;
-				this.startLiveness(session);
-			}
-			return;
-		}
-		if (msg?.type === "pong") {
-			if (typeof msg.nonce === "string" && msg.nonce === session.awaitingNonce) {
-				session.awaitingNonce = undefined;
-				session.lastPongAt = (this.opts.now ?? Date.now)();
-			}
-			return;
-		}
-		// Live typing indicator: track busy/idle per session and push an immediate
-		// chat action so "typing…" appears without waiting for the refresh tick.
-		if (msg?.type === "activity") {
-			if (msg.state === "busy") {
-				this.busy.add(session.sessionId);
-				await this.sendTyping(session.sessionId);
-			} else {
-				this.busy.delete(session.sessionId);
-			}
-			return;
-		}
-		// Inbound delivery double-check: flip the queued reaction to the consumed
-		// reaction once the session reports a turn picked the message up.
-		if (msg?.type === "inbound_ack" && typeof msg.updateId === "number") {
-			const target = this.inboundReactions.get(msg.updateId);
-			if (target && msg.state === "consumed") {
-				this.inboundReactions.delete(msg.updateId);
-				await this.setReaction(target.messageId, CONSUMED_REACTION);
-			}
-			return;
-		}
+		if (await this.sessionRouter.dispatch(session, msg as Record<string, unknown>)) return;
 		if (typeof msg?.type === "string" && TelegramNotificationDaemon.THREADED_FRAMES.has(msg.type)) {
 			const send = renderThreadedFrame(msg);
 			if (!send) return;
-			const topicId = await this.ensureTopic(session.sessionId, this.topicNameFor(session.sessionId, msg));
+			const existingTopic = this.topics.get(session.sessionId)?.topicId;
+			if (!send.identity && !existingTopic && !this.flatIdentitySent.has(session.sessionId)) {
+				this.rememberPendingThreadedFrame(session.sessionId, send, msg as Record<string, unknown>);
+				return;
+			}
+			if (send.identity) {
+				const ownerId = this.topicOwnerForIdentity(msg);
+				const ownerTopic = ownerId ? this.topics.get(ownerId) : undefined;
+				if (ownerId && ownerId !== session.sessionId && ownerTopic) {
+					await this.flushPendingThreadedFrames(session.sessionId, ownerTopic.topicId);
+					return;
+				}
+			}
+			const topicId =
+				existingTopic ?? (await this.ensureTopic(session.sessionId, this.topicNameFor(session.sessionId, msg)));
 			if (!topicId) {
 				await this.deliverFlatFallback(session.sessionId, send);
 				return;
 			}
 			if (send.identity) {
+				const identityKey = this.topicIdentityKey(msg);
+				if (identityKey) this.topicOwnerByIdentity.set(identityKey, session.sessionId);
 				// Rename the topic if the title changed (e.g. the session title was
 				// auto-generated after the topic was first created). This runs on
 				// every identity frame, but does NOT re-send the bulleted message.
@@ -1241,25 +1407,14 @@ export class TelegramNotificationDaemon {
 				}
 				// Send the full bulleted identity header EXACTLY ONCE per topic.
 				if (this.topics.needsIdentity(session.sessionId)) {
-					this.pool.submit({
-						sessionId: session.sessionId,
-						lane: send.lane,
-						coalesceKey: send.coalesceKey,
-						payload: { send, topicId },
-					});
-					await this.flushPool();
+					await this.submitThreadedFrame(session.sessionId, send, topicId);
 					this.topics.markIdentitySent(session.sessionId);
 				}
+				await this.flushPendingThreadedFrames(session.sessionId, topicId);
 				await this.persistTopics();
 				return;
 			}
-			this.pool.submit({
-				sessionId: session.sessionId,
-				lane: send.lane,
-				coalesceKey: send.coalesceKey,
-				payload: { send, topicId },
-			});
-			await this.flushPool();
+			await this.submitThreadedFrame(session.sessionId, send, topicId);
 			return;
 		}
 		if (msg.type === "action_needed" && msg.id) {
@@ -1343,11 +1498,11 @@ export class TelegramNotificationDaemon {
 			const inbound = decideThreadedInbound(update as never, {
 				pairedChatId: this.opts.chatId,
 				topicToSession: t => this.topics.sessionForTopic(t),
-				isDuplicate: id => this.seenUpdateIds.has(id),
+				isDuplicate: id => this.dispatchState.seenUpdateIds.has(id),
 			});
 			if (inbound.kind === "duplicate") return;
 			if (inbound.kind === "inject") {
-				this.seenUpdateIds.add(inbound.updateId);
+				this.dispatchState.seenUpdateIds.add(inbound.updateId);
 				const session = this.sessions.get(inbound.sessionId);
 				if (session?.ws.readyState === WebSocket.OPEN) {
 					const attachmentResult = inbound.attachment
@@ -1425,67 +1580,7 @@ export class TelegramNotificationDaemon {
 	}
 
 	async pollOnce(signal?: AbortSignal): Promise<number> {
-		let body: {
-			ok?: boolean;
-			error_code?: number;
-			description?: string;
-			result?: Array<{ update_id: number } & Record<string, unknown>>;
-		};
-		try {
-			body = (await this.botApi.call(
-				"getUpdates",
-				{ offset: this.offset, timeout: 25, allowed_updates: ["message", "callback_query"] },
-				{ signal },
-			)) as typeof body;
-		} catch (err) {
-			// A cooperative stop aborts the in-flight long poll; treat as a clean wake.
-			if (isAbortError(err)) return 0;
-			// A transient Telegram API failure (e.g. ECONNRESET on the long-poll) must
-			// never crash the daemon — that silently stops all delivery, including ask
-			// notifications. Log, back off, and let the run loop retry.
-			console.error("notifications daemon: getUpdates failed:", err);
-			await this.sleep(POLL_BACKOFF_MS, signal);
-			return 0;
-		}
-		// Telegram allows only one active getUpdates poller per bot. A 409 means
-		// another poller is live; back off boundedly instead of hot-looping.
-		if (body && body.ok === false && (body.error_code === 409 || /409|conflict/i.test(body.description ?? ""))) {
-			this.pollConflictBackoffMs = Math.min(
-				this.pollConflictBackoffMs ? this.pollConflictBackoffMs * 2 : 500,
-				5_000,
-			);
-			console.error(
-				`notifications daemon: Telegram getUpdates 409 conflict (${body.description ?? "no description"}); backing off ${this.pollConflictBackoffMs}ms`,
-			);
-			await this.sleep(this.pollConflictBackoffMs, signal);
-			return 0;
-		}
-		this.pollConflictBackoffMs = 0;
-		for (const update of body.result ?? []) {
-			this.offset = update.update_id + 1;
-			try {
-				await this.handleTelegramUpdate(update);
-			} catch (err) {
-				console.error("notifications daemon: handleTelegramUpdate failed:", err);
-			}
-		}
-		return body.result?.length ?? 0;
-	}
-
-	/** Abortable sleep honoring the injected timer; resolves early on abort. */
-	private sleep(ms: number, signal?: AbortSignal): Promise<void> {
-		return new Promise<void>(resolve => {
-			if (signal?.aborted) return resolve();
-			const timer = (this.opts.setTimeoutImpl ?? setTimeout)(() => resolve(), ms);
-			signal?.addEventListener(
-				"abort",
-				() => {
-					(this.opts.clearTimeoutImpl ?? clearTimeout)(timer);
-					resolve();
-				},
-				{ once: true },
-			);
-		});
+		return this.poller.pollOnce(signal);
 	}
 
 	/** Sync the bot's Telegram command menu to what the daemon actually handles. */
@@ -1512,6 +1607,7 @@ export class TelegramNotificationDaemon {
 			pid: this.opts.pid ?? process.pid,
 		});
 		if (!this.running) return;
+		this.runtime.start();
 		this.startFlushTimer();
 		this.startScanTimer();
 		this.startTypingTimer();
@@ -1520,8 +1616,7 @@ export class TelegramNotificationDaemon {
 			await this.loadAliases();
 			await this.loadTopics();
 			await this.runScan();
-			let idleSince = (this.opts.now ?? Date.now)();
-			let pollBackoffMs = 0;
+			let idleSince = this.runtime.now();
 			while (this.running) {
 				if (await this.controlStopRequested()) break;
 				if (
@@ -1537,29 +1632,30 @@ export class TelegramNotificationDaemon {
 				await this.runScan();
 				if (await this.controlStopRequested()) break;
 				if (this.sessions.size === 0) {
-					if ((this.opts.now ?? Date.now)() - idleSince >= (this.opts.idleTimeoutMs ?? 60_000)) break;
+					if (this.runtime.now() - idleSince >= (this.opts.idleTimeoutMs ?? 60_000)) break;
 				} else {
-					idleSince = (this.opts.now ?? Date.now)();
-					this.activePoll = new AbortController();
+					idleSince = this.runtime.now();
+					const activePoll = this.runtime.createAbortController();
 					try {
-						await this.pollOnce(this.activePoll.signal);
-						pollBackoffMs = 0;
+						await this.pollOnce(activePoll.signal);
+						this.loopBackoff.reset();
 					} catch (e) {
 						// A transient getUpdates/network failure must not kill the
 						// daemon. Back off (bounded, below the heartbeat TTL) and keep
 						// renewing ownership at the loop top.
-						pollBackoffMs = pollBackoffMs === 0 ? 250 : Math.min(pollBackoffMs * 2, 4_000);
-						logger.warn(`notifications: getUpdates failed, backing off ${pollBackoffMs}ms: ${String(e)}`);
-						await new Promise(resolve => (this.opts.setTimeoutImpl ?? setTimeout)(resolve, pollBackoffMs));
+						const backoffMs = this.loopBackoff.next();
+						logger.warn(`notifications: getUpdates failed, backing off ${backoffMs}ms: ${String(e)}`);
+						await this.runtime.sleep(backoffMs);
 						continue;
 					} finally {
-						this.activePoll = undefined;
+						this.runtime.clearAbortController(activePoll);
 					}
 				}
 				if (await this.controlStopRequested()) break;
-				await new Promise(resolve => (this.opts.setTimeoutImpl ?? setTimeout)(resolve, 10));
+				await this.runtime.sleep(10);
 			}
 		} finally {
+			this.runtime.stop();
 			this.stopFlushTimer();
 			this.stopScanTimer();
 			this.stopTypingTimer();
@@ -1580,7 +1676,7 @@ export class TelegramNotificationDaemon {
 
 	/** True when a signal-driven stop or an owner-scoped control request asks the loop to exit. */
 	private async controlStopRequested(): Promise<boolean> {
-		if (this.stopRequested) return true;
+		if (this.runtime.stopRequested) return true;
 		if (!this.opts.control) return false;
 		try {
 			return await this.opts.control.shouldStop(this.opts.ownerId);