switchroom 0.18.7 → 0.18.9

package/telegram-plugin/tests/stream-controller-chunk-cap.test.ts

@@ -0,0 +1,122 @@
+/**
+ * Wire-level regression test for the chunk-boundary cap bug
+ * (fix/rich-render-chunk-boundary-cap).
+ *
+ * With `SWITCHROOM_RICH_RENDER` on, a near-cap body full of escapable chars
+ * (`_ * |`) makes `renderSafe` degrade the whole document to plain (its escaped
+ * rich form exceeds RICH_MESSAGE_MAX_CHARS). BEFORE the fix, the stream
+ * controller shipped that ~32k plain body through the plain `sendMessage`
+ * endpoint in ONE call — Telegram's plain endpoint caps at 4096, so the send
+ * is rejected (`message is too long`) and the streamed answer is dropped.
+ *
+ * AFTER the fix, `renderOutboundChunks` re-splits at safe boundaries so every
+ * emitted send fits its own wire cap: rich pieces <= 32768, plain pieces
+ * <= 4096, and no fenced block is bisected.
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { createStreamController } from "../stream-controller.js";
+import { createFakeBotApi } from "./fake-bot-api.js";
+import { RICH_MESSAGE_MAX_CHARS } from "../format.js";
+
+const PLAIN_CAP = 4096; // Telegram's legacy plain-text sendMessage cap (format.ts:29).
+
+function fenceCount(s: string): number {
+  return (s.match(/^```/gm) ?? []).length;
+}
+
+describe("stream-controller enforces the wire cap on the post-escape body", () => {
+  afterEach(() => {
+    delete process.env.SWITCHROOM_RICH_RENDER;
+  });
+
+  it("REGRESSION: near-cap escapable first send never exceeds the plain wire cap", async () => {
+    process.env.SWITCHROOM_RICH_RENDER = "1";
+    const bot = createFakeBotApi({ startMessageId: 1000 });
+    const unit = "a_b*c|d ";
+    const body = unit.repeat(Math.floor((RICH_MESSAGE_MAX_CHARS - 20) / unit.length));
+
+    const stream = createStreamController({
+      bot: bot as unknown as Parameters<typeof createStreamController>[0]["bot"],
+      chatId: "c1",
+      throttleMs: 0,
+    });
+    await stream.update(body);
+    await stream.finalize();
+
+    expect(bot.state.sent.length).toBeGreaterThan(0);
+    for (const s of bot.state.sent) {
+      // Every send fits the rich cap...
+      expect(s.text.length).toBeLessThanOrEqual(RICH_MESSAGE_MAX_CHARS);
+      // ...and a PLAIN send (rich !== true) additionally fits the 4096 plain
+      // endpoint cap — the invariant HEAD violated (one ~32k plain send).
+      if (!s.rich) expect(s.text.length).toBeLessThanOrEqual(PLAIN_CAP);
+      // No send bisects a fenced block.
+      expect(fenceCount(s.text) % 2).toBe(0);
+    }
+  }, 30000);
+
+  it("BLOCKER: multi-update oversize stream emits tails ONCE, not per edit tick", async () => {
+    // Reproduces the duplicate-flood blocker: an oversize body splits into N
+    // pieces. The FIRST flush (send path) emits the anchor + (N-1) tail
+    // messages. Every SUBSEQUENT throttled flush routes through the EDIT
+    // callback. The pre-fix code re-sent all (N-1) tails as brand-new messages
+    // on each edit tick, so `sent.length` grew by (N-1) every update. After the
+    // fix, tails are parked once and edited in place — `sent.length` is flat.
+    process.env.SWITCHROOM_RICH_RENDER = "1";
+    const bot = createFakeBotApi({ startMessageId: 3000 });
+    const unit = "a_b*c|d ";
+    // Near-cap body that degrades to plain and splits into several pieces.
+    const base = unit.repeat(Math.floor((RICH_MESSAGE_MAX_CHARS - 20) / unit.length));
+    // Distinct short prefix per flush so the HEAD piece actually changes —
+    // an unchanged head yields a not-modified edit, which short-circuits before
+    // the tail loop and would hide the duplicate-resend bug.
+    const bodyFor = (i: number) => `v${i} ${base}`;
+
+    const stream = createStreamController({
+      bot: bot as unknown as Parameters<typeof createStreamController>[0]["bot"],
+      chatId: "c1",
+      throttleMs: 0,
+    });
+
+    // First flush → send path: anchor + tails, emitted exactly once.
+    await stream.update(bodyFor(1));
+    const afterFirst = bot.state.sent.length;
+    expect(afterFirst).toBeGreaterThan(1); // genuinely multi-piece
+
+    // Drive several more oversize updates — each routes through the EDIT
+    // callback. The count must NOT grow: tails are edited in place, not resent.
+    await stream.update(bodyFor(2));
+    expect(bot.state.sent.length).toBe(afterFirst);
+    await stream.update(bodyFor(3));
+    expect(bot.state.sent.length).toBe(afterFirst);
+    await stream.update(bodyFor(4));
+    expect(bot.state.sent.length).toBe(afterFirst);
+    await stream.finalize();
+
+    // Final: exactly the anchor + tail set, no duplicates across the lifetime.
+    expect(bot.state.sent.length).toBe(afterFirst);
+    const ids = bot.state.sent.map((s) => s.message_id);
+    expect(new Set(ids).size).toBe(ids.length); // no duplicate message ids
+
+    // Every currently-visible message fits its wire cap and (for plain) 4096.
+    for (const s of bot.state.sent) {
+      const cur = bot.textOf(s.message_id) ?? "";
+      expect(cur.length).toBeLessThanOrEqual(RICH_MESSAGE_MAX_CHARS);
+      if (!s.rich) expect(cur.length).toBeLessThanOrEqual(PLAIN_CAP);
+    }
+  }, 30000);
+
+  it("flag OFF leaves the single-send path untouched", async () => {
+    const bot = createFakeBotApi({ startMessageId: 2000 });
+    const stream = createStreamController({
+      bot: bot as unknown as Parameters<typeof createStreamController>[0]["bot"],
+      chatId: "c1",
+      throttleMs: 0,
+    });
+    await stream.update("**hi** _there_");
+    await stream.finalize();
+    expect(bot.state.sent).toHaveLength(1);
+    expect(bot.state.sent[0].rich).toBe(true);
+    expect(bot.state.sent[0].text).toBe("**hi** _there_");
+  });
+});

package/telegram-plugin/tests/turn-flush-safety.test.ts

@@ -261,10 +261,24 @@ describe('#2798 turn-flush punctuation/bold parity with reply', () => {
   )
 
   it('reply path: normalizes AFTER redact and BEFORE the voice scrub', () => {
-    const start = gatewaySrc.indexOf('async function executeReply(')
-    const redactIdx = gatewaySrc.indexOf(`redactOutboundText(text, 'reply')`, start)
-    const normIdx = gatewaySrc.indexOf('stripExcessBold(normalizePunctuation(text))', start)
-    const scrubIdx = gatewaySrc.indexOf('scrubVoice(text)', start)
+    // #2996: the reply-path entry pipeline moved into outbound-send-path.ts
+    // (`normalizeOutboundBody`). The reply path delegates to it via
+    // `normalizeOutboundBody(rawText, 'reply', redactOutboundText)`; the
+    // redact→normalize→scrub ordering is now pinned in the module source.
+    const replyDelegates = gatewaySrc.indexOf(
+      `normalizeOutboundBody(rawText, 'reply', redactOutboundText)`,
+      gatewaySrc.indexOf('async function executeReply('),
+    )
+    expect(replyDelegates).toBeGreaterThan(0)
+
+    const moduleSrc = readFileSync(
+      new URL('../gateway/outbound-send-path.ts', import.meta.url),
+      'utf8',
+    )
+    const start = moduleSrc.indexOf('export function normalizeOutboundBody(')
+    const redactIdx = moduleSrc.indexOf('redact(text, site)', start)
+    const normIdx = moduleSrc.indexOf('stripExcessBold(normalizePunctuation(text))', start)
+    const scrubIdx = moduleSrc.indexOf('scrubVoice(text)', start)
     expect(start).toBeGreaterThan(0)
     expect(redactIdx).toBeGreaterThan(start)
     expect(normIdx).toBeGreaterThan(redactIdx) // normalize AFTER the reply redact

package/telegram-plugin/tests/vault-approval-posture.test.ts

@@ -41,10 +41,14 @@ import { readFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { resolveVaultApprovalPosture } from '../vault-approval-posture.js'
 
-const gatewaySrc = readFileSync(
-  resolve(__dirname, '..', 'gateway', 'gateway.ts'),
-  'utf-8',
-)
+// #2996 Phase 5: the callback-query handler families moved verbatim to
+// gateway/callback-query-handlers.ts; these pins read the gateway source
+// COMBINED with that module so the wiring assertions keep covering the
+// same runtime source text.
+const gatewaySrc =
+  readFileSync(resolve(__dirname, '..', 'gateway', 'gateway.ts'), 'utf-8') +
+  '\n' +
+  readFileSync(resolve(__dirname, '..', 'gateway', 'callback-query-handlers.ts'), 'utf-8')
 
 function sliceAccessApproveBlock(): string {
   const fn =
@@ -73,7 +77,10 @@ describe('vault grant approval posture — module-level wiring', () => {
 describe('handleVaultRequestAccessCallback — posture branch', () => {
   it('mints via posture attestation (NOT in-memory passphrase) when posture is telegram-id', () => {
     const approveBlock = sliceAccessApproveBlock()
-    expect(approveBlock).toMatch(/VAULT_APPROVAL_AUTH_MODE === ['"]telegram-id['"]/)
+    // #2996 Phase 5: inside the extracted handler module the mutable gateway
+    // `let` is read via the injected getter (gateway wires it as
+    // `getVaultApprovalAuthMode: () => VAULT_APPROVAL_AUTH_MODE`).
+    expect(approveBlock).toMatch(/getVaultApprovalAuthMode\(\) === ['"]telegram-id['"]/)
     // Pinned: the call shape MUST be `{ kind: 'posture' }`. If the
     // gateway ever reverts to passing a real passphrase here, the
     // bypass surface returns.
@@ -138,7 +145,8 @@ describe('handleVaultRequestSaveCallback — posture-attested broker put (#1115
     // calls `defaultVaultWritePosture` (posture-attested broker put,
     // no passphrase). Under passphrase mode it keeps the legacy
     // cached-passphrase + shell-out path.
-    expect(fnBlock).toMatch(/VAULT_APPROVAL_AUTH_MODE === 'telegram-id'/)
+    // #2996 Phase 5: getter read of the gateway's mutable posture `let`.
+    expect(fnBlock).toMatch(/getVaultApprovalAuthMode\(\) === 'telegram-id'/)
     expect(fnBlock).toMatch(/defaultVaultWritePosture\(/)
     // Passphrase-mode branch still present.
     expect(fnBlock).toMatch(/vaultPassphraseCache\.get\(pending\.chat_id\)/)
@@ -203,7 +211,7 @@ describe('allowlist is the first gate in every vault callback handler', () => {
         'mintGrantViaBroker',
         'performVaultAccessApproval',
         'pendingVaultOps.set',
-        "VAULT_APPROVAL_AUTH_MODE === 'telegram-id'",
+        "getVaultApprovalAuthMode() === 'telegram-id'",
         'attest_via_posture',
       ]) {
         expect(

package/telegram-plugin/tests/vault-grant-auto-resume.test.ts

@@ -23,10 +23,14 @@ import { describe, it, expect } from "vitest";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
-const gatewaySrc = readFileSync(
-  resolve(__dirname, "..", "gateway", "gateway.ts"),
-  "utf-8",
-);
+// #2996 Phase 5: the callback-query handler families moved verbatim to
+// gateway/callback-query-handlers.ts; these pins read the gateway source
+// COMBINED with that module so the wiring assertions keep covering the
+// same runtime source text.
+const gatewaySrc =
+  readFileSync(resolve(__dirname, "..", "gateway", "gateway.ts"), "utf-8") +
+  "\n" +
+  readFileSync(resolve(__dirname, "..", "gateway", "callback-query-handlers.ts"), "utf-8");
 
 function extractPerformBlock(): string {
   const start = gatewaySrc.indexOf("async function performVaultAccessApproval");

package/telegram-plugin/tests/vault-grant-union.test.ts

@@ -22,10 +22,14 @@ import { describe, it, expect } from "vitest";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
-const gatewaySrc = readFileSync(
-  resolve(__dirname, "..", "gateway", "gateway.ts"),
-  "utf-8",
-);
+// #2996 Phase 5: the callback-query handler families moved verbatim to
+// gateway/callback-query-handlers.ts; these pins read the gateway source
+// COMBINED with that module so the wiring assertions keep covering the
+// same runtime source text.
+const gatewaySrc =
+  readFileSync(resolve(__dirname, "..", "gateway", "gateway.ts"), "utf-8") +
+  "\n" +
+  readFileSync(resolve(__dirname, "..", "gateway", "callback-query-handlers.ts"), "utf-8");
 
 function extractPerformBlock(): string {
   const start = gatewaySrc.indexOf("async function performVaultAccessApproval");

package/telegram-plugin/tests/vault-grant-wizard.test.ts

@@ -40,7 +40,14 @@ function readSrc(rel: string): string {
 // `telegram-plugin/docs/gateway-server-split.md` for the F4 cleanup notes.
 
 describe('/vault grant inline-keyboard wizard — gateway (#227, #262, #265)', () => {
-  const gatewaySrc = readSrc('telegram-plugin/gateway/gateway.ts')
+  // #2996 Phase 5: the callback-query handler families moved verbatim to
+  // gateway/callback-query-handlers.ts; these pins read the gateway source
+  // COMBINED with that module so the wiring assertions keep covering the
+  // same runtime source text.
+  const gatewaySrc =
+    readSrc('telegram-plugin/gateway/gateway.ts') +
+    '\n' +
+    readSrc('telegram-plugin/gateway/callback-query-handlers.ts')
 
   it('gateway.ts: dispatches /vault grant to the wizard entry', () => {
     expect(gatewaySrc).toMatch(/\/vault grant/i)

package/telegram-plugin/tests/vault-grants-revoke.test.ts

@@ -33,7 +33,14 @@ import { join, dirname } from 'node:path'
 const __dir = dirname(fileURLToPath(import.meta.url))
 const pluginDir = join(__dir, '..')
 
-const gatewaySrc = readFileSync(join(pluginDir, 'gateway', 'gateway.ts'), 'utf8')
+// #2996 Phase 5: the callback-query handler families moved verbatim to
+// gateway/callback-query-handlers.ts; these pins read the gateway source
+// COMBINED with that module so the wiring assertions keep covering the
+// same runtime source text.
+const gatewaySrc =
+  readFileSync(join(pluginDir, 'gateway', 'gateway.ts'), 'utf8') +
+  '\n' +
+  readFileSync(join(pluginDir, 'gateway', 'callback-query-handlers.ts'), 'utf8')
 
 // ─── helpers ─────────────────────────────────────────────────────────────────
 

package/telegram-plugin/tests/vault-key-regex-allows-slash.test.ts

@@ -27,10 +27,14 @@ import { describe, it, expect } from "vitest";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
-const gatewaySrc = readFileSync(
-  resolve(__dirname, "..", "gateway", "gateway.ts"),
-  "utf-8",
-);
+// #2996 Phase 5: the callback-query handler families moved verbatim to
+// gateway/callback-query-handlers.ts; these pins read the gateway source
+// COMBINED with that module so the wiring assertions keep covering the
+// same runtime source text.
+const gatewaySrc =
+  readFileSync(resolve(__dirname, "..", "gateway", "gateway.ts"), "utf-8") +
+  "\n" +
+  readFileSync(resolve(__dirname, "..", "gateway", "callback-query-handlers.ts"), "utf-8");
 
 /** The exported regex literal — what the gateway actually validates against. */
 function extractVaultKeyRegex(): RegExp {

package/telegram-plugin/tests/vault-request-access-tool.test.ts

@@ -23,10 +23,14 @@ const bridgeSrc = readFileSync(
   resolve(__dirname, '..', 'bridge', 'bridge.ts'),
   'utf-8',
 )
-const gatewaySrc = readFileSync(
-  resolve(__dirname, '..', 'gateway', 'gateway.ts'),
-  'utf-8',
-)
+// #2996 Phase 5: the callback-query handler families moved verbatim to
+// gateway/callback-query-handlers.ts; these pins read the gateway source
+// COMBINED with that module so the wiring assertions keep covering the
+// same runtime source text.
+const gatewaySrc =
+  readFileSync(resolve(__dirname, '..', 'gateway', 'gateway.ts'), 'utf-8') +
+  '\n' +
+  readFileSync(resolve(__dirname, '..', 'gateway', 'callback-query-handlers.ts'), 'utf-8')
 
 describe('vault_request_access (#1012)', () => {
   it('bridge advertises the tool to MCP clients', () => {

package/telegram-plugin/tests/vault-request-access-unlock-resume.test.ts

@@ -22,10 +22,14 @@ import { describe, it, expect } from 'vitest'
 import { readFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 
-const gatewaySrc = readFileSync(
-  resolve(__dirname, '..', 'gateway', 'gateway.ts'),
-  'utf-8',
-)
+// #2996 Phase 5: the callback-query handler families moved verbatim to
+// gateway/callback-query-handlers.ts; these pins read the gateway source
+// COMBINED with that module so the wiring assertions keep covering the
+// same runtime source text.
+const gatewaySrc =
+  readFileSync(resolve(__dirname, '..', 'gateway', 'gateway.ts'), 'utf-8') +
+  '\n' +
+  readFileSync(resolve(__dirname, '..', 'gateway', 'callback-query-handlers.ts'), 'utf-8')
 
 describe('vault_request_access — tap-to-unlock-and-approve UX', () => {
   it('declares the passphrase-for-access-approve PendingVaultOp variant', () => {

package/telegram-plugin/tests/voice-send.test.ts

@@ -0,0 +1,308 @@
+/**
+ * Telegram file_id reuse for the on-demand '🔊 Listen' send path.
+ *
+ * gateway.ts is a 25k-line module with import-time side effects, so the send
+ * decision core lives in ../voice-send.ts (imported by the gateway). These
+ * tests drive the real orchestrator + cache primitive with a mocked bot api,
+ * proving the observable contract the gateway wires up:
+ *
+ *   (a) FIRST tap (no stored id) uploads via InputFile and captures the
+ *       returned file_id onto the cache entry;
+ *   (b) SECOND tap sends BY the file_id string — no disk read, no InputFile;
+ *   (c) a file_id send REJECTED as stale (400) falls back to a re-upload and
+ *       refreshes the stored id, so a dead id never permanently breaks Listen.
+ */
+
+import { describe, it, expect } from 'bun:test'
+import {
+  sendVoiceReusingFileId,
+  extractVoiceFileId,
+  isInvalidTelegramFileIdError,
+  isHttp400Error,
+  type SentVoiceMessage,
+} from '../voice-send.js'
+import { VoiceOnDemandCache } from '../voice-ondemand.js'
+
+/** A minimal grammy-shaped 400 error (duck-typed the way the gateway sees it). */
+function grammy400(description: string): Error {
+  return Object.assign(new Error(description), { error_code: 400, description })
+}
+
+/** Sent-message stub echoing a file_id, as Telegram returns from sendVoice. */
+function sentWithFileId(fileId: string): SentVoiceMessage {
+  return { voice: { file_id: fileId } }
+}
+
+const OGG = new Uint8Array([0x4f, 0x67, 0x67, 0x53]) // OggS magic
+
+describe('sendVoiceReusingFileId — file_id reuse contract', () => {
+  it('(a) first tap: no stored id → uploads via InputFile, captures the id', async () => {
+    const calls: string[] = []
+    let byFileId = 0
+    let uploaded = 0
+    let captured: string | null = null
+
+    const res = await sendVoiceReusingFileId({
+      fileId: null,
+      sendByFileId: async () => {
+        byFileId++
+        return null
+      },
+      loadAudio: async () => {
+        calls.push('loadAudio')
+        return OGG
+      },
+      sendByUpload: async (audio) => {
+        uploaded++
+        expect(audio).toBe(OGG)
+        return sentWithFileId('FILE_ID_1')
+      },
+      onFileId: (id) => {
+        captured = id
+      },
+    })
+
+    expect(res).toEqual({ ok: true, path: 'upload', refreshed: false })
+    expect(byFileId).toBe(0) // never tried the id path — none stored
+    expect(uploaded).toBe(1) // exactly one upload
+    expect(calls).toEqual(['loadAudio']) // audio WAS loaded on the first tap
+    expect(captured).toBe('FILE_ID_1') // id captured for reuse
+  })
+
+  it('(b) second tap: stored id → sends by file_id string, no disk read, no InputFile', async () => {
+    let loadAudioCalls = 0
+    let uploadCalls = 0
+    let sentId: string | null = null
+
+    const res = await sendVoiceReusingFileId({
+      fileId: 'FILE_ID_1',
+      sendByFileId: async (fid) => {
+        sentId = fid
+        return sentWithFileId('FILE_ID_1') // Telegram echoes the same id
+      },
+      loadAudio: async () => {
+        loadAudioCalls++ // MUST NOT happen — proves no disk read
+        return OGG
+      },
+      sendByUpload: async () => {
+        uploadCalls++ // MUST NOT happen — proves no re-upload
+        return null
+      },
+      onFileId: () => {},
+    })
+
+    expect(res).toEqual({ ok: true, path: 'file_id', refreshed: false })
+    expect(sentId).toBe('FILE_ID_1') // sent BY the string id
+    expect(loadAudioCalls).toBe(0) // no disk read
+    expect(uploadCalls).toBe(0) // no InputFile upload
+  })
+
+  it('(c) stale id (400): falls back to re-upload and refreshes the stored id', async () => {
+    let byFileId = 0
+    let uploaded = 0
+    let refreshedTo: string | null = null
+
+    const res = await sendVoiceReusingFileId({
+      fileId: 'STALE_ID',
+      sendByFileId: async () => {
+        byFileId++
+        throw grammy400('Bad Request: wrong file identifier/HTTP URL specified')
+      },
+      loadAudio: async () => OGG,
+      sendByUpload: async () => {
+        uploaded++
+        return sentWithFileId('FRESH_ID')
+      },
+      onFileId: (id) => {
+        refreshedTo = id
+      },
+    })
+
+    expect(res).toEqual({ ok: true, path: 'upload', refreshed: true })
+    expect(byFileId).toBe(1) // tried the stale id once
+    expect(uploaded).toBe(1) // then re-uploaded
+    expect(refreshedTo).toBe('FRESH_ID') // stored id refreshed, not left stale
+  })
+
+  it('a NON-stale send error is a real failure — no silent re-upload', async () => {
+    let uploaded = 0
+    const res = await sendVoiceReusingFileId({
+      fileId: 'FILE_ID_1',
+      sendByFileId: async () => {
+        throw Object.assign(new Error('forbidden'), { error_code: 403 })
+      },
+      loadAudio: async () => OGG,
+      sendByUpload: async () => {
+        uploaded++
+        return null
+      },
+      onFileId: () => {},
+    })
+    expect(res.ok).toBe(false)
+    expect(uploaded).toBe(0) // did NOT paper over a 403 with an upload
+  })
+
+  it('(C1) UNKNOWN-wording 400: re-uploads + refreshes id even outside the stale-id substrings', async () => {
+    // A 400 whose text is NOT in isInvalidTelegramFileIdError's substring set.
+    // Pre-tweak (substring-gated) this classified as send-failed and never
+    // refreshed the id; post-tweak ANY 400 recovers via re-upload.
+    let byFileId = 0
+    let uploaded = 0
+    let refreshedTo: string | null = null
+
+    const err400 = grammy400('Bad Request: some brand-new file rejection wording')
+    expect(isInvalidTelegramFileIdError(err400)).toBe(false) // guard: outside old substrings
+    expect(isHttp400Error(err400)).toBe(true) // but IS a 400 → now re-uploadable
+
+    const res = await sendVoiceReusingFileId({
+      fileId: 'STALE_ID',
+      sendByFileId: async () => {
+        byFileId++
+        throw err400
+      },
+      loadAudio: async () => OGG,
+      sendByUpload: async () => {
+        uploaded++
+        return sentWithFileId('FRESH_ID')
+      },
+      onFileId: (id) => {
+        refreshedTo = id
+      },
+    })
+
+    expect(res).toEqual({ ok: true, path: 'upload', refreshed: true })
+    expect(byFileId).toBe(1) // tried the id once
+    expect(uploaded).toBe(1) // then re-uploaded on the unknown 400
+    expect(refreshedTo).toBe('FRESH_ID') // stored id refreshed, not left stale
+  })
+
+  it('(C1) a network error (no error_code) still does NOT re-upload', async () => {
+    let uploaded = 0
+    const res = await sendVoiceReusingFileId({
+      fileId: 'FILE_ID_1',
+      sendByFileId: async () => {
+        throw new Error('ECONNRESET') // no error_code → not a 400
+      },
+      loadAudio: async () => OGG,
+      sendByUpload: async () => {
+        uploaded++
+        return null
+      },
+      onFileId: () => {},
+    })
+    expect(res.ok).toBe(false)
+    expect(uploaded).toBe(0) // transient network error is a real failure, not a re-upload
+  })
+
+  it('(C1) re-upload after a 400 ALSO fails → returns failure, no second re-upload', async () => {
+    let byFileId = 0
+    let uploaded = 0
+    let refreshed: string | null = null
+
+    const res = await sendVoiceReusingFileId({
+      fileId: 'STALE_ID',
+      sendByFileId: async () => {
+        byFileId++
+        throw grammy400('Bad Request: totally unfamiliar 400 wording')
+      },
+      loadAudio: async () => OGG,
+      sendByUpload: async () => {
+        uploaded++
+        throw grammy400('Bad Request: upload also rejected') // recovery send fails too
+      },
+      onFileId: (id) => {
+        refreshed = id
+      },
+    })
+
+    expect(res.ok).toBe(false)
+    if (!res.ok) expect(res.reason).toBe('send-failed')
+    expect(byFileId).toBe(1) // id tried once
+    expect(uploaded).toBe(1) // re-uploaded exactly once — NO second attempt / loop
+    expect(refreshed).toBeNull() // failed upload never refreshed the id
+  })
+
+  it('no-audio on the upload path returns { ok:false, reason:"no-audio" }', async () => {
+    const res = await sendVoiceReusingFileId({
+      fileId: null,
+      sendByFileId: async () => null,
+      loadAudio: async () => null, // swept + synth unavailable
+      sendByUpload: async () => {
+        throw new Error('should not be called')
+      },
+      onFileId: () => {},
+    })
+    expect(res).toEqual({ ok: false, reason: 'no-audio' })
+  })
+})
+
+describe('extractVoiceFileId / isInvalidTelegramFileIdError', () => {
+  it('extracts a present file_id, ignores missing/empty', () => {
+    expect(extractVoiceFileId({ voice: { file_id: 'abc' } })).toBe('abc')
+    expect(extractVoiceFileId({ voice: {} })).toBeUndefined()
+    expect(extractVoiceFileId({ voice: { file_id: '' } })).toBeUndefined()
+    expect(extractVoiceFileId(null)).toBeUndefined()
+    expect(extractVoiceFileId(undefined)).toBeUndefined()
+  })
+
+  it('classifies a 400 wrong-file-identifier as stale, others as not', () => {
+    expect(
+      isInvalidTelegramFileIdError(grammy400('Bad Request: wrong file identifier/HTTP URL specified')),
+    ).toBe(true)
+    expect(isInvalidTelegramFileIdError(grammy400('Bad Request: wrong remote file identifier'))).toBe(
+      true,
+    )
+    // Not a file_id problem — genuine failures the caller must surface.
+    expect(isInvalidTelegramFileIdError(grammy400('Bad Request: chat not found'))).toBe(false)
+    expect(
+      isInvalidTelegramFileIdError(Object.assign(new Error('forbidden'), { error_code: 403 })),
+    ).toBe(false)
+    expect(isInvalidTelegramFileIdError(new Error('network'))).toBe(false)
+    expect(isInvalidTelegramFileIdError(null)).toBe(false)
+  })
+
+  it('isHttp400Error: true only for error_code 400, wording-agnostic', () => {
+    expect(isHttp400Error(grammy400('any wording at all'))).toBe(true)
+    expect(isHttp400Error(grammy400('Bad Request: chat not found'))).toBe(true) // 400 regardless of text
+    expect(isHttp400Error(Object.assign(new Error('x'), { error_code: 403 }))).toBe(false)
+    expect(isHttp400Error(Object.assign(new Error('x'), { error_code: 500 }))).toBe(false)
+    expect(isHttp400Error(new Error('network'))).toBe(false) // no error_code
+    expect(isHttp400Error(null)).toBe(false)
+    expect(isHttp400Error(undefined)).toBe(false)
+  })
+})
+
+describe('VoiceOnDemandCache.setTelegramFileId — capture + sweep drop', () => {
+  it('stores an id on a live entry and returns it via get()', () => {
+    const cache = new VoiceOnDemandCache()
+    cache.put('tok', { text: 'hi', speed: 1.1 })
+    cache.setTelegramFileId('tok', 'FILE_ID_1')
+    expect(cache.get('tok')?.telegramFileId).toBe('FILE_ID_1')
+  })
+
+  it('ignores an empty id and unknown/evicted tokens', () => {
+    const cache = new VoiceOnDemandCache()
+    cache.put('tok', { text: 'hi', speed: 1.1 })
+    cache.setTelegramFileId('tok', '') // ignored
+    expect(cache.get('tok')?.telegramFileId).toBeUndefined()
+    cache.setTelegramFileId('missing', 'X') // no-op, no throw
+    expect(cache.get('missing')).toBeNull()
+  })
+
+  it('drops the stored id when the 7-day sweep prunes the entry — no resurrection', () => {
+    const cache = new VoiceOnDemandCache()
+    cache.put('tok', { text: 'hi', speed: 1.1 })
+    cache.setTelegramFileId('tok', 'FILE_ID_1')
+    cache.prune(['tok']) // sweep deleted the on-disk file for this token
+    expect(cache.get('tok')).toBeNull() // entry AND its file_id are gone
+  })
+
+  it('does not store an id on an already-expired entry', () => {
+    let t = 1000
+    const cache = new VoiceOnDemandCache({ ttlMs: 100, now: () => t })
+    cache.put('tok', { text: 'hi', speed: 1.1 })
+    t = 2000 // past TTL
+    cache.setTelegramFileId('tok', 'FILE_ID_1') // no-op on expired entry
+    expect(cache.get('tok')).toBeNull()
+  })
+})