@gajae-code/coding-agent 0.13.2 → 0.14.0

package/src/sdk/bus/discord-live-provider.ts

@@ -11,6 +11,7 @@ import type {
 const API_BASE = "https://discord.com/api/v10";
 const GATEWAY_INTENTS = 1 + 512 + 32_768;
 const MAX_RATE_LIMIT_RETRIES = 2;
+const REST_REQUEST_TIMEOUT_MS = 5_000;
 const NONCE_PREFIX = "<!-- gjc-thread-nonce:";
 const INVALID_SESSION_RECONNECT_DELAY_MS = 1_000;
 const TERMINAL_GATEWAY_CLOSE_CODES: ReadonlySet<number> = new Set([4_004, 4_010, 4_011, 4_012, 4_013, 4_014]);
@@ -42,6 +43,22 @@ export interface DiscordLiveProviderOptions {
 }
 
 type JsonRecord = Record<string, unknown>;
+type DiscordRequestContext = {
+	deadline: number;
+	controller: AbortController;
+	signal: AbortSignal;
+	timeoutError: Error;
+	timeout: NodeJS.Timeout;
+};
+
+function discordRequestTimeoutError(): Error {
+	return new Error("Discord API request timed out");
+}
+
+function discordAbortError(signal: AbortSignal): Error {
+	const reason = signal.reason;
+	return reason instanceof Error ? reason : new Error("Discord API request aborted");
+}
 
 /** Discord REST/Gateway implementation. The only credential is held privately and is never emitted. */
 export class DiscordLiveProvider implements DiscordProvider, DiscordDiagnosticProvider {
@@ -112,33 +129,47 @@ export class DiscordLiveProvider implements DiscordProvider, DiscordDiagnosticPr
 		name: string;
 		nonce: string;
 	}): Promise<DiscordThread> {
-		const marker = `${NONCE_PREFIX}${input.nonce}${NONCE_SUFFIX}`;
-		const starter = await this.#findStarterMessage(input.parentId, marker);
-		if (starter?.thread) {
-			const existing = this.#starterThread(starter.thread, input.guildId, input.parentId);
-			if (!existing) throw new Error("Discord returned an invalid starter-message thread");
-			return existing;
-		}
-		const messageId = starter?.id ?? (await this.#createStarterMessage(input.parentId, marker));
-		const body = await this.#request(`/channels/${input.parentId}/messages/${messageId}/threads`, {
-			method: "POST",
-			body: JSON.stringify({ name: input.name, auto_archive_duration: 1_440 }),
+		return await this.#withRequestContext(undefined, async context => {
+			const marker = `${NONCE_PREFIX}${input.nonce}${NONCE_SUFFIX}`;
+			const starter = await this.#findStarterMessage(input.parentId, marker, context);
+			if (starter?.thread) {
+				const existing = this.#starterThread(starter.thread, input.guildId, input.parentId);
+				if (!existing) throw new Error("Discord returned an invalid starter-message thread");
+				return existing;
+			}
+			const messageId = starter?.id ?? (await this.#createStarterMessage(input.parentId, marker, context));
+			const body = await this.#request(
+				`/channels/${input.parentId}/messages/${messageId}/threads`,
+				{
+					method: "POST",
+					body: JSON.stringify({ name: input.name, auto_archive_duration: 1_440 }),
+				},
+				context,
+			);
+			return this.#thread(body, input.guildId, input.parentId);
 		});
-		return this.#thread(body, input.guildId, input.parentId);
 	}
 
-	async #createStarterMessage(parentId: string, marker: string): Promise<string> {
-		const message = await this.#request(`/channels/${parentId}/messages`, {
-			method: "POST",
-			body: JSON.stringify({ content: marker }),
-		});
+	async #createStarterMessage(parentId: string, marker: string, context: DiscordRequestContext): Promise<string> {
+		const message = await this.#request(
+			`/channels/${parentId}/messages`,
+			{
+				method: "POST",
+				body: JSON.stringify({ content: marker }),
+			},
+			context,
+		);
 		const id = this.#string(message, "id");
 		if (!id) throw new Error("Discord returned an invalid starter-message response");
 		return id;
 	}
 
-	async #findStarterMessage(parentId: string, marker: string): Promise<{ id: string; thread?: unknown } | undefined> {
-		const messages = await this.#request(`/channels/${parentId}/messages?limit=100`);
+	async #findStarterMessage(
+		parentId: string,
+		marker: string,
+		context: DiscordRequestContext,
+	): Promise<{ id: string; thread?: unknown } | undefined> {
+		const messages = await this.#request(`/channels/${parentId}/messages?limit=100`, {}, context);
 		if (!Array.isArray(messages)) return undefined;
 		for (const message of messages) {
 			if (!this.#messageContent(message).includes(marker)) continue;
@@ -153,21 +184,23 @@ export class DiscordLiveProvider implements DiscordProvider, DiscordDiagnosticPr
 	}
 
 	async findThreadByNonce(input: { guildId: string; parentId: string; nonce: string }): Promise<DiscordThread | null> {
-		const marker = `${NONCE_PREFIX}${input.nonce}${NONCE_SUFFIX}`;
-		const parentMessages = await this.#request(`/channels/${input.parentId}/messages?limit=100`);
-		if (Array.isArray(parentMessages))
-			for (const message of parentMessages) {
-				if (!this.#messageContent(message).includes(marker)) continue;
-				const thread = this.#starterThread(this.#record(message).thread, input.guildId, input.parentId);
-				if (thread) return thread;
+		return await this.#withRequestContext(undefined, async context => {
+			const marker = `${NONCE_PREFIX}${input.nonce}${NONCE_SUFFIX}`;
+			const parentMessages = await this.#request(`/channels/${input.parentId}/messages?limit=100`, {}, context);
+			if (Array.isArray(parentMessages))
+				for (const message of parentMessages) {
+					if (!this.#messageContent(message).includes(marker)) continue;
+					const thread = this.#starterThread(this.#record(message).thread, input.guildId, input.parentId);
+					if (thread) return thread;
+				}
+			const candidates = await this.#listThreads(input.guildId, input.parentId, context);
+			for (const candidate of candidates) {
+				const messages = await this.#request(`/channels/${candidate.id}/messages?limit=25`, {}, context);
+				if (Array.isArray(messages) && messages.some(message => this.#messageContent(message).includes(marker)))
+					return candidate;
 			}
-		const candidates = await this.#listThreads(input.guildId, input.parentId);
-		for (const candidate of candidates) {
-			const messages = await this.#request(`/channels/${candidate.id}/messages?limit=25`);
-			if (Array.isArray(messages) && messages.some(message => this.#messageContent(message).includes(marker)))
-				return candidate;
-		}
-		return null;
+			return null;
+		});
 	}
 
 	async postMessage(input: {
@@ -242,15 +275,17 @@ export class DiscordLiveProvider implements DiscordProvider, DiscordDiagnosticPr
 	async probeConfiguration(signal?: AbortSignal): Promise<DiscordConfigurationProbeResult> {
 		if (signal?.aborted) return { ok: false, detail: "Discord configuration probe cancelled." };
 		try {
-			const currentUser = await this.#request("/users/@me", { signal });
-			const botUserId = this.#string(currentUser, "id");
-			if (!botUserId) return { ok: false, detail: "Discord returned an invalid bot identity." };
-			const application = await this.#request("/applications/@me", { signal });
-			const applicationId = this.#string(application, "id");
-			if (!applicationId || applicationId !== this.applicationId) {
-				return { ok: false, detail: "Discord application identity does not match the configured application ID." };
-			}
-			return { ok: true, detail: "Discord bot and application credentials are valid.", botUserId };
+			return await this.#withRequestContext(signal, async context => {
+				const currentUser = await this.#request("/users/@me", {}, context);
+				const botUserId = this.#string(currentUser, "id");
+				if (!botUserId) throw new Error("Discord returned an invalid bot identity.");
+				const application = await this.#request("/applications/@me", {}, context);
+				const applicationId = this.#string(application, "id");
+				if (!applicationId || applicationId !== this.applicationId) {
+					throw new Error("Discord application identity does not match the configured application ID.");
+				}
+				return { ok: true, detail: "Discord bot and application credentials are valid.", botUserId };
+			});
 		} catch (error) {
 			if (signal?.aborted) return { ok: false, detail: "Discord configuration probe cancelled." };
 			const detail = error instanceof Error ? error.message : "Discord configuration probe failed.";
@@ -265,20 +300,25 @@ export class DiscordLiveProvider implements DiscordProvider, DiscordDiagnosticPr
 	}): Promise<DiscordOneShotTestResult> {
 		if (input.signal?.aborted) return { ok: false, detail: "Discord notification test cancelled." };
 		try {
-			const response = await this.#request(`/channels/${input.channelId}/messages`, {
-				method: "POST",
-				body: JSON.stringify({ content: input.message }),
-				signal: input.signal,
+			return await this.#withRequestContext(input.signal, async context => {
+				const response = await this.#request(
+					`/channels/${input.channelId}/messages`,
+					{
+						method: "POST",
+						body: JSON.stringify({ content: input.message }),
+					},
+					context,
+				);
+				const messageId = this.#string(response, "id");
+				if (!messageId) {
+					return {
+						ok: false,
+						detail: "Discord may have accepted the message but returned no message receipt.",
+						uncertain: true,
+					};
+				}
+				return { ok: true, detail: "Discord notification test delivered.", messageId };
 			});
-			const messageId = this.#string(response, "id");
-			if (!messageId) {
-				return {
-					ok: false,
-					detail: "Discord may have accepted the message but returned no message receipt.",
-					uncertain: true,
-				};
-			}
-			return { ok: true, detail: "Discord notification test delivered.", messageId };
 		} catch (error) {
 			if (input.signal?.aborted) return { ok: false, detail: "Discord notification test cancelled." };
 			const detail = error instanceof Error ? error.message : "Discord notification test failed.";
@@ -291,15 +331,17 @@ export class DiscordLiveProvider implements DiscordProvider, DiscordDiagnosticPr
 		this.#onEvent = onEvent;
 		this.#stopped = false;
 		try {
-			const me = await this.#request("/users/@me");
-			const id = this.#string(me, "id");
-			if (!id) throw new Error("Discord returned an invalid current-user response");
-			this.#botUserId = id;
-			const gateway = await this.#request("/gateway/bot");
-			const url = this.#string(gateway, "url");
-			if (!url) throw new Error("Discord returned an invalid gateway response");
-			this.#gatewayUrl = url;
-			this.#connect(url);
+			await this.#withRequestContext(undefined, async context => {
+				const me = await this.#request("/users/@me", {}, context);
+				const id = this.#string(me, "id");
+				if (!id) throw new Error("Discord returned an invalid current-user response");
+				this.#botUserId = id;
+				const gateway = await this.#request("/gateway/bot", {}, context);
+				const url = this.#string(gateway, "url");
+				if (!url) throw new Error("Discord returned an invalid gateway response");
+				this.#gatewayUrl = url;
+				this.#connect(url);
+			});
 		} catch (error) {
 			await this.stop();
 			throw error;
@@ -462,16 +504,18 @@ export class DiscordLiveProvider implements DiscordProvider, DiscordDiagnosticPr
 		);
 	}
 
-	async #listThreads(guildId: string, parentId: string): Promise<DiscordThread[]> {
+	async #listThreads(guildId: string, parentId: string, context: DiscordRequestContext): Promise<DiscordThread[]> {
 		const result: DiscordThread[] = [];
-		const active = this.#record(await this.#request(`/guilds/${guildId}/threads/active`));
+		const active = this.#record(await this.#request(`/guilds/${guildId}/threads/active`, {}, context));
 		const activeThreads = active.threads;
 		if (Array.isArray(activeThreads))
 			for (const thread of activeThreads) {
 				const parsed = this.#threadOrUndefined(thread, guildId, parentId);
 				if (parsed) result.push(parsed);
 			}
-		const archived = this.#record(await this.#request(`/channels/${parentId}/threads/archived/public?limit=100`));
+		const archived = this.#record(
+			await this.#request(`/channels/${parentId}/threads/archived/public?limit=100`, {}, context),
+		);
 		const archivedThreads = archived.threads;
 		if (Array.isArray(archivedThreads))
 			for (const thread of archivedThreads) {
@@ -481,29 +525,112 @@ export class DiscordLiveProvider implements DiscordProvider, DiscordDiagnosticPr
 		return result;
 	}
 
-	async #request(path: string, init: RequestInit = {}): Promise<unknown> {
-		return await this.#requestWithHeaders(
-			path,
-			{ Authorization: `Bot ${this.#token}`, "Content-Type": "application/json" },
-			init,
+	async #withRequestContext<T>(
+		callerSignal: AbortSignal | undefined,
+		run: (context: DiscordRequestContext) => Promise<T>,
+	): Promise<T> {
+		const controller = new AbortController();
+		const timeoutError = discordRequestTimeoutError();
+		const deadline = this.#now() + REST_REQUEST_TIMEOUT_MS;
+		const signal = callerSignal ? AbortSignal.any([callerSignal, controller.signal]) : controller.signal;
+		const timeout = setTimeout(() => controller.abort(timeoutError), REST_REQUEST_TIMEOUT_MS);
+		const context: DiscordRequestContext = {
+			deadline,
+			controller,
+			signal,
+			timeoutError,
+			timeout,
+		};
+		try {
+			return await run(context);
+		} finally {
+			clearTimeout(timeout);
+		}
+	}
+
+	async #request(path: string, init: RequestInit = {}, context?: DiscordRequestContext): Promise<unknown> {
+		if (context) {
+			return await this.#requestWithHeaders(
+				path,
+				{ Authorization: `Bot ${this.#token}`, "Content-Type": "application/json" },
+				init,
+				context,
+			);
+		}
+		return await this.#withRequestContext(init.signal ?? undefined, requestContext =>
+			this.#requestWithHeaders(
+				path,
+				{ Authorization: `Bot ${this.#token}`, "Content-Type": "application/json" },
+				init,
+				requestContext,
+			),
 		);
 	}
-	async #interactionRequest(path: string, init: RequestInit = {}): Promise<unknown> {
-		return await this.#requestWithHeaders(path, { "Content-Type": "application/json" }, init);
+	async #interactionRequest(path: string, init: RequestInit = {}, context?: DiscordRequestContext): Promise<unknown> {
+		if (context) return await this.#requestWithHeaders(path, { "Content-Type": "application/json" }, init, context);
+		return await this.#withRequestContext(init.signal ?? undefined, requestContext =>
+			this.#requestWithHeaders(path, { "Content-Type": "application/json" }, init, requestContext),
+		);
 	}
-	async #requestWithHeaders(path: string, headers: Record<string, string>, init: RequestInit): Promise<unknown> {
+	async #requestWithHeaders(
+		path: string,
+		headers: Record<string, string>,
+		init: RequestInit,
+		context: DiscordRequestContext,
+	): Promise<unknown> {
 		for (let attempt = 0; ; attempt++) {
+			this.#assertRequestDeadline(context);
 			const mergedHeaders = new Headers(headers);
 			for (const [key, value] of new Headers(init.headers)) mergedHeaders.set(key, value);
-			const response = await this.#fetch(`${this.#apiBaseUrl}${path}`, { ...init, headers: mergedHeaders });
+			const response = await this.#requestPhase(
+				() =>
+					this.#fetch(`${this.#apiBaseUrl}${path}`, { ...init, headers: mergedHeaders, signal: context.signal }),
+				context,
+			);
 			if (response.status !== 429) {
 				if (!response.ok) throw new Error(`Discord API request failed (${response.status})`);
-				return response.status === 204 ? undefined : await response.json();
+				return response.status === 204 ? undefined : await this.#responseJson(response, context);
 			}
 			if (attempt >= MAX_RATE_LIMIT_RETRIES) throw new Error("Discord API rate limit retry exhausted");
-			const limited = this.#record(await response.json());
+			const limited = this.#record(await this.#responseJson(response, context));
 			const seconds = this.#number(limited, "retry_after") ?? 1;
-			await this.#sleep(Math.max(0, seconds * 1_000));
+			this.#assertRequestDeadline(context);
+			const retryRemaining = context.deadline - this.#now();
+			await this.#requestPhase(() => this.#sleep(Math.min(Math.max(0, seconds * 1_000), retryRemaining)), context);
+		}
+	}
+
+	async #responseJson(response: Response, context: DiscordRequestContext): Promise<unknown> {
+		return await this.#requestPhase(() => response.json(), context);
+	}
+
+	async #requestPhase<T>(phase: () => Promise<T> | T, context: DiscordRequestContext): Promise<T> {
+		this.#assertRequestDeadline(context);
+		const aborted = Promise.withResolvers<never>();
+		const onAbort = () => aborted.reject(discordAbortError(context.signal));
+		context.signal.addEventListener("abort", onAbort, { once: true });
+		if (context.signal.aborted) onAbort();
+		try {
+			const value = await Promise.race([Promise.resolve().then(phase), aborted.promise]);
+			this.#assertRequestDeadline(context);
+			return value as T;
+		} catch (error) {
+			if (context.controller.signal.aborted || this.#now() >= context.deadline) {
+				if (!context.controller.signal.aborted) context.controller.abort(context.timeoutError);
+				throw context.timeoutError;
+			}
+			throw error;
+		} finally {
+			context.signal.removeEventListener("abort", onAbort);
+		}
+	}
+
+	#assertRequestDeadline(context: DiscordRequestContext): void {
+		if (context.controller.signal.aborted) throw context.timeoutError;
+		if (context.signal.aborted) throw discordAbortError(context.signal);
+		if (this.#now() >= context.deadline) {
+			context.controller.abort(context.timeoutError);
+			throw context.timeoutError;
 		}
 	}
 

package/src/sdk/bus/existing-thread-readiness.ts

@@ -4,29 +4,17 @@
  * Stock startup publishes a session's readiness immediately, so the running
  * chat daemon surfaces the session and creates its own root before an operator
  * could ever name an existing one. A session that opts in is *prepared*
- * instead: its id, endpoint, and broker registration are discoverable authority
- * while readiness stays withheld, which leaves exactly one root claim for
- * `gjc notify bind-thread` to fill. Activation then publishes readiness once,
- * and the daemon adopts the bound root instead of replacing it.
+ * instead: readiness stays withheld while the provider applies its one root
+ * claim. The SessionRouter owns endpoint authority and activation; this module
+ * only proves that the provider mapping authorizes readiness publication.
  *
  * Nothing here mutates a mapping. The gate only reads the daemon-owned store to
- * prove a binding exists, and the activation client only asks the session's own
- * host to publish the readiness it withheld.
+ * prove a binding exists for the exact session and endpoint generation.
  */
 
-import type { SessionIndex } from "../broker/session-index";
-import { SdkClient } from "../client/client";
-import type { SdkSessionEndpoint, SdkSessionEndpointScope } from "../client/discovery";
 import type { SessionActivationGate } from "../host";
-import {
-	type ActivatedPreparedSession,
-	type PreparedSessionActivationClient,
-	requestPreparedSessionActivation,
-	SessionActivationError,
-} from "../session-activation";
 import type { ConversationStore } from "./conversation-store";
 import type { SlackConversation } from "./slack-conversation";
-import { resolveSessionBindingAuthority } from "./slack-thread-binding";
 
 /** Explicit, session-scoped opt-in for withholding readiness until a root is bound. */
 export const EXISTING_THREAD_BIND_ENV = "GJC_NOTIFY_BIND_EXISTING_THREAD";
@@ -72,84 +60,3 @@ export function createSlackBindingActivationGate(input: SlackBindingActivationIn
 		);
 	};
 }
-
-export type {
-	ActivatedPreparedSession,
-	PreparedSessionActivationClient,
-	SessionActivationErrorCode,
-} from "../session-activation";
-export { requestPreparedSessionActivation, SessionActivationError } from "../session-activation";
-
-export interface PreparedSessionActivationInput {
-	sessionIndex: SessionIndex;
-	sessionId: string;
-}
-
-export interface PreparedSessionActivationDeps {
-	readEndpoint?: (
-		repo: string,
-		sessionId: string,
-		scope?: SdkSessionEndpointScope,
-	) => Promise<SdkSessionEndpoint | null>;
-	connect?: (endpoint: { url: string; token: string }) => Promise<PreparedSessionActivationClient>;
-}
-
-/**
- * Ask a prepared session to publish the readiness it withheld.
- *
- * The same discovery authority the binding requires is resolved first, so an
- * unindexed, terminated, or endpoint-rolled session is refused before any
- * connection is opened. The request names the exact session and endpoint
- * generation, and the answer is accepted only when it proves both, so a
- * replacement session can never be activated in place of the requested one.
- * Activation is idempotent: an exact retry answers `already` without a second
- * readiness signal.
- */
-export async function activatePreparedSession(
-	input: PreparedSessionActivationInput,
-	deps: PreparedSessionActivationDeps = {},
-): Promise<ActivatedPreparedSession> {
-	const authority = await resolveSessionBindingAuthority({
-		sessionIndex: input.sessionIndex,
-		sessionId: input.sessionId,
-		...(deps.readEndpoint ? { readEndpoint: deps.readEndpoint } : {}),
-	});
-	if (!authority)
-		throw new SessionActivationError(
-			"session_not_live",
-			"Session activation requires an exact live session endpoint.",
-		);
-	// Deliberately not a second discovery read. The authority proof is bound to
-	// one endpoint file, verified by pid and mtime at one scope; re-resolving here
-	// could connect to a replacement process whose endpoint generation repeats,
-	// and the generation carried below could not tell the two apart.
-	const endpoint = authority.endpoint;
-	if (!endpoint.url || !endpoint.token)
-		throw new SessionActivationError(
-			"session_not_live",
-			"Session activation requires a readable session discovery endpoint.",
-		);
-	let client: PreparedSessionActivationClient;
-	try {
-		client = await (deps.connect ?? defaultActivationClient)({ url: endpoint.url, token: endpoint.token });
-	} catch {
-		// Nothing was ever sent, so no activation can have been applied.
-		throw new SessionActivationError("activation_unavailable", "The session endpoint could not be reached.");
-	}
-	try {
-		return await requestPreparedSessionActivation(client, input.sessionId, authority.endpointGeneration);
-	} finally {
-		await client.close().catch(() => undefined);
-	}
-}
-
-async function defaultActivationClient(endpoint: {
-	url: string;
-	token: string;
-}): Promise<PreparedSessionActivationClient> {
-	const client = await SdkClient.connect(endpoint.url, endpoint.token, { reconnectAttempts: 0 });
-	return {
-		request: async frame => (await client.request(frame)) as Record<string, unknown>,
-		close: async () => await client.close(),
-	};
-}

package/src/sdk/bus/inbound-reaction-ordering.ts

@@ -0,0 +1,122 @@
+/**
+ * Pure per-update inbound reaction transition ordering.
+ *
+ * Extracted from the Telegram daemon so the serialization and terminal-state
+ * contract is testable without daemon/attachment/topic-lease infrastructure.
+ * The production router dispatches notification frames without awaiting prior
+ * callbacks, so an `accepted` handler can still be in flight when the
+ * `consumed` handler runs. Chaining every transition for one update through a
+ * single promise keeps effects ordered, and skipping nonterminal transitions
+ * after a terminal one makes the terminal state monotonic: a late queued
+ * marker can never overwrite an already-sent consumed marker or retraction.
+ */
+
+/** A single ordered Bot API reaction transition for one update id. */
+export interface InboundReactionTransition {
+	/** Serialized in submission order per update id. */
+	readonly effect: () => Promise<void>;
+	/** Terminal transitions (consumed / retraction) close the update. */
+	readonly terminal: boolean;
+}
+
+/**
+ * Terminal tombstones are retained only for a bounded window of recent update
+ * ids. Telegram update ids are monotonically increasing per bot, so a stale
+ * `accepted` ack that could overwrite a terminal state always carries an id at
+ * or below the terminal one; ids far below the window are long-expired updates
+ * whose correction target no longer exists, so the daemon's own target lookup
+ * already ignores them.
+ */
+export const INBOUND_REACTION_TOMBSTONE_WINDOW = 512;
+
+export class InboundReactionSequencer {
+	/** Update ids whose reaction reached a terminal (consumed/retracted) state. */
+	readonly #terminal = new Map<number, true>();
+	/** Per-update serialization chain, deleted once settled. */
+	readonly #chains = new Map<number, Promise<void>>();
+
+	/** True once a terminal transition completed for this update. */
+	isTerminal(updateId: number): boolean {
+		return this.#terminal.has(updateId);
+	}
+
+	/**
+	 * Enqueue one transition. The returned promise settles when the transition
+	 * has run (or was skipped because a terminal state already closed it).
+	 */
+	apply(updateId: number, transition: InboundReactionTransition): Promise<void> {
+		const run = async (): Promise<void> => {
+			if (this.#terminal.has(updateId)) return;
+			await transition.effect();
+			if (transition.terminal) {
+				this.#terminal.set(updateId, true);
+				this.#evictStaleTombstones(updateId);
+			}
+		};
+		const prior = this.#chains.get(updateId) ?? Promise.resolve();
+		const next = prior.then(run, run);
+		// The chain is retained only while unsettled work exists for the update;
+		// once settled it is deleted so the map cannot grow without bound. The
+		// stored tail never rejects (both arms handle) so an unawaited chain can
+		// never surface an unhandled rejection.
+		const settled = next.then(
+			() => this.#chains.delete(updateId),
+			() => this.#chains.delete(updateId),
+		);
+		this.#chains.set(
+			updateId,
+			settled.then(() => undefined),
+		);
+		return next;
+	}
+
+	/** @internal Test-only: number of retained per-update chains. */
+	debugChainCount(): number {
+		return this.#chains.size;
+	}
+
+	/** @internal Test-only: number of retained terminal tombstones. */
+	debugTombstoneCount(): number {
+		return this.#terminal.size;
+	}
+
+	/** Keep only recent terminal tombstones relative to the newest terminal id. */
+	#evictStaleTombstones(newestTerminalId: number): void {
+		// Distance-based, not count-based: any terminal id further than the
+		// retention window below the newest terminal id is evicted regardless of
+		// how many tombstones are currently retained, so the map stays bounded by
+		// the window while near-term tombstones always survive.
+		for (const updateId of this.#terminal.keys()) {
+			if (newestTerminalId - updateId >= INBOUND_REACTION_TOMBSTONE_WINDOW) this.#terminal.delete(updateId);
+		}
+	}
+}
+
+/** Body for setting an emoji reaction on an inbound Telegram message. */
+export function inboundReactionSetPayload(
+	chatId: string,
+	messageId: number,
+	emoji: string,
+): {
+	chat_id: string;
+	message_id: number;
+	reaction: Array<{ type: "emoji"; emoji: string }>;
+} {
+	return { chat_id: chatId, message_id: messageId, reaction: [{ type: "emoji", emoji }] };
+}
+
+/**
+ * Body for retracting a reaction. The Bot API clears a bot reaction with the
+ * empty reaction list; an empty `emoji` string is not a valid reaction and is
+ * silently rejected, leaving the stale queued marker visible.
+ */
+export function inboundReactionRetractPayload(
+	chatId: string,
+	messageId: number,
+): {
+	chat_id: string;
+	message_id: number;
+	reaction: [];
+} {
+	return { chat_id: chatId, message_id: messageId, reaction: [] };
+}