@s0nderlabs/anima-plugin-telegram 0.21.4 → 0.21.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@s0nderlabs/anima-plugin-telegram",
-  "version": "0.21.4",
+  "version": "0.21.6",
   "type": "module",
   "description": "Telegram gateway plugin for anima — long-poll bot, debounced dispatch, reactions, allowlist",
   "license": "MIT",

package/src/index.ts

@@ -80,6 +80,7 @@ export {
 export {
   acquireTelegramTokenLock,
   BotTokenLockedError,
+  clearStaleTelegramTokenLock,
   clearWebhookBeforePolling,
   classifyStartFailure,
   TELEGRAM_TOKEN_LOCK_SCOPE,

package/src/recovery.test.ts

@@ -1,11 +1,13 @@
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
-import { mkdtempSync, rmSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import {
   BotTokenLockedError,
   acquireTelegramTokenLock,
   classifyStartFailure,
+  clearStaleTelegramTokenLock,
   clearWebhookBeforePolling,
 } from './recovery'
 
@@ -91,6 +93,70 @@ describe('classifyStartFailure', () => {
   })
 })
 
+describe('clearStaleTelegramTokenLock', () => {
+  it('returns no-lock when nothing exists', () => {
+    const r = clearStaleTelegramTokenLock('token-xyz', { agentId: 'agent-7', rootDir: lockDir })
+    expect(r.cleared).toBe(false)
+    expect(r.reason).toBe('no-lock')
+  })
+
+  it('returns alive-pid when a live owner holds the lock', () => {
+    const lock = acquireTelegramTokenLock('token-live', { agentId: 'agent-7', rootDir: lockDir })
+    const r = clearStaleTelegramTokenLock('token-live', { agentId: 'agent-7', rootDir: lockDir })
+    expect(r.cleared).toBe(false)
+    expect(r.reason).toBe('alive-pid')
+    lock.release()
+  })
+
+  it('clears a dead-PID lock written manually', () => {
+    const identity = 'agent-7:token-zombie'
+    const hash = createHash('sha256').update(identity).digest('hex').slice(0, 16)
+    const path = join(lockDir, `telegram-bot-token-${hash}.lock`)
+    writeFileSync(
+      path,
+      JSON.stringify({
+        pid: 999_996,
+        scope: 'telegram-bot-token',
+        identityHash: hash,
+        startedAt: Math.floor(Date.now() / 1000),
+        updatedAt: Math.floor(Date.now() / 1000),
+        ttl: 600,
+      }),
+    )
+    const r = clearStaleTelegramTokenLock('token-zombie', { agentId: 'agent-7', rootDir: lockDir })
+    expect(r.cleared).toBe(true)
+    expect(r.reason).toBe('cleared-stale')
+  })
+
+  it('lets a fresh acquire follow a clear', () => {
+    const identity = 'agent-X:token-recoverable'
+    const hash = createHash('sha256').update(identity).digest('hex').slice(0, 16)
+    const path = join(lockDir, `telegram-bot-token-${hash}.lock`)
+    writeFileSync(
+      path,
+      JSON.stringify({
+        pid: 999_995,
+        scope: 'telegram-bot-token',
+        identityHash: hash,
+        startedAt: 0,
+        updatedAt: 0,
+        ttl: 1,
+      }),
+    )
+    const cleanup = clearStaleTelegramTokenLock('token-recoverable', {
+      agentId: 'agent-X',
+      rootDir: lockDir,
+    })
+    expect(cleanup.cleared).toBe(true)
+    const lock = acquireTelegramTokenLock('token-recoverable', {
+      agentId: 'agent-X',
+      rootDir: lockDir,
+    })
+    expect(lock).toBeDefined()
+    lock.release()
+  })
+})
+
 describe('clearWebhookBeforePolling', () => {
   it('calls bot.api.deleteWebhook with drop_pending_updates=false', async () => {
     let called = false

package/src/recovery.ts

@@ -9,9 +9,11 @@
 // classification is sufficient.
 
 import {
+  type ClearStaleScopedLockResult,
   DEFAULT_LOCK_TTL_SECONDS,
   type ScopedLockHandle,
   acquireScopedLock,
+  clearStaleScopedLock,
 } from '@s0nderlabs/anima-core'
 import type { Bot } from 'grammy'
 
@@ -61,6 +63,30 @@ 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 anima 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