switchroom 0.18.7 → 0.18.9

package/telegram-plugin/uat/scenarios/vault-card-survives-gateway-restart-dm.test.ts

@@ -0,0 +1,140 @@
+/**
+ * UAT scenario named by `reference/jobs/approve-what-my-agent-can-touch.md`
+ * § Prove it — "Card survives a gateway restart (DM)".
+ *
+ * Contract under test (#2989 durability fix): an agent-initiated
+ * `vault_request_access` card issued BEFORE a gateway restart is still
+ * tappable AFTER it. The gateway persists card metadata to the durable
+ * pending-card store, restores it on boot, and a tap on the still-valid card
+ * grants and resumes the parked agent exactly like a pre-restart tap —
+ * never the "Card expired — ask the agent to re-request" tombstone while the
+ * agent is parked and structurally cannot re-request.
+ *
+ * Load-bearing assertions:
+ *   1. The post-restart tap does NOT produce the expired-card tombstone edit.
+ *   2. The approve flow completes (passphrase → Granted card edit).
+ *   3. The parked agent resumes on the grant with no driver nudge.
+ *
+ * **Skipped by default.** To unskip:
+ *
+ *   1. Standard UAT preflight (`uat/SETUP.md` §5-6).
+ *   2. NOPASSWD sudo on the runner host (the scenario restarts test-harness).
+ *   3. `TELEGRAM_UAT_VAULT_PASSPHRASE` set in env.
+ *   4. Pre-create a sacrificial vault key:
+ *
+ *      ```bash
+ *      TMPF=$(mktemp) && printf '%s' 'sentinel-2989-value' > "$TMPF" && \
+ *        switchroom vault set uat/card-survives-restart --file "$TMPF" \
+ *          --format string ; shred -u "$TMPF"
+ *      ```
+ *
+ *   5. Remove `describe.skip` below.
+ *
+ * Why skipped: mutates vault state (mints a grant) and bounces the harness
+ * agent. Cleanup is operator-side (`switchroom vault revoke <grant-id>`).
+ *
+ * Module-level twin (every CI run): the restart round-trip in
+ * `tests/approval-card-restart-outcome.test.ts` and the store contract in
+ * `tests/pending-card-store.test.ts`.
+ */
+
+import { describe, expect, it } from "vitest";
+import { execSync, spawn } from "node:child_process";
+import { spinUp } from "../harness.js";
+
+const AGENT = "test-harness";
+const KEY = "uat/card-survives-restart";
+const CARD_BUDGET_MS = 120_000;
+const BOOT_BUDGET_MS = 180_000;
+const RESUME_BUDGET_MS = 180_000;
+
+function canShellSudo(): boolean {
+  try {
+    execSync("sudo -n true", { stdio: "ignore", timeout: 2_000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function kickRestartDetached(name: string): void {
+  const child = spawn(
+    "sudo",
+    ["-n", "env", `PATH=${process.env.PATH}`, `HOME=${process.env.HOME}`,
+      "switchroom", "agent", "restart", name, "--force"],
+    { detached: true, stdio: "ignore" },
+  );
+  child.unref();
+}
+
+describe.skip("uat: approval card survives a gateway restart (DM, #2989)", () => {
+  it(
+    "card issued pre-restart is tappable post-restart: grant lands and the agent resumes",
+    async () => {
+      if (!canShellSudo()) {
+        throw new Error("NOPASSWD sudo required — see header to set up.");
+      }
+      const passphrase = process.env.TELEGRAM_UAT_VAULT_PASSPHRASE;
+      if (!passphrase) {
+        throw new Error(
+          "TELEGRAM_UAT_VAULT_PASSPHRASE must be set in env (see uat/SETUP.md).",
+        );
+      }
+      const sc = await spinUp({ agent: AGENT, settleMs: 0 });
+      try {
+        // 1. Park the agent on an approval card.
+        await sc.sendDM(
+          `Please call your vault_request_access MCP tool for the key ` +
+          `\`${KEY}\` (scope read, 30d, reason "UAT #2989 card durability"). ` +
+          `END YOUR TURN cleanly and wait; when the operator approves, resume ` +
+          `by running \`switchroom vault get ${KEY}\` and reporting success.`,
+        );
+        const card = await sc.expectMessage(/wants vault access/, {
+          from: "bot",
+          timeout: CARD_BUDGET_MS,
+        });
+
+        // 2. Bounce the gateway BEFORE anyone taps.
+        kickRestartDetached(AGENT);
+        await new Promise((r) => setTimeout(r, BOOT_BUDGET_MS));
+
+        // 3. Tap Approve on the ORIGINAL, pre-restart card message.
+        const kb = await sc.driver.getKeyboard(sc.botUserId, card.messageId);
+        const approveButton = kb!
+          .flat()
+          .find((b) => b.callbackData !== undefined && /approve/i.test(b.text));
+        expect(approveButton).toBeDefined();
+        await sc.driver.pressButton(
+          sc.botUserId,
+          card.messageId,
+          approveButton!.callbackData!,
+        );
+
+        // 4. The restored card must run the REAL approve flow — the expired
+        //    tombstone ("expired before you tapped") is the pre-#2989 defect.
+        const next = await sc.expectMessage(
+          (m) =>
+            /Reply with your passphrase|Granted|expired before you tapped/i.test(m.text),
+          { from: "bot", timeout: 60_000 },
+        );
+        expect(next.text).not.toMatch(/expired before you tapped/i);
+
+        if (/passphrase/i.test(next.text)) {
+          await sc.sendDM(passphrase);
+        }
+
+        // 5. Grant lands and the parked agent resumes without a nudge.
+        //    Edits excluded — the "✅ Granted" edit of the card itself must
+        //    not satisfy this; only a NEW message from the resumed turn does.
+        const resumed = await sc.expectMessage(
+          (m) => !m.edited && /(granted|access|vault get|succe)/i.test(m.text) && m.text.length > 40,
+          { from: "bot", timeout: RESUME_BUDGET_MS },
+        );
+        expect(resumed.text.length).toBeGreaterThan(40);
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    CARD_BUDGET_MS + BOOT_BUDGET_MS + RESUME_BUDGET_MS + 120_000,
+  );
+});

package/telegram-plugin/uat/scenarios/vault-deny-resumes-turn-dm.test.ts

@@ -0,0 +1,84 @@
+/**
+ * UAT scenario named by `reference/jobs/approve-what-my-agent-can-touch.md`
+ * § Prove it — "Denied request resumes the turn (DM)".
+ *
+ * Contract under test: the operator taps Deny on an agent-initiated
+ * `vault_request_access` card; the parked turn RESUMES (the gateway injects
+ * the `vault_grant_denied` synthetic), and the agent states plainly what it
+ * now can't do and continues or degrades — never left waiting on a card it
+ * already got an answer to, and never treating the denial as a reason to
+ * silently strand.
+ *
+ * Load-bearing assertion: after the Deny tap, the DRIVER sees a NEW bot turn
+ * that acknowledges the denial/degraded path WITHOUT the driver sending any
+ * further message. (The unit-level twin pins the synthetic's envelope in
+ * `tests/vault-grant-inbound-builders.test.ts`; this scenario proves the
+ * user-visible outcome over real Telegram.)
+ *
+ * Needs only the standard UAT preflight (`uat/SETUP.md` §5-6) — a Deny mints
+ * nothing and mutates no vault state, so no passphrase or sacrificial key is
+ * required. The requested key deliberately does not exist.
+ */
+
+import { describe, expect, it } from "vitest";
+import { spinUp } from "../harness.js";
+
+const KEY = "uat/deny-resume-nonexistent-key";
+const CARD_BUDGET_MS = 120_000;
+const RESUME_BUDGET_MS = 120_000;
+
+// The deny synthetic steers the model toward naming the blocked capability
+// and a fallback — this framing is the stable signal of a resumed turn.
+const DENY_RESUME_FRAMING =
+  /den(?:ied|ial)|can(?:'|no)t|won'?t be able|without (?:that|the) (?:key|access|credential)|not (?:been )?grant/i;
+
+describe("uat: denied vault request resumes the parked turn (DM)", () => {
+  it(
+    "operator taps Deny → parked turn resumes and the agent names what it can't do, with no nudge",
+    async () => {
+      const sc = await spinUp({ agent: "test-harness" });
+      try {
+        // 1. Park the agent on an approval card.
+        await sc.sendDM(
+          `Please call your vault_request_access MCP tool for the key ` +
+          `\`${KEY}\` (scope read, reason "UAT deny-resumes-turn"). Then END ` +
+          `YOUR TURN cleanly and wait. When you hear the operator's decision, ` +
+          `resume: if denied, tell me plainly that you can't read that key ` +
+          `and what you'd do instead.`,
+        );
+
+        // 2. Wait for the approval card and find the Deny button.
+        const card = await sc.expectMessage(/wants vault access/, {
+          from: "bot",
+          timeout: CARD_BUDGET_MS,
+        });
+        const kb = await sc.driver.getKeyboard(sc.botUserId, card.messageId);
+        const denyButton = kb!
+          .flat()
+          .find((b) => b.callbackData !== undefined && /deny/i.test(b.text));
+        expect(denyButton).toBeDefined();
+
+        // 3. Tap Deny. NO further driver message after this point.
+        await sc.driver.pressButton(
+          sc.botUserId,
+          card.messageId,
+          denyButton!.callbackData!,
+        );
+
+        // 4. The deny synthetic must wake the parked turn: a substantive
+        //    bot reply that acknowledges the denial arrives unprompted.
+        //    Edits are excluded — the gateway's own "🚫 Denied" edit of the
+        //    approval card must not satisfy this; only a genuinely NEW
+        //    message from a resumed turn counts.
+        const reply = await sc.expectMessage(
+          (m) => !m.edited && DENY_RESUME_FRAMING.test(m.text) && m.text.length > 40,
+          { from: "bot", timeout: RESUME_BUDGET_MS },
+        );
+        expect(reply.text).toMatch(DENY_RESUME_FRAMING);
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    CARD_BUDGET_MS + RESUME_BUDGET_MS + 60_000,
+  );
+});

package/telegram-plugin/uat/scenarios/vault-timeout-wakes-agent-dm.test.ts

@@ -0,0 +1,91 @@
+/**
+ * UAT scenario named by `reference/jobs/approve-what-my-agent-can-touch.md`
+ * § Prove it — "Timeout wakes the agent as timeout-not-denial (DM)".
+ *
+ * Contract under test: an agent-initiated `vault_request_access` card ages
+ * past the approval TTL (60-min default) with NO operator tap. The reaper
+ * expires the card, records the missed-approvals re-offer, and injects the
+ * `vault_grant_timeout` synthetic — waking the parked agent with a *timeout,
+ * not a denial* outcome. The agent then says the request went unanswered
+ * (rather than reading silence as a "no" and rather than staying parked).
+ *
+ * A real 60-min wait is not viable in a scenario, so this test requires the
+ * test-harness gateway to run with a SHORT approval TTL:
+ *
+ *   1. Standard UAT preflight (`uat/SETUP.md` §5-6).
+ *   2. Set `channels.telegram.approval_timeout_minutes: 2` on the
+ *      test-harness agent (threads to `SWITCHROOM_TG_APPROVAL_TIMEOUT_MS`,
+ *      see `approvalTtlMs()` in gateway/permission-timeout.ts) and restart it.
+ *   3. Export `SWITCHROOM_UAT_APPROVAL_TTL_MINUTES=2` in the runner env so
+ *      this scenario unskips and sizes its wait window.
+ *
+ * Self-skips green when `SWITCHROOM_UAT_APPROVAL_TTL_MINUTES` is unset (the
+ * default 60-min TTL cannot be observed within test wall-clock). The
+ * module-level twin covering the same outcome deterministically is
+ * `tests/approval-card-restart-outcome.test.ts` plus
+ * `tests/approval-timeout-inbound-builders.test.ts` (the "TIMEOUT, not a
+ * denial" wording pin).
+ */
+
+import { describe, expect, it } from "vitest";
+import { spinUp } from "../harness.js";
+
+const TTL_MINUTES = Number.parseInt(
+  process.env.SWITCHROOM_UAT_APPROVAL_TTL_MINUTES ?? "",
+  10,
+);
+const ttlTuned = Number.isFinite(TTL_MINUTES) && TTL_MINUTES > 0 && TTL_MINUTES <= 5;
+
+const KEY = "uat/timeout-wake-nonexistent-key";
+const CARD_BUDGET_MS = 120_000;
+// TTL + reaper tick slack + model turn budget.
+const WAKE_BUDGET_MS = (ttlTuned ? TTL_MINUTES : 2) * 60_000 + 240_000;
+
+// The timeout synthetic's load-bearing wording is "TIMEOUT, not a denial" —
+// the model is steered to say the request went unanswered, not refused.
+const TIMEOUT_FRAMING =
+  /unanswer|timed?[ -]?out|no (?:response|answer|decision)|didn'?t (?:hear|get|respond)|went without/i;
+
+(ttlTuned ? describe : describe.skip)(
+  "uat: unanswered approval card times out and wakes the agent as timeout-not-denial (DM)",
+  () => {
+    it(
+      "card ages past the TTL with no tap → agent says the request went unanswered, unprompted",
+      async () => {
+        const sc = await spinUp({ agent: "test-harness" });
+        try {
+          // 1. Park the agent on an approval card that nobody will answer.
+          await sc.sendDM(
+            `Please call your vault_request_access MCP tool for the key ` +
+            `\`${KEY}\` (scope read, reason "UAT timeout-wakes-agent"). Then ` +
+            `END YOUR TURN cleanly and wait for the operator. If the request ` +
+            `times out unanswered, tell me plainly that it went unanswered ` +
+            `(not that it was denied) and what you'll do about it.`,
+          );
+
+          // 2. The card must render — and then we deliberately never tap it.
+          await sc.expectMessage(/wants vault access/, {
+            from: "bot",
+            timeout: CARD_BUDGET_MS,
+          });
+
+          // 3. TTL elapses → reaper fires the vault_grant_timeout synthetic →
+          //    a substantive bot reply arrives with timeout (never denial)
+          //    framing, with no further driver message. Edits are excluded —
+          //    the reaper's own "timed out" edit of the approval card must
+          //    not satisfy this; only a NEW message from the woken turn does.
+          const reply = await sc.expectMessage(
+            (m) => !m.edited && TIMEOUT_FRAMING.test(m.text) && m.text.length > 40,
+            { from: "bot", timeout: WAKE_BUDGET_MS },
+          );
+          expect(reply.text).toMatch(TIMEOUT_FRAMING);
+          // A timeout must never be narrated as an operator refusal.
+          expect(reply.text).not.toMatch(/operator denied|was denied|refused my request/i);
+        } finally {
+          await sc.tearDown();
+        }
+      },
+      CARD_BUDGET_MS + WAKE_BUDGET_MS + 60_000,
+    );
+  },
+);

package/telegram-plugin/voice-ondemand.ts

@@ -49,6 +49,15 @@ export type VoiceOnDemandPayload = {
    *  the pre-synth queue after a successful background synth. Absent on
    *  pre-feature entries, on kill-switched gateways, and until the job runs. */
   filePath?: string
+  /** Telegram's reusable file_id for the audio, captured from the FIRST
+   *  successful `sendVoice` for this entry. On subsequent taps the gateway
+   *  sends BY this id (a plain string, not an InputFile) so Telegram serves
+   *  the already-uploaded bytes — no disk read, no re-upload round-trip, so
+   *  the voice note arrives near-instantly. Absent until the first send;
+   *  refreshed if a stale id is rejected and the audio is re-uploaded. It
+   *  lives on the entry, so the 7-day sweep's `prune()` drops it together
+   *  with the entry — a dead id is never resurrected. */
+  telegramFileId?: string
   /** Epoch ms the entry was stored (put time) — recorded alongside filePath
    *  per #2763 so the sweep/introspection can reason about entry age. */
   createdAt?: number
@@ -136,7 +145,7 @@ export class VoiceOnDemandCache {
       this.flush()
       return null
     }
-    const { text, voice, speed, filePath } = entry
+    const { text, voice, speed, filePath, telegramFileId } = entry
     // createdAt stays internal (persisted for sweep/introspection) so the
     // returned shape only grows when a pre-synth file actually exists —
     // pre-#2763 callers and tests see the exact old payload.
@@ -145,6 +154,7 @@ export class VoiceOnDemandCache {
       speed,
       ...(voice !== undefined ? { voice } : {}),
       ...(filePath !== undefined ? { filePath } : {}),
+      ...(telegramFileId !== undefined ? { telegramFileId } : {}),
     }
   }
 
@@ -159,6 +169,20 @@ export class VoiceOnDemandCache {
     this.flush()
   }
 
+  /** Record (or refresh) Telegram's reusable file_id on an existing entry,
+   *  captured from a successful `sendVoice`. Mirrors {@link setFilePath}: no-op
+   *  if the entry has expired or been evicted meanwhile, and does NOT bump LRU
+   *  position or TTL — the entry's lifetime stays anchored at put time so a
+   *  captured id can never resurrect a dying entry. Passing an empty string is
+   *  ignored (nothing to store). */
+  setTelegramFileId(token: string, fileId: string): void {
+    if (fileId.length === 0) return
+    const entry = this.store.get(token)
+    if (entry == null || entry.expiresAt <= this.now()) return
+    entry.telegramFileId = fileId
+    this.flush()
+  }
+
   /** Drop entries whose pre-synth files the sweep deleted (#2763). Unknown
    *  tokens are ignored (file may belong to an already-evicted entry). */
   prune(tokens: Iterable<string>): void {

package/telegram-plugin/voice-send.ts

@@ -0,0 +1,154 @@
+/**
+ * On-demand voice send with Telegram file_id reuse.
+ *
+ * The Listen-button tap used to re-upload the audio bytes as a fresh InputFile
+ * on EVERY send — an upload + server-side ingest round-trip each time, which is
+ * the delay users felt on repeat taps. Telegram returns a reusable `file_id`
+ * after the first upload; sending BY that id (a plain string, not an InputFile)
+ * makes Telegram serve the already-stored bytes, which is near-instant and
+ * skips the disk read entirely.
+ *
+ * {@link sendVoiceReusingFileId} is the dependency-free decision core so it can
+ * be unit-tested without importing the 25k-line gateway (which has import-time
+ * side effects) or grammy. The gateway supplies the concrete send closures.
+ *
+ * Contract:
+ *   1. If a stored file_id exists → send BY id (no disk read, no upload). On
+ *      success capture the returned id (Telegram may echo the same one).
+ *   2. If the stored id send fails with ANY HTTP 400 → treat the id as
+ *      stale/invalid (regardless of the exact wording), fall through to the
+ *      upload path ONCE and refresh the stored id so a dead id can never
+ *      permanently break Listen. Any NON-400 error (network / 5xx / 403
+ *      blocked-by-user) is a real failure and is surfaced (no silent
+ *      re-upload storm, no papering over a 403).
+ *   3. If no id yet → load the audio (disk fast-path or on-demand synth) and
+ *      send it as an InputFile, capturing the returned file_id for next time.
+ */
+
+/** The subset of a Telegram Message we read back: the sent voice's file_id. */
+export type SentVoiceMessage = { voice?: { file_id?: string } } | undefined | null
+
+/** Extract the reusable file_id from a `sendVoice` response, if present. */
+export function extractVoiceFileId(sent: SentVoiceMessage): string | undefined {
+  const id = sent?.voice?.file_id
+  return typeof id === 'string' && id.length > 0 ? id : undefined
+}
+
+/**
+ * True iff `err` looks like Telegram rejecting a file_id we sent (expired or
+ * malformed id) — the one case where re-uploading from disk is the right
+ * recovery. Duck-typed so this module stays grammy-free: a GrammyError carries
+ * `error_code` (number) and `description` (string). A 400 whose text names the
+ * file identifier is a stale-id signal; any other error is a genuine failure
+ * the caller must NOT paper over with a silent re-upload.
+ */
+export function isInvalidTelegramFileIdError(err: unknown): boolean {
+  if (err == null || typeof err !== 'object') return false
+  const e = err as { error_code?: unknown; description?: unknown; message?: unknown }
+  const code = typeof e.error_code === 'number' ? e.error_code : undefined
+  if (code !== undefined && code !== 400) return false
+  const text = String(e.description ?? e.message ?? '').toLowerCase()
+  return (
+    text.includes('file identifier') ||
+    text.includes('file_id') ||
+    text.includes('wrong file') ||
+    text.includes('wrong remote file') ||
+    text.includes('wrong padding')
+  )
+}
+
+/**
+ * True iff `err` is an HTTP 400-class Telegram rejection (grammy `error_code`
+ * 400), regardless of the description wording. This is the re-upload trigger:
+ * a send-by-file_id that fails with a 400 is treated as a stale/invalid id and
+ * recovered by re-uploading from disk ONCE, superseding the narrower
+ * substring-matched {@link isInvalidTelegramFileIdError}. Rationale: a
+ * re-upload is always safe recovery and can never be worse than re-hitting a
+ * guaranteed-failing id, whereas Telegram may return a stale-id 400 with
+ * wording outside the known substring set. Non-400 errors (network / 5xx /
+ * 403 blocked-by-user) are NOT 400 and must remain real failures — never
+ * re-uploaded. Duck-typed so this module stays grammy-free.
+ */
+export function isHttp400Error(err: unknown): boolean {
+  if (err == null || typeof err !== 'object') return false
+  const e = err as { error_code?: unknown }
+  return e.error_code === 400
+}
+
+export type ReuseFileIdDeps = {
+  /** The entry's stored Telegram file_id, or null if none captured yet. */
+  fileId: string | null
+  /** Send by an already-uploaded file_id string. Resolves to the sent Message. */
+  sendByFileId: (fileId: string) => Promise<SentVoiceMessage>
+  /** Load the audio bytes (disk fast-path, then on-demand synth). Returns null
+   *  when audio is unavailable — the impl has already surfaced any user-facing
+   *  toast in that case. Only invoked on the upload path (never when a valid
+   *  file_id served the tap). */
+  loadAudio: () => Promise<Uint8Array | null>
+  /** Upload the audio as an InputFile. Resolves to the sent Message. */
+  sendByUpload: (audio: Uint8Array) => Promise<SentVoiceMessage>
+  /** Persist a freshly captured/refreshed file_id onto the cache entry. */
+  onFileId: (fileId: string) => void
+  /** Classify a `sendByFileId` rejection: true → re-upload from disk once +
+   *  refresh the id; false → surface as a real failure. Defaults to
+   *  {@link isHttp400Error} — ANY HTTP 400 is treated as a stale/invalid id
+   *  (safe recovery), superseding the narrower substring-matched
+   *  {@link isInvalidTelegramFileIdError}. Non-400 errors (network / 5xx /
+   *  403) stay real failures and never re-upload. */
+  isInvalidFileIdError?: (err: unknown) => boolean
+  log?: (line: string) => void
+}
+
+export type ReuseFileIdResult =
+  | { ok: true; path: 'file_id' | 'upload'; refreshed: boolean }
+  | { ok: false; reason: 'no-audio' }
+  | { ok: false; reason: 'send-failed'; error: unknown }
+
+/**
+ * Send a voice note reusing a stored file_id when possible, with a disk/synth
+ * re-upload fallback on a stale id. See the module header for the full
+ * contract. Never throws — send failures are returned as `{ ok: false }`.
+ */
+export async function sendVoiceReusingFileId(deps: ReuseFileIdDeps): Promise<ReuseFileIdResult> {
+  const shouldReupload = deps.isInvalidFileIdError ?? isHttp400Error
+
+  // 1. Fast path — reuse the stored file_id. No disk read, no re-upload.
+  if (deps.fileId != null && deps.fileId.length > 0) {
+    try {
+      const sent = await deps.sendByFileId(deps.fileId)
+      const fresh = extractVoiceFileId(sent)
+      if (fresh != null) deps.onFileId(fresh)
+      return { ok: true, path: 'file_id', refreshed: false }
+    } catch (err) {
+      if (!shouldReupload(err)) {
+        // Non-400 (network / 5xx / 403 blocked-by-user) — a real failure, not a
+        // stale id. Never re-upload; surface it so the caller can retry/report.
+        return { ok: false, reason: 'send-failed', error: err }
+      }
+      // Any 400 — treat the stored id as stale/invalid regardless of wording and
+      // recover by re-uploading below ONCE + refreshing the id. This can never
+      // be worse than re-hitting a guaranteed-failing id, and covers stale-id
+      // 400s whose text falls outside isInvalidTelegramFileIdError's substrings.
+      deps.log?.(
+        `voice-ondemand: stored file_id rejected (${String(
+          (err as { description?: unknown; message?: unknown })?.description ??
+            (err as { message?: unknown })?.message ??
+            err,
+        )}) — re-uploading from disk\n`,
+      )
+    }
+  }
+
+  // 2. Upload path — load audio then send as an InputFile; capture the id.
+  const audio = await deps.loadAudio()
+  if (audio == null) return { ok: false, reason: 'no-audio' }
+  const refreshed = deps.fileId != null && deps.fileId.length > 0
+  try {
+    const sent = await deps.sendByUpload(audio)
+    const fresh = extractVoiceFileId(sent)
+    if (fresh != null) deps.onFileId(fresh)
+    return { ok: true, path: 'upload', refreshed }
+  } catch (err) {
+    return { ok: false, reason: 'send-failed', error: err }
+  }
+}