switchroom 0.18.9 → 0.18.11

package/telegram-plugin/tests/pending-session-command.test.ts

@@ -0,0 +1,322 @@
+/**
+ * Contract pins for the mid-turn ack-queue-apply-confirm slots (#3017/#3018)
+ * that back `/model` + `/effort` when the agent is busy.
+ *
+ * The gateway wiring (busy-gate enqueue, idle-gate drain, reaper drain-cap,
+ * shutdown resolution) is exercised end-to-end by the UAT harness and pinned
+ * structurally in gateway-pending-command-wiring.test.ts; these lock the PURE
+ * contract the gateway relies on:
+ *
+ *   - one slot PER KIND (model, effort): same-kind last-write-wins (a rapid
+ *     re-issue queues only the latest and REPORTS the displaced one so it's
+ *     never silently lost); cross-kind requests COEXIST (#3018 finding 2)
+ *   - take(kind)/takeAll() are the atomic drain reads (empty the slots)
+ *   - size mirrors the `pendingRestarts.size` gate shape (0..2)
+ *   - the reaper's drainCapDecision DEFERS while a turn is in flight — the
+ *     60s cap must never force a mid-turn drain (#3018 finding 1)
+ *   - shutdownResolutionActions empties the slots and yields, per queued
+ *     command, the durable persist the gateway should perform so the choice
+ *     still applies across the bounce (#3039) — with a re-issue fallback only
+ *     for the unresolvable menu-tag case
+ *   - the ack / superseded / restart-superseded text names the target so the
+ *     operator always sees their choice was captured, replaced, or deferred —
+ *     never dropped.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  createPendingSessionCommandSlots,
+  drainCapDecision,
+  shutdownResolutionActions,
+  resolveForRestart,
+  drainTakenCommands,
+  type DrainIo,
+  ackText,
+  supersededText,
+  restartSupersededText,
+  type PendingSessionCommand,
+} from '../gateway/pending-session-command.js'
+
+const ident = (s: string) => s
+
+function cmd(overrides: Partial<PendingSessionCommand> = {}): PendingSessionCommand {
+  return {
+    kind: 'model',
+    origin: 'typed',
+    arg: 'fable',
+    targetLabel: 'fable',
+    chatId: '100',
+    threadId: undefined,
+    ackChatId: '100',
+    ackMessageId: 42,
+    requestedAt: 1_000,
+    ...overrides,
+  }
+}
+
+describe('pending-session-command slots', () => {
+  it('start empty (size 0, get null, take null, takeAll empty)', () => {
+    const slots = createPendingSessionCommandSlots()
+    expect(slots.size).toBe(0)
+    expect(slots.get('model')).toBeNull()
+    expect(slots.get('effort')).toBeNull()
+    expect(slots.take('model')).toBeNull()
+    expect(slots.takeAll()).toEqual([])
+    expect(slots.list()).toEqual([])
+  })
+
+  it('set on an empty slot displaces nothing and becomes gettable', () => {
+    const slots = createPendingSessionCommandSlots()
+    const a = cmd({ arg: 'opus', targetLabel: 'opus' })
+    expect(slots.set(a)).toBeNull()
+    expect(slots.size).toBe(1)
+    expect(slots.get('model')).toBe(a)
+  })
+
+  it('SAME-KIND last-write-wins: a second set returns the displaced command', () => {
+    const slots = createPendingSessionCommandSlots()
+    const first = cmd({ arg: 'fable', targetLabel: 'fable', ackMessageId: 1 })
+    const second = cmd({ arg: 'opus', targetLabel: 'opus', ackMessageId: 2 })
+    expect(slots.set(first)).toBeNull()
+    const displaced = slots.set(second)
+    expect(displaced).toBe(first) // caller edits THIS ack card to "superseded"
+    expect(slots.get('model')).toBe(second) // only the latest is queued
+    expect(slots.size).toBe(1)
+  })
+
+  it('CROSS-KIND commands coexist: /effort never displaces a queued /model (#3018 finding 2)', () => {
+    const slots = createPendingSessionCommandSlots()
+    const model = cmd({ kind: 'model', arg: 'fable', targetLabel: 'fable', ackMessageId: 1 })
+    const effort = cmd({ kind: 'effort', arg: 'high', targetLabel: 'high', ackMessageId: 2 })
+    expect(slots.set(model)).toBeNull()
+    expect(slots.set(effort)).toBeNull() // NOT a displacement
+    expect(slots.size).toBe(2)
+    expect(slots.get('model')).toBe(model)
+    expect(slots.get('effort')).toBe(effort)
+    // …and vice versa: a later model re-issue displaces only the model slot.
+    const model2 = cmd({ kind: 'model', arg: 'opus', targetLabel: 'opus', ackMessageId: 3 })
+    expect(slots.set(model2)).toBe(model)
+    expect(slots.get('effort')).toBe(effort)
+    expect(slots.size).toBe(2)
+  })
+
+  it('take(kind) atomically empties only that slot (the per-kind drain read)', () => {
+    const slots = createPendingSessionCommandSlots()
+    const model = cmd({ kind: 'model' })
+    const effort = cmd({ kind: 'effort', arg: 'high', targetLabel: 'high' })
+    slots.set(model)
+    slots.set(effort)
+    expect(slots.take('model')).toBe(model)
+    expect(slots.size).toBe(1)
+    expect(slots.get('model')).toBeNull()
+    expect(slots.get('effort')).toBe(effort)
+    expect(slots.take('model')).toBeNull() // second drain is a no-op
+  })
+
+  it('takeAll() empties everything in enqueue order; a same-kind re-enqueue moves to the back', () => {
+    const slots = createPendingSessionCommandSlots()
+    const model1 = cmd({ kind: 'model', targetLabel: 'fable', ackMessageId: 1 })
+    const effort = cmd({ kind: 'effort', arg: 'high', targetLabel: 'high', ackMessageId: 2 })
+    const model2 = cmd({ kind: 'model', targetLabel: 'opus', ackMessageId: 3 })
+    slots.set(model1)
+    slots.set(effort)
+    slots.set(model2) // displaces model1 AND moves the model slot behind effort
+    const all = slots.takeAll()
+    expect(all).toEqual([effort, model2])
+    expect(slots.size).toBe(0)
+    expect(slots.takeAll()).toEqual([])
+  })
+
+  it('clear() drops every queued command without returning them', () => {
+    const slots = createPendingSessionCommandSlots()
+    slots.set(cmd({ kind: 'model' }))
+    slots.set(cmd({ kind: 'effort', arg: 'high', targetLabel: 'high' }))
+    slots.clear()
+    expect(slots.size).toBe(0)
+    expect(slots.get('model')).toBeNull()
+    expect(slots.get('effort')).toBeNull()
+  })
+})
+
+describe('drainCapDecision (#3018 finding 1: the cap must never force mid-turn)', () => {
+  const CAP = 60_000
+
+  it('waits when nothing is queued', () => {
+    expect(drainCapDecision([], 1_000_000, CAP, false)).toBe('wait')
+    expect(drainCapDecision([], 1_000_000, CAP, true)).toBe('wait')
+  })
+
+  it('waits while the queued command is younger than the cap', () => {
+    const q = [cmd({ requestedAt: 100_000 })]
+    expect(drainCapDecision(q, 100_000 + CAP, CAP, false)).toBe('wait')
+  })
+
+  it('forces once overdue AND the session is idle (missed idle gate)', () => {
+    const q = [cmd({ requestedAt: 100_000 })]
+    expect(drainCapDecision(q, 100_000 + CAP + 1, CAP, false)).toBe('force')
+  })
+
+  it('DEFERS (keeps waiting) when overdue but a turn is in flight — a forced mid-turn drain would destroy the queued command', () => {
+    const q = [cmd({ requestedAt: 100_000 })]
+    expect(drainCapDecision(q, 100_000 + CAP + 1, CAP, true)).toBe('defer-turn-in-flight')
+    // …even hours overdue: the idle gate at turn end is the drain point.
+    expect(drainCapDecision(q, 100_000 + 100 * CAP, CAP, true)).toBe('defer-turn-in-flight')
+  })
+
+  it('any one overdue command trips the cap (mixed ages)', () => {
+    const q = [
+      cmd({ kind: 'model', requestedAt: 100_000 }),
+      cmd({ kind: 'effort', requestedAt: 100_000 + CAP }),
+    ]
+    expect(drainCapDecision(q, 100_000 + CAP + 1, CAP, false)).toBe('force')
+  })
+})
+
+describe('shutdownResolutionActions (#3018 finding 3 + #3039: SIGTERM persists the queued choice)', () => {
+  it('empties the slots and yields a persist action per queued command', () => {
+    const slots = createPendingSessionCommandSlots()
+    slots.set(cmd({ kind: 'model', targetLabel: 'fable', arg: 'fable', ackChatId: '100', ackMessageId: 7 }))
+    slots.set(cmd({ kind: 'effort', targetLabel: 'high', arg: 'high', ackChatId: '100', ackMessageId: 9 }))
+    const actions = shutdownResolutionActions(slots, ident)
+    expect(actions).toHaveLength(2)
+    expect(slots.size).toBe(0) // the queue is RESOLVED, not left behind
+    const model = actions.find(a => a.cmd.ackMessageId === 7)!
+    expect(model.persist).toBe('model')
+    expect(model.arg).toBe('fable')
+    expect(model.persistedText).toContain('`fable`')
+    expect(model.persistedText).toContain('saved')
+    // The fallback (persist failed) still names the choice + how to recover.
+    expect(model.reissueText).toContain('re-issue')
+    const effort = actions.find(a => a.cmd.ackMessageId === 9)!
+    expect(effort.persist).toBe('effort')
+    expect(effort.arg).toBe('high')
+  })
+
+  it('typed /model default → clear-model; typed /effort default → clear-effort', () => {
+    expect(resolveForRestart(cmd({ kind: 'model', arg: 'default', targetLabel: 'default' }), ident).persist).toBe('clear-model')
+    expect(resolveForRestart(cmd({ kind: 'effort', arg: 'default', targetLabel: 'default' }), ident).persist).toBe('clear-effort')
+  })
+
+  it('menu model selection (mdl:s:<tag>) is not offline-resolvable → persist null, re-issue fallback', () => {
+    const a = resolveForRestart(cmd({ kind: 'model', origin: 'menu', arg: 'mdl:s:abcd1234', targetLabel: 'the selected model' }), ident)
+    expect(a.persist).toBeNull()
+    expect(a.reissueText).toContain('re-issue')
+  })
+
+  it('menu effort tap (eff:s:<level>) IS resolvable → persist effort with the level', () => {
+    const a = resolveForRestart(cmd({ kind: 'effort', origin: 'menu', arg: 'eff:s:xhigh', targetLabel: 'xhigh' }), ident)
+    expect(a.persist).toBe('effort')
+    expect(a.arg).toBe('xhigh')
+  })
+
+  it('returns no actions when nothing is queued', () => {
+    expect(shutdownResolutionActions(createPendingSessionCommandSlots(), ident)).toEqual([])
+  })
+})
+
+describe('ackText', () => {
+  it('names the model target with a mid-turn framing', () => {
+    const t = ackText('model', 'fable', ident)
+    expect(t).toContain('mid-turn')
+    expect(t).toContain('`fable`')
+    expect(t).toContain('switch to')
+  })
+
+  it('uses the effort verb for effort commands', () => {
+    const t = ackText('effort', 'high', ident)
+    expect(t).toContain('set effort to')
+    expect(t).toContain('`high`')
+  })
+
+  it('routes the label through escapeHtml', () => {
+    const seen: string[] = []
+    ackText('model', 'sr-glm-5', (s) => { seen.push(s); return s })
+    expect(seen).toContain('sr-glm-5')
+  })
+})
+
+describe('supersededText', () => {
+  it('names BOTH the replaced and the new target', () => {
+    const displaced = cmd({ kind: 'model', targetLabel: 'fable' })
+    const next = cmd({ kind: 'model', targetLabel: 'opus' })
+    const t = supersededText(displaced, next, ident)
+    expect(t).toContain('`opus`')
+    expect(t).toContain('`fable`')
+    expect(t).toContain('replaced')
+  })
+})
+
+describe('restartSupersededText', () => {
+  it('tells the operator to re-issue after the restart', () => {
+    const t = restartSupersededText(cmd({ kind: 'effort', targetLabel: 'max' }), ident)
+    expect(t).toContain('restarting')
+    expect(t).toContain('/effort max')
+    expect(t).toContain('`max`')
+  })
+})
+
+
+// ─── #3042 blocker 1: drain loss-safety across a two-command batch ───────────
+
+describe('drainTakenCommands (#3042 blocker 1: an early stop must not drop the rest of the batch)', () => {
+  function makeIo(overrides: Partial<DrainIo> = {}) {
+    const events: string[] = []
+    const io: DrainIo = {
+      restartPending: () => false,
+      turnInFlight: () => false,
+      apply: async c => { events.push(`apply:${c.kind}`); return `✅ ${c.kind} done` },
+      isBusyRefusal: t => t.includes('BUSY'),
+      resolveForRestartText: c => `persisted:${c.kind}`,
+      editCard: async (c, text) => { events.push(`edit:${c.kind}:${text}`) },
+      reEnqueue: c => { events.push(`requeue:${c.kind}`) },
+      failureText: (c, err) => `fail:${c.kind}:${(err as Error).message}`,
+      ...overrides,
+    }
+    return { io, events }
+  }
+  const batch = () => [cmd({ kind: 'model' }), cmd({ kind: 'effort', arg: 'high', targetLabel: 'high' })]
+
+  it('happy path applies and confirms both commands in order', async () => {
+    const { io, events } = makeIo()
+    await drainTakenCommands(batch(), io)
+    expect(events).toEqual(['apply:model', 'edit:model:✅ model done', 'apply:effort', 'edit:effort:✅ effort done'])
+  })
+
+  it('turn races in before the FIRST command → BOTH are re-enqueued, none applied or confirmed', async () => {
+    const { io, events } = makeIo({ turnInFlight: () => true })
+    await drainTakenCommands(batch(), io)
+    expect(events).toEqual(['requeue:model', 'requeue:effort'])
+  })
+
+  it('turn races in before the SECOND command → first applied, second re-enqueued (not lost)', async () => {
+    let calls = 0
+    const { io, events } = makeIo({ turnInFlight: () => ++calls > 1 })
+    await drainTakenCommands(batch(), io)
+    expect(events).toEqual(['apply:model', 'edit:model:✅ model done', 'requeue:effort'])
+  })
+
+  it('handler busy-refusal on the FIRST command → the refusal never reaches the ack card and BOTH are re-enqueued', async () => {
+    const { io, events } = makeIo({
+      apply: async c => (c.kind === 'model' ? 'BUSY — mid-turn' : '✅ effort done'),
+    })
+    await drainTakenCommands(batch(), io)
+    expect(events).toEqual(['requeue:model', 'requeue:effort'])
+  })
+
+  it('apply throwing on the first command does NOT stop the second (failure is per-command)', async () => {
+    const { io, events } = makeIo({
+      apply: async c => {
+        if (c.kind === 'model') throw new Error('boom')
+        return '✅ effort done'
+      },
+    })
+    await drainTakenCommands(batch(), io)
+    expect(events).toEqual(['edit:model:fail:model:boom', 'edit:effort:✅ effort done'])
+  })
+
+  it('restart pending → every command is resolved via the carriers, none applied live', async () => {
+    const { io, events } = makeIo({ restartPending: () => true })
+    await drainTakenCommands(batch(), io)
+    expect(events).toEqual(['edit:model:persisted:model', 'edit:effort:persisted:effort'])
+  })
+})

package/telegram-plugin/tests/permission-timeout.test.ts

@@ -19,6 +19,8 @@ import {
   HOSTD_PERMISSION_TTL_MS,
   ttlForTool,
   buildTimedOutCardEdits,
+  buildCancelledCardEdits,
+  CANCELLED_FOOTER,
   isStaleTap,
   STALE_TAP_NOTICE,
   TIMED_OUT_FOOTER,
@@ -178,6 +180,30 @@ describe('buildTimedOutCardEdits (Bug 2 fix #1 — strip stale keyboard)', () =>
   })
 })
 
+describe('buildCancelledCardEdits (#3020 — halt cancels pending cards)', () => {
+  it('marks every recorded card for keyboard-strip and appends the cancelled footer', () => {
+    const cards = [
+      { chatId: '111', messageId: 5 },
+      { chatId: '222', messageId: 9 },
+    ]
+    const edits = buildCancelledCardEdits('🔐 **Overlord** wants to roll the fleet', cards)
+    expect(edits).toHaveLength(2)
+    for (const [i, edit] of edits.entries()) {
+      // Same contract as the timeout path: a live Approve after the halt
+      // would dispatch a verdict into an idle session.
+      expect(edit.stripKeyboard).toBe(true)
+      expect(edit.chatId).toBe(cards[i]!.chatId)
+      expect(edit.messageId).toBe(cards[i]!.messageId)
+      expect(edit.text).toContain('roll the fleet')
+      expect(edit.text.endsWith(CANCELLED_FOOTER)).toBe(true)
+    }
+  })
+
+  it('returns no edits when there were no recorded cards', () => {
+    expect(buildCancelledCardEdits('body', [])).toEqual([])
+  })
+})
+
 describe('isStaleTap (Bug 2 fix #3 — do not dispatch a verdict for a dead id)', () => {
   it('is stale when no pending entry exists for the tapped request_id', () => {
     // hasPending=false ⇒ the reaper already auto-denied + deleted it.

package/telegram-plugin/tests/permission-verdict-resume-guard.test.ts

@@ -79,6 +79,18 @@ const isSilentNoCardVerdict = (idx: number): boolean =>
 const isCardFoldedResume = (idx: number): boolean =>
   LINES.slice(idx, idx + POST_WINDOW + 1).some((l) => /card-folded-resume/.test(l))
 
+// A HALTED-TURN verdict (#3020 `executeHaltNow` → `cancelPendingPermissionsForHalt`)
+// denies the pending call because the operator is KILLING the turn (/stop,
+// bare "stop", empty `!`). There is nothing to resume — the turn is about to
+// be C-c'd and its busy state torn down — so neither the glyph flip nor the
+// "got it, continuing" message applies. The card is still visibly terminal:
+// the halt path edits it to "⏹ Cancelled" with the keyboard stripped, and the
+// /stop reply acks the operator. Such callsites carry the
+// `halted-turn-verdict` sentinel within the 5 lines above the dispatch and
+// are exempt from BOTH pairings.
+const isHaltedTurnVerdict = (idx: number): boolean =>
+  LINES.slice(Math.max(0, idx - 5), idx + 1).some((l) => /halted-turn-verdict/.test(l))
+
 // How far below the dispatch the resume call is allowed to live. The
 // widest real gap today is ~9 lines (the slash-command path); 15 gives
 // refactor headroom without letting an unrelated resume "cover" a
@@ -99,6 +111,8 @@ describe('permission verdict → resume reaction wiring', () => {
     const unpaired: number[] = []
     for (const idx of dispatchCallsites) {
       if (isSilentNoCardVerdict(idx)) continue
+      // Exempt: the halt path kills the turn — nothing resumes (#3020).
+      if (isHaltedTurnVerdict(idx)) continue
       const window = LINES.slice(idx, idx + RESUME_WINDOW + 1).join('\n')
       if (!/\bresumeReactionAfterVerdict\s*\(\s*\)/.test(window)) {
         // 1-based line number for a human-readable failure.
@@ -125,6 +139,8 @@ describe('permission verdict → resume reaction wiring', () => {
     const unpaired: number[] = []
     for (const idx of dispatchCallsites) {
       if (isSilentNoCardVerdict(idx)) continue
+      // Exempt: the halt path kills the turn — nothing resumes (#3020).
+      if (isHaltedTurnVerdict(idx)) continue
       // Exempt: card-ux fix 3 folds the resume line into the card edit
       // instead of a separate message (still visibly resumes the operator).
       if (isCardFoldedResume(idx)) continue

package/telegram-plugin/tests/photo-dimension-fallback.test.ts

@@ -0,0 +1,129 @@
+/**
+ * Covers the photo→document graceful fallback contract (#klanker
+ * 2026-07-10 incident: a tall phone screenshot sent via the reply tool's
+ * `files` param threw PHOTO_INVALID_DIMENSIONS).
+ *
+ * Two production pieces make the gateway's fallback work:
+ *   1. `isPhotoDimensionRejectError` classifies the 400s that mean "not
+ *      usable AS a photo" (dimensions / save-file / too-large).
+ *   2. `retryApiCall` must NOT swallow or retry those 400s — they have to
+ *      reach the caller's catch so it can re-send as a document.
+ *
+ * The final block exercises the EXACT try/catch shape the gateway's reply
+ * file-send loop uses (`retryWithThreadFallback` + the predicate), proving
+ * the file is still delivered as a document.
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import {
+  createRetryApiCall,
+  retryWithThreadFallback,
+  isPhotoDimensionRejectError,
+} from '../retry-api-call.js'
+import { errors } from './fake-bot-api.js'
+
+describe('isPhotoDimensionRejectError', () => {
+  it('is true for PHOTO_INVALID_DIMENSIONS', () => {
+    expect(isPhotoDimensionRejectError(errors.badRequest('PHOTO_INVALID_DIMENSIONS', 'sendPhoto'))).toBe(true)
+  })
+
+  it('is true for PHOTO_SAVE_FILE_INVALID', () => {
+    expect(isPhotoDimensionRejectError(errors.badRequest('PHOTO_SAVE_FILE_INVALID', 'sendPhoto'))).toBe(true)
+  })
+
+  it('is true for the mediagroup-wrapped variant', () => {
+    const err = errors.badRequest(
+      'failed to send message #2 with the error message "PHOTO_INVALID_DIMENSIONS"',
+      'sendMediaGroup',
+    )
+    expect(isPhotoDimensionRejectError(err)).toBe(true)
+  })
+
+  it('is true for photo-too-big size rejections', () => {
+    expect(isPhotoDimensionRejectError(errors.badRequest('PHOTO_SAVE_FILE_INVALID: photo is too big', 'sendPhoto'))).toBe(true)
+    expect(isPhotoDimensionRejectError(errors.badRequest('Image is too big', 'sendPhoto'))).toBe(true)
+  })
+
+  it('is false for unrelated 400s', () => {
+    expect(isPhotoDimensionRejectError(errors.badRequest('chat not found', 'sendPhoto'))).toBe(false)
+    expect(isPhotoDimensionRejectError(errors.threadNotFound('sendPhoto'))).toBe(false)
+  })
+
+  it('is false for non-400 and non-grammy errors', () => {
+    expect(isPhotoDimensionRejectError(errors.forbidden('sendPhoto'))).toBe(false)
+    expect(isPhotoDimensionRejectError(errors.floodWait(3, 'sendPhoto'))).toBe(false)
+    expect(isPhotoDimensionRejectError(new Error('PHOTO_INVALID_DIMENSIONS'))).toBe(false)
+    expect(isPhotoDimensionRejectError(null)).toBe(false)
+  })
+})
+
+describe('retryApiCall does not swallow photo-dimension rejects', () => {
+  it('rethrows PHOTO_INVALID_DIMENSIONS so the caller can fall back', async () => {
+    const retry = createRetryApiCall()
+    const err = errors.badRequest('PHOTO_INVALID_DIMENSIONS', 'sendPhoto')
+    await expect(retry(() => Promise.reject(err))).rejects.toBe(err)
+  })
+
+  it('propagates through retryWithThreadFallback (not treated as THREAD_NOT_FOUND)', async () => {
+    const retry = createRetryApiCall()
+    const err = errors.badRequest('PHOTO_INVALID_DIMENSIONS', 'sendPhoto')
+    await expect(
+      retryWithThreadFallback(retry, () => Promise.reject(err), {
+        threadId: 42,
+        chat_id: '123',
+        verb: 'sendPhoto',
+      }),
+    ).rejects.toBe(err)
+  })
+})
+
+describe('photo→document fallback (gateway reply-loop shape)', () => {
+  it('re-sends as a document when sendPhoto is rejected for dimensions', async () => {
+    const retry = createRetryApiCall()
+    const err = errors.badRequest('PHOTO_INVALID_DIMENSIONS', 'sendPhoto')
+    const sendPhoto = vi.fn(() => Promise.reject(err))
+    const sendDocument = vi.fn(() => Promise.resolve({ message_id: 555 }))
+
+    // Mirror gateway.ts executeReply's per-file try/catch.
+    let sent: { message_id: number }
+    try {
+      sent = await retryWithThreadFallback(retry, () => sendPhoto(), {
+        threadId: undefined,
+        chat_id: '123',
+        verb: 'sendPhoto',
+      })
+    } catch (caught) {
+      expect(isPhotoDimensionRejectError(caught)).toBe(true)
+      sent = await retryWithThreadFallback(retry, () => sendDocument(), {
+        threadId: undefined,
+        chat_id: '123',
+        verb: 'sendDocument',
+      })
+    }
+
+    expect(sendPhoto).toHaveBeenCalledTimes(1)
+    expect(sendDocument).toHaveBeenCalledTimes(1)
+    expect(sent!.message_id).toBe(555)
+  })
+
+  it('does NOT fall back for non-dimension errors (they propagate)', async () => {
+    const retry = createRetryApiCall()
+    const err = errors.forbidden('sendPhoto')
+    const sendDocument = vi.fn(() => Promise.resolve({ message_id: 1 }))
+
+    let threw = false
+    try {
+      await retryWithThreadFallback(retry, () => Promise.reject(err), {
+        threadId: undefined,
+        chat_id: '123',
+        verb: 'sendPhoto',
+      })
+    } catch (caught) {
+      threw = true
+      // The gateway only falls back when this predicate holds.
+      expect(isPhotoDimensionRejectError(caught)).toBe(false)
+    }
+    expect(threw).toBe(true)
+    expect(sendDocument).not.toHaveBeenCalled()
+  })
+})