switchroom 0.5.0

package/telegram-plugin/tests/auth-code-redact.test.ts

@@ -0,0 +1,248 @@
+import { describe, it, expect, vi } from 'vitest'
+
+import { redactAuthCodeMessage } from '../auth-code-redact.js'
+
+/**
+ * Regression coverage for #488. The helper is wired into all 6
+ * auth-code paste paths (gateway + server, bare-paste + /auth code +
+ * /reauth shortcut). The contract pinned here is what callers depend
+ * on — and what makes the difference between "OAuth code stays in
+ * chat history" and "OAuth code disappears within ~1s".
+ */
+describe('redactAuthCodeMessage', () => {
+  function makeApi() {
+    return {
+      deleteMessage: vi.fn(async () => true as const),
+      setMessageReaction: vi.fn(async () => true as const),
+    }
+  }
+
+  it('deletes the message AND emits a 🔑 reaction (best-effort breadcrumb)', () => {
+    const api = makeApi()
+    redactAuthCodeMessage(api, '12345', 999)
+
+    expect(api.deleteMessage).toHaveBeenCalledTimes(1)
+    expect(api.deleteMessage).toHaveBeenCalledWith('12345', 999)
+
+    expect(api.setMessageReaction).toHaveBeenCalledTimes(1)
+    expect(api.setMessageReaction).toHaveBeenCalledWith('12345', 999, [
+      { type: 'emoji', emoji: '🔑' },
+    ])
+  })
+
+  it('is a no-op when messageId is null (defensive guard for ctx without a message)', () => {
+    const api = makeApi()
+    redactAuthCodeMessage(api, '12345', null)
+
+    expect(api.deleteMessage).not.toHaveBeenCalled()
+    expect(api.setMessageReaction).not.toHaveBeenCalled()
+  })
+
+  it('returns synchronously — does not await either call', () => {
+    // The function fires both API calls fire-and-forget so the caller
+    // can return to the event loop immediately. A blocking helper
+    // would slow every auth-code paste by ~1 RTT to Telegram.
+    const api = {
+      deleteMessage: vi.fn(() => new Promise(() => {})), // never resolves
+      setMessageReaction: vi.fn(() => new Promise(() => {})),
+    }
+    const start = Date.now()
+    redactAuthCodeMessage(api, '12345', 999)
+    const elapsed = Date.now() - start
+    // <50ms is plenty of headroom for the synchronous fire-and-forget
+    // dispatch — would be ~∞ if we awaited.
+    expect(elapsed).toBeLessThan(50)
+  })
+
+  it('swallows deleteMessage errors (message too old, user already deleted)', async () => {
+    const api = {
+      deleteMessage: vi.fn(async () => {
+        throw new Error('Bad Request: message to delete not found')
+      }),
+      setMessageReaction: vi.fn(async () => true as const),
+    }
+    // Must not throw synchronously, must not reject the unhandled promise.
+    expect(() => redactAuthCodeMessage(api, '12345', 999)).not.toThrow()
+    // Drain the microtask queue so the rejection fires + is caught.
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    expect(api.deleteMessage).toHaveBeenCalledTimes(1)
+  })
+
+  it('swallows setMessageReaction errors (race with successful delete)', async () => {
+    const api = {
+      deleteMessage: vi.fn(async () => true as const),
+      setMessageReaction: vi.fn(async () => {
+        throw new Error('Bad Request: message not found')
+      }),
+    }
+    expect(() => redactAuthCodeMessage(api, '12345', 999)).not.toThrow()
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    expect(api.setMessageReaction).toHaveBeenCalledTimes(1)
+  })
+
+  it('handles negative chat ids (groups / supergroups / channels)', () => {
+    // Telegram chat ids are negative for groups; helper passes them
+    // through verbatim — no parsing, no validation.
+    const api = makeApi()
+    redactAuthCodeMessage(api, '-1001234567890', 42)
+    expect(api.deleteMessage).toHaveBeenCalledWith('-1001234567890', 42)
+    expect(api.setMessageReaction).toHaveBeenCalledWith('-1001234567890', 42, [
+      { type: 'emoji', emoji: '🔑' },
+    ])
+  })
+
+  it('keeps reaction + delete independently dispatched even if one fails', async () => {
+    // The two calls should not depend on each other — if delete
+    // succeeds the reaction silently fails (message gone), if delete
+    // fails the reaction provides the visible breadcrumb. Both
+    // fire-and-forget, neither blocks the other.
+    const api = {
+      deleteMessage: vi.fn(async () => {
+        throw new Error('failed')
+      }),
+      setMessageReaction: vi.fn(async () => true as const),
+    }
+    redactAuthCodeMessage(api, '12345', 999)
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    // Delete failed but reaction still went through.
+    expect(api.deleteMessage).toHaveBeenCalledTimes(1)
+    expect(api.setMessageReaction).toHaveBeenCalledTimes(1)
+  })
+})
+
+/**
+ * Diagnostic logging (#561 follow-up). Before this commit the function
+ * silently swallowed every API failure — when an OAuth code paste stuck
+ * around in chat, operators had no way to tell whether deleteMessage
+ * failed on permissions, on a 48h-too-old message, or because msgId was
+ * null. The optional `log` sink emits one line per attempt (success or
+ * specific error message).
+ */
+describe('redactAuthCodeMessage — diagnostic logging', () => {
+  it('logs nothing when no log sink is provided (back-compat)', async () => {
+    const api = {
+      deleteMessage: vi.fn(async () => true as const),
+      setMessageReaction: vi.fn(async () => true as const),
+    }
+    // Just verify it doesn't crash without a sink.
+    expect(() => redactAuthCodeMessage(api, '12345', 999)).not.toThrow()
+    await new Promise((resolve) => setTimeout(resolve, 0))
+  })
+
+  it('logs the no-message-id case so the silent skip is visible', () => {
+    const api = {
+      deleteMessage: vi.fn(async () => true as const),
+      setMessageReaction: vi.fn(async () => true as const),
+    }
+    const lines: string[] = []
+    redactAuthCodeMessage(api, '12345', null, line => lines.push(line))
+    expect(lines).toHaveLength(1)
+    expect(lines[0]).toMatch(/no message_id/)
+    expect(lines[0]).toMatch(/skipping/)
+  })
+
+  it('logs SUCCESS for both delete and reaction with msgId + chatId for grep-by', async () => {
+    const api = {
+      deleteMessage: vi.fn(async () => true as const),
+      setMessageReaction: vi.fn(async () => true as const),
+    }
+    const lines: string[] = []
+    redactAuthCodeMessage(api, '12345', 999, line => lines.push(line))
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    expect(lines).toHaveLength(2)
+    // Order isn't guaranteed (independent dispatch). Assert content.
+    const joined = lines.join('\n')
+    expect(joined).toMatch(/deleted/)
+    expect(joined).toMatch(/reaction added/)
+    expect(joined).toMatch(/msgId=999/)
+    expect(joined).toMatch(/chatId=12345/)
+  })
+
+  it('logs FAILED with the actual error message on deleteMessage rejection', async () => {
+    const api = {
+      deleteMessage: vi.fn(async () => {
+        throw new Error('Bad Request: not enough rights to delete a message')
+      }),
+      setMessageReaction: vi.fn(async () => true as const),
+    }
+    const lines: string[] = []
+    redactAuthCodeMessage(api, '12345', 999, line => lines.push(line))
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    const failed = lines.find(l => l.includes('delete FAILED'))
+    expect(failed).toBeDefined()
+    // The actual Telegram error must be carried verbatim — that's the
+    // signal operators need to root-cause the redaction failure.
+    expect(failed).toMatch(/not enough rights to delete a message/)
+    // And the warning must mention the user-visible consequence so a
+    // reader of the journal understands why this matters.
+    expect(failed).toMatch(/may still be visible/)
+  })
+
+  it('logs FAILED with the actual error message on setMessageReaction rejection', async () => {
+    const api = {
+      deleteMessage: vi.fn(async () => true as const),
+      setMessageReaction: vi.fn(async () => {
+        throw new Error('Bad Request: REACTION_INVALID')
+      }),
+    }
+    const lines: string[] = []
+    redactAuthCodeMessage(api, '12345', 999, line => lines.push(line))
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    const failed = lines.find(l => l.includes('reaction FAILED'))
+    expect(failed).toBeDefined()
+    expect(failed).toMatch(/REACTION_INVALID/)
+  })
+
+  it('logs are independent — failure of one path does not suppress the other', async () => {
+    const api = {
+      deleteMessage: vi.fn(async () => {
+        throw new Error('boom')
+      }),
+      setMessageReaction: vi.fn(async () => true as const),
+    }
+    const lines: string[] = []
+    redactAuthCodeMessage(api, '12345', 999, line => lines.push(line))
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    expect(lines).toHaveLength(2)
+    expect(lines.some(l => l.includes('reaction added'))).toBe(true)
+    expect(lines.some(l => l.includes('delete FAILED'))).toBe(true)
+  })
+})
+
+/**
+ * Architectural pin: every auth-code paste call site MUST go through
+ * the helper. Greps the source — if a future PR adds a new auth-code
+ * paste handler that forgets to call `redactAuthCodeMessage`, this
+ * test fails and points at the right pattern.
+ *
+ * The current 2 call sites (post-v0.6.13):
+ *   1. gateway.ts — bare-code paste during pending reauth (the
+ *      generic message intercept that watches `pendingReauthFlows`)
+ *   2. gateway.ts — /auth code intent dispatch
+ *
+ * Removed in v0.6.13:
+ *   - /reauth <code> typed-command shortcut (the entire `bot.command(
+ *     'reauth', ...)` handler removed; the dashboard's Reauth button
+ *     fires the same flow and the generic intercept catches the
+ *     paste-back).
+ *
+ * #235 Wave 3 F4: server.ts monolith removed; the 3 server.ts call
+ * sites previously listed (bare paste / /auth code / /reauth <code>)
+ * no longer exist — gateway.ts is the only file with the live paths.
+ */
+describe('auth-code paste call-site coverage (architectural pin)', () => {
+  it('every gateway.ts call site calls redactAuthCodeMessage', async () => {
+    const fs = await import('node:fs')
+    const path = await import('node:path')
+    const repoRoot = path.resolve(__dirname, '..', '..')
+    const text = fs.readFileSync(
+      path.join(repoRoot, 'telegram-plugin', 'gateway', 'gateway.ts'),
+      'utf-8',
+    )
+    const matches = text.match(/redactAuthCodeMessage\s*\(/g) ?? []
+    // 2 call sites + 1 import statement = ≥3. Floor at 2 to be safe.
+    // (Pre-v0.6.13 was floor=3 with three call sites including
+    // the now-removed /reauth typed handler.)
+    expect(matches.length).toBeGreaterThanOrEqual(2)
+  })
+})

package/telegram-plugin/tests/auth-dashboard-edge-cases.test.ts

@@ -0,0 +1,260 @@
+import { describe, it, expect } from "vitest";
+import {
+  buildDashboardText,
+  buildDashboardKeyboard,
+  parseCallbackData,
+  encodeCallbackData,
+  isQuotaHot,
+  buildRemoveConfirmKeyboard,
+  QUOTA_HOT_THRESHOLD_PCT,
+  type DashboardSlot,
+} from "../auth-dashboard";
+
+/**
+ * Edge-case coverage for the /auth dashboard. Pair with
+ * auth-dashboard.test.ts which covers the happy paths. This file
+ * focuses on pathological input, security boundaries, and failure
+ * modes we should not regress.
+ */
+
+function slot(o: Partial<DashboardSlot> = {}): DashboardSlot {
+  return { slot: "default", active: false, health: "healthy", quotaExhaustedUntil: null, fiveHourPct: null, sevenDayPct: null, ...o };
+}
+
+describe("callback payload — hostile inputs", () => {
+  const cases: Array<[string, string]> = [
+    ["shell expansion", "auth:reauth:$(whoami)"],
+    ["backticks", "auth:reauth:`id`"],
+    ["semicolons", "auth:reauth:clerk;ls"],
+    ["pipes", "auth:reauth:clerk|nc attacker"],
+    ["dot-segments", "auth:use:../../../etc/passwd:default"],
+    ["null bytes", "auth:reauth:clerk\0xyz"],
+    ["tabs", "auth:reauth:clerk\ttab"],
+    ["newlines", "auth:reauth:clerk\nextra"],
+    ["leading space", "auth:reauth: clerk"],
+    ["trailing space", "auth:reauth:clerk "],
+    ["unicode lookalike", "auth:reauth:\u202eevil"],
+    ["empty agent", "auth:reauth:"],
+    ["empty slot for use", "auth:use:clerk:"],
+    ["slot too long (33 chars)", "auth:use:clerk:" + "a".repeat(33)],
+    ["agent too long (65 chars)", "auth:reauth:" + "a".repeat(65)],
+    ["slot contains dot", "auth:use:clerk:slot.name"],
+    ["slot contains slash", "auth:use:clerk:slot/name"],
+    ["slot contains space", "auth:use:clerk:slot name"],
+  ];
+
+  it.each(cases)("rejects %s as noop: %s", (_desc, data) => {
+    expect(parseCallbackData(data)).toEqual({ kind: "noop" });
+  });
+
+  it("accepts legitimately hyphenated slot names", () => {
+    expect(parseCallbackData("auth:use:clerk:backup-1")).toMatchObject({ kind: "use", slot: "backup-1" });
+  });
+
+  it("accepts underscored names", () => {
+    expect(parseCallbackData("auth:use:clerk:work_personal")).toMatchObject({ kind: "use", slot: "work_personal" });
+  });
+});
+
+describe("dashboard text — pathological slot states", () => {
+  it("renders 10 slots without breaking layout", () => {
+    const slots: DashboardSlot[] = Array.from({ length: 10 }, (_, i) => slot({
+      slot: `slot-${i}`,
+      active: i === 0,
+    }));
+    const text = buildDashboardText({ agent: "clerk", bankId: "assistant", plan: "max", slots, quotaHot: false });
+    // All 10 slot names appear in the output
+    for (let i = 0; i < 10; i++) {
+      expect(text).toContain(`slot-${i}`);
+    }
+  });
+
+  it("renders when ALL slots are quota-exhausted (fallback-impossible state)", () => {
+    const slots = [
+      slot({ slot: "default", active: true, health: "quota-exhausted", quotaExhaustedUntil: Date.now() + 60_000 }),
+      slot({ slot: "backup", active: false, health: "quota-exhausted", quotaExhaustedUntil: Date.now() + 120_000 }),
+    ];
+    const text = buildDashboardText({ agent: "clerk", bankId: "assistant", slots, quotaHot: true });
+    expect(text).toContain("default");
+    expect(text).toContain("backup");
+    expect(text.match(/quota-exhausted/g)?.length).toBe(2);
+  });
+
+  it("renders when a slot has zero quota data (no fiveHour/sevenDay pct)", () => {
+    const text = buildDashboardText({
+      agent: "clerk",
+      bankId: "assistant",
+      slots: [slot({ active: true, fiveHourPct: null, sevenDayPct: null })],
+      quotaHot: false,
+    });
+    // Shouldn't contain '5h:' or '7d:' if no data
+    expect(text).not.toContain("5h:");
+    expect(text).not.toContain("7d:");
+  });
+
+  it("handles plan=null gracefully", () => {
+    const text = buildDashboardText({
+      agent: "clerk",
+      bankId: "assistant",
+      plan: null,
+      slots: [slot({ active: true })],
+      quotaHot: false,
+    });
+    expect(text).toContain("assistant");
+    expect(text).not.toContain("Plan:");
+  });
+
+  it("handles 0% utilization (falsy but present)", () => {
+    const text = buildDashboardText({
+      agent: "clerk",
+      bankId: "a",
+      slots: [slot({ active: true, fiveHourPct: 0, sevenDayPct: 0 })],
+      quotaHot: false,
+    });
+    expect(text).toContain("5h: 0%");
+    expect(text).toContain("7d: 0%");
+  });
+
+  it("handles 100% utilization", () => {
+    const text = buildDashboardText({
+      agent: "clerk",
+      bankId: "a",
+      slots: [slot({ active: true, fiveHourPct: 100, sevenDayPct: 100 })],
+      quotaHot: true,
+    });
+    expect(text).toContain("5h: 100%");
+    expect(text).toContain("7d: 100%");
+  });
+
+  it("handles negative reset time (already expired)", () => {
+    const text = buildDashboardText({
+      agent: "clerk",
+      bankId: "a",
+      slots: [slot({ active: true, health: "quota-exhausted", quotaExhaustedUntil: Date.now() - 60_000 })],
+      quotaHot: true,
+    });
+    // Should clamp to 0 rather than show negative minutes
+    expect(text).toContain("resets in ~0m");
+  });
+
+  it("escapes very adversarial agent names", () => {
+    const text = buildDashboardText({
+      agent: '</b><script>alert("x")</script><b>',
+      bankId: "a",
+      slots: [slot({ active: true })],
+      quotaHot: false,
+    });
+    expect(text).not.toContain("<script>");
+    expect(text).toContain("&lt;script&gt;");
+  });
+});
+
+describe("dashboard keyboard — edge cases", () => {
+  it("caps non-active slot buttons at 3 (prevents runaway rows)", () => {
+    const slots = [
+      slot({ slot: "active", active: true }),
+      slot({ slot: "s1" }),
+      slot({ slot: "s2" }),
+      slot({ slot: "s3" }),
+      slot({ slot: "s4" }),
+      slot({ slot: "s5" }),
+    ];
+    const kb = buildDashboardKeyboard({ agent: "clerk", bankId: "a", slots, quotaHot: false });
+    const useButtons = kb.inline_keyboard.flat().filter((b) => b.text.startsWith("Use:"));
+    expect(useButtons.length).toBeLessThanOrEqual(3);
+  });
+
+  it("no [Reauth active] button when no active slot", () => {
+    const kb = buildDashboardKeyboard({ agent: "clerk", bankId: "a", slots: [slot({ slot: "a", active: false })], quotaHot: false });
+    const reauthButton = kb.inline_keyboard.flat().find((b) => b.text.includes("Reauth"));
+    // There IS still a Reauth button (agent-level, no slot) — expected behaviour
+    expect(reauthButton).toBeDefined();
+    // But it should NOT reference a specific slot name
+    expect(reauthButton!.text).not.toMatch(/Reauth \S+$/);
+  });
+
+  it("no Use/Remove rows at all when only the active slot exists", () => {
+    const kb = buildDashboardKeyboard({ agent: "clerk", bankId: "a", slots: [slot({ active: true })], quotaHot: false });
+    const flat = kb.inline_keyboard.flat();
+    expect(flat.some((b) => b.text.startsWith("Use:"))).toBe(false);
+    expect(flat.some((b) => b.text.startsWith("🗑 Remove:"))).toBe(false);
+  });
+
+  it("empty slot set still shows Add + Refresh", () => {
+    const kb = buildDashboardKeyboard({ agent: "clerk", bankId: "a", slots: [], quotaHot: false });
+    const flat = kb.inline_keyboard.flat();
+    expect(flat.some((b) => b.text.includes("Add slot"))).toBe(true);
+    expect(flat.some((b) => b.text.includes("Refresh"))).toBe(true);
+  });
+
+  it("Refresh callback always targets the correct agent", () => {
+    const kb = buildDashboardKeyboard({ agent: "specific-agent", bankId: "a", slots: [], quotaHot: false });
+    const refreshBtn = kb.inline_keyboard.flat().find((b) => b.text.includes("Refresh"));
+    if (refreshBtn && "callback_data" in refreshBtn) {
+      expect(refreshBtn.callback_data).toBe("auth:refresh:specific-agent");
+    }
+  });
+});
+
+describe("isQuotaHot — boundary conditions", () => {
+  it("99% 5h does NOT trip hot (cold, auto-fallback at 99.5%)", () => {
+    expect(isQuotaHot([slot({ fiveHourPct: 89 })])).toBe(false);
+  });
+
+  it("exactly QUOTA_HOT_THRESHOLD_PCT (90%) trips hot", () => {
+    expect(isQuotaHot([slot({ fiveHourPct: QUOTA_HOT_THRESHOLD_PCT })])).toBe(true);
+    expect(isQuotaHot([slot({ sevenDayPct: QUOTA_HOT_THRESHOLD_PCT })])).toBe(true);
+  });
+
+  it("one hot slot among many cold → hot", () => {
+    expect(isQuotaHot([
+      slot({ fiveHourPct: 10 }),
+      slot({ fiveHourPct: 20 }),
+      slot({ fiveHourPct: 95 }),
+      slot({ fiveHourPct: 0 }),
+    ])).toBe(true);
+  });
+
+  it("quota-exhausted always hot, even with 0% pct", () => {
+    expect(isQuotaHot([slot({ health: "quota-exhausted", fiveHourPct: 0, sevenDayPct: 0 })])).toBe(true);
+  });
+
+  it("null utilization doesn't trip", () => {
+    expect(isQuotaHot([slot({ fiveHourPct: null, sevenDayPct: null })])).toBe(false);
+  });
+});
+
+describe("remove confirm keyboard — edge cases", () => {
+  it("cancel button refreshes back to the dashboard (doesn't leave orphan)", () => {
+    const kb = buildRemoveConfirmKeyboard("clerk", "personal");
+    const cancelBtn = kb.inline_keyboard.flat().find((b) => b.text.includes("Cancel"));
+    if (cancelBtn && "callback_data" in cancelBtn) {
+      expect(cancelBtn.callback_data).toBe("auth:refresh:clerk");
+    }
+  });
+
+  it("handles slot names with hyphens/underscores in the confirm label", () => {
+    const kb = buildRemoveConfirmKeyboard("clerk", "backup_slot-v2");
+    const confirmBtn = kb.inline_keyboard.flat().find((b) => b.text.startsWith("⚠️"));
+    expect(confirmBtn?.text).toContain("backup_slot-v2");
+  });
+});
+
+describe("encode/parse round-trip — lots of identities", () => {
+  const actions = [
+    { kind: "refresh", agent: "a" },
+    { kind: "reauth", agent: "a" },
+    { kind: "reauth", agent: "a", slot: "b" },
+    { kind: "add", agent: "a" },
+    { kind: "use", agent: "a", slot: "b" },
+    { kind: "rm", agent: "a", slot: "b" },
+    { kind: "confirm-rm", agent: "a", slot: "b" },
+    { kind: "fallback", agent: "a" },
+    { kind: "usage", agent: "a" },
+  ] as const;
+
+  it.each(actions)("round-trips %s", (action) => {
+    const encoded = encodeCallbackData(action);
+    expect(parseCallbackData(encoded)).toEqual(action);
+  });
+});

package/telegram-plugin/tests/auth-dashboard-restart-flow.test.ts

@@ -0,0 +1,140 @@
+import { describe, it, expect } from "vitest";
+import {
+  buildDashboardText,
+  buildDashboardKeyboard,
+  encodeCallbackData,
+  parseCallbackData,
+  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 };
+}
+
+/**
+ * PR C — [♻️ Restart flow] dashboard button.
+ *
+ * Pairs with PR B (automatic stale-session detection). When the user
+ * wants to explicitly kill + restart a pending auth flow without
+ * waiting for the PKCE challenge to drift, the dashboard surfaces a
+ * button keyed by the pending slot name. Gateway routes it to
+ * cancel + re-initiate the matching reauth/add.
+ */
+
+describe("restart-flow callback — encode / parse round-trip", () => {
+  it("encodes as auth:restart-flow:<agent>:<slot>", () => {
+    expect(encodeCallbackData({ kind: "restart-flow", agent: "clerk", slot: "default" }))
+      .toBe("auth:restart-flow:clerk:default");
+    expect(encodeCallbackData({ kind: "restart-flow", agent: "lawgpt", slot: "slot-2" }))
+      .toBe("auth:restart-flow:lawgpt:slot-2");
+  });
+
+  it("round-trips cleanly", () => {
+    for (const action of [
+      { kind: "restart-flow", agent: "clerk", slot: "default" },
+      { kind: "restart-flow", agent: "lawgpt", slot: "slot-2" },
+      { kind: "restart-flow", agent: "klanker", slot: "personal_v2" },
+    ] as const) {
+      expect(parseCallbackData(encodeCallbackData(action))).toEqual(action);
+    }
+  });
+
+  it("rejects restart-flow without a slot (slot is required)", () => {
+    // The `use`, `rm`, `confirm-rm`, and `restart-flow` verbs all
+    // require a slot. Missing slot → noop (doesn't accidentally fire
+    // a wider-scope reset).
+    expect(parseCallbackData("auth:restart-flow:clerk")).toEqual({ kind: "noop" });
+    expect(parseCallbackData("auth:restart-flow:clerk:")).toEqual({ kind: "noop" });
+  });
+
+  it("rejects unsafe slot names as noop (shell-injection guard)", () => {
+    expect(parseCallbackData("auth:restart-flow:clerk:../etc")).toEqual({ kind: "noop" });
+    expect(parseCallbackData("auth:restart-flow:clerk:bad slot")).toEqual({ kind: "noop" });
+    expect(parseCallbackData("auth:restart-flow:clerk:slot;ls")).toEqual({ kind: "noop" });
+  });
+
+  it("encoded payload fits Telegram's 64-byte callback_data cap", () => {
+    // Longest practical: auth:restart-flow:<agent32>:<slot32> = 17 + 32 + 1 + 32 = 82.
+    // Agent + slot each capped at 16 chars realistic → well under 64.
+    const realistic = encodeCallbackData({
+      kind: "restart-flow",
+      agent: "a".repeat(16),
+      slot: "b".repeat(16),
+    });
+    expect(realistic.length).toBeLessThanOrEqual(64);
+  });
+});
+
+describe("dashboard renders [Restart flow] button when pending session exists", () => {
+  const base: DashboardState = {
+    agent: "lawgpt",
+    bankId: "lawgpt",
+    plan: "max",
+    slots: [slot({ slot: "default", active: true })],
+    quotaHot: false,
+  };
+
+  it("omits the button when pendingSessionSlot is absent", () => {
+    const kb = buildDashboardKeyboard(base);
+    const flat = kb.inline_keyboard.flat();
+    expect(flat.some((b) => b.text.includes("Restart"))).toBe(false);
+  });
+
+  it("renders the button when pendingSessionSlot is set", () => {
+    const kb = buildDashboardKeyboard({ ...base, pendingSessionSlot: "default" });
+    const flat = kb.inline_keyboard.flat();
+    const btn = flat.find((b) => b.text.includes("Restart"));
+    expect(btn).toBeDefined();
+    expect(btn!.text).toContain("default");
+    if (btn && "callback_data" in btn && btn.callback_data) {
+      expect(btn.callback_data).toBe("auth:restart-flow:lawgpt:default");
+    }
+  });
+
+  it("includes slot name in the button label for named-slot pending flows", () => {
+    const kb = buildDashboardKeyboard({ ...base, pendingSessionSlot: "slot-2" });
+    const flat = kb.inline_keyboard.flat();
+    const btn = flat.find((b) => b.text.includes("Restart"));
+    expect(btn!.text).toContain("slot-2");
+    if (btn && "callback_data" in btn && btn.callback_data) {
+      expect(btn.callback_data).toBe("auth:restart-flow:lawgpt:slot-2");
+    }
+  });
+
+  it("pendingSessionSlot=null is treated as 'no pending' (no button)", () => {
+    const kb = buildDashboardKeyboard({ ...base, pendingSessionSlot: null });
+    const flat = kb.inline_keyboard.flat();
+    expect(flat.some((b) => b.text.includes("Restart"))).toBe(false);
+  });
+});
+
+describe("dashboard text includes the pending-flow notice", () => {
+  const base: DashboardState = {
+    agent: "lawgpt",
+    bankId: "lawgpt",
+    plan: "max",
+    slots: [slot({ active: true })],
+    quotaHot: false,
+  };
+
+  it("no notice when no pending", () => {
+    const text = buildDashboardText(base);
+    expect(text).not.toContain("Auth flow pending");
+    expect(text).not.toContain("⏳");
+  });
+
+  it("shows a pending-flow notice when pendingSessionSlot is set", () => {
+    const text = buildDashboardText({ ...base, pendingSessionSlot: "slot-2" });
+    expect(text).toContain("Auth flow pending");
+    expect(text).toContain("slot-2");
+    expect(text).toContain("⏳");
+    expect(text).toContain("♻️");
+  });
+
+  it("escapes HTML in pendingSessionSlot to guard against injection", () => {
+    const text = buildDashboardText({ ...base, pendingSessionSlot: "<script>alert(1)</script>" });
+    expect(text).not.toContain("<script>");
+    expect(text).toContain("&lt;script&gt;");
+  });
+});