@gajae-code/coding-agent 0.6.5 → 0.7.1

package/src/notifications/telegram-reference.ts

@@ -0,0 +1,335 @@
+/**
+ * Telegram **reference** client for the notifications SDK.
+ *
+ * This is an example/template, NOT an upstream-owned integration: it implements
+ * the documented WS protocol (see `docs/notifications-sdk.md`) so you can copy it
+ * to build Discord/Slack/etc. clients with zero upstream changes. The Bot API
+ * transport shape is salvaged from the removed `telegram-remote` package.
+ *
+ * Flow: read the endpoint discovery file -> connect to the session WS -> render
+ * `action_needed` to a Telegram chat (inline keyboard for options) -> map button
+ * taps / text replies to `reply` frames -> reflect `action_resolved` /
+ * `reply_rejected`.
+ *
+ * Dependency-free: uses global `fetch` and `WebSocket` (Bun/Node 22+).
+ */
+
+import * as fs from "node:fs";
+import { bold, buildButtonGrid, escapeHtml, TELEGRAM_PARSE_MODE, truncateTelegramHtml } from "./html-format";
+import { renderThreadedFrame } from "./threaded-render";
+
+/** One inline-keyboard button. */
+export interface InlineButton {
+	text: string;
+	callback_data: string;
+}
+
+/** A rendered Telegram message for an `action_needed`. */
+export interface RenderedMessage {
+	text: string;
+	inline_keyboard?: InlineButton[][];
+}
+
+/** Encode `actionId` + option `index` into Telegram callback_data (<=64 bytes). */
+export function encodeCallbackData(actionId: string, index: number): string {
+	return `r:${index}:${actionId}`.slice(0, 64);
+}
+
+/** Decode callback_data produced by {@link encodeCallbackData}. */
+export function decodeCallbackData(data: string): { id: string; index: number } | null {
+	const m = /^r:(\d+):(.+)$/.exec(data);
+	if (!m) return null;
+	return { index: Number(m[1]), id: m[2]! };
+}
+
+export interface CallbackRoute {
+	sessionId: string;
+	actionId: string;
+	answer: number | string;
+}
+
+export interface SerializedAliasTable {
+	version: 1;
+	next: number;
+	routes: Record<string, CallbackRoute>;
+}
+
+export interface AliasTable {
+	put(route: CallbackRoute): string;
+	get(alias: string): CallbackRoute | undefined;
+	delete(alias: string): boolean;
+	serialize(): SerializedAliasTable;
+	load(json: unknown): void;
+	entries(): Array<[string, CallbackRoute]>;
+}
+
+function isCallbackRoute(value: unknown): value is CallbackRoute {
+	if (!value || typeof value !== "object") return false;
+	const route = value as Partial<CallbackRoute>;
+	return (
+		typeof route.sessionId === "string" &&
+		typeof route.actionId === "string" &&
+		(typeof route.answer === "string" || typeof route.answer === "number")
+	);
+}
+
+/** Create a compact, durable callback alias table. Serialized data contains routing ids only. */
+export function createAliasTable(): AliasTable {
+	let next = 1;
+	const routes = new Map<string, CallbackRoute>();
+	return {
+		put(route) {
+			let alias: string;
+			do {
+				alias = `a${(next++).toString(36)}`;
+			} while (routes.has(alias));
+			if (Buffer.byteLength(alias, "utf8") > 64) throw new Error("callback alias exceeded Telegram limit");
+			routes.set(alias, { ...route });
+			return alias;
+		},
+		get(alias) {
+			const route = routes.get(alias);
+			return route ? { ...route } : undefined;
+		},
+		delete(alias) {
+			return routes.delete(alias);
+		},
+		serialize() {
+			return { version: 1, next, routes: Object.fromEntries(routes.entries()) };
+		},
+		load(json) {
+			routes.clear();
+			const data = typeof json === "string" ? JSON.parse(json) : json;
+			if (!data || typeof data !== "object") return;
+			const obj = data as { next?: unknown; routes?: unknown };
+			if (typeof obj.next === "number" && Number.isFinite(obj.next) && obj.next > 0) next = Math.floor(obj.next);
+			if (!obj.routes || typeof obj.routes !== "object" || Array.isArray(obj.routes)) return;
+			for (const [alias, route] of Object.entries(obj.routes)) {
+				if (Buffer.byteLength(alias, "utf8") <= 64 && isCallbackRoute(route)) routes.set(alias, { ...route });
+			}
+		},
+		entries() {
+			return Array.from(routes.entries()).map(([alias, route]) => [alias, { ...route }]);
+		},
+	};
+}
+
+/** Render an `action_needed` payload into a Telegram message. */
+export function buildActionMessage(action: {
+	kind: "ask" | "idle";
+	id: string;
+	question?: string;
+	options?: string[];
+	summary?: string;
+}): RenderedMessage {
+	if (action.kind === "idle") {
+		const text = action.summary ? `🟢 Agent idle\n${escapeHtml(action.summary)}` : "🟢 Agent idle";
+		return { text: truncateTelegramHtml(text) };
+	}
+	const text = `❓ ${bold(action.question ?? "Question")}`;
+	const options = action.options ?? [];
+	if (options.length === 0) return { text: truncateTelegramHtml(`${text}\n\n(reply with text)`) };
+	const inline_keyboard = buildButtonGrid(options, i => encodeCallbackData(action.id, i));
+	return { text: truncateTelegramHtml(text), inline_keyboard };
+}
+
+/** A protocol `reply` frame the client should send to the server. */
+export interface ReplyFrame {
+	type: "reply";
+	id: string;
+	answer: number | string;
+	token: string;
+}
+
+/**
+ * Map a Telegram update into a reply frame, given the most recent pending ask id
+ * (for free-text replies). Returns `null` when the update is not actionable.
+ */
+export function telegramUpdateToReply(
+	update: unknown,
+	token: string,
+	latestPendingAskId: string | undefined,
+): ReplyFrame | null {
+	const u = update as {
+		callback_query?: { data?: string };
+		message?: { text?: string };
+	};
+	if (u.callback_query?.data) {
+		const decoded = decodeCallbackData(u.callback_query.data);
+		if (decoded) return { type: "reply", id: decoded.id, answer: decoded.index, token };
+	}
+	if (u.message?.text && latestPendingAskId) {
+		return { type: "reply", id: latestPendingAskId, answer: u.message.text, token };
+	}
+	return null;
+}
+
+export type RouteDecision =
+	| ({ kind: "reply" } & CallbackRoute)
+	| { kind: "stale"; reason: string }
+	| { kind: "ignore" };
+
+export interface PendingAsk {
+	sessionId: string;
+	actionId: string;
+}
+
+export interface RouteInboundContext {
+	aliasTable: Pick<AliasTable, "get">;
+	messageRoutes: Map<string | number, CallbackRoute | Omit<CallbackRoute, "answer">>;
+	pendingBySession: (sessionId?: string) => PendingAsk[];
+	pairedChatId: string;
+}
+
+type TelegramUpdateShape = {
+	callback_query?: {
+		id?: unknown;
+		data?: unknown;
+		message?: { chat?: { id?: unknown }; message_id?: unknown };
+	};
+	message?: {
+		text?: unknown;
+		chat?: { id?: unknown };
+		message_id?: unknown;
+		reply_to_message?: { message_id?: unknown };
+	};
+};
+
+function updateChatId(update: TelegramUpdateShape): string | undefined {
+	const id = update.message?.chat?.id ?? update.callback_query?.message?.chat?.id;
+	return id === undefined || id === null ? undefined : String(id);
+}
+
+function routeWithAnswer(route: CallbackRoute | Omit<CallbackRoute, "answer">, answer: number | string): CallbackRoute {
+	return { sessionId: route.sessionId, actionId: route.actionId, answer };
+}
+
+/** Route a Telegram update to a session/action without I/O. Fail closed under ambiguity. */
+export function routeInboundUpdate(update: unknown, ctx: RouteInboundContext): RouteDecision {
+	const u = update as TelegramUpdateShape;
+	if (updateChatId(u) !== String(ctx.pairedChatId)) return { kind: "ignore" };
+
+	const callbackData = u.callback_query?.data;
+	if (typeof callbackData === "string") {
+		const route = ctx.aliasTable.get(callbackData);
+		return route ? { kind: "reply", ...route } : { kind: "stale", reason: "unknown_alias" };
+	}
+
+	const text = typeof u.message?.text === "string" ? u.message.text : undefined;
+	const replyTo = u.message?.reply_to_message?.message_id;
+	if (replyTo !== undefined && text) {
+		const route = ctx.messageRoutes.get(String(replyTo)) ?? ctx.messageRoutes.get(Number(replyTo));
+		if (!route) return { kind: "stale", reason: "unknown_reply_message" };
+		return { kind: "reply", ...routeWithAnswer(route, text) };
+	}
+
+	if (text) {
+		const allPending = ctx.pendingBySession(undefined);
+		if (allPending.length === 1) {
+			const [pending] = allPending;
+			return { kind: "reply", sessionId: pending!.sessionId, actionId: pending!.actionId, answer: text };
+		}
+		if (allPending.length > 1) return { kind: "stale", reason: "ambiguous_plain_text" };
+	}
+
+	return { kind: "ignore" };
+}
+
+/** Read `{url, token}` from an endpoint discovery file. */
+export function readEndpoint(path: string): { url: string; token: string } {
+	const raw = JSON.parse(fs.readFileSync(path, "utf8")) as { url?: unknown; token?: unknown };
+	if (typeof raw.url !== "string" || typeof raw.token !== "string") {
+		throw new Error(`invalid endpoint file: ${path}`);
+	}
+	return { url: raw.url, token: raw.token };
+}
+
+/** Options for {@link runTelegramReferenceClient}. */
+export interface TelegramReferenceOptions {
+	botToken: string;
+	chatId: string;
+	endpointFile: string;
+	apiBase?: string;
+	fetchImpl?: typeof fetch;
+}
+
+/**
+ * Run the reference bridge until the WebSocket closes. Sends `action_needed` to
+ * the chat and forwards taps/text as replies. This is a minimal example loop;
+ * production clients add reconnection, multi-chat routing, and persistence.
+ */
+export async function runTelegramReferenceClient(opts: TelegramReferenceOptions): Promise<void> {
+	const fetchImpl = opts.fetchImpl ?? fetch;
+	const apiBase = opts.apiBase ?? "https://api.telegram.org";
+	const api = `${apiBase}/bot${opts.botToken}`;
+	const { url, token } = readEndpoint(opts.endpointFile);
+
+	const ws = new WebSocket(`${url}/?token=${encodeURIComponent(token)}`);
+	let latestPendingAskId: string | undefined;
+
+	const send = (method: string, body: unknown): Promise<Response> =>
+		fetchImpl(`${api}/${method}`, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify(body),
+		});
+
+	ws.addEventListener("message", (ev: MessageEvent) => {
+		const msg = JSON.parse(String(ev.data)) as {
+			type: string;
+			kind?: "ask" | "idle";
+			id?: string;
+			question?: string;
+			options?: string[];
+			summary?: string;
+			reason?: string;
+		};
+		if (msg.type === "action_needed" && msg.id) {
+			if (msg.kind === "ask") latestPendingAskId = msg.id;
+			const rendered = buildActionMessage({
+				kind: msg.kind ?? "ask",
+				id: msg.id,
+				question: msg.question,
+				options: msg.options,
+				summary: msg.summary,
+			});
+			void send("sendMessage", {
+				chat_id: opts.chatId,
+				text: rendered.text,
+				parse_mode: TELEGRAM_PARSE_MODE,
+				...(rendered.inline_keyboard ? { reply_markup: { inline_keyboard: rendered.inline_keyboard } } : {}),
+			});
+		} else if (msg.type === "action_resolved" && msg.id === latestPendingAskId) {
+			latestPendingAskId = undefined;
+		} else {
+			// Threaded frames (identity/context/turn/config): render as plain messages
+			// in this flat example client. The bundled daemon renders them into the
+			// session's forum topic; this reference shows the minimal handling.
+			const threaded = renderThreadedFrame(msg as never);
+			if (threaded?.text) {
+				void send("sendMessage", { chat_id: opts.chatId, text: threaded.text, parse_mode: TELEGRAM_PARSE_MODE });
+			}
+		}
+	});
+
+	// Telegram long-poll loop.
+	let offset = 0;
+	let running = true;
+	ws.addEventListener("close", () => {
+		running = false;
+	});
+
+	while (running) {
+		const res = await send("getUpdates", { offset, timeout: 25, allowed_updates: ["message", "callback_query"] });
+		const body = (await res.json()) as { result?: Array<{ update_id: number } & Record<string, unknown>> };
+		for (const update of body.result ?? []) {
+			offset = update.update_id + 1;
+			const callbackId = (update as { callback_query?: { id?: unknown } }).callback_query?.id;
+			if (typeof callbackId === "string") {
+				void send("answerCallbackQuery", { callback_query_id: callbackId });
+			}
+			const reply = telegramUpdateToReply(update, token, latestPendingAskId);
+			if (reply && ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(reply));
+		}
+	}
+}

package/src/notifications/threaded-inbound.ts

@@ -0,0 +1,80 @@
+/**
+ * Fail-closed routing for inbound Telegram updates in threaded session mode.
+ *
+ * In the threaded surface, a free-text reply inside a session's forum topic
+ * injects a new user turn into that session (steering it at any time). That is
+ * remote control of the agent, so every inbound path must fail closed:
+ *
+ * - the update must come from the single paired chat id;
+ * - it must carry a `message_thread_id` (topic) that maps to a KNOWN session;
+ * - its `update_id` must not have been seen before (idempotency / replay guard);
+ * - the text must be non-empty.
+ *
+ * Anything ambiguous or unmapped is ignored with a reason rather than guessed.
+ * This module is pure (the dedupe set and topic map are injected) so the
+ * security rules are exhaustively unit-testable without a live Bot API.
+ */
+
+/** Minimal shape of the inbound Telegram message we route on. */
+export interface InboundUpdate {
+	update_id?: unknown;
+	message?: {
+		message_id?: unknown;
+		text?: unknown;
+		chat?: { id?: unknown };
+		message_thread_id?: unknown;
+	};
+}
+
+/** Context for {@link decideThreadedInbound}. All lookups are injected. */
+export interface ThreadedInboundCtx {
+	/** The single paired chat id (string-compared). */
+	pairedChatId: string;
+	/** Resolve a topic/thread id to its owning session id, or undefined. */
+	topicToSession: (threadId: string) => string | undefined;
+	/** Whether this `update_id` has already been processed. */
+	isDuplicate: (updateId: number) => boolean;
+}
+
+/** Outcome of routing an inbound update. */
+export type ThreadedInboundDecision =
+	| { kind: "inject"; sessionId: string; text: string; updateId: number; threadId: string; messageId?: number }
+	| { kind: "duplicate"; updateId: number }
+	| { kind: "ignore"; reason: string };
+
+function asString(value: unknown): string | undefined {
+	if (typeof value === "string") return value;
+	if (typeof value === "number") return String(value);
+	return undefined;
+}
+
+/**
+ * Decide whether an inbound update should inject a user turn. Fail-closed:
+ * returns `ignore` (with a reason) or `duplicate` for anything that is not an
+ * unambiguous, first-seen, paired-chat, known-topic text message.
+ */
+export function decideThreadedInbound(update: InboundUpdate, ctx: ThreadedInboundCtx): ThreadedInboundDecision {
+	const message = update.message;
+	if (!message) return { kind: "ignore", reason: "no_message" };
+
+	const chatId = asString(message.chat?.id);
+	if (chatId === undefined || chatId !== String(ctx.pairedChatId)) {
+		return { kind: "ignore", reason: "wrong_chat" };
+	}
+
+	const threadId = asString(message.message_thread_id);
+	if (threadId === undefined) return { kind: "ignore", reason: "no_topic" };
+
+	const sessionId = ctx.topicToSession(threadId);
+	if (sessionId === undefined) return { kind: "ignore", reason: "unknown_topic" };
+
+	if (typeof update.update_id !== "number") return { kind: "ignore", reason: "missing_update_id" };
+	const updateId = update.update_id;
+	if (ctx.isDuplicate(updateId)) return { kind: "duplicate", updateId };
+
+	const text = typeof message.text === "string" ? message.text.trim() : "";
+	if (!text) return { kind: "ignore", reason: "empty_text" };
+
+	const messageId = typeof message.message_id === "number" ? message.message_id : undefined;
+	return { kind: "inject", sessionId, text, updateId, threadId, messageId };
+}

package/src/notifications/threaded-render.ts

@@ -0,0 +1,155 @@
+/**
+ * Pure rendering of threaded-session frames into Telegram send specs.
+ *
+ * The daemon receives the additive `ServerMessage` frames (identity_header,
+ * context_update, turn_stream, image_attachment, config_update) over the session
+ * WS and must turn each into a Bot API call scoped to the session's forum topic
+ * (`message_thread_id`), throttled through the shared rate-limit pool. This
+ * module is the pure frame→send mapping (including the priority lane and live-
+ * edit coalesce key), so rendering is unit-testable without a live Bot API.
+ */
+
+import { truncate } from "./helpers";
+import { bold, code, escapeHtml, finalizeTelegramHtml, italic, markdownToTelegramHtml, pre } from "./html-format";
+import type { RateLimitLane } from "./rate-limit-pool";
+
+/** A Telegram send derived from a threaded frame (topic id is applied by the daemon). */
+export interface ThreadedSend {
+	method: "sendMessage" | "sendPhoto";
+	/** Rate-limit lane for prioritisation/fairness. */
+	lane: RateLimitLane;
+	/** Message text (sendMessage) or photo caption (sendPhoto). */
+	text?: string;
+	/** Base64 image bytes for sendPhoto. */
+	photoBase64?: string;
+	/** Image MIME type for sendPhoto. */
+	mime?: string;
+	/** Coalesce key for live edits (same key collapses to the latest). */
+	coalesceKey?: string;
+	/** True for the one-time identity header (the daemon pins it once). */
+	identity?: boolean;
+}
+
+interface ThreadedFrame {
+	type?: unknown;
+	sessionId?: unknown;
+	// identity_header
+	repo?: unknown;
+	branch?: unknown;
+	machine?: unknown;
+	title?: unknown;
+	// context_update
+	lastMessage?: unknown;
+	task?: unknown;
+	goal?: unknown;
+	tokenUsage?: unknown;
+	model?: unknown;
+	diff?: unknown;
+	// turn_stream
+	phase?: unknown;
+	text?: unknown;
+	messageRef?: unknown;
+	// image_attachment
+	source?: unknown;
+	data?: unknown;
+	mime?: unknown;
+	caption?: unknown;
+	// config_update
+	verbosity?: unknown;
+	redact?: unknown;
+}
+
+function str(v: unknown): string | undefined {
+	return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+/** Format the one-time identity header as pinned bullets. */
+export function formatIdentityHeader(frame: {
+	repo?: unknown;
+	branch?: unknown;
+	machine?: unknown;
+	sessionId?: unknown;
+	title?: unknown;
+}): string {
+	const title = str(frame.title) ?? "GJC session";
+	const bullets = [
+		`• repo: ${code(str(frame.repo) ?? "?")}`,
+		`• branch: ${code(str(frame.branch) ?? "?")}`,
+		`• machine: ${code(str(frame.machine) ?? "?")}`,
+		`• session: ${code(str(frame.sessionId) ?? "?")}`,
+	];
+	return `${bold(title)}\n${bullets.join("\n")}`;
+}
+
+/** Format a streamed context update into a compact block (omitting empty fields). */
+export function formatContextUpdate(frame: ThreadedFrame): string | undefined {
+	const lines: string[] = [];
+	const last = str(frame.lastMessage);
+	if (last) lines.push(escapeHtml(truncate(last, 600)));
+	const task = str(frame.task);
+	if (task) lines.push(`${italic("task:")} ${escapeHtml(task)}`);
+	const goal = str(frame.goal);
+	if (goal) lines.push(`${italic("goal:")} ${escapeHtml(goal)}`);
+	const usage = str(frame.tokenUsage);
+	const model = str(frame.model);
+	if (usage || model) lines.push(`ctx: ${code([usage, model].filter(Boolean).join(" · "))}`);
+	const diff = str(frame.diff);
+	if (diff) lines.push(`diff:\n${pre(truncate(diff, 1200))}`);
+	return lines.length ? lines.join("\n") : undefined;
+}
+
+/**
+ * Map a threaded frame to a Telegram send spec, or `undefined` when there is
+ * nothing to send (e.g. an empty context update or an unknown frame type).
+ */
+export function renderThreadedFrame(frame: ThreadedFrame): ThreadedSend | undefined {
+	switch (frame.type) {
+		case "identity_header":
+			return {
+				method: "sendMessage",
+				lane: "finalized",
+				text: finalizeTelegramHtml(formatIdentityHeader(frame)),
+				identity: true,
+			};
+		case "context_update": {
+			const text = finalizeTelegramHtml(formatContextUpdate(frame));
+			return text
+				? { method: "sendMessage", lane: "live", text, coalesceKey: `ctx:${str(frame.sessionId) ?? ""}` }
+				: undefined;
+		}
+		case "turn_stream": {
+			const raw = str(frame.text);
+			if (!raw) return undefined;
+			const text = finalizeTelegramHtml(markdownToTelegramHtml(raw));
+			const finalized = frame.phase === "finalized";
+			return {
+				method: "sendMessage",
+				lane: finalized ? "finalized" : "live",
+				text,
+				coalesceKey: finalized ? undefined : `turn:${str(frame.messageRef) ?? str(frame.sessionId) ?? ""}`,
+			};
+		}
+		case "image_attachment": {
+			const data = str(frame.data);
+			if (!data) return undefined;
+			const caption = str(frame.caption);
+			return {
+				method: "sendPhoto",
+				lane: "finalized",
+				photoBase64: data,
+				mime: str(frame.mime),
+				text: finalizeTelegramHtml(caption === undefined ? undefined : escapeHtml(caption)),
+			};
+		}
+		case "config_update": {
+			const verbosity = str(frame.verbosity);
+			const redact = typeof frame.redact === "boolean" ? `redact ${frame.redact ? "on" : "off"}` : undefined;
+			const parts = [verbosity ? `verbosity ${verbosity}` : undefined, redact].filter(Boolean);
+			return parts.length
+				? { method: "sendMessage", lane: "idle", text: finalizeTelegramHtml(`⚙ ${escapeHtml(parts.join(", "))}`) }
+				: undefined;
+		}
+		default:
+			return undefined;
+	}
+}

package/src/notifications/topic-registry.ts

@@ -0,0 +1,133 @@
+/**
+ * Per-session forum-topic registry for the threaded session surface.
+ *
+ * Each GJC session owns exactly one Telegram forum topic in the paired private
+ * DM. The topic is created once (via `createForumTopic`) and REUSED on resume,
+ * keyed by session id, so a resumed session streams back into its existing
+ * thread/history. The registry also tracks whether the one-time identity header
+ * has already been pinned, so it is sent exactly once per topic even across
+ * reconnects.
+ *
+ * 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
+ * live Bot API.
+ */
+
+/** Persisted record for one session's topic. */
+export interface TopicRecord {
+	/** Telegram forum topic id (message_thread_id). */
+	topicId: string;
+	/** Whether the one-time identity header has been sent/pinned. */
+	identitySent: boolean;
+	/** Creation timestamp (ms epoch). */
+	createdAt: number;
+	/** Last applied topic title (for rename detection). */
+	name?: string;
+}
+
+/** Serialisable shape persisted to disk. */
+export interface TopicRegistryState {
+	/** sessionId -> record. */
+	topics: Record<string, TopicRecord>;
+}
+
+export function emptyTopicRegistryState(): TopicRegistryState {
+	return { topics: {} };
+}
+
+/**
+ * In-memory registry over a serialisable state. Topic creation is injected via
+ * `getOrCreateTopic`'s `create` callback (the daemon supplies a real
+ * `createForumTopic` call); reuse-on-resume is automatic when a record exists.
+ */
+export class TopicRegistry {
+	private readonly topics: Map<string, TopicRecord>;
+	/** Maps topicId -> sessionId for fast inbound routing. */
+	private readonly byTopic = new Map<string, string>();
+	/** In-flight create promises, keyed by session, to dedupe concurrent creates. */
+	private readonly inflight = new Map<string, Promise<TopicRecord>>();
+
+	constructor(state: TopicRegistryState = emptyTopicRegistryState()) {
+		this.topics = new Map(Object.entries(state.topics ?? {}));
+		for (const [sessionId, record] of this.topics) this.byTopic.set(record.topicId, sessionId);
+	}
+
+	/** Merge a serialized state into this registry, preserving all persisted fields. */
+	load(state: TopicRegistryState): void {
+		for (const [sessionId, record] of Object.entries(state.topics ?? {})) {
+			this.topics.set(sessionId, record);
+			this.byTopic.set(record.topicId, sessionId);
+		}
+	}
+
+	/** Resolve the owning session for a topic id (for fail-closed inbound routing). */
+	sessionForTopic(topicId: string): string | undefined {
+		return this.byTopic.get(topicId);
+	}
+
+	/** The existing topic record for a session, if any. */
+	get(sessionId: string): TopicRecord | undefined {
+		return this.topics.get(sessionId);
+	}
+
+	/**
+	 * Return the existing topic for `sessionId`, or create one via `create`
+	 * (called only on first use). Reuse-on-resume: an existing record is
+	 * returned without invoking `create`.
+	 */
+	async getOrCreateTopic(
+		sessionId: string,
+		create: () => Promise<string>,
+		now: () => number = Date.now,
+	): Promise<TopicRecord> {
+		const existing = this.topics.get(sessionId);
+		if (existing) return existing;
+		// Concurrency guard: many session frames (identity/idle/turn/ask) can race
+		// to first-use the same session. Without this, each call passes the
+		// `existing` check before `create()` resolves and creates a DUPLICATE
+		// forum topic. Share a single in-flight create per session id.
+		const pending = this.inflight.get(sessionId);
+		if (pending) return pending;
+		const promise = (async () => {
+			const topicId = await create();
+			const record: TopicRecord = { topicId, identitySent: false, createdAt: now() };
+			this.topics.set(sessionId, record);
+			this.byTopic.set(topicId, sessionId);
+			return record;
+		})();
+		this.inflight.set(sessionId, promise);
+		try {
+			return await promise;
+		} finally {
+			this.inflight.delete(sessionId);
+		}
+	}
+
+	/** Mark the identity header as sent for a session. Idempotent. */
+	markIdentitySent(sessionId: string): void {
+		const record = this.topics.get(sessionId);
+		if (record) record.identitySent = true;
+	}
+
+	/** Whether the identity header still needs sending for this session. */
+	needsIdentity(sessionId: string): boolean {
+		const record = this.topics.get(sessionId);
+		return record ? !record.identitySent : true;
+	}
+
+	/**
+	 * Record the topic's applied title. Returns `true` when it changed (so the
+	 * caller should `editForumTopic`), `false` when already current or unknown.
+	 */
+	applyName(sessionId: string, name: string): boolean {
+		const record = this.topics.get(sessionId);
+		if (!record || record.name === name) return false;
+		record.name = name;
+		return true;
+	}
+
+	/** Serialise for atomic persistence beside the daemon state. */
+	serialize(): TopicRegistryState {
+		return { topics: Object.fromEntries(this.topics) };
+	}
+}