nebula-ai-plugin-telegram 0.1.0

package/src/markdown.ts

@@ -0,0 +1,211 @@
+// MarkdownV2 escape + plain-text fallback + standard-markdown translator.
+//
+// The brain emits standard CommonMark (`**bold**`, `*italic*`, `` `code` ``,
+// `# heading`, `[text](url)`, lists, blockquotes). Telegram MarkdownV2 has
+// different syntax AND requires every reserved character outside formatting
+// markers to be backslash-escaped. Sending the brain's text directly with
+// `parse_mode: 'MarkdownV2'` either parse-errors or renders escape characters
+// literally.
+//
+// `formatMarkdownV2(text)` is the canonical translator: protect code blocks
+// and links behind placeholders, convert markdown structures to MarkdownV2
+// equivalents, escape remaining reserved chars, restore placeholders. Ported
+// from hermes telegram.py:format_message.
+//
+// `escapeMarkdownV2(text)` and `stripMarkdownV2(text)` remain available for
+// callers that need raw escaping or a plain-text fallback when send fails.
+
+const MARKDOWN_V2_ESCAPE_REGEX = /([_*[\]()~`>#+\-=|{}.!\\])/g
+
+export function escapeMarkdownV2(text: string): string {
+  return text.replace(MARKDOWN_V2_ESCAPE_REGEX, '\\$1')
+}
+
+/**
+ * Strip MarkdownV2 markers so a parse_error fallback can send the same content
+ * as plain text. Handles the four common formatting markers (`*bold*`,
+ * `_italic_`, `~strike~`, `||spoiler||`) plus drops escape backslashes.
+ *
+ * Code-block markers stay (TG renders them as plain text without parse_mode).
+ */
+export function stripMarkdownV2(text: string): string {
+  let out = text
+  out = out.replace(/\\([_*[\]()~`>#+\-=|{}.!\\])/g, '$1')
+  out = out.replace(/\|\|([^|]+)\|\|/g, '$1')
+  out = out.replace(/\*([^*]+)\*/g, '$1')
+  out = out.replace(/(?:^|[\s])_([^_]+)_(?=[\s]|$)/g, ' $1')
+  out = out.replace(/~([^~]+)~/g, '$1')
+  return out
+}
+
+/**
+ * Detect if a grammy / Bot API error is a MarkdownV2 parse error so callers
+ * can fall back to plain-text. Hermes pattern: the error message contains
+ * "can't parse entities" with the MarkdownV2 mention.
+ */
+export function isMarkdownParseError(err: unknown): boolean {
+  const msg = err instanceof Error ? err.message : String(err)
+  const lower = msg.toLowerCase()
+  return (
+    lower.includes("can't parse entities") ||
+    lower.includes('cannot parse entities') ||
+    (lower.includes('bad request') && (lower.includes('parse') || lower.includes('entities')))
+  )
+}
+
+/**
+ * Translate standard CommonMark (what the brain emits) into Telegram MarkdownV2.
+ * Ports hermes `format_message` (telegram.py:1838-1993). Strategy: stash code
+ * spans and links behind NUL-bracketed placeholders, rewrite formatting
+ * markers, then escape every reserved char in the remaining plain text and
+ * restore placeholders. The trailing safety pass catches stray `( ) { }` that
+ * survived the dance, while leaving link parens intact.
+ */
+export function formatMarkdownV2(content: string): string {
+  if (!content) return content
+
+  // GFM tables don't render in MarkdownV2 — pipes show literally and columns
+  // misalign. Wrap detected table blocks in ``` fences so TG renders them
+  // monospace + preserves column alignment. Detection: a line starting with
+  // `|` followed by a separator row (`|---|---|`) makes the start of a table;
+  // contiguous `|...|` lines are pulled in until the first non-table line.
+  const wrapped = wrapGfmTablesInCodeBlocks(content)
+
+  const placeholders: string[] = []
+  const ph = (value: string): string => {
+    const key = `\x00PH${placeholders.length}\x00`
+    placeholders.push(value)
+    return key
+  }
+
+  let text = wrapped
+
+  text = text.replace(/```(?:[^\n]*\n)?[\s\S]*?```/g, raw => {
+    const newlineIdx = raw.indexOf('\n', 3)
+    const headerEnd = newlineIdx === -1 ? 3 : newlineIdx + 1
+    const header = raw.slice(0, headerEnd)
+    const body = raw.slice(headerEnd, raw.length - 3)
+    const escaped = body.replace(/\\/g, '\\\\').replace(/`/g, '\\`')
+    return ph(`${header}${escaped}\`\`\``)
+  })
+
+  text = text.replace(/`[^`\n]+`/g, raw => ph(raw.replace(/\\/g, '\\\\')))
+
+  text = text.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_match, display: string, url: string) => {
+    const safeDisplay = escapeMarkdownV2(display)
+    const safeUrl = url.replace(/\\/g, '\\\\').replace(/\)/g, '\\)')
+    return ph(`[${safeDisplay}](${safeUrl})`)
+  })
+
+  text = text.replace(/^(#{1,6})\s+(.+)$/gm, (_match, _hashes, inner: string) => {
+    const cleaned = inner.trim().replace(/\*\*(.+?)\*\*/g, '$1')
+    return ph(`*${escapeMarkdownV2(cleaned)}*`)
+  })
+
+  text = text.replace(/\*\*(.+?)\*\*/g, (_match, inner: string) =>
+    ph(`*${escapeMarkdownV2(inner)}*`),
+  )
+
+  text = text.replace(/\*([^*\n]+)\*/g, (_match, inner: string) =>
+    ph(`_${escapeMarkdownV2(inner)}_`),
+  )
+
+  text = text.replace(/~~(.+?)~~/g, (_match, inner: string) => ph(`~${escapeMarkdownV2(inner)}~`))
+
+  text = text.replace(/\|\|(.+?)\|\|/g, (_match, inner: string) =>
+    ph(`||${escapeMarkdownV2(inner)}||`),
+  )
+
+  text = text.replace(/^(>{1,3}) (.+)$/gm, (_match, marker: string, body: string) =>
+    ph(`${marker} ${escapeMarkdownV2(body)}`),
+  )
+
+  text = escapeMarkdownV2(text)
+
+  for (let i = placeholders.length - 1; i >= 0; i--) {
+    const value = placeholders[i] ?? ''
+    text = text.replace(`\x00PH${i}\x00`, value)
+  }
+
+  text = escapeStrayParens(text)
+
+  return text
+}
+
+/**
+ * Last-ditch pass over `( ) { }` that survived the placeholder dance. Runs
+ * outside code spans only — anything inside `` `…` `` or ``` ```…``` ``` is
+ * preserved verbatim. Mirrors hermes safety net at telegram.py:1957-1991.
+ */
+function escapeStrayParens(text: string): string {
+  const segments = text.split(/(```[\s\S]*?```|`[^`]+`)/g)
+  return segments
+    .map((seg, idx) => {
+      if (idx % 2 === 1) return seg
+      return seg.replace(/[(){}]/g, (ch, offset: number) => {
+        if (offset > 0 && seg[offset - 1] === '\\') return ch
+        if (ch === '(' && offset > 0 && seg[offset - 1] === ']') return ch
+        if (ch === ')' && isInsideLinkUrl(seg, offset)) return ch
+        return `\\${ch}`
+      })
+    })
+    .join('')
+}
+
+/**
+ * Detect GFM table blocks in the brain's reply and wrap them in ``` fences.
+ * TG MarkdownV2 doesn't render tables; without the fence, pipes show literally
+ * and columns drift. With the fence, TG renders monospace + preserves the
+ * brain's space padding so columns line up.
+ *
+ * Table boundary: a `|...|` row immediately followed by a separator row
+ * `|---|---|` (or `:---:`, `---|---`, etc.) is the start. Contiguous `|...|`
+ * data rows are pulled into the same block. First non-pipe line ends it.
+ */
+const TABLE_SEPARATOR_RE = /^\s*\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)*\|?\s*$/
+const TABLE_ROW_RE = /^\s*\|.+\|?\s*$/
+
+export function wrapGfmTablesInCodeBlocks(text: string): string {
+  const lines = text.split('\n')
+  const out: string[] = []
+  let i = 0
+  while (i < lines.length) {
+    const line = lines[i] ?? ''
+    if (
+      TABLE_ROW_RE.test(line) &&
+      i + 1 < lines.length &&
+      TABLE_SEPARATOR_RE.test(lines[i + 1] ?? '')
+    ) {
+      const block: string[] = [line, lines[i + 1] ?? '']
+      let j = i + 2
+      while (j < lines.length && TABLE_ROW_RE.test(lines[j] ?? '')) {
+        block.push(lines[j] ?? '')
+        j += 1
+      }
+      out.push('```')
+      out.push(...block)
+      out.push('```')
+      i = j
+      continue
+    }
+    out.push(line)
+    i += 1
+  }
+  return out.join('\n')
+}
+
+function isInsideLinkUrl(seg: string, closeIdx: number): boolean {
+  let depth = 0
+  for (let j = closeIdx - 1; j >= Math.max(closeIdx - 2000, 0); j--) {
+    const ch = seg[j]
+    if (ch === ')') {
+      depth += 1
+      continue
+    }
+    if (ch !== '(') continue
+    depth -= 1
+    if (depth >= 0) continue
+    return j > 0 && seg[j - 1] === ']'
+  }
+  return false
+}

package/src/pairing-flow.ts

@@ -0,0 +1,31 @@
+// Pairing-flow message formatter.
+//
+// When an unknown user DMs the bot, the listener replies with a pairing code
+// they can give to the operator. The operator approves out-of-band via
+// `nebula pairing approve telegram <code>`, which writes the user-id to
+// `~/.nebula/agents/<id>/pairing/telegram-approved.json`. The next message
+// from that user passes sanitize and reaches the brain.
+
+export interface PairingMessageOpts {
+  code: string
+  agentName?: string
+  /** Optional override of the approval CLI hint. */
+  approveCommand?: string
+}
+
+export function formatPairingMessage(opts: PairingMessageOpts): string {
+  const cmd = opts.approveCommand ?? `nebula pairing approve telegram ${opts.code}`
+  const greeting = opts.agentName
+    ? `🔐 Hi! I'm ${opts.agentName} and I don't recognize you yet.`
+    : "🔐 Hi! I don't recognize you yet."
+  return [
+    greeting,
+    '',
+    `Your pairing code: ${opts.code}`,
+    '',
+    'Send this code to the bot owner and ask them to approve you. They will run:',
+    `  ${cmd}`,
+    '',
+    "Codes expire in 1 hour. Once approved, send your next message and I'll respond.",
+  ].join('\n')
+}

package/src/progress.ts

@@ -0,0 +1,240 @@
+/**
+ * Tool-call progress tracker for live TG dispatch surfacing.
+ *
+ * Mirrors hermes' `send_progress_messages` (run.py:7070-7272): the agent's
+ * tool calls accumulate into a single "scratch" TG message that gets edited
+ * in place as the brain progresses through the turn. Final answer arrives
+ * later as a separate message.
+ *
+ * Behavior:
+ *  - First `push` sends a new message and saves messageId.
+ *  - Subsequent pushes within the throttle window are coalesced — a single
+ *    trailing edit fires after the throttle elapses.
+ *  - On a TG flood error (HTTP 429), `canEdit` flips off and remaining
+ *    pushes go as separate messages instead of edits.
+ *  - All errors swallowed: progress is best-effort, never blocks dispatch.
+ *  - `finalize()` is idempotent and forces any pending edit to flush.
+ *
+ * Tool emoji mapping is a small allowlist; everything else gets the wrench.
+ * Args preview is provided by the brain via `BrainToolEvent.argsPreview`
+ * (see `previewToolArgs` in og-compute.ts).
+ */
+import type { Bot } from 'grammy'
+import { escapeMarkdownV2, isMarkdownParseError, stripMarkdownV2 } from './markdown'
+
+const PROGRESS_EDIT_INTERVAL_MS = 1_500
+/** TG hard cap is 4096; keep margin for `(N/N)` suffix and edit growth. */
+const PROGRESS_TEXT_CAP = 3_800
+
+const TOOL_EMOJI: Record<string, string> = {
+  'shell.run': '💻',
+  'shell.cd': '📁',
+  'shell.process_start': '🚀',
+  'shell.process_output': '📥',
+  'shell.process_list': '📋',
+  'shell.process_kill': '🛑',
+  'fs.read': '📄',
+  'fs.write': '✏️',
+  'fs.patch': '🩹',
+  'fs.search': '🔍',
+  'web.fetch': '🌐',
+  'browser.navigate': '🌐',
+  'browser.snapshot': '📸',
+  'browser.click': '🖱️',
+  'browser.type': '⌨️',
+  'browser.scroll': '🖱️',
+  'browser.back': '⬅️',
+  'browser.press': '⌨️',
+  'browser.get_images': '🖼️',
+  'browser.console': '🛠',
+  'browser.vision': '👁',
+  'memory.read': '🧠',
+  'memory.save': '💾',
+  todo: '📝',
+  clarify: '❓',
+  'skills.list': '📚',
+  'skills.view': '📖',
+  'skills.manage': '🛠',
+  'session.search': '🔎',
+  'code.execute': '🐍',
+  'vision.analyze': '👁',
+  'delegate.task': '🤝',
+  'tool.search': '🔧',
+  'chain.gas': '⛽',
+  'chain.balance': '💰',
+  'chain.contract': '📜',
+  'chain.tx': '📝',
+  'wallet.transfer': '💸',
+  'swap.quote': '🔁',
+  'swap.execute': '🔄',
+  'stake.delegate': '🥩',
+  'comms.send': '📨',
+  'comms.list': '📬',
+  'market.list': '🛒',
+  'market.bid': '🪙',
+  'account.info': 'ℹ️',
+}
+
+interface ProgressEvent {
+  kind: 'start' | 'end'
+  tool: string
+  callId: string
+  argsPreview?: string
+  ok?: boolean
+}
+
+export class ProgressTracker {
+  private messageId: number | null = null
+  /** Map of callId → line index in `lines` so 'end' events can mark ✓/✗. */
+  private callIndex = new Map<string, number>()
+  private lines: string[] = []
+  private lastEditTs = 0
+  /** Last text we successfully sent or edited; used to skip no-op flushes. */
+  private lastFlushedText = ''
+  private canEdit = true
+  private pendingTimer: ReturnType<typeof setTimeout> | null = null
+  private finalized = false
+  /**
+   * Serialize all flush operations so the start-event's sendMessage finishes
+   * (assigning messageId) before any end-event's flush runs. Without this
+   * lock, fast tools that fire start+end within ~5ms (e.g. strict-deny path)
+   * would race two parallel sendMessage calls, producing a duplicate "tool
+   * starting" message followed by a separate "tool ended ✗" message instead
+   * of one in-place edit. v0.22.1 fix.
+   */
+  private flushLock: Promise<void> = Promise.resolve()
+
+  constructor(
+    private readonly bot: Bot,
+    private readonly chatId: number,
+  ) {}
+
+  /**
+   * Add an event to the progress timeline. Drives a sendMessage on first
+   * call, editMessageText on subsequent calls (throttled at 1.5s).
+   *
+   * Returns the in-flight flush promise so dispatch can `await tracker.push`
+   * if it wants strict ordering, but normal use is fire-and-forget.
+   */
+  async push(ev: ProgressEvent): Promise<void> {
+    if (this.finalized) return
+    if (ev.kind === 'start') {
+      const line = formatStartLine(ev)
+      this.callIndex.set(ev.callId, this.lines.length)
+      this.lines.push(line)
+    } else {
+      const idx = this.callIndex.get(ev.callId)
+      if (idx == null || this.lines[idx] == null) return
+      this.lines[idx] = `${this.lines[idx]} ${ev.ok === false ? '✗' : '✓'}`
+    }
+    // Serialize: subsequent flushes wait for any in-flight sendMessage to
+    // resolve so the second flush sees the assigned messageId and routes to
+    // editMessageText, not a second sendMessage. v0.22.1 fix for fast-tool
+    // double-message regression.
+    const previous = this.flushLock
+    this.flushLock = previous.then(() => this.flush()).catch(() => {})
+    await this.flushLock
+  }
+
+  /**
+   * Force any pending throttled edit to fire NOW, then mark the tracker
+   * closed. Future pushes are no-ops.
+   */
+  async finalize(): Promise<void> {
+    if (this.finalized) return
+    if (this.pendingTimer) {
+      clearTimeout(this.pendingTimer)
+      this.pendingTimer = null
+    }
+    // Serialize through the lock so finalize doesn't race a still-flying
+    // push from the brain. Important for fast tools where end-event flush
+    // and finalize() race the same scratch message edit.
+    const previous = this.flushLock
+    this.flushLock = previous.then(() => this.flush(true)).catch(() => {})
+    await this.flushLock
+    this.finalized = true
+  }
+
+  /**
+   * Whether the tracker has rendered anything yet. Used by the listener to
+   * decide whether to skip the final reply ("..." sandwich UX).
+   */
+  hasRendered(): boolean {
+    return this.messageId !== null
+  }
+
+  private async flush(force = false): Promise<void> {
+    if (this.lines.length === 0) return
+    const text = capProgressText(this.lines.join('\n'))
+    // Skip no-op flushes: nothing changed since the last send/edit.
+    if (text === this.lastFlushedText) return
+    const remaining = PROGRESS_EDIT_INTERVAL_MS - (Date.now() - this.lastEditTs)
+    if (!force && remaining > 0 && this.messageId !== null) {
+      // Throttle: schedule one trailing edit if not already pending.
+      if (!this.pendingTimer) {
+        this.pendingTimer = setTimeout(() => {
+          this.pendingTimer = null
+          void this.flush()
+        }, remaining)
+      }
+      return
+    }
+    this.pendingTimer = null
+    const md = escapeMarkdownV2(text)
+    try {
+      if (this.messageId === null) {
+        const sent = await this.bot.api.sendMessage(this.chatId, md, {
+          parse_mode: 'MarkdownV2',
+        })
+        this.messageId = sent.message_id
+      } else if (this.canEdit) {
+        await this.bot.api.editMessageText(this.chatId, this.messageId, md, {
+          parse_mode: 'MarkdownV2',
+        })
+      } else {
+        // Flood-mode fallback: append the latest line as a new message.
+        const lastLine = this.lines[this.lines.length - 1] ?? ''
+        await this.bot.api.sendMessage(this.chatId, escapeMarkdownV2(lastLine), {
+          parse_mode: 'MarkdownV2',
+        })
+      }
+      this.lastEditTs = Date.now()
+      this.lastFlushedText = text
+    } catch (err) {
+      const msg = String((err as Error).message ?? '').toLowerCase()
+      if (msg.includes('flood') || msg.includes('too many requests') || msg.includes('429')) {
+        this.canEdit = false
+      } else if (isMarkdownParseError(err)) {
+        // MarkdownV2 escape miss; retry as plain text once.
+        try {
+          const plain = stripMarkdownV2(text)
+          if (this.messageId === null) {
+            const sent = await this.bot.api.sendMessage(this.chatId, plain)
+            this.messageId = sent.message_id
+          } else {
+            await this.bot.api.editMessageText(this.chatId, this.messageId, plain)
+          }
+          this.lastEditTs = Date.now()
+        } catch {
+          /* swallow — never block dispatch */
+        }
+      }
+      // All other errors swallowed.
+    }
+  }
+}
+
+function formatStartLine(ev: ProgressEvent): string {
+  const emoji = TOOL_EMOJI[ev.tool] ?? '🔧'
+  if (ev.argsPreview && ev.argsPreview.length > 0) {
+    return `${emoji} ${ev.tool}: ${ev.argsPreview}`
+  }
+  return `${emoji} ${ev.tool}`
+}
+
+function capProgressText(text: string): string {
+  if (text.length <= PROGRESS_TEXT_CAP) return text
+  return `${text.slice(0, PROGRESS_TEXT_CAP - 1)}…`
+}
+
+export const PROGRESS_EDIT_INTERVAL = PROGRESS_EDIT_INTERVAL_MS

package/src/reactions.ts

@@ -0,0 +1,54 @@
+/**
+ * Atomic reaction state machine: 👀 (processing) → 👍 (success) | 👎 (error).
+ * Telegram's setMessageReaction REPLACES all bot reactions on the message in
+ * one call, so transitions are atomic. No remove step needed.
+ *
+ * If the bot doesn't have permission to react in the chat (rare for DMs but
+ * possible if the user blocks), the call fails silently and message handling
+ * continues. We never let a reaction failure abort a brain turn.
+ */
+import type { Bot } from 'grammy'
+import type { ReactionTypeEmoji } from 'grammy/types'
+
+type Emoji = ReactionTypeEmoji['emoji']
+
+export const REACTION_PROCESSING: Emoji = '\u{1F440}' // 👀
+export const REACTION_OK: Emoji = '\u{1F44D}' // 👍
+export const REACTION_ERR: Emoji = '\u{1F44E}' // 👎
+
+export async function reactProcessing(bot: Bot, chatId: number, messageId: number): Promise<void> {
+  await safeSetReaction(bot, chatId, messageId, REACTION_PROCESSING)
+}
+
+export async function reactSuccess(bot: Bot, chatId: number, messageId: number): Promise<void> {
+  await safeSetReaction(bot, chatId, messageId, REACTION_OK)
+}
+
+export async function reactError(bot: Bot, chatId: number, messageId: number): Promise<void> {
+  await safeSetReaction(bot, chatId, messageId, REACTION_ERR)
+}
+
+export async function clearReaction(bot: Bot, chatId: number, messageId: number): Promise<void> {
+  await safeSetReactionEmpty(bot, chatId, messageId)
+}
+
+async function safeSetReaction(
+  bot: Bot,
+  chatId: number,
+  messageId: number,
+  emoji: Emoji,
+): Promise<void> {
+  try {
+    await bot.api.setMessageReaction(chatId, messageId, [{ type: 'emoji', emoji }])
+  } catch {
+    // Reaction failures are cosmetic; never block the turn on them.
+  }
+}
+
+async function safeSetReactionEmpty(bot: Bot, chatId: number, messageId: number): Promise<void> {
+  try {
+    await bot.api.setMessageReaction(chatId, messageId, [])
+  } catch {
+    // Same: silent.
+  }
+}

package/src/recovery.ts

@@ -0,0 +1,131 @@
+// Listener recovery primitives.
+//
+// Token lock: only one nebula process per machine can poll a given bot token.
+// Cross-machine collisions (laptop + sandbox both polling same bot) still
+// produce 409 Conflict on bot.start. We classify those failures so callers
+// can decide retry/abort. The 3-retry-409 + 10-retry-network state machines
+// hermes runs internally are deferred to v0.19 when we adopt @grammyjs/runner
+// for finer-grained polling control. For v0.18.x the lock plus explicit
+// classification is sufficient.
+
+import type { Bot } from 'grammy'
+import {
+  type ClearStaleScopedLockResult,
+  DEFAULT_LOCK_TTL_SECONDS,
+  type ScopedLockHandle,
+  acquireScopedLock,
+  clearStaleScopedLock,
+} from 'nebula-ai-core'
+
+export const TELEGRAM_TOKEN_LOCK_SCOPE = 'telegram-bot-token'
+
+export class BotTokenLockedError extends Error {
+  readonly heldByPid: number
+  readonly heldSinceSec: number
+  constructor(pid: number, sinceSec: number) {
+    super(`telegram bot token already in use by pid ${pid} (started ${sinceSec})`)
+    this.name = 'BotTokenLockedError'
+    this.heldByPid = pid
+    this.heldSinceSec = sinceSec
+  }
+}
+
+export interface AcquireTokenLockOpts {
+  agentId?: string
+  ttl?: number
+  rootDir?: string
+}
+
+export interface TokenLock {
+  release: () => void
+  refresh: () => boolean
+}
+
+export function acquireTelegramTokenLock(
+  botToken: string,
+  opts: AcquireTokenLockOpts = {},
+): TokenLock {
+  const identity = `${opts.agentId ?? 'default'}:${botToken}`
+  const result = acquireScopedLock({
+    scope: TELEGRAM_TOKEN_LOCK_SCOPE,
+    identity,
+    ttl: opts.ttl ?? DEFAULT_LOCK_TTL_SECONDS,
+    rootDir: opts.rootDir,
+  })
+  if (!result.acquired || !result.handle) {
+    const ex = result.existing ?? { pid: -1, startedAt: 0, updatedAt: 0 }
+    throw new BotTokenLockedError(ex.pid, ex.startedAt)
+  }
+  return wrapLockHandle(result.handle)
+}
+
+function wrapLockHandle(handle: ScopedLockHandle): TokenLock {
+  return { release: handle.releaseFn, refresh: handle.refreshFn }
+}
+
+/**
+ * v0.21.5: gateway boot must proactively reap a zombie/crashed listener's
+ * bot-token lock before TelegramListener.start() runs. Without this, the
+ * acquire path calls scheduleStartRetry which waits 30s × 12 attempts (6 min)
+ * for the TTL to expire — operators see "TG silent" the whole time.
+ *
+ * Returns whether a stale lock was cleared. Never deletes a lock held by a
+ * live foreign PID (that's the legitimate "another nebula is polling this bot"
+ * case, where the listener should fail loud).
+ *
+ * Identity hash matches `acquireTelegramTokenLock`: `${agentId ?? 'default'}:${botToken}`.
+ */
+export function clearStaleTelegramTokenLock(
+  botToken: string,
+  opts: AcquireTokenLockOpts = {},
+): ClearStaleScopedLockResult {
+  const identity = `${opts.agentId ?? 'default'}:${botToken}`
+  return clearStaleScopedLock({
+    scope: TELEGRAM_TOKEN_LOCK_SCOPE,
+    identity,
+    rootDir: opts.rootDir,
+  })
+}
+
+/**
+ * Pre-polling webhook clear. grammy does this internally on bot.start, but
+ * making it explicit lets us surface failures (rare but possible if someone
+ * sets a webhook between init and start_polling).
+ */
+export async function clearWebhookBeforePolling(bot: Bot): Promise<void> {
+  try {
+    await bot.api.deleteWebhook({ drop_pending_updates: false })
+  } catch {
+    // Best-effort; grammy retries on bot.start. Caller can opt in to logging.
+  }
+}
+
+export type StartFailureKind = 'conflict' | 'network' | 'auth' | 'fatal' | 'cancelled'
+
+export interface StartFailure {
+  kind: StartFailureKind
+  detail: string
+  retryable: boolean
+}
+
+export function classifyStartFailure(err: unknown): StartFailure {
+  const msg = err instanceof Error ? err.message : String(err)
+  const lower = msg.toLowerCase()
+  const code = (err as { error_code?: number }).error_code
+  if (code === 409) return { kind: 'conflict', detail: msg, retryable: true }
+  if (code === 401) return { kind: 'auth', detail: msg, retryable: false }
+  if (
+    lower.includes('econnreset') ||
+    lower.includes('econnrefused') ||
+    lower.includes('enetunreach') ||
+    lower.includes('socket hang up') ||
+    lower.includes('eai_again') ||
+    lower.includes('network')
+  ) {
+    return { kind: 'network', detail: msg, retryable: true }
+  }
+  if (lower.includes('aborted') || lower.includes('cancelled')) {
+    return { kind: 'cancelled', detail: msg, retryable: false }
+  }
+  return { kind: 'fatal', detail: msg, retryable: false }
+}