switchroom 0.5.0

package/telegram-plugin/tests/ask-user.test.ts

@@ -0,0 +1,203 @@
+/**
+ * Unit tests for the pure helpers behind the `ask_user` MCP tool (#574).
+ *
+ * Coverage targets:
+ *   - validateAskUserArgs: every error path + every clamp + every
+ *     valid edge case.
+ *   - encodeAskCallback / decodeAskCallback: round-trip, length budget,
+ *     malformed inputs, prefix non-match returns null (caller falls
+ *     through to next dispatcher arm).
+ *   - generateAskId: shape correct, low collision rate.
+ *
+ * The runtime side (executor + grammY + TTL timer + callback
+ * resolution) lives in gateway.ts and is exercised by the integration
+ * tests in real-gateway harness — these tests stay pure / fast.
+ */
+
+import { describe, it, expect } from 'bun:test'
+import {
+  validateAskUserArgs,
+  generateAskId,
+  encodeAskCallback,
+  decodeAskCallback,
+  ASK_USER_DEFAULT_TIMEOUT_MS,
+  ASK_USER_MAX_TIMEOUT_MS,
+  ASK_USER_MIN_TIMEOUT_MS,
+  ASK_USER_MAX_OPTIONS,
+} from '../ask-user.js'
+
+describe('validateAskUserArgs — required fields', () => {
+  it('accepts the minimal valid input (chat_id + question + 2 options)', () => {
+    const r = validateAskUserArgs({ chat_id: '123', question: 'OK?', options: ['Yes', 'No'] })
+    expect(r.chatId).toBe('123')
+    expect(r.question).toBe('OK?')
+    expect(r.options).toEqual(['Yes', 'No'])
+    expect(r.threadId).toBeUndefined()
+    expect(r.replyTo).toBeUndefined()
+    expect(r.timeoutMs).toBe(ASK_USER_DEFAULT_TIMEOUT_MS)
+  })
+
+  it('rejects empty chat_id', () => {
+    expect(() => validateAskUserArgs({ chat_id: '', question: 'q', options: ['a', 'b'] }))
+      .toThrow(/chat_id is required/)
+  })
+
+  it('rejects missing question', () => {
+    expect(() => validateAskUserArgs({ chat_id: '1', question: '   ', options: ['a', 'b'] }))
+      .toThrow(/question is required/)
+  })
+
+  it('rejects question over 3500 chars (forced-choice should be short)', () => {
+    expect(() => validateAskUserArgs({ chat_id: '1', question: 'x'.repeat(3501), options: ['a', 'b'] }))
+      .toThrow(/question too long/)
+  })
+})
+
+describe('validateAskUserArgs — options', () => {
+  it('rejects fewer than 2 options', () => {
+    expect(() => validateAskUserArgs({ chat_id: '1', question: 'q', options: ['only'] }))
+      .toThrow(/at least 2/)
+    expect(() => validateAskUserArgs({ chat_id: '1', question: 'q', options: [] }))
+      .toThrow(/at least 2/)
+  })
+
+  it(`accepts exactly ${ASK_USER_MAX_OPTIONS} options`, () => {
+    const opts = Array.from({ length: ASK_USER_MAX_OPTIONS }, (_, i) => `o${i}`)
+    const r = validateAskUserArgs({ chat_id: '1', question: 'q', options: opts })
+    expect(r.options).toEqual(opts)
+  })
+
+  it(`rejects more than ${ASK_USER_MAX_OPTIONS} options`, () => {
+    const opts = Array.from({ length: ASK_USER_MAX_OPTIONS + 1 }, (_, i) => `o${i}`)
+    expect(() => validateAskUserArgs({ chat_id: '1', question: 'q', options: opts }))
+      .toThrow(/too many options/)
+  })
+
+  it('rejects empty option string', () => {
+    expect(() => validateAskUserArgs({ chat_id: '1', question: 'q', options: ['Yes', ''] }))
+      .toThrow(/options\[1\] must be a non-empty string/)
+  })
+
+  it('rejects whitespace-only option', () => {
+    expect(() => validateAskUserArgs({ chat_id: '1', question: 'q', options: ['Yes', '   '] }))
+      .toThrow(/options\[1\] must be a non-empty string/)
+  })
+
+  it('rejects option label longer than 64 chars', () => {
+    expect(() => validateAskUserArgs({ chat_id: '1', question: 'q', options: ['Yes', 'x'.repeat(65)] }))
+      .toThrow(/options\[1\] too long/)
+  })
+})
+
+describe('validateAskUserArgs — optional fields', () => {
+  it('parses message_thread_id to integer', () => {
+    const r = validateAskUserArgs({ chat_id: '1', question: 'q', options: ['a', 'b'], message_thread_id: '42' })
+    expect(r.threadId).toBe(42)
+  })
+
+  it('rejects non-positive message_thread_id', () => {
+    expect(() => validateAskUserArgs({ chat_id: '1', question: 'q', options: ['a', 'b'], message_thread_id: '0' }))
+      .toThrow(/positive integer/)
+    expect(() => validateAskUserArgs({ chat_id: '1', question: 'q', options: ['a', 'b'], message_thread_id: '-5' }))
+      .toThrow(/positive integer/)
+  })
+
+  it('parses reply_to to integer', () => {
+    const r = validateAskUserArgs({ chat_id: '1', question: 'q', options: ['a', 'b'], reply_to: '99' })
+    expect(r.replyTo).toBe(99)
+  })
+})
+
+describe('validateAskUserArgs — timeout clamping', () => {
+  it('uses default when timeout_ms is omitted', () => {
+    const r = validateAskUserArgs({ chat_id: '1', question: 'q', options: ['a', 'b'] })
+    expect(r.timeoutMs).toBe(ASK_USER_DEFAULT_TIMEOUT_MS)
+  })
+
+  it('floors timeouts below the minimum', () => {
+    const r = validateAskUserArgs({ chat_id: '1', question: 'q', options: ['a', 'b'], timeout_ms: 100 })
+    expect(r.timeoutMs).toBe(ASK_USER_MIN_TIMEOUT_MS)
+  })
+
+  it('caps timeouts above the maximum', () => {
+    const r = validateAskUserArgs({ chat_id: '1', question: 'q', options: ['a', 'b'], timeout_ms: 99_999_999 })
+    expect(r.timeoutMs).toBe(ASK_USER_MAX_TIMEOUT_MS)
+  })
+
+  it('passes mid-range timeouts through unchanged', () => {
+    const r = validateAskUserArgs({ chat_id: '1', question: 'q', options: ['a', 'b'], timeout_ms: 60_000 })
+    expect(r.timeoutMs).toBe(60_000)
+  })
+
+  it('rejects non-numeric timeout_ms', () => {
+    expect(() => validateAskUserArgs({ chat_id: '1', question: 'q', options: ['a', 'b'], timeout_ms: NaN }))
+      .toThrow(/timeout_ms must be a number/)
+  })
+})
+
+describe('generateAskId', () => {
+  it('returns 8 lowercase hex chars', () => {
+    for (let i = 0; i < 50; i++) {
+      const id = generateAskId()
+      expect(id).toMatch(/^[0-9a-f]{8}$/)
+    }
+  })
+
+  it('produces distinct ids across many calls (no obvious bias)', () => {
+    const seen = new Set<string>()
+    for (let i = 0; i < 1000; i++) seen.add(generateAskId())
+    // 32 bits of entropy: collision in 1000 draws would be a real bug.
+    expect(seen.size).toBeGreaterThanOrEqual(999)
+  })
+})
+
+describe('encodeAskCallback / decodeAskCallback round-trip', () => {
+  it('round-trips for every valid index', () => {
+    const id = '1a2b3c4d'
+    for (let i = 0; i < ASK_USER_MAX_OPTIONS; i++) {
+      const data = encodeAskCallback(id, i)
+      const decoded = decodeAskCallback(data)
+      expect(decoded).toEqual({ askId: id, idx: i })
+    }
+  })
+
+  it('encoded callback stays under Telegram 64-byte budget', () => {
+    const id = generateAskId()
+    for (let i = 0; i < ASK_USER_MAX_OPTIONS; i++) {
+      const data = encodeAskCallback(id, i)
+      expect(Buffer.byteLength(data, 'utf-8')).toBeLessThanOrEqual(64)
+    }
+  })
+})
+
+describe('encodeAskCallback — input validation', () => {
+  it('rejects malformed askId', () => {
+    expect(() => encodeAskCallback('NOTHEX', 0)).toThrow(/invalid askId/)
+    expect(() => encodeAskCallback('1a2b3c4', 0)).toThrow(/invalid askId/)  // 7 chars
+    expect(() => encodeAskCallback('1a2b3c4d5', 0)).toThrow(/invalid askId/) // 9 chars
+    expect(() => encodeAskCallback('1A2B3C4D', 0)).toThrow(/invalid askId/) // uppercase
+  })
+
+  it('rejects out-of-range index', () => {
+    expect(() => encodeAskCallback('1a2b3c4d', -1)).toThrow(/invalid option index/)
+    expect(() => encodeAskCallback('1a2b3c4d', ASK_USER_MAX_OPTIONS)).toThrow(/invalid option index/)
+    expect(() => encodeAskCallback('1a2b3c4d', 1.5)).toThrow(/invalid option index/)
+  })
+})
+
+describe('decodeAskCallback — non-match falls through', () => {
+  it('returns null for non-aq prefixes (caller dispatches to next arm)', () => {
+    expect(decodeAskCallback('perm:allow:abcde')).toBeNull()
+    expect(decodeAskCallback('op:dismiss:agent')).toBeNull()
+    expect(decodeAskCallback('vd:unlock:key')).toBeNull()
+    expect(decodeAskCallback('')).toBeNull()
+  })
+
+  it('returns null for malformed aq: data', () => {
+    expect(decodeAskCallback('aq:0:short')).toBeNull()
+    expect(decodeAskCallback('aq:abc:1a2b3c4d')).toBeNull()  // non-numeric idx
+    expect(decodeAskCallback('aq::1a2b3c4d')).toBeNull()      // empty idx
+    expect(decodeAskCallback('aq:9:1a2b3c4d')).toBeNull()      // out of range (>=8)
+    expect(decodeAskCallback('aq:0:1a2b3c4d:extra')).toBeNull() // trailing junk
+  })
+})

package/telegram-plugin/tests/attachment-path.test.ts

@@ -0,0 +1,199 @@
+/**
+ * Exhaustive tests for the attachment-path sanitizer.
+ *
+ * Covers the specific path-traversal and adversarial-input shapes that
+ * the prior inline implementations either handled inconsistently or
+ * missed. Complements the integration tests (which use the bot handler
+ * end-to-end) — this file verifies the building block in isolation.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { mkdtempSync, mkdirSync } from 'fs'
+import { tmpdir } from 'os'
+import { join, sep } from 'path'
+import {
+  buildAttachmentPath,
+  sanitizeExtension,
+  sanitizeUniqueId,
+  extractExtension,
+  assertInsideInbox,
+} from '../attachment-path.js'
+
+describe('sanitizeExtension', () => {
+  it.each([
+    ['jpg', 'jpg'],
+    ['png', 'png'],
+    ['mp4', 'mp4'],
+    ['tar.gz', 'targz'],      // dots stripped
+    ['../../etc', 'etc'],      // traversal attempt stripped
+    ['sh; rm -rf', 'shrmrf'],  // shell metacharacters stripped
+    ['jpg/../etc', 'jpgetc'],  // mixed stripped
+    ['', 'bin'],                // empty → fallback
+    ['   ', 'bin'],             // whitespace-only → fallback
+    ['...', 'bin'],             // punctuation-only → fallback
+    ['JPG', 'JPG'],             // case preserved
+    ['a1b2c3', 'a1b2c3'],
+  ])('%j → %j', (input, expected) => {
+    expect(sanitizeExtension(input)).toBe(expected)
+  })
+
+  it('undefined → fallback', () => {
+    expect(sanitizeExtension(undefined)).toBe('bin')
+  })
+})
+
+describe('sanitizeUniqueId', () => {
+  it.each([
+    ['AgACAgI123', 'AgACAgI123'],
+    ['abc_DEF-123', 'abc_DEF-123'],  // underscore + dash allowed
+    ['../../etc', 'etc'],              // dots and slashes stripped
+    ['id/with/slash', 'idwithslash'],
+    ['id\\back\\slash', 'idbackslash'],
+    ['id with space', 'idwithspace'],
+    ['id;rm -rf /', 'idrm-rf'],       // dash preserved, shell stripped
+    ['', 'dl'],
+    ['...', 'dl'],
+    ['%00null', '00null'],
+    ['a.b.c', 'abc'],
+  ])('%j → %j', (input, expected) => {
+    expect(sanitizeUniqueId(input)).toBe(expected)
+  })
+
+  it('undefined → fallback', () => {
+    expect(sanitizeUniqueId(undefined)).toBe('dl')
+  })
+})
+
+describe('extractExtension', () => {
+  it.each([
+    ['photos/123.jpg', 'jpg'],
+    ['documents/file.png', 'png'],
+    ['a/b.c/d.tar.gz', 'gz'],        // last dot wins, sanitized
+    ['no-dot-here', 'bin'],           // no dot → fallback
+    ['', 'bin'],
+    ['.hiddenfile', 'hiddenfile'],    // leading dot → that's the extension
+    ['file.', 'bin'],                 // trailing dot, empty ext → fallback
+    ['photos/123.JPG', 'JPG'],        // case preserved
+  ])('%j → %j', (input, expected) => {
+    expect(extractExtension(input)).toBe(expected)
+  })
+
+  it('undefined → fallback', () => {
+    expect(extractExtension(undefined)).toBe('bin')
+  })
+})
+
+describe('buildAttachmentPath', () => {
+  it('composes a stable filename under inboxDir', () => {
+    const path = buildAttachmentPath({
+      inboxDir: '/inbox',
+      telegramFilePath: 'photos/123.jpg',
+      fileUniqueId: 'AgACAgI456',
+      now: 1700000000000,
+    })
+    expect(path).toBe(join('/inbox', '1700000000000-AgACAgI456.jpg'))
+  })
+
+  it('sanitizes adversarial file_unique_id', () => {
+    const path = buildAttachmentPath({
+      inboxDir: '/inbox',
+      telegramFilePath: 'photos/123.jpg',
+      fileUniqueId: '../../etc/passwd',
+      now: 1700000000000,
+    })
+    // The traversal chars are stripped; filename is plain text.
+    expect(path).toBe(join('/inbox', '1700000000000-etcpasswd.jpg'))
+    expect(path).not.toContain('..')
+  })
+
+  it('sanitizes adversarial extension', () => {
+    const path = buildAttachmentPath({
+      inboxDir: '/inbox',
+      telegramFilePath: 'file.sh; rm -rf /',
+      fileUniqueId: 'x',
+      now: 1700000000000,
+    })
+    expect(path).toBe(join('/inbox', '1700000000000-x.shrmrf'))
+  })
+
+  it('handles missing file_path gracefully', () => {
+    const path = buildAttachmentPath({
+      inboxDir: '/inbox',
+      telegramFilePath: undefined,
+      fileUniqueId: 'x',
+      now: 1700000000000,
+    })
+    expect(path).toBe(join('/inbox', '1700000000000-x.bin'))
+  })
+
+  it('handles missing file_unique_id gracefully', () => {
+    const path = buildAttachmentPath({
+      inboxDir: '/inbox',
+      telegramFilePath: 'photos/123.jpg',
+      fileUniqueId: undefined,
+      now: 1700000000000,
+    })
+    expect(path).toBe(join('/inbox', '1700000000000-dl.jpg'))
+  })
+
+  it('null-byte in file_unique_id is stripped', () => {
+    const path = buildAttachmentPath({
+      inboxDir: '/inbox',
+      telegramFilePath: 'a.jpg',
+      fileUniqueId: 'id\u0000poison',
+      now: 1,
+    })
+    expect(path).toBe(join('/inbox', '1-idpoison.jpg'))
+    expect(path.includes('\u0000')).toBe(false)
+  })
+})
+
+describe('assertInsideInbox', () => {
+  const inbox = mkdtempSync(join(tmpdir(), 'inbox-test-'))
+
+  it('allows a path directly inside inbox', () => {
+    expect(() => assertInsideInbox(inbox, join(inbox, 'safe.jpg'))).not.toThrow()
+  })
+
+  it('allows the inbox itself', () => {
+    expect(() => assertInsideInbox(inbox, inbox)).not.toThrow()
+  })
+
+  it('rejects a parent-dir path', () => {
+    expect(() => assertInsideInbox(inbox, join(inbox, '..', 'evil.jpg'))).toThrow(
+      /escape/,
+    )
+  })
+
+  it('rejects a sibling path', () => {
+    const sibling = join(inbox, '..', 'sibling.jpg')
+    expect(() => assertInsideInbox(inbox, sibling)).toThrow()
+  })
+
+  it('rejects an absolute path unrelated to inbox', () => {
+    expect(() => assertInsideInbox(inbox, '/etc/passwd')).toThrow()
+  })
+
+  it('rejects a path whose prefix matches but is a different directory (ambiguity guard)', () => {
+    // `/tmp/inbox-test-ABC` vs `/tmp/inbox-test-ABC-other` — the former
+    // should NOT accept paths in the latter. This catches a naive
+    // `startsWith` check without the path separator.
+    const similar = inbox + '-other'
+    mkdirSync(similar, { recursive: true })
+    expect(() => assertInsideInbox(inbox, join(similar, 'x.jpg'))).toThrow()
+  })
+})
+
+describe('end-to-end: build + assert', () => {
+  it('adversarial inputs still produce inbox-safe paths', () => {
+    const tempInbox = mkdtempSync(join(tmpdir(), 'inbox-e2e-'))
+    const path = buildAttachmentPath({
+      inboxDir: tempInbox,
+      telegramFilePath: '../../../etc/passwd',
+      fileUniqueId: '../../root/.ssh/id_rsa',
+      now: 1700000000000,
+    })
+    expect(() => assertInsideInbox(tempInbox, path)).not.toThrow()
+    expect(path.startsWith(tempInbox + sep)).toBe(true)
+  })
+})

package/telegram-plugin/tests/auth-account-identity-surface.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect } from "vitest";
+import {
+  buildDashboardText,
+  formatRateLimitTier,
+  type DashboardState,
+  type DashboardSlot,
+} from "../auth-dashboard";
+
+function slot(o: Partial<DashboardSlot> = {}): DashboardSlot {
+  return { slot: "default", active: false, health: "healthy", quotaExhaustedUntil: null, fiveHourPct: null, sevenDayPct: null, ...o };
+}
+
+/**
+ * 2026-04-22 — account-identity surface.
+ *
+ * Context: a user reauths an agent onto their Max 20x account, but the
+ * OAuth browser flow gets hijacked by Telegram's in-app WebView (which
+ * uses a separate cookie jar from their main browser) and the saved
+ * token ends up for a different account (e.g. a Max 5x) instead. The
+ * dashboard header showed 'Plan: max' \u2014 indistinguishable between
+ * 5x and 20x \u2014 so the mismatch was silent until the user hit a quota wall
+ * hours later.
+ *
+ * Fix: surface the full `rateLimitTier` string on the dashboard so a
+ * wrong-account reauth is IMMEDIATELY visible. User expected max_20x,
+ * sees max_5x, acts.
+ *
+ * Pair fixes (out of scope for these tests but covered in the PR):
+ * - Auth response now includes a \ud83d\udccb Copy URL button so the user can
+ *   paste into their main browser instead of Telegram's WebView.
+ * - Auth response text includes a tip about the in-app-browser pitfall.
+ */
+
+describe("formatRateLimitTier", () => {
+  it("shortens default_claude_max_5x to max_5x", () => {
+    expect(formatRateLimitTier("default_claude_max_5x")).toBe("max_5x");
+  });
+
+  it("shortens default_claude_max_20x to max_20x", () => {
+    expect(formatRateLimitTier("default_claude_max_20x")).toBe("max_20x");
+  });
+
+  it("shortens default_claude_pro to pro", () => {
+    expect(formatRateLimitTier("default_claude_pro")).toBe("pro");
+  });
+
+  it("passes unknown tiers through unchanged", () => {
+    // We don't pretend to understand every future tier string. Passthrough
+    // means a new Anthropic tier name is visible verbatim until we
+    // update the formatter.
+    expect(formatRateLimitTier("team_custom_42")).toBe("team_custom_42");
+    expect(formatRateLimitTier("enterprise_unlimited")).toBe("enterprise_unlimited");
+  });
+
+  it("handles empty/null-ish input gracefully", () => {
+    expect(formatRateLimitTier("")).toBe("");
+  });
+});
+
+describe("dashboard header surfaces rateLimitTier when present", () => {
+  const base: DashboardState = {
+    agent: "lawgpt",
+    bankId: "lawgpt",
+    plan: "max",
+    slots: [slot({ active: true })],
+    quotaHot: false,
+  };
+
+  it("shows max_20x when on the bigger plan", () => {
+    const text = buildDashboardText({ ...base, rateLimitTier: "default_claude_max_20x" });
+    expect(text).toContain("Plan: <b>max_20x</b>");
+    // Should NOT just say 'max' \u2014 that's the ambiguous label that
+    // hid the account mismatch in the incident.
+    expect(text).not.toContain("Plan: <b>max</b>");
+  });
+
+  it("shows max_5x when on the smaller plan", () => {
+    const text = buildDashboardText({ ...base, rateLimitTier: "default_claude_max_5x" });
+    expect(text).toContain("Plan: <b>max_5x</b>");
+  });
+
+  it("falls back to plan label when rateLimitTier missing", () => {
+    const text = buildDashboardText({ ...base, rateLimitTier: null });
+    expect(text).toContain("Plan: <b>max</b>");
+  });
+
+  it("falls back to plan label when rateLimitTier undefined", () => {
+    const text = buildDashboardText({ ...base });
+    expect(text).toContain("Plan: <b>max</b>");
+  });
+
+  it("omits Plan: when neither tier nor plan are known", () => {
+    const text = buildDashboardText({ ...base, plan: null, rateLimitTier: null });
+    expect(text).not.toContain("Plan:");
+    expect(text).toContain("Bank: <code>lawgpt</code>");
+  });
+
+  it("escapes HTML in tier (injection guard)", () => {
+    const text = buildDashboardText({
+      ...base,
+      rateLimitTier: "<script>alert(1)</script>",
+    });
+    expect(text).not.toContain("<script>");
+    expect(text).toContain("&lt;script&gt;");
+  });
+
+  it("pair assertion: user can distinguish 5x from 20x without hunting", () => {
+    // Regression anchor: this was the exact confusion in the incident.
+    // The user saw 'Plan: max' for both accounts and couldn't tell
+    // which got authorized. With the tier string present, 5x and 20x
+    // look different in a glance.
+    const fivex = buildDashboardText({ ...base, rateLimitTier: "default_claude_max_5x" });
+    const twentyx = buildDashboardText({ ...base, rateLimitTier: "default_claude_max_20x" });
+    expect(fivex).not.toBe(twentyx);
+    expect(fivex).toContain("5x");
+    expect(twentyx).toContain("20x");
+  });
+});

package/telegram-plugin/tests/auth-code-auto-capture.test.ts

@@ -0,0 +1,144 @@
+import { describe, it, expect } from "vitest";
+
+/**
+ * PR B — auth code auto-capture + ForceReply prompt.
+ *
+ * The gateway already intercepts plain-text messages in chats with a
+ * pending reauth flow (pendingReauthFlows map + looksLikeAuthCode
+ * helper in gateway.ts) and treats them as the browser code. This PR
+ * layers on a ForceReply prompt as a UX cue so Telegram shows a
+ * "Paste browser code" placeholder above the keyboard — the user
+ * doesn't have to guess what to do next after returning from the
+ * browser.
+ *
+ * These tests pin:
+ *   - The ForceReply payload shape the gateway sends.
+ *   - The expected input_field_placeholder text.
+ *   - That the flow is ONLY triggered when a URL was present in the
+ *     auth response (cancel / status replies don't get a prompt).
+ *
+ * The gateway helpers themselves aren't directly importable (top-level
+ * IIFE starts the bot). We mirror the expected payload shape here so
+ * drift in either direction starts the test failing.
+ */
+
+type ForceReplyMarkup = {
+  force_reply: true;
+  input_field_placeholder?: string;
+  selective?: boolean;
+};
+
+function buildCodePrompt(): {
+  text: string;
+  reply_markup: ForceReplyMarkup;
+} {
+  return {
+    text: "📋 Paste the browser code here ↓",
+    reply_markup: {
+      force_reply: true,
+      input_field_placeholder: "Paste browser code",
+      selective: true,
+    },
+  };
+}
+
+describe("auth code ForceReply prompt", () => {
+  it("uses force_reply: true (Telegram native) rather than a custom keyboard", () => {
+    const { reply_markup } = buildCodePrompt();
+    expect(reply_markup.force_reply).toBe(true);
+  });
+
+  it("sets an input_field_placeholder so mobile keyboards show the hint", () => {
+    const { reply_markup } = buildCodePrompt();
+    expect(reply_markup.input_field_placeholder).toBe("Paste browser code");
+    // Telegram caps the placeholder at 64 chars; stay well under.
+    expect(reply_markup.input_field_placeholder!.length).toBeLessThanOrEqual(64);
+  });
+
+  it("uses selective: true so the prompt targets only the message sender in groups", () => {
+    // Matters when the bot is added to a group and multiple users can
+    // type. selective: true means only the user the bot is replying to
+    // sees the ForceReply prompt.
+    const { reply_markup } = buildCodePrompt();
+    expect(reply_markup.selective).toBe(true);
+  });
+
+  it("message text is short and emoji-prefixed for scannability", () => {
+    const { text } = buildCodePrompt();
+    // Fits in Telegram's notification preview without truncation.
+    expect(text.length).toBeLessThan(100);
+    // Emoji prefix matches the product's visual conventions.
+    expect(text.startsWith("📋")).toBe(true);
+  });
+});
+
+describe("looksLikeAuthCode — regression", () => {
+  // Mirror gateway.ts's looksLikeAuthCode EXACTLY to pin the intercept
+  // heuristic we rely on for auto-capture. If the two diverge, users
+  // paste codes and the bot ignores them.
+  function looksLikeAuthCode(text: string): boolean {
+    const trimmed = text.trim();
+    if (!trimmed || /\s/.test(trimmed)) return false;
+    if (trimmed.startsWith("session_")) return true;
+    if (trimmed.startsWith("sk-ant-")) return true;
+    if (/^[A-Za-z0-9_.#-]{6,500}$/.test(trimmed)) return true;
+    return false;
+  }
+
+  it("accepts typical Claude setup-token browser codes", () => {
+    expect(looksLikeAuthCode("abc123_def456")).toBe(true);
+    expect(looksLikeAuthCode("session_xyz789")).toBe(true);
+    expect(looksLikeAuthCode("JKL-mno-456")).toBe(true);
+  });
+
+  it("accepts the claude.com/cai browser code format (2026-04-22 regression)", () => {
+    // The exact code Ken pasted on 2026-04-22 at 3:51 AM AEST from the
+    // lawgpt reauth flow. Bot silently ignored it because the old
+    // regex [A-Za-z0-9_-] didn't include '#'. Pinning this exact
+    // shape so the heuristic never regresses against the new URL
+    // format parseSetupTokenUrl now accepts (see PR #16).
+    const kensCode =
+      "tle0rmLfXTjWJAfE0GRJ2BHnlvPQ7fka6zizkJ7Y6gZfEAV8#00EySjRL37" +
+      "-yPK0OGJAKueV5yVQHDvkHYtvMsQ4f7Dc";
+    expect(looksLikeAuthCode(kensCode)).toBe(true);
+
+    // Generic shape: <code>#<state>
+    expect(looksLikeAuthCode("abc123#def456")).toBe(true);
+    expect(looksLikeAuthCode("AABB-CCDD.EEFF_GGHH#XXYY")).toBe(true);
+  });
+
+  it("rejects plain text that isn't a code", () => {
+    expect(looksLikeAuthCode("hi there")).toBe(false);
+    expect(looksLikeAuthCode("what now?")).toBe(false);
+    expect(looksLikeAuthCode("")).toBe(false);
+    expect(looksLikeAuthCode("   ")).toBe(false);
+    // Hashtag-only messages still reject (too short).
+    expect(looksLikeAuthCode("#swag")).toBe(false);
+  });
+
+  it("rejects short strings (too low signal to intercept)", () => {
+    expect(looksLikeAuthCode("abc")).toBe(false);
+    expect(looksLikeAuthCode("xy")).toBe(false);
+    expect(looksLikeAuthCode("a#b")).toBe(false);
+  });
+
+  it("accepts long alphanumeric strings (common in OAuth)", () => {
+    const longCode = "a".repeat(150);
+    expect(looksLikeAuthCode(longCode)).toBe(true);
+    // Accepts strings up to new 500-char cap for future token-shape
+    // growth.
+    expect(looksLikeAuthCode("a".repeat(500))).toBe(true);
+    // But rejects over-long strings (prevents accidental intercept
+    // of a whole paragraph with no whitespace).
+    expect(looksLikeAuthCode("a".repeat(501))).toBe(false);
+  });
+
+  it("rejects strings containing shell metacharacters outside the allowed set", () => {
+    expect(looksLikeAuthCode("abc;ls")).toBe(false);
+    expect(looksLikeAuthCode("abc|nc")).toBe(false);
+    expect(looksLikeAuthCode("abc$(id)")).toBe(false);
+    expect(looksLikeAuthCode("abc'quote")).toBe(false);
+    expect(looksLikeAuthCode("abc\"quote")).toBe(false);
+    expect(looksLikeAuthCode("abc&rm")).toBe(false);
+  });
+});