switchroom 0.5.0

package/telegram-plugin/shared/bot-runtime.ts

@@ -0,0 +1,324 @@
+/**
+ * Shared bot runtime helpers — extracted from gateway.ts so both the
+ * per-agent gateway and the foreman bot can share the same core plumbing
+ * without duplicating code.
+ *
+ * What lives here:
+ *   - `createRobustApiCall` — thin re-export of createRetryApiCall pre-wired
+ *     with stderr logging (mirrors how gateway.ts constructs `robustApiCall`).
+ *   - `makeSwitchroomExec` / `makeSwitchroomExecCombined` — factory fns for
+ *     the switchroom CLI exec helpers (callers pass their own CLI path / config
+ *     env so each process can be configured independently).
+ *   - `escapeHtmlForTg`, `preBlock`, `stripAnsi`, `formatSwitchroomOutput` —
+ *     pure text-formatting helpers used by both gateways.
+ *   - `makeSwitchroomReply` — factory that returns a `switchroomReply`-like
+ *     function bound to a thread-resolver; gateway keeps its own resolver.
+ *   - `runPollingLoop` — thin wrapper around the grammyjs/runner `run()` call
+ *     with built-in 409 retry logic, matching the loop in gateway.ts.
+ *
+ * IMPORTANT: This module MUST NOT import anything from gateway.ts — the
+ * dependency is the other way around. Only import from grammy, node builtins,
+ * or other telegram-plugin/shared or telegram-plugin/*.ts modules.
+ */
+
+import { GrammyError, type Bot, type Context } from 'grammy'
+import { run, type RunnerHandle } from '@grammyjs/runner'
+import { execFileSync, spawnSync } from 'child_process'
+import { createHash } from 'crypto'
+import { clearStaleTelegramPollingState } from '../startup-reset.js'
+import { createRetryApiCall } from '../retry-api-call.js'
+
+// ─── tg-post observability transformer ────────────────────────────────────
+
+/**
+ * Installs an API transformer on the bot that emits one stderr line per
+ * outbound Telegram Bot API POST. This is the single catchment point for
+ * correlating user-visible duplicate-message reports (switchroom #656,
+ * #657) against the actual outbound calls — the transformer runs inside
+ * grammY immediately before each HTTP POST and again on the response, so
+ * it sees every call regardless of whether it was routed through the
+ * `robustApiCall` retry helper or made directly via `bot.api.*`.
+ *
+ * Log shape (one line per POST, on both success and failure):
+ *
+ *   tg-post method=<m> chat=<id> thread=<id|-> parse_mode=<HTML|MarkdownV2|none> bytes=<n> hash=<sha1-12> status=<ok|err> err=<class-or--> code=<http-or--> desc=<short|-->
+ *
+ * Body content is never logged — only its length and a 12-char sha1 prefix
+ * so we can recognise repeated identical sends without leaking PII. The
+ * `code` field carries the Telegram error_code (400/403/429/etc.) on
+ * failure and the short `desc` is the first ~80 chars of the API
+ * description — together these let us correlate "duplicate message"
+ * reports with the precise rejection reason (issue #657).
+ *
+ * Pure observability: no behaviour change, no error swallowing, no retry
+ * effects. The transformer always re-throws after logging.
+ */
+export function installTgPostLogger(bot: Bot): void {
+  bot.api.config.use(async (prev, method, payload, signal) => {
+    const p = (payload ?? {}) as Record<string, unknown>
+    const chat = p.chat_id != null ? String(p.chat_id) : '-'
+    const thread = p.message_thread_id != null ? String(p.message_thread_id) : '-'
+    const parseMode = (p.parse_mode as string | undefined) ?? 'none'
+    const text = typeof p.text === 'string' ? p.text : ''
+    const bytes = text.length
+    const hash = bytes > 0
+      ? createHash('sha1').update(text).digest('hex').slice(0, 12)
+      : '-'
+    try {
+      const res = await prev(method, payload, signal)
+      process.stderr.write(
+        `tg-post method=${method} chat=${chat} thread=${thread} parse_mode=${parseMode} bytes=${bytes} hash=${hash} status=ok err=- code=- desc=-\n`,
+      )
+      return res
+    } catch (err) {
+      const errClass = err instanceof GrammyError
+        ? `grammy_${(err as GrammyError).error_code}`
+        : (err as { constructor?: { name?: string } } | null)?.constructor?.name ?? 'Error'
+      const code = err instanceof GrammyError ? String((err as GrammyError).error_code) : '-'
+      const rawDesc = err instanceof GrammyError
+        ? (err as GrammyError).description
+        : (err instanceof Error ? err.message : '')
+      // Sanitise the description for single-line log output — collapse
+      // whitespace, strip newlines, cap at 80 chars. PII-safe: Telegram
+      // error descriptions are server-generated and don't echo body.
+      const desc = rawDesc
+        ? rawDesc.replace(/\s+/g, ' ').slice(0, 80).replace(/[\r\n]/g, ' ') || '-'
+        : '-'
+      process.stderr.write(
+        `tg-post method=${method} chat=${chat} thread=${thread} parse_mode=${parseMode} bytes=${bytes} hash=${hash} status=err err=${errClass} code=${code} desc=${desc}\n`,
+      )
+      throw err
+    }
+  })
+}
+
+// ─── robustApiCall factory ────────────────────────────────────────────────
+
+/**
+ * Creates a robust API call wrapper pre-wired with stderr logging.
+ * This is exactly how gateway.ts constructs its `robustApiCall`.
+ *
+ * Usage:
+ *   const robustApiCall = createRobustApiCall()
+ */
+export function createRobustApiCall() {
+  return createRetryApiCall({
+    log: (line) => process.stderr.write(line),
+  })
+}
+
+// ─── HTML escape helpers ─────────────────────────────────────────────────
+
+export function escapeHtmlForTg(text: string): string {
+  return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+export function preBlock(text: string): string {
+  return '<pre>' + escapeHtmlForTg(text) + '</pre>'
+}
+
+export function stripAnsi(text: string): string {
+  return text.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '')
+}
+
+export function formatSwitchroomOutput(output: string, maxLen = 4000): string {
+  const trimmed = output.trim()
+  if (trimmed.length <= maxLen) return trimmed
+  return trimmed.slice(0, maxLen - 20) + '\n... (truncated)'
+}
+
+// ─── CLI exec factories ───────────────────────────────────────────────────
+
+export interface CliConfig {
+  /** Path to the switchroom CLI binary. Defaults to 'switchroom'. */
+  cliPath?: string
+  /** Optional --config path forwarded to every CLI invocation. */
+  configPath?: string
+}
+
+/** Returns a function that calls the CLI and returns stdout. */
+export function makeSwitchroomExec(cfg: CliConfig = {}) {
+  const cli = cfg.cliPath ?? process.env.SWITCHROOM_CLI_PATH ?? 'switchroom'
+  const config = cfg.configPath ?? process.env.SWITCHROOM_CONFIG
+
+  return function switchroomExec(args: string[], timeoutMs = 15000): string {
+    const fullArgs = config ? ['--config', config, ...args] : args
+    return execFileSync(cli, fullArgs, {
+      encoding: 'utf-8',
+      timeout: timeoutMs,
+      env: { ...process.env, FORCE_COLOR: '0', NO_COLOR: '1' },
+      maxBuffer: 4 * 1024 * 1024,
+    })
+  }
+}
+
+/** Returns a function that calls the CLI with stderr merged into stdout. */
+export function makeSwitchroomExecCombined(cfg: CliConfig = {}) {
+  const cli = cfg.cliPath ?? process.env.SWITCHROOM_CLI_PATH ?? 'switchroom'
+  const config = cfg.configPath ?? process.env.SWITCHROOM_CONFIG
+
+  // Pre-#28 fix this used `execSync(\`${quoted} 2>&1\`, { shell: '/bin/bash' })`,
+  // hand-quoting each argument. The shell-quoting was correct today, but the
+  // structural shape meant any future caller passing user-controlled input
+  // would re-introduce a command-injection class of bug. spawnSync with
+  // argv array eliminates the shell entirely; we then concat stdout + stderr
+  // ourselves to preserve the merged-output contract callers depend on.
+  return function switchroomExecCombined(args: string[], timeoutMs = 15000): string {
+    const fullArgs = config ? ['--config', config, ...args] : args
+    const result = spawnSync(cli, fullArgs, {
+      encoding: 'utf-8',
+      timeout: timeoutMs,
+      env: { ...process.env, FORCE_COLOR: '0', NO_COLOR: '1' },
+      maxBuffer: 4 * 1024 * 1024,
+    })
+    const stdout = (result.stdout as string | undefined) ?? ''
+    const stderr = (result.stderr as string | undefined) ?? ''
+    const merged = stderr.length > 0 ? stdout + stderr : stdout
+    if (result.error) throw result.error
+    if (result.status !== 0) {
+      // Mirror execSync's behaviour: throw on non-zero exit, attaching the
+      // merged output so callers (which catch and inspect .stdout) can read it.
+      const err = new Error(`Command failed: ${cli} ${fullArgs.join(' ')}`) as Error & {
+        stdout?: string
+        stderr?: string
+        status?: number | null
+      }
+      err.stdout = merged
+      err.stderr = stderr
+      err.status = result.status
+      throw err
+    }
+    return merged
+  }
+}
+
+/** Returns a CLI exec wrapper that parses JSON output (--json flag). */
+export function makeSwitchroomExecJson(cfg: CliConfig = {}) {
+  const exec = makeSwitchroomExec(cfg)
+  return function switchroomExecJson<T = unknown>(args: string[]): T | null {
+    try {
+      const output = exec([...args, '--json'])
+      return JSON.parse(output) as T
+    } catch {
+      return null
+    }
+  }
+}
+
+// ─── Reply helper factory ─────────────────────────────────────────────────
+
+import { InlineKeyboard } from 'grammy'
+
+export type SwitchroomReplyMarkup =
+  | InlineKeyboard
+  | { force_reply: true; input_field_placeholder?: string; selective?: boolean }
+
+/**
+ * Creates a `switchroomReply` function that sends an HTML reply to the
+ * chat in `ctx`, optionally threaded.
+ *
+ * @param resolveThreadId - returns the thread ID to use for the given
+ *   chat_id + optional explicit thread (mirrors gateway's resolveThreadId).
+ *   Pass `() => undefined` for bots that don't use forum topics.
+ */
+export function makeSwitchroomReply(
+  resolveThreadId: (chatId: string, explicit?: number | null) => number | undefined,
+) {
+  return async function switchroomReply(
+    ctx: Context,
+    text: string,
+    options: { html?: boolean; reply_markup?: SwitchroomReplyMarkup } = {},
+  ): Promise<void> {
+    const chatId = String(ctx.chat!.id)
+    const threadId = resolveThreadId(chatId, ctx.message?.message_thread_id)
+    await ctx.reply(text, {
+      ...(threadId != null ? { message_thread_id: threadId } : {}),
+      ...(options.html ? { parse_mode: 'HTML' as const, link_preview_options: { is_disabled: true } } : {}),
+      ...(options.reply_markup ? { reply_markup: options.reply_markup } : {}),
+    })
+  }
+}
+
+// ─── Polling loop ─────────────────────────────────────────────────────────
+
+export interface PollingLoopCallbacks {
+  /** Fired once after `getMe()` on the first (non-409) attempt. */
+  onReady?: (botUsername: string, botId: number) => void | Promise<void>
+  /**
+   * Fired exactly once per process lifetime (not on 409 retries) after
+   * `onReady`. Use for one-time startup work (command registration, sweeps,
+   * intervals).
+   */
+  onOneTimeSetup?: (botUsername: string) => void | Promise<void>
+  /** Fired when the polling loop exits cleanly (runner task resolved). */
+  onStop?: () => void | Promise<void>
+  /** Called each time a 409 is detected (useful for logging). */
+  on409?: (attempt: number, delayMs: number) => void
+}
+
+/**
+ * Runs a grammyjs/runner polling loop with built-in 409 retry backoff,
+ * matching the loop structure in gateway.ts.
+ *
+ * Returns the RunnerHandle so callers can call `.stop()` on SIGTERM.
+ *
+ * The promise resolves when the polling loop exits cleanly.
+ * The promise rejects on non-409, non-Aborted errors.
+ */
+export async function runPollingLoop(
+  bot: Bot,
+  callbacks: PollingLoopCallbacks = {},
+): Promise<void> {
+  let didOneTimeSetup = false
+
+  for (let attempt = 1; ; attempt++) {
+    try {
+      await clearStaleTelegramPollingState(bot.api)
+
+      const me = await bot.api.getMe()
+      process.stderr.write(`bot-runtime: polling as @${me.username}\n`)
+
+      if (callbacks.onReady) {
+        await callbacks.onReady(me.username ?? '', me.id)
+      }
+
+      if (!didOneTimeSetup) {
+        didOneTimeSetup = true
+        if (callbacks.onOneTimeSetup) {
+          await callbacks.onOneTimeSetup(me.username ?? '')
+        }
+      }
+
+      process.stderr.write(`bot-runtime: starting runner pid=${process.pid}\n`)
+      const handle: RunnerHandle = run(bot)
+      await handle.task()
+      if (callbacks.onStop) await callbacks.onStop()
+      return
+    } catch (err) {
+      if (err instanceof GrammyError && err.error_code === 409) {
+        const delay = Math.min(1000 * attempt, 15000)
+        if (callbacks.on409) callbacks.on409(attempt, delay)
+        process.stderr.write(
+          `bot-runtime: 409 Conflict attempt=${attempt} retry_in_ms=${delay}\n`,
+        )
+        await new Promise(r => setTimeout(r, delay))
+        continue
+      }
+      if (err instanceof Error && err.message === 'Aborted delay') return
+      process.stderr.write(`bot-runtime: polling failed: ${err}\n`)
+      throw err
+    }
+  }
+}
+
+// ─── Access guard ─────────────────────────────────────────────────────────
+
+/**
+ * Returns true if the sender's user ID is in the allowFrom list.
+ * Used by both gateway and foreman for auth gating.
+ */
+export function isAllowedSender(ctx: Context, allowFrom: string[]): boolean {
+  const from = ctx.from
+  if (!from) return false
+  return allowFrom.includes(String(from.id))
+}

package/telegram-plugin/silent-reply.ts

@@ -0,0 +1,58 @@
+/**
+ * Silent-reply markers + allowlist guard.
+ *
+ * Lives in its own module (separate from server.ts) so that tests and
+ * other importers can pull these helpers in without booting the
+ * full MCP server — server.ts has top-level side effects (env load,
+ * TELEGRAM_BOT_TOKEN check, history.db open, session-tail spawn) that
+ * are inappropriate for a unit-test import boundary.
+ *
+ * Sprint1 review finding #6: an earlier revision of the reply /
+ * stream_reply tool handlers returned the silent-reply ack BEFORE
+ * calling `assertAllowedChat`, so unauthorised chats could bypass the
+ * outbound allowlist by having the agent emit `NO_REPLY`. The ack
+ * itself is a cross-chat signal (it confirms to the LLM that the chat
+ * exists and is reachable) even though no Telegram message is sent, so
+ * we must refuse disallowed chats *before* producing it. The
+ * guardSilentReply helper locks that ordering in.
+ */
+
+const SILENT_REPLY_MARKERS = new Set(['NO_REPLY', 'HEARTBEAT_OK'])
+
+// Derive the char-length bound from the marker set so adding a new
+// marker doesn't silently desync with a hand-tuned constant.
+const SILENT_REPLY_MAX_LEN = Math.max(
+  ...Array.from(SILENT_REPLY_MARKERS, (m) => m.length),
+) + 2 // small buffer for trailing punctuation callers might add accidentally
+
+export function isSilentReplyMarker(text: string | undefined): boolean {
+  if (typeof text !== 'string') return false
+  const trimmed = text.trim()
+  if (trimmed.length === 0) return false
+  if (trimmed.length > SILENT_REPLY_MAX_LEN) return false
+  // Case-insensitive match: models occasionally emit `no_reply` or
+  // `NoReply`. Require letters/underscores/digits only so legitimate
+  // prose that happens to contain "NO_REPLY was suggested" still sends.
+  return SILENT_REPLY_MARKERS.has(trimmed.toUpperCase())
+}
+
+/**
+ * Decide whether a `reply`/`stream_reply` invocation should be short-
+ * circuited as a silent-reply ack, enforcing the allowlist FIRST.
+ *
+ * `assertAllowed` throws when `chat_id` is not on the allowlist; callers
+ * let that propagate so the MCP tool call fails loudly.
+ */
+export function guardSilentReply(params: {
+  chat_id: string
+  text: string | undefined
+  hasFiles: boolean
+  assertAllowed: (chat_id: string) => void
+}): { kind: 'silent'; markerText: string } | { kind: 'continue' } {
+  const { chat_id, text, hasFiles, assertAllowed } = params
+  if (hasFiles) return { kind: 'continue' }
+  if (!isSilentReplyMarker(text)) return { kind: 'continue' }
+  // Allowlist check BEFORE returning the ack — see docblock above.
+  assertAllowed(chat_id)
+  return { kind: 'silent', markerText: (text as string).trim() }
+}

package/telegram-plugin/slot-banner-driver.ts

@@ -0,0 +1,147 @@
+/**
+ * Slot-banner driver — executes the BannerAction state transition
+ * against a Telegram Bot API. Extracted from gateway.ts so the
+ * dispatch is testable end-to-end via `tests/fake-bot-api.ts`.
+ *
+ * The pure decision lives in `slot-banner.ts` (decideBannerAction).
+ * This module is the side-effecting half: takes a `bot` dependency,
+ * executes the action, returns the next state. The state itself
+ * stays in the caller (gateway.ts holds a module-global `let
+ * pinnedBannerState` and re-passes it on every call).
+ *
+ * Error-handling contract: API failures are reported via `onError`
+ * but never throw. The caller decides logging cadence (gateway logs
+ * to stderr; tests can assert via the callback). On a pin failure
+ * mid-sequence (sendMessage succeeded but pinChatMessage failed),
+ * the prior state is preserved so we don't claim ownership of an
+ * unpinned message.
+ *
+ * See #421 (banner pin lifecycle) and JTBD
+ * `reference/track-plan-quota-live.md` ("at a glance").
+ */
+
+import type { BannerState } from './slot-banner.js';
+import { decideBannerAction } from './slot-banner.js';
+
+/** Minimal subset of grammy's `bot.api` we depend on. Letting tests
+ *  swap in `fake-bot-api.ts` without dragging in the full Bot type. */
+export interface BannerBotApi {
+  sendMessage(
+    chat_id: string | number,
+    text: string,
+    opts?: Record<string, unknown>,
+  ): Promise<{ message_id: number }>;
+  editMessageText(
+    chat_id: string | number,
+    message_id: number,
+    text: string,
+    opts?: Record<string, unknown>,
+  ): Promise<unknown>;
+  pinChatMessage(
+    chat_id: string | number,
+    message_id: number,
+    opts?: Record<string, unknown>,
+  ): Promise<unknown>;
+  unpinChatMessage(
+    chat_id: string | number,
+    message_id: number,
+  ): Promise<unknown>;
+}
+
+export interface BannerBot {
+  api: BannerBotApi;
+}
+
+export interface RefreshBannerArgs {
+  bot: BannerBot;
+  ownerChatId: string;
+  agentName: string;
+  /** Active slot reported by `currentActiveSlot(agentDir)`. `null`
+   *  means we couldn't read one — treated like default state (unpins
+   *  any existing banner; never pins). */
+  currentSlot: string | null;
+  defaultSlot: string;
+  /** State the gateway is holding from the last call. Pass `null`
+   *  on first call. */
+  prevState: BannerState | null;
+  /** Optional API-failure observer. Phase identifies which Bot API
+   *  call failed so the caller can log meaningfully. Default: silent. */
+  onError?: (phase: 'pin' | 'edit' | 'unpin', err: unknown) => void;
+}
+
+/**
+ * Execute the next banner-state transition. Returns the new
+ * `BannerState` (or `null` when unpinned). Always resolves; never
+ * throws — API errors are routed through `onError`.
+ *
+ * On pin-mid-sequence failure (sendMessage succeeded but
+ * pinChatMessage failed), the function returns the *prior* state
+ * unchanged. Otherwise the gateway would track a message_id it
+ * never managed to pin, and the next refresh would think a banner
+ * exists and try to edit/unpin it.
+ */
+export async function refreshBanner(
+  args: RefreshBannerArgs,
+): Promise<BannerState | null> {
+  const action = decideBannerAction(
+    args.prevState,
+    args.currentSlot,
+    args.agentName,
+    args.defaultSlot,
+  );
+
+  if (action.kind === 'noop') return args.prevState;
+
+  if (action.kind === 'unpin') {
+    try {
+      await args.bot.api.unpinChatMessage(args.ownerChatId, action.messageId);
+    } catch (err) {
+      args.onError?.('unpin', err);
+    }
+    // Even if unpin failed, drop our claim — the message may have been
+    // unpinned out-of-band (operator did it manually) and re-pinning
+    // would be more confusing than surfacing it again later.
+    return null;
+  }
+
+  if (action.kind === 'pin') {
+    let sent: { message_id: number };
+    try {
+      sent = await args.bot.api.sendMessage(args.ownerChatId, action.text, {
+        parse_mode: 'HTML',
+        link_preview_options: { is_disabled: true },
+      });
+    } catch (err) {
+      args.onError?.('pin', err);
+      return args.prevState;
+    }
+    try {
+      await args.bot.api.pinChatMessage(args.ownerChatId, sent.message_id, {
+        disable_notification: true,
+      });
+    } catch (err) {
+      args.onError?.('pin', err);
+      // sendMessage succeeded but pin failed — don't claim the message.
+      return args.prevState;
+    }
+    return { messageId: sent.message_id, slot: action.slot };
+  }
+
+  // action.kind === 'edit'
+  try {
+    await args.bot.api.editMessageText(
+      args.ownerChatId,
+      action.messageId,
+      action.text,
+      {
+        parse_mode: 'HTML',
+        link_preview_options: { is_disabled: true },
+      },
+    );
+    return { messageId: action.messageId, slot: action.slot };
+  } catch (err) {
+    args.onError?.('edit', err);
+    // Edit failed — keep the prior state so the next refresh tries again.
+    return args.prevState;
+  }
+}

package/telegram-plugin/slot-banner.ts

@@ -0,0 +1,86 @@
+/**
+ * Pinned slot banner — pure decision logic.
+ *
+ * The gateway pins a banner in the owner chat when the agent is
+ * running on a non-default account slot (e.g. after auto-fallback
+ * swapped away from `default`). The banner unpins when the agent
+ * returns to `default`. This gives the user an always-visible answer
+ * to "what slot am I on right now?" exactly when it's not what they
+ * expect, and zero noise when everything is normal.
+ *
+ * This module is dependency-free so it's testable in isolation; the
+ * gateway translates `BannerAction` into actual Telegram API calls.
+ *
+ * v1 scope: one banner per gateway process, in the owner chat
+ * (access.allowFrom[0]). Per-topic forum support and multi-chat
+ * pinning are tracked as #421 follow-ups.
+ *
+ * See #421 (Switchroom).
+ */
+
+export type BannerState = {
+  /** Telegram message_id of the currently pinned banner. */
+  messageId: number;
+  /** The slot name shown by the pinned message — used to skip
+   *  redundant edits when the slot hasn't changed. */
+  slot: string;
+};
+
+export type BannerAction =
+  | { kind: 'noop'; reason: string }
+  /** Pin a fresh banner. Caller sends + pins, then records the
+   *  resulting message_id back into BannerState. */
+  | { kind: 'pin'; text: string; slot: string }
+  /** Edit the existing pinned banner's text. */
+  | { kind: 'edit'; messageId: number; text: string; slot: string }
+  /** Unpin + forget. Caller unpins (best-effort) and clears state. */
+  | { kind: 'unpin'; messageId: number };
+
+/**
+ * Decide what to do with the banner given the current active slot,
+ * the default slot, and the previously-pinned banner state.
+ */
+export function decideBannerAction(
+  prev: BannerState | null,
+  currentSlot: string | null,
+  agentName: string,
+  defaultSlot: string,
+): BannerAction {
+  // Default state (or no slot yet): no banner needed. If one is
+  // pinned from a prior failover, unpin so the chat is clean again.
+  if (currentSlot === null || currentSlot === defaultSlot) {
+    if (prev) return { kind: 'unpin', messageId: prev.messageId };
+    return { kind: 'noop', reason: 'on default slot, nothing pinned' };
+  }
+
+  // Non-default state. Either pin fresh or edit existing.
+  const text = formatBannerHtml(agentName, currentSlot, defaultSlot);
+  if (!prev) return { kind: 'pin', text, slot: currentSlot };
+  if (prev.slot === currentSlot) {
+    return { kind: 'noop', reason: 'banner already shows current slot' };
+  }
+  return { kind: 'edit', messageId: prev.messageId, text, slot: currentSlot };
+}
+
+/**
+ * The banner body. Kept short — the user reads this at a glance,
+ * and pinned messages eat vertical space at the top of the chat.
+ */
+export function formatBannerHtml(
+  agentName: string,
+  currentSlot: string,
+  defaultSlot: string,
+): string {
+  return [
+    `📌 <b>${escapeHtml(agentName)}</b> is running on slot <code>${escapeHtml(currentSlot)}</code>`,
+    `<i>(failover from <code>${escapeHtml(defaultSlot)}</code>)</i>`,
+  ].join(' ');
+}
+
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}

package/telegram-plugin/start.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env bun
+// MCP-server entry shim. Resolved by `bun run start` (see package.json).
+//
+// Strategic packaging fix (#634): the production MCP launcher invokes
+// `bun run --cwd <pluginDir> --silent start`, which executes this file.
+// We prefer the bundled `dist/server.js` because the npm package's
+// `files` array doesn't include `src/` — direct `.ts` execution from
+// the global install fails with `Cannot find module '../../src/...'`
+// against the bundle's cross-imports. The bundle resolves them at
+// build time so dist runs everywhere.
+//
+// Dev workspaces that haven't run `bun run build` yet (or operators
+// running pre-#634 packages) fall back to the .ts source. The fallback
+// is the legacy behavior — preserves dev ergonomics where editing
+// .ts and restarting an agent picks up changes without an explicit
+// build step (modulo the documented `bun run build` cycle).
+import { existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const distPath = resolve(here, "dist/server.js");
+const sourcePath = resolve(here, "server.ts");
+
+const target = existsSync(distPath) ? distPath : sourcePath;
+await import(target);

package/telegram-plugin/startup-reset.ts

@@ -0,0 +1,45 @@
+/**
+ * Clear stale Telegram polling state on gateway startup.
+ *
+ * The Telegram Bot API tracks one active long-poll session per bot
+ * token. If the previous gateway process crashed mid-poll (e.g. systemd
+ * killed it with SIGKILL after a start-timeout, which is exactly what
+ * happened to klanker on 2026-04-21 at 16:35 AEST), the API-side slot
+ * can remain occupied for several minutes. The new gateway then races
+ * that orphan on every getUpdates call and gets back a 409 Conflict
+ * ("terminated by other getUpdates request"). Grammy retries with
+ * backoff but the loop can persist for hours.
+ *
+ * deleteWebhook is a no-op when no webhook is configured but it also
+ * invalidates any active long-poll claim. Combined with
+ * drop_pending_updates, it gives us a clean slate regardless of how
+ * the previous process died. Safe to call on every startup — it's
+ * idempotent and has no user-visible side effects beyond clearing the
+ * (probably-empty) pending-updates queue.
+ *
+ * Reference: reference/restart-and-know-what-im-running.md — "silent
+ * respawn. Agent comes back and the user has to guess whether it's
+ * the same agent." A gateway stuck in a 409 loop is exactly that
+ * failure mode.
+ *
+ * Lives in a separate module (not gateway.ts) so the test file can
+ * import it without firing gateway.ts's top-level IIFE that starts
+ * the bot.
+ */
+
+export interface DeleteWebhookCapable {
+  deleteWebhook: (opts: { drop_pending_updates: boolean }) => Promise<unknown>;
+}
+
+export async function clearStaleTelegramPollingState(
+  api: DeleteWebhookCapable,
+): Promise<void> {
+  try {
+    await api.deleteWebhook({ drop_pending_updates: true });
+  } catch (err) {
+    // Best-effort — if deleteWebhook fails the runner will still start
+    // and grammy's built-in 409 handling kicks in. Log so we can
+    // diagnose if this becomes a recurring failure.
+    process.stderr.write(`telegram gateway: deleteWebhook on startup failed: ${err}\n`);
+  }
+}