switchroom 0.5.0

package/telegram-plugin/registry/turns-schema.ts

@@ -0,0 +1,417 @@
+/**
+ * Turn-tracking schema for the per-agent registry.
+ *
+ * Phase 0 of #250 (the SQLite event registry). This module ships only what
+ * subsequent stages of the simplify-restart plan need to detect "this turn
+ * was orphaned by a restart" — a minimal, strictly-subset design so later
+ * registry work can extend without breaking changes.
+ *
+ * The DB file lives at `<agentDir>/telegram/registry.db`. Storage is
+ * `bun:sqlite` (Bun's bundled SQLite, no extra dep), same as history.ts.
+ *
+ * Schema (one table):
+ *
+ *   turns
+ *     turn_key              TEXT PK           -- e.g. "8248703757:11"
+ *     chat_id               TEXT NOT NULL
+ *     thread_id             TEXT              -- nullable: forum topics only
+ *     started_at            INTEGER NOT NULL  -- unix ms
+ *     ended_at              INTEGER           -- nullable until turn ends
+ *     ended_via             TEXT              -- 'stop' | 'sigterm' | 'restart' | 'timeout' | 'unknown'
+ *     last_assistant_msg_id TEXT              -- last outbound message_id in this turn
+ *     last_assistant_done   INTEGER           -- 0|1; 1 = stream_reply done=true sent
+ *     last_user_msg_id      TEXT              -- inbound message_id that started the turn
+ *     user_prompt_preview   TEXT              -- first ~200 chars of user message (Phase 1)
+ *     assistant_reply_preview TEXT            -- first ~200 chars of bot's terminal message (Phase 1)
+ *     tool_call_count       INTEGER           -- count of tool_use events in the turn (Phase 1)
+ *     created_at            INTEGER NOT NULL
+ *     updated_at            INTEGER NOT NULL
+ *
+ * Boot-time usage:
+ *   On every gateway boot, call `markOrphanedAsRestarted(db)` immediately
+ *   after opening the DB. Any turn with `ended_at IS NULL` was killed
+ *   mid-flight (SIGKILL, OOM, power loss) — it never got a chance to write
+ *   a clean-shutdown marker. Stage 3 of simplify-restart will wire this up
+ *   from the gateway entry point.
+ */
+
+import { chmodSync, mkdirSync } from 'fs'
+import { join } from 'path'
+
+// ---------------------------------------------------------------------------
+// bun:sqlite lazy-loader (same pattern as history.ts)
+// ---------------------------------------------------------------------------
+
+/**
+ * `bun:sqlite` is a Bun built-in — Vite/Node loaders can't resolve it
+ * statically, which would crash any vitest test that transitively imports
+ * this module. Hide the require behind `import.meta.require` so static
+ * analysis passes; runtime resolution is per-Bun and works fine.
+ */
+type SqliteDatabase = {
+  exec(sql: string): void
+  prepare(sql: string): {
+    run(...params: unknown[]): unknown
+    all(...params: unknown[]): unknown[]
+    get(...params: unknown[]): unknown
+  }
+  transaction(fn: (...args: unknown[]) => unknown): (...args: unknown[]) => unknown
+  close(): void
+}
+type SqliteDatabaseConstructor = new (path: string, opts?: { create?: boolean }) => SqliteDatabase
+
+let DatabaseClass: SqliteDatabaseConstructor | null = null
+function loadDatabaseClass(): SqliteDatabaseConstructor {
+  if (DatabaseClass != null) return DatabaseClass
+  try {
+    const metaRequire = (import.meta as { require?: (id: string) => unknown }).require
+    if (typeof metaRequire !== 'function') {
+      throw new Error('import.meta.require not available — Bun runtime required')
+    }
+    const mod = metaRequire('bun:sqlite') as { Database?: SqliteDatabaseConstructor }
+    if (!mod.Database) throw new Error('bun:sqlite did not export Database')
+    DatabaseClass = mod.Database
+    return DatabaseClass
+  } catch (err) {
+    throw new Error(
+      `turns-schema.ts requires Bun runtime (bun:sqlite). Caller: ${(err as Error).message}`,
+    )
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type TurnEndedVia = 'stop' | 'sigterm' | 'restart' | 'timeout' | 'unknown'
+
+export interface Turn {
+  turn_key: string
+  chat_id: string
+  thread_id: string | null
+  started_at: number
+  ended_at: number | null
+  ended_via: TurnEndedVia | null
+  last_assistant_msg_id: string | null
+  last_assistant_done: boolean | null
+  last_user_msg_id: string | null
+  user_prompt_preview: string | null
+  assistant_reply_preview: string | null
+  tool_call_count: number | null
+  created_at: number
+  updated_at: number
+}
+
+export interface RecordTurnStartArgs {
+  turnKey: string
+  chatId: string
+  threadId?: string | null
+  lastUserMsgId?: string | null
+  userPromptPreview?: string | null
+}
+
+export interface RecordTurnEndArgs {
+  turnKey: string
+  endedVia: TurnEndedVia
+  lastAssistantMsgId?: string | null
+  lastAssistantDone?: boolean
+  assistantReplyPreview?: string | null
+  toolCallCount?: number
+}
+
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+
+const SCHEMA_SQL = `
+  CREATE TABLE IF NOT EXISTS turns (
+    turn_key                TEXT    PRIMARY KEY,
+    chat_id                 TEXT    NOT NULL,
+    thread_id               TEXT,
+    started_at              INTEGER NOT NULL,
+    ended_at                INTEGER,
+    ended_via               TEXT,
+    last_assistant_msg_id   TEXT,
+    last_assistant_done     INTEGER,
+    last_user_msg_id        TEXT,
+    user_prompt_preview     TEXT,
+    assistant_reply_preview TEXT,
+    tool_call_count         INTEGER,
+    created_at              INTEGER NOT NULL,
+    updated_at              INTEGER NOT NULL
+  );
+  CREATE INDEX IF NOT EXISTS idx_turns_chat_ended ON turns(chat_id, ended_at);
+`
+
+// Columns added in Phase 1 of #332. Applied via ALTER TABLE so existing
+// registry.db files on disk are migrated non-destructively on first open.
+const PHASE1_MIGRATIONS = [
+  `ALTER TABLE turns ADD COLUMN user_prompt_preview TEXT`,
+  `ALTER TABLE turns ADD COLUMN assistant_reply_preview TEXT`,
+  `ALTER TABLE turns ADD COLUMN tool_call_count INTEGER`,
+]
+
+function applySchema(db: SqliteDatabase): void {
+  db.exec('PRAGMA journal_mode = WAL')
+  db.exec('PRAGMA synchronous = NORMAL')
+  db.exec(SCHEMA_SQL)
+  // Run migrations for Phase 1 columns. SQLite doesn't support
+  // "ADD COLUMN IF NOT EXISTS", so we swallow the "duplicate column" error.
+  for (const sql of PHASE1_MIGRATIONS) {
+    try {
+      db.exec(sql)
+    } catch (err) {
+      const msg = (err as Error).message ?? ''
+      if (!msg.includes('duplicate column')) throw err
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// openTurnsDb
+// ---------------------------------------------------------------------------
+
+/**
+ * Open (or create) the per-agent registry DB at
+ * `<agentDir>/telegram/registry.db`.
+ *
+ * Returns the raw Database instance — callers hold it and pass it to the
+ * helpers below. This is intentionally NOT a singleton so tests can use
+ * in-memory or temp-file DBs without global state pollution.
+ *
+ * Callers that need a singleton can wrap this themselves. The gateway will
+ * hold one instance for the lifetime of the process (Stage 3).
+ */
+export function openTurnsDb(agentDir: string): SqliteDatabase {
+  const Database = loadDatabaseClass()
+  const dir = join(agentDir, 'telegram')
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  const path = join(dir, 'registry.db')
+  const db = new Database(path, { create: true })
+  applySchema(db)
+  try {
+    chmodSync(path, 0o600)
+  } catch {
+    /* ignore — chmod not supported on some FUSE mounts */
+  }
+  return db
+}
+
+/**
+ * Open an in-memory DB with the turns schema applied.
+ * Useful for tests without touching the filesystem.
+ */
+export function openTurnsDbInMemory(): SqliteDatabase {
+  const Database = loadDatabaseClass()
+  const db = new Database(':memory:')
+  applySchema(db)
+  return db
+}
+
+// ---------------------------------------------------------------------------
+// Row mapper
+// ---------------------------------------------------------------------------
+
+interface RawTurnRow {
+  turn_key: string
+  chat_id: string
+  thread_id: string | null
+  started_at: number
+  ended_at: number | null
+  ended_via: string | null
+  last_assistant_msg_id: string | null
+  last_assistant_done: number | null
+  last_user_msg_id: string | null
+  user_prompt_preview: string | null
+  assistant_reply_preview: string | null
+  tool_call_count: number | null
+  created_at: number
+  updated_at: number
+}
+
+function mapRow(row: RawTurnRow): Turn {
+  return {
+    turn_key: row.turn_key,
+    chat_id: row.chat_id,
+    thread_id: row.thread_id,
+    started_at: row.started_at,
+    ended_at: row.ended_at,
+    ended_via: (row.ended_via as TurnEndedVia | null) ?? null,
+    last_assistant_msg_id: row.last_assistant_msg_id,
+    last_assistant_done:
+      row.last_assistant_done === null ? null : row.last_assistant_done !== 0,
+    last_user_msg_id: row.last_user_msg_id,
+    user_prompt_preview: row.user_prompt_preview,
+    assistant_reply_preview: row.assistant_reply_preview,
+    tool_call_count: row.tool_call_count,
+    created_at: row.created_at,
+    updated_at: row.updated_at,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Record that a new turn has started. Inserts a row with `ended_at = NULL`.
+ * If a row with the same `turnKey` already exists it is left unchanged
+ * (INSERT OR IGNORE) — callers should generate unique keys.
+ */
+export function recordTurnStart(db: SqliteDatabase, args: RecordTurnStartArgs): void {
+  const now = Date.now()
+  db.prepare(`
+    INSERT OR IGNORE INTO turns
+      (turn_key, chat_id, thread_id, started_at, last_user_msg_id,
+       user_prompt_preview, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    args.turnKey,
+    args.chatId,
+    args.threadId ?? null,
+    now,
+    args.lastUserMsgId ?? null,
+    args.userPromptPreview ?? null,
+    now,
+    now,
+  )
+}
+
+/**
+ * Record that a turn has ended cleanly. Updates `ended_at`, `ended_via`,
+ * and optionally the last outbound message fields, reply preview, and
+ * tool-call count.
+ *
+ * No-ops gracefully if `turnKey` is not found (turn may have already been
+ * swept by `markOrphanedAsRestarted` on a prior boot).
+ */
+export function recordTurnEnd(db: SqliteDatabase, args: RecordTurnEndArgs): void {
+  const now = Date.now()
+  db.prepare(`
+    UPDATE turns
+    SET
+      ended_at                = ?,
+      ended_via               = ?,
+      last_assistant_msg_id   = COALESCE(?, last_assistant_msg_id),
+      last_assistant_done     = COALESCE(?, last_assistant_done),
+      assistant_reply_preview = COALESCE(?, assistant_reply_preview),
+      tool_call_count         = COALESCE(?, tool_call_count),
+      updated_at              = ?
+    WHERE turn_key = ?
+  `).run(
+    now,
+    args.endedVia,
+    args.lastAssistantMsgId ?? null,
+    args.lastAssistantDone !== undefined ? (args.lastAssistantDone ? 1 : 0) : null,
+    args.assistantReplyPreview ?? null,
+    args.toolCallCount !== undefined ? args.toolCallCount : null,
+    now,
+    args.turnKey,
+  )
+}
+
+/**
+ * Return all turns for `chatId` where `ended_at IS NULL` — these are
+ * candidates for "killed mid-turn" (the gateway crashed before the turn
+ * completed and wrote its end record).
+ *
+ * Results are ordered by `started_at ASC` so callers can process
+ * oldest-first if they need to replay or report them.
+ */
+export function findOrphanedTurns(db: SqliteDatabase, chatId: string): Turn[] {
+  const rows = db.prepare(`
+    SELECT * FROM turns
+    WHERE chat_id = ? AND ended_at IS NULL
+    ORDER BY started_at ASC
+  `).all(chatId) as RawTurnRow[]
+  return rows.map(mapRow)
+}
+
+/**
+ * Boot-time reaper. Sweeps ALL turns (across all chats) that have
+ * `ended_at IS NULL` and stamps them with `ended_via = 'restart'` and
+ * `ended_at = now()`.
+ *
+ * Call this once, immediately after `openTurnsDb`, before any new turns
+ * are recorded for the current boot. That way the current boot's turns
+ * are cleanly separable from orphans inherited from the prior process.
+ *
+ * Returns the number of rows updated.
+ */
+export function markOrphanedAsRestarted(db: SqliteDatabase): number {
+  const now = Date.now()
+  const result = db.prepare(`
+    UPDATE turns
+    SET ended_at   = ?,
+        ended_via  = 'restart',
+        updated_at = ?
+    WHERE ended_at IS NULL
+  `).run(now, now) as { changes: number }
+  return result.changes
+}
+
+/**
+ * Return the most recent N turns for `chatId` (any state — running or ended),
+ * ordered by started_at DESC. Used by the idle-footer renderer to decide
+ * whether to render "working since" vs "idle · last reply".
+ *
+ * `limit` defaults to 1 because the renderer only inspects the top row, but
+ * callers can pass more if they need backfill.
+ */
+export function findRecentTurnsForChat(
+  db: SqliteDatabase,
+  chatId: string,
+  limit = 1,
+): Turn[] {
+  const rows = db.prepare(`
+    SELECT * FROM turns
+    WHERE chat_id = ?
+    ORDER BY started_at DESC
+    LIMIT ?
+  `).all(chatId, limit) as RawTurnRow[]
+  return rows.map(mapRow)
+}
+
+/**
+ * Return the most recent N turns across all chats for an agent, ordered by
+ * started_at DESC. Intended for the REST API endpoint
+ * `GET /api/agents/:name/turns?limit=20`.
+ *
+ * `limit` defaults to 20, max 200.
+ */
+export function listTurnsForAgent(
+  db: SqliteDatabase,
+  opts: { limit?: number } = {},
+): Turn[] {
+  const limit = Math.min(Math.max(1, opts.limit ?? 20), 200)
+  const rows = db.prepare(`
+    SELECT * FROM turns
+    ORDER BY started_at DESC
+    LIMIT ?
+  `).all(limit) as RawTurnRow[]
+  return rows.map(mapRow)
+}
+
+/**
+ * Find the single most-recently-started turn that ended via an interrupt
+ * (`'restart'` | `'sigterm'` | `'timeout'`) OR is still open
+ * (`ended_at IS NULL`). Used by Stage 4 to surface "you had pending work"
+ * to the agent on cold start.
+ *
+ * Returns null if no such turn exists (clean boot — last turn ended 'stop').
+ *
+ * Note on ordering: we use `started_at DESC` (not `updated_at`) so the
+ * boot-time reaper (which mass-stamps orphans with the SAME `ended_at` /
+ * `updated_at`) doesn't reorder them; the temporal "last turn" is what
+ * the user remembers, and that's `started_at`.
+ */
+export function findMostRecentInterruptedTurn(db: SqliteDatabase): Turn | null {
+  const row = db.prepare(`
+    SELECT * FROM turns
+    WHERE ended_at IS NULL
+       OR ended_via IN ('restart', 'sigterm', 'timeout')
+    ORDER BY started_at DESC
+    LIMIT 1
+  `).get() as RawTurnRow | undefined
+  return row ? mapRow(row) : null
+}

package/telegram-plugin/retry-api-call.ts

@@ -0,0 +1,172 @@
+/**
+ * Retry wrapper for Telegram Bot API calls — the single policy the rest
+ * of the plugin relies on for flood-wait handling, benign 400 swallowing,
+ * and thread-not-found fallback.
+ *
+ * Extracted from gateway.ts so that:
+ *   - it's unit-testable (the previous in-gateway definition couldn't be
+ *     exercised without spinning up the whole bot runner)
+ *   - stream-reply-handler / server.ts can share one implementation
+ *     instead of each threading a `retry` dep through every callsite
+ *   - callers can install an observer (`onRetry`, `onGiveUp`) for tests
+ *     and production logging without reaching into the function body.
+ *
+ * Behaviour contract — each case is independently tested in
+ * `tests/retry-api-call.test.ts`:
+ *
+ *   | Thrown error                                  | This wrapper does                          |
+ *   |-----------------------------------------------|--------------------------------------------|
+ *   | GrammyError 429                               | sleep retry_after seconds, retry          |
+ *   | GrammyError 400 "message is not modified"     | swallow, return undefined                 |
+ *   | GrammyError 400 "message to edit not found"   | swallow, return undefined                 |
+ *   | GrammyError 400 "message to delete not found" | swallow, return undefined                 |
+ *   | GrammyError 400 "thread not found" (w/ opts)  | throw `THREAD_NOT_FOUND` wrapper          |
+ *   | Network error (fetch failed / ECONN…)         | exponential backoff retry, 3 attempts     |
+ *   | Anything else                                 | rethrow immediately                       |
+ */
+
+import { GrammyError } from 'grammy'
+
+export interface RetryCallOpts {
+  /**
+   * The forum-topic thread id, used only to decide whether the
+   * "thread not found" 400 is retryable for a fallback path. If both
+   * `threadId` and `chat_id` are set, a thread-not-found 400 is rethrown
+   * as `THREAD_NOT_FOUND` so callers can drop the thread and retry on
+   * the main chat.
+   */
+  threadId?: number
+  chat_id?: string
+  /**
+   * Optional caller-supplied label for the API call (e.g. "sendMessage",
+   * "editMessageText"). Currently informational only — accepted to allow
+   * call sites to self-document. Future: surface in retry logs / metrics.
+   */
+  verb?: string
+}
+
+export interface RetryObserver {
+  /** Fires just before sleeping for a retry. */
+  onRetry?(info: { attempt: number; reason: 'flood_wait' | 'network'; delayMs: number }): void
+  /** Fires when max retries is reached and the wrapper gives up. */
+  onGiveUp?(info: { attempts: number; error: unknown }): void
+  /** Fires for each benign error we swallowed (not-modified, not-found). */
+  onBenign?(info: { kind: 'not_modified' | 'message_not_found' | 'delete_not_found' }): void
+}
+
+export interface RetryApiCallConfig {
+  /** Max retries before giving up. Defaults to 3. */
+  maxRetries?: number
+  /** Sleep helper — injected so tests can use fake timers. */
+  sleep?: (ms: number) => Promise<void>
+  /** Optional observer hooks. */
+  observer?: RetryObserver
+  /** Optional log sink for flood-wait / network lines. */
+  log?: (line: string) => void
+}
+
+const DEFAULT_SLEEP = (ms: number) => new Promise<void>((r) => setTimeout(r, ms))
+
+/**
+ * Wrap a Telegram API call with the standard retry policy.
+ *
+ * Returns `fn`'s resolved value on success. Returns `undefined` for the
+ * swallowed-400 cases (caller must tolerate this — the typical caller is
+ * a `bot.api.editMessageText` which returns `true` on success, so
+ * `undefined` cleanly flags "no-op, target gone or identical"). Throws
+ * on 3rd network-error attempt or on any non-retryable error.
+ */
+export function createRetryApiCall(
+  config: RetryApiCallConfig = {},
+): <T>(fn: () => Promise<T>, opts?: RetryCallOpts) => Promise<T> {
+  const maxRetries = config.maxRetries ?? 3
+  const sleep = config.sleep ?? DEFAULT_SLEEP
+  const observer = config.observer
+  const log = config.log
+
+  return async function retryApiCall<T>(
+    fn: () => Promise<T>,
+    opts?: RetryCallOpts,
+  ): Promise<T> {
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      try {
+        return await fn()
+      } catch (err) {
+        const isGrammyErr = err instanceof GrammyError
+        const msg = err instanceof Error ? err.message : String(err)
+        const desc = isGrammyErr ? (err as GrammyError).description : msg
+
+        // Flood-wait — sleep retry_after and try again.
+        if (isGrammyErr && (err as GrammyError).error_code === 429) {
+          const retryAfter = Number(
+            (err as GrammyError).parameters?.retry_after ?? 5,
+          )
+          const delayMs = retryAfter * 1000
+          log?.(`telegram gateway: 429 rate limited, waiting ${retryAfter}s\n`)
+          observer?.onRetry?.({ attempt, reason: 'flood_wait', delayMs })
+          await sleep(delayMs)
+          continue
+        }
+
+        // Swallow "message is not modified" — Telegram's no-op-on-equal-text.
+        if (
+          isGrammyErr &&
+          (err as GrammyError).error_code === 400 &&
+          desc.includes('not modified')
+        ) {
+          observer?.onBenign?.({ kind: 'not_modified' })
+          return undefined as unknown as T
+        }
+
+        // Swallow "message to edit/delete not found" — target vanished.
+        if (
+          isGrammyErr &&
+          (err as GrammyError).error_code === 400 &&
+          (desc.includes('message to edit not found') ||
+            desc.includes('message to delete not found'))
+        ) {
+          observer?.onBenign?.({
+            kind: desc.includes('edit') ? 'message_not_found' : 'delete_not_found',
+          })
+          return undefined as unknown as T
+        }
+
+        // Stale forum-thread — caller may want to fall back to main chat.
+        if (
+          isGrammyErr &&
+          (err as GrammyError).error_code === 400 &&
+          desc.includes('thread not found') &&
+          opts?.threadId &&
+          opts?.chat_id
+        ) {
+          throw Object.assign(new Error('THREAD_NOT_FOUND'), { original: err })
+        }
+
+        // Network-level transient errors — exponential backoff, bounded.
+        if (
+          !isGrammyErr &&
+          (msg.includes('ECONNRESET') ||
+            msg.includes('ETIMEDOUT') ||
+            msg.includes('fetch failed') ||
+            msg.includes('ENOTFOUND'))
+        ) {
+          if (attempt < maxRetries - 1) {
+            const delayMs = Math.pow(2, attempt) * 1000
+            log?.(
+              `telegram gateway: network error, retrying in ${delayMs / 1000}s: ${msg}\n`,
+            )
+            observer?.onRetry?.({ attempt, reason: 'network', delayMs })
+            await sleep(delayMs)
+            continue
+          }
+        }
+
+        observer?.onGiveUp?.({ attempts: attempt + 1, error: err })
+        throw err
+      }
+    }
+    const giveUpErr = new Error('retryApiCall: max retries exceeded')
+    observer?.onGiveUp?.({ attempts: maxRetries, error: giveUpErr })
+    throw giveUpErr
+  }
+}

package/telegram-plugin/scripts/build.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// Build script for @switchroom-ai/telegram-plugin npm publish.
+import { execSync } from "node:child_process";
+import { readFileSync, writeFileSync, chmodSync, mkdirSync, rmSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { escapeBundleNonAscii } from "../../scripts/escape-bundle-non-ascii.mjs";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const outDir = resolve(root, "dist");
+
+console.log("[build] cleaning dist/");
+rmSync(outDir, { recursive: true, force: true });
+mkdirSync(outDir, { recursive: true });
+
+try {
+  execSync("bun --version", { stdio: "ignore" });
+} catch {
+  console.error("[build] bun is required to build. Install from https://bun.sh");
+  process.exit(1);
+}
+
+const entries = [
+  { src: "server.ts", out: "server.js", label: "server (legacy + dual-mode shim)" },
+  { src: "gateway/gateway.ts", out: "gateway/gateway.js", label: "gateway (persistent service)" },
+  { src: "bridge/bridge.ts", out: "bridge/bridge.js", label: "bridge (MCP proxy)" },
+  { src: "foreman/foreman.ts", out: "foreman/foreman.js", label: "foreman (admin bot)" },
+];
+
+for (const { src, out, label } of entries) {
+  const srcPath = resolve(root, src);
+  const outPath = resolve(outDir, out);
+  const outDirForEntry = dirname(outPath);
+  mkdirSync(outDirForEntry, { recursive: true });
+
+  console.log(`[build] bundling ${src} -> dist/${out}`);
+  // `--external node-fetch`: grammy depends on node-fetch@2 which is a
+  // CJS package using node's `http`/`stream` directly. When bundled with
+  // `--target node`, bun's bundler INLINES node-fetch as the fetch
+  // implementation. Under bun runtime that inlined node-fetch breaks
+  // grammy's API calls with a generic "Network request failed!" — the
+  // gateway boot then loops 8x retrying getMe and exits, rendering the
+  // entire fleet unresponsive (every reply path fails, agent thumbs-up
+  // works but no message lands).
+  //
+  // Externalizing node-fetch keeps the bundle target-node compatible
+  // for npm-i-g users on a node runtime (grammy declares node-fetch as
+  // a dep so it'll be present in node_modules) AND lets bun's native
+  // fetch shim take over when the bundle runs under bun (the actual
+  // production deployment via `systemd ExecStart=bun gateway.js`).
+  //
+  // Verified: the un-externalized bundle reproducibly fails under bun
+  // with "HttpError: Network request for 'getMe' failed!" within 1s of
+  // boot. The externalized bundle boots cleanly and polls successfully.
+  execSync(
+    `bun build ${JSON.stringify(srcPath)} --outdir ${JSON.stringify(outDirForEntry)} --target node --external node-fetch`,
+    { stdio: "inherit", cwd: root }
+  );
+
+  let content = readFileSync(outPath, "utf8");
+  if (content.startsWith("#!/usr/bin/env bun")) {
+    content = content.replace(/^#!\/usr\/bin\/env bun/, "#!/usr/bin/env node");
+    writeFileSync(outPath, content);
+  }
+  chmodSync(outPath, 0o755);
+
+  // Bun parser bug workaround — see scripts/escape-bundle-non-ascii.mjs.
+  // Required for the gateway bundle: without it, the boot card's `✅`
+  // and the inline `·` separator in the ack-line template literal get
+  // double-UTF-8 encoded on the wire (#642 follow-up; mojibake reported
+  // as `â LawGPT back up · v0.6.3`).
+  const escResult = escapeBundleNonAscii(outPath);
+  if (escResult.changed) {
+    console.log(`[build] ASCII-escaped ${escResult.nonAsciiCount} non-ASCII code units in dist/${out}`);
+  }
+}
+
+console.log("[build] done");