switchroom 0.18.13 → 0.18.14

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

@@ -2,7 +2,8 @@
  * Wire-level regression test for the chunk-boundary cap bug
  * (fix/rich-render-chunk-boundary-cap).
  *
- * With `SWITCHROOM_RICH_RENDER` on, a near-cap body full of escapable chars
+ * With the rich renderer enabled (the default — escape hatch, not opt-in), a
+ * near-cap body full of escapable chars
  * (`_ * |`) makes `renderSafe` degrade the whole document to plain (its escaped
  * rich form exceeds RICH_MESSAGE_MAX_CHARS). BEFORE the fix, the stream
  * controller shipped that ~32k plain body through the plain `sendMessage`
@@ -13,7 +14,7 @@
  * emitted send fits its own wire cap: rich pieces <= 32768, plain pieces
  * <= 4096, and no fenced block is bisected.
  */
-import { describe, it, expect, afterEach } from "vitest";
+import { describe, it, expect } from "vitest";
 import { createStreamController } from "../stream-controller.js";
 import { createFakeBotApi } from "./fake-bot-api.js";
 import { RICH_MESSAGE_MAX_CHARS } from "../format.js";
@@ -25,12 +26,7 @@ function fenceCount(s: string): number {
 }
 
 describe("stream-controller enforces the wire cap on the post-escape body", () => {
-  afterEach(() => {
-    delete process.env.SWITCHROOM_RICH_RENDER;
-  });
-
   it("REGRESSION: near-cap escapable first send never exceeds the plain wire cap", async () => {
-    process.env.SWITCHROOM_RICH_RENDER = "1";
     const bot = createFakeBotApi({ startMessageId: 1000 });
     const unit = "a_b*c|d ";
     const body = unit.repeat(Math.floor((RICH_MESSAGE_MAX_CHARS - 20) / unit.length));
@@ -62,7 +58,6 @@ describe("stream-controller enforces the wire cap on the post-escape body", () =
     // callback. The pre-fix code re-sent all (N-1) tails as brand-new messages
     // on each edit tick, so `sent.length` grew by (N-1) every update. After the
     // fix, tails are parked once and edited in place — `sent.length` is flat.
-    process.env.SWITCHROOM_RICH_RENDER = "1";
     const bot = createFakeBotApi({ startMessageId: 3000 });
     const unit = "a_b*c|d ";
     // Near-cap body that degrades to plain and splits into several pieces.
@@ -106,17 +101,22 @@ describe("stream-controller enforces the wire cap on the post-escape body", () =
     }
   }, 30000);
 
-  it("flag OFF leaves the single-send path untouched", async () => {
-    const bot = createFakeBotApi({ startMessageId: 2000 });
-    const stream = createStreamController({
-      bot: bot as unknown as Parameters<typeof createStreamController>[0]["bot"],
-      chatId: "c1",
-      throttleMs: 0,
-    });
-    await stream.update("**hi** _there_");
-    await stream.finalize();
-    expect(bot.state.sent).toHaveLength(1);
-    expect(bot.state.sent[0].rich).toBe(true);
-    expect(bot.state.sent[0].text).toBe("**hi** _there_");
+  it("kill-switch (=0) leaves the single-send path byte-for-byte untouched", async () => {
+    process.env.SWITCHROOM_RICH_RENDER = "0";
+    try {
+      const bot = createFakeBotApi({ startMessageId: 2000 });
+      const stream = createStreamController({
+        bot: bot as unknown as Parameters<typeof createStreamController>[0]["bot"],
+        chatId: "c1",
+        throttleMs: 0,
+      });
+      await stream.update("**hi** _there_");
+      await stream.finalize();
+      expect(bot.state.sent).toHaveLength(1);
+      expect(bot.state.sent[0].rich).toBe(true);
+      expect(bot.state.sent[0].text).toBe("**hi** _there_");
+    } finally {
+      delete process.env.SWITCHROOM_RICH_RENDER;
+    }
   });
 });

package/telegram-plugin/tests/stream-reply-handler.test.ts

@@ -81,7 +81,7 @@ describe('handleStreamReply', () => {
     expect(state.activeDraftStreams.size).toBe(1)
   })
 
-  it('a non-text format ships raw GFM markdown unescaped (no parse_mode)', async () => {
+  it('a non-text format ships GFM markdown unescaped (no parse_mode)', async () => {
     const state = makeState()
     const deps = makeDeps(bot)
 
@@ -94,7 +94,10 @@ describe('handleStreamReply', () => {
     await pending
 
     expect(bot.api.sendRichMessage).toHaveBeenCalledTimes(1)
-    expect(richSendMarkdown(bot)).toBe('**hi** _there_')
+    // The default-on rich renderer (parse -> renderSafe) normalises the
+    // italic marker (`_there_` -> `*there*`, same wire entity) but the
+    // payload stays unescaped GFM markdown — no HTML, no MarkdownV2 escaping.
+    expect(richSendMarkdown(bot)).toBe('**hi** *there*')
     // No parse_mode on rich opts.
     expect(bot.api.sendRichMessage.mock.calls[0][2]?.parse_mode).toBeUndefined()
   })

package/telegram-plugin/tests/throttle-tier-wiring.test.ts

@@ -0,0 +1,290 @@
+/**
+ * Tests for gateway/throttle-tier-wiring.ts — the 429 throttle tier's
+ * side-effect runner, driven with fully injected deps (no gateway import).
+ *
+ * Pins the OUTCOMES the wiring promises:
+ *  - EVERY fire reaches the broker's mark-throttled (the escalation counter),
+ *    even when the user-facing notice is cooldown-suppressed;
+ *  - ONE notice per account per window, deduped locally AND fleet-wide via
+ *    the broker claim verb (denied claim → no send; claim error → fail open);
+ *  - the retry nudge is armed at throttled_until + slack + jitter, replaced
+ *    (not stacked) by a newer throttle, and at FIRE time:
+ *      - restarts when idle and the resume gate says 'resume';
+ *      - DEFERS to the turn-complete drain when the in-flight gate is held
+ *        by the dead throttled turn (never SIGTERM-now under a live turn);
+ *      - SKIPS entirely when a NEWER turn (started after the throttle was
+ *        armed) is live — restarting would kill live work and boot-resume
+ *        would replay the WRONG turn;
+ *  - the escalated outcome posts the corroborated-wall announcement (fleet-
+ *    deduped) and nudges the resume immediately through the same guards;
+ *  - a broker-unreachable fire degrades to notice-only without throwing.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  createThrottleTierRunner,
+  THROTTLE_RETRY_NUDGE_SLACK_MS,
+  type ThrottleBrokerClient,
+  type ThrottleTierRunnerDeps,
+} from '../gateway/throttle-tier-wiring.js'
+
+const NOW = Date.UTC(2026, 6, 12, 8, 0, 0)
+
+interface Harness {
+  deps: ThrottleTierRunnerDeps
+  calls: {
+    markThrottled: number[]
+    claims: string[]
+    notices: Array<{ chatId: string | number; markdown: string }>
+    deferrals: string[]
+    restarts: string[]
+    logs: string[]
+    timers: Array<{ ms: number; fn: () => void; cancelled: boolean }>
+  }
+  clock: { set(ms: number): void }
+  fireTimer(idx: number): void
+}
+
+function makeHarness(opts: {
+  markThrottledResult?:
+    | { account: string; throttled_until: number; escalated: boolean; rolledTo?: string | null }
+    | 'unreachable'
+    | 'throw'
+  claimGranted?: (key: string) => boolean | 'throw'
+  resumeVerdict?: 'resume' | 'skip-inflight' | 'skip-stale'
+  turnInFlight?: () => boolean
+  newestTurnStartedAt?: () => number | null
+  jitterMs?: number
+} = {}): Harness {
+  let nowMs = NOW
+  const calls: Harness['calls'] = {
+    markThrottled: [],
+    claims: [],
+    notices: [],
+    deferrals: [],
+    restarts: [],
+    logs: [],
+    timers: [],
+  }
+  const client: ThrottleBrokerClient = {
+    async markThrottled(until: number) {
+      calls.markThrottled.push(until)
+      if (opts.markThrottledResult === 'throw') throw new Error('boom')
+      const r = opts.markThrottledResult
+      if (r && r !== 'unreachable') return r
+      return { account: 'alice', throttled_until: until, escalated: false, rolledTo: null }
+    },
+    async claimNotification(key: string) {
+      calls.claims.push(key)
+      const g = opts.claimGranted?.(key) ?? true
+      if (g === 'throw') throw new Error('claim boom')
+      return { granted: g }
+    },
+  }
+  const deps: ThrottleTierRunnerDeps = {
+    agentName: 'carrie',
+    getBrokerClient: async () =>
+      opts.markThrottledResult === 'unreachable' ? null : client,
+    listNoticeChats: () => ['111', '222'],
+    sendNotice: (chatId, markdown) => calls.notices.push({ chatId, markdown }),
+    resumeDecide: () => opts.resumeVerdict ?? 'resume',
+    newestActiveTurnStartedAtMs: opts.newestTurnStartedAt ?? (() => null),
+    turnInFlight: opts.turnInFlight ?? (() => false),
+    deferRestartToTurnComplete: (_agent, reason) => calls.deferrals.push(reason),
+    restartNow: (_agent, reason) => calls.restarts.push(reason),
+    log: (m) => calls.logs.push(m),
+    now: () => nowMs,
+    schedule: (fn, ms) => {
+      const t = { ms, fn, cancelled: false }
+      calls.timers.push(t)
+      return { cancel: () => { t.cancelled = true } }
+    },
+    jitterMs: () => opts.jitterMs ?? 0,
+  }
+  return {
+    deps,
+    calls,
+    clock: { set: (ms) => { nowMs = ms } },
+    fireTimer(idx: number) {
+      const t = calls.timers[idx]
+      if (!t || t.cancelled) throw new Error('no live timer at idx ' + idx)
+      t.fn()
+    },
+  }
+}
+
+describe('throttle-tier runner — broker mark + notice dedup', () => {
+  it('every fire reaches markThrottled; the notice is sent ONCE per cooldown window', async () => {
+    const h = makeHarness()
+    const runner = createThrottleTierRunner(h.deps)
+    await runner.fire('carrie', NOW + 60_000, true)
+    h.clock.set(NOW + 30_000) // same window
+    await runner.fire('carrie', NOW + 90_000, true)
+
+    // Both hits reached the broker (the escalation counter needs them)…
+    expect(h.calls.markThrottled).toEqual([NOW + 60_000, NOW + 90_000])
+    // …but only ONE notice per chat went out.
+    expect(h.calls.notices).toHaveLength(2) // 2 chats × 1 notice
+    expect(h.calls.notices.map((n) => n.chatId)).toEqual(['111', '222'])
+    expect(h.calls.notices[0].markdown).toContain('alice')
+    expect(h.calls.notices[0].markdown).toContain('Rate-limited, staying put')
+  })
+
+  it('fleet-wide claim dedup: a denied claim suppresses that chat, an error fails open', async () => {
+    const h = makeHarness({
+      claimGranted: (key) => (key.endsWith(':111') ? false : 'throw'),
+    })
+    const runner = createThrottleTierRunner(h.deps)
+    await runner.fire('carrie', NOW + 60_000, true)
+
+    // chat 111 denied (another gateway won the claim), chat 222 errored → open.
+    expect(h.calls.claims).toEqual([
+      `throttle-notice:alice:111`,
+      `throttle-notice:alice:222`,
+    ])
+    expect(h.calls.notices.map((n) => n.chatId)).toEqual(['222'])
+  })
+
+  it('degrades to notice-only when the broker is unreachable (no throw, no claim)', async () => {
+    const h = makeHarness({ markThrottledResult: 'unreachable' })
+    const runner = createThrottleTierRunner(h.deps)
+    await runner.fire('carrie', NOW + 60_000, false)
+    expect(h.calls.markThrottled).toHaveLength(0)
+    expect(h.calls.claims).toHaveLength(0) // no account → no claim key
+    expect(h.calls.notices).toHaveLength(2)
+    expect(h.calls.notices[0].markdown).toContain('the active account')
+  })
+
+  it('a markThrottled throw is swallowed and the notice still goes out', async () => {
+    const h = makeHarness({ markThrottledResult: 'throw' })
+    const runner = createThrottleTierRunner(h.deps)
+    await expect(runner.fire('carrie', NOW + 60_000, true)).resolves.toBeUndefined()
+    expect(h.calls.notices).toHaveLength(2)
+  })
+})
+
+describe('throttle-tier runner — retry nudge scheduling + turn safety', () => {
+  it('arms the nudge at reset + slack + jitter and restarts when idle', async () => {
+    const h = makeHarness({ jitterMs: 7_000 })
+    const runner = createThrottleTierRunner(h.deps)
+    await runner.fire('carrie', NOW + 60_000, true)
+
+    expect(h.calls.timers).toHaveLength(1)
+    expect(h.calls.timers[0].ms).toBe(60_000 + THROTTLE_RETRY_NUDGE_SLACK_MS + 7_000)
+    expect(runner.inspect().nudgePending).toBe(true)
+
+    h.fireTimer(0)
+    expect(h.calls.restarts).toEqual(['throttle-retry-resume'])
+    expect(h.calls.deferrals).toHaveLength(0)
+    expect(runner.inspect().nudgePending).toBe(false)
+  })
+
+  it('a newer throttle REPLACES the pending nudge instead of stacking restarts', async () => {
+    const h = makeHarness()
+    const runner = createThrottleTierRunner(h.deps)
+    await runner.fire('carrie', NOW + 60_000, true)
+    await runner.fire('carrie', NOW + 120_000, true)
+    expect(h.calls.timers).toHaveLength(2)
+    expect(h.calls.timers[0].cancelled).toBe(true)
+    expect(h.calls.timers[1].cancelled).toBe(false)
+  })
+
+  it('DEFERS to the turn-complete drain when the dead throttled turn still holds the gate', async () => {
+    const h = makeHarness({
+      turnInFlight: () => true,
+      // The in-flight turn started BEFORE the throttle was armed — it IS the
+      // dead turn (a 429-killed turn never writes its turn-end marker).
+      newestTurnStartedAt: () => NOW - 60_000,
+    })
+    const runner = createThrottleTierRunner(h.deps)
+    await runner.fire('carrie', NOW + 60_000, true)
+    h.fireTimer(0)
+    expect(h.calls.restarts).toHaveLength(0) // never SIGTERM-now under a live gate
+    expect(h.calls.deferrals).toEqual(['throttle-retry-resume'])
+  })
+
+  it('SKIPS entirely when a NEWER live turn supersedes the dead one', async () => {
+    let nowAtNudge = NOW
+    const h = makeHarness({
+      turnInFlight: () => true,
+      // Started AFTER the throttle was armed — live user work.
+      newestTurnStartedAt: () => nowAtNudge + 30_000,
+    })
+    const runner = createThrottleTierRunner(h.deps)
+    await runner.fire('carrie', NOW + 60_000, true)
+    nowAtNudge = NOW // armedAt == NOW; newest = NOW+30s > armedAt
+    h.fireTimer(0)
+    expect(h.calls.restarts).toHaveLength(0)
+    expect(h.calls.deferrals).toHaveLength(0)
+    expect(h.calls.logs.some((l) => l.includes('superseded'))).toBe(true)
+  })
+
+  it('honours the shared resume gate verdict (skip-inflight → no restart)', async () => {
+    const h = makeHarness({ resumeVerdict: 'skip-inflight' })
+    const runner = createThrottleTierRunner(h.deps)
+    await runner.fire('carrie', NOW + 60_000, true)
+    h.fireTimer(0)
+    expect(h.calls.restarts).toHaveLength(0)
+    expect(h.calls.logs.some((l) => l.includes('skip-inflight'))).toBe(true)
+  })
+})
+
+describe('throttle-tier runner — escalated outcome (corroborated wall)', () => {
+  it('posts the fleet-deduped escalation announcement and resumes immediately', async () => {
+    const h = makeHarness({
+      markThrottledResult: {
+        account: 'alice',
+        throttled_until: NOW + 60_000,
+        escalated: true,
+        rolledTo: 'bob',
+      },
+    })
+    const runner = createThrottleTierRunner(h.deps)
+    await runner.fire('carrie', NOW + 60_000, true)
+
+    // Announcement (not the staying-put notice), per chat, claim-deduped.
+    expect(h.calls.claims).toEqual([
+      `throttle-escalation:alice:111`,
+      `throttle-escalation:alice:222`,
+    ])
+    expect(h.calls.notices).toHaveLength(2)
+    expect(h.calls.notices[0].markdown).toContain('actually a wall')
+    expect(h.calls.notices[0].markdown).toContain('bob')
+
+    // Immediate resume (fleet just swapped accounts) — no delayed nudge armed.
+    expect(h.calls.restarts).toEqual(['throttle-escalation-resume'])
+    expect(h.calls.timers).toHaveLength(0)
+  })
+
+  it('escalated with rolledTo=null (all blocked) announces but does NOT restart', async () => {
+    const h = makeHarness({
+      markThrottledResult: {
+        account: 'alice',
+        throttled_until: NOW + 60_000,
+        escalated: true,
+        rolledTo: null,
+      },
+    })
+    const runner = createThrottleTierRunner(h.deps)
+    await runner.fire('carrie', NOW + 60_000, true)
+    expect(h.calls.notices[0].markdown).toContain('all blocked')
+    expect(h.calls.restarts).toHaveLength(0)
+  })
+
+  it('escalated resume respects the live-turn guards too', async () => {
+    const h = makeHarness({
+      markThrottledResult: {
+        account: 'alice',
+        throttled_until: NOW + 60_000,
+        escalated: true,
+        rolledTo: 'bob',
+      },
+      turnInFlight: () => true,
+      newestTurnStartedAt: () => NOW - 60_000, // the dead turn holds the gate
+    })
+    const runner = createThrottleTierRunner(h.deps)
+    await runner.fire('carrie', NOW + 60_000, true)
+    expect(h.calls.restarts).toHaveLength(0)
+    expect(h.calls.deferrals).toEqual(['throttle-escalation-resume'])
+  })
+})

package/telegram-plugin/tests/throttle-tier.test.ts

@@ -0,0 +1,278 @@
+/**
+ * Unit tests for telegram-plugin/throttle-tier.ts — the 429 throttle tier.
+ *
+ * Pins the operator-approved decision matrix ("retry in place under 5 min,
+ * else mark + failover, honest reset messaging"):
+ *   - transient wording + reset ≤ threshold  → throttle (stay put)
+ *   - transient wording + reset > threshold  → failover (escalate)
+ *   - transient wording + unparseable reset  → throttle, now+60s default
+ *   - non-transient (wall) wording           → none (caller's existing path)
+ * plus the per-account notice cooldown and the notice text itself.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  decideThrottleTier,
+  evaluateThrottleNotice,
+  isAccountScopedThrottle,
+  renderThrottleEscalationNotice,
+  renderThrottleNotice,
+  throttleRetryInPlaceMaxMs,
+  THROTTLE_DEFAULT_WAIT_MS,
+  THROTTLE_NOTICE_COOLDOWN_MS,
+  THROTTLE_RETRY_IN_PLACE_MAX_MS_DEFAULT,
+  type ThrottleNoticeState,
+} from '../throttle-tier.js'
+import { formatModelUnavailableCard, parseResetTime } from '../model-unavailable.js'
+
+const NOW = Date.UTC(2026, 6, 12, 8, 0, 0) // 2026-07-12T08:00:00Z
+const THRESHOLD = THROTTLE_RETRY_IN_PLACE_MAX_MS_DEFAULT // 5 min
+
+// The canonical transient-negation wording (Anthropic burst-429 shape).
+const TRANSIENT = (suffix: string): string =>
+  `This request would exceed your account's rate limit (not your usage limit). ${suffix}`
+
+describe('decideThrottleTier — decision matrix', () => {
+  it('transient wording + reset within threshold → throttle at the parsed reset', () => {
+    const d = decideThrottleTier({
+      detail: TRANSIENT('Please retry after 90 seconds.'),
+      now: NOW,
+      thresholdMs: THRESHOLD,
+    })
+    expect(d).toEqual({
+      action: 'throttle',
+      throttledUntilMs: NOW + 90_000,
+      resetParsed: true,
+    })
+  })
+
+  it('transient wording + "resets in 3m" → throttle (≤ 5 min)', () => {
+    const d = decideThrottleTier({
+      detail: TRANSIENT('resets in 3m'),
+      now: NOW,
+      thresholdMs: THRESHOLD,
+    })
+    expect(d).toEqual({
+      action: 'throttle',
+      throttledUntilMs: NOW + 3 * 60_000,
+      resetParsed: true,
+    })
+  })
+
+  it('transient wording + reset beyond threshold → failover with the parsed reset', () => {
+    const d = decideThrottleTier({
+      detail: TRANSIENT('resets in 2h 15m'),
+      now: NOW,
+      thresholdMs: THRESHOLD,
+    })
+    expect(d).toEqual({
+      action: 'failover',
+      resetAtMs: NOW + (2 * 60 + 15) * 60_000,
+    })
+  })
+
+  it('transient wording + NO parseable reset → throttle for the 60s default', () => {
+    const d = decideThrottleTier({
+      detail: TRANSIENT('try again later.'),
+      now: NOW,
+      thresholdMs: THRESHOLD,
+    })
+    expect(d).toEqual({
+      action: 'throttle',
+      throttledUntilMs: NOW + THROTTLE_DEFAULT_WAIT_MS,
+      resetParsed: false,
+    })
+  })
+
+  it('transient wording + reset in the PAST → throttle for the 60s default', () => {
+    const past = new Date(NOW - 60_000).toISOString()
+    const d = decideThrottleTier({
+      detail: TRANSIENT(`resets ${past}`),
+      now: NOW,
+      thresholdMs: THRESHOLD,
+    })
+    expect(d).toEqual({
+      action: 'throttle',
+      throttledUntilMs: NOW + THROTTLE_DEFAULT_WAIT_MS,
+      resetParsed: false,
+    })
+  })
+
+  it('genuine wall wording (no transient negation) → none (existing quota path owns it)', () => {
+    const d = decideThrottleTier({
+      detail: "You've hit your limit · resets 8:50am (Australia/Melbourne)",
+      now: NOW,
+      thresholdMs: THRESHOLD,
+    })
+    expect(d).toEqual({ action: 'none' })
+  })
+
+  it('SERVER-side transient wording (529 shape) → none — never account-throttled', () => {
+    // This carries the transient NEGATION ("not your usage limit") but does
+    // NOT affirm the account's own rate limit — it is a server-wide
+    // condition; an account-scoped throttle + restart nudge would be the
+    // wrong action. It stays on the existing calm rate-limited path.
+    const d = decideThrottleTier({
+      detail: 'Server is temporarily limiting requests (not your usage limit). retry after 60 seconds',
+      now: NOW,
+      thresholdMs: THRESHOLD,
+    })
+    expect(d).toEqual({ action: 'none' })
+  })
+
+  it('honours a custom threshold (boundary: exactly at threshold stays in place)', () => {
+    const atThreshold = decideThrottleTier({
+      detail: TRANSIENT('retry after 300 seconds'),
+      now: NOW,
+      thresholdMs: 5 * 60_000,
+    })
+    expect(atThreshold.action).toBe('throttle')
+    const beyond = decideThrottleTier({
+      detail: TRANSIENT('retry after 301 seconds'),
+      now: NOW,
+      thresholdMs: 5 * 60_000,
+    })
+    expect(beyond.action).toBe('failover')
+  })
+})
+
+describe('isAccountScopedThrottle — the tier gate', () => {
+  it("matches account-affirming wording (both apostrophe variants + 'not your account')", () => {
+    expect(isAccountScopedThrottle("would exceed your account's rate limit")).toBe(true)
+    expect(isAccountScopedThrottle('would exceed your account’s rate limit')).toBe(true)
+    expect(isAccountScopedThrottle("this is not your account's limit")).toBe(true)
+  })
+
+  it('rejects server-side transient / 529 wordings and walls', () => {
+    expect(isAccountScopedThrottle('Server is temporarily limiting requests (not your usage limit)')).toBe(false)
+    expect(isAccountScopedThrottle('temporarily rate limited, overloaded_error 529')).toBe(false)
+    expect(isAccountScopedThrottle("You've hit your limit · resets 8:50am")).toBe(false)
+    expect(isAccountScopedThrottle('')).toBe(false)
+  })
+})
+
+describe('throttleRetryInPlaceMaxMs — env resolution', () => {
+  it('defaults to 5 minutes', () => {
+    expect(throttleRetryInPlaceMaxMs({})).toBe(5 * 60_000)
+  })
+
+  it('reads SWITCHROOM_THROTTLE_RETRY_IN_PLACE_MAX_MS', () => {
+    expect(
+      throttleRetryInPlaceMaxMs({ SWITCHROOM_THROTTLE_RETRY_IN_PLACE_MAX_MS: '120000' }),
+    ).toBe(120_000)
+  })
+
+  it('falls back to the default on junk / non-positive values', () => {
+    expect(
+      throttleRetryInPlaceMaxMs({ SWITCHROOM_THROTTLE_RETRY_IN_PLACE_MAX_MS: 'soon' }),
+    ).toBe(THROTTLE_RETRY_IN_PLACE_MAX_MS_DEFAULT)
+    expect(
+      throttleRetryInPlaceMaxMs({ SWITCHROOM_THROTTLE_RETRY_IN_PLACE_MAX_MS: '-5' }),
+    ).toBe(THROTTLE_RETRY_IN_PLACE_MAX_MS_DEFAULT)
+  })
+})
+
+describe('evaluateThrottleNotice — per-account cooldown', () => {
+  it('sends the first notice and suppresses a repeat inside the window', () => {
+    let state: ThrottleNoticeState = { lastSentAtMsByAccount: {} }
+    const first = evaluateThrottleNotice(state, 'acct-a', NOW)
+    expect(first.send).toBe(true)
+    state = first.next
+    const repeat = evaluateThrottleNotice(state, 'acct-a', NOW + 60_000)
+    expect(repeat.send).toBe(false)
+  })
+
+  it('a DIFFERENT account is not suppressed by the first account\'s window', () => {
+    const first = evaluateThrottleNotice({ lastSentAtMsByAccount: {} }, 'acct-a', NOW)
+    const other = evaluateThrottleNotice(first.next, 'acct-b', NOW + 1)
+    expect(other.send).toBe(true)
+  })
+
+  it('sends again once the cooldown window has elapsed', () => {
+    const first = evaluateThrottleNotice({ lastSentAtMsByAccount: {} }, 'acct-a', NOW)
+    const later = evaluateThrottleNotice(
+      first.next,
+      'acct-a',
+      NOW + THROTTLE_NOTICE_COOLDOWN_MS,
+    )
+    expect(later.send).toBe(true)
+  })
+})
+
+describe('renderThrottleNotice — honest reset messaging', () => {
+  it('names the account, the agent, the reset, and that it is NOT a quota wall', () => {
+    const text = renderThrottleNotice({
+      account: 'alice',
+      agent: 'carrie',
+      throttledUntilMs: NOW + 3 * 60_000,
+      resetParsed: true,
+      now: new Date(NOW),
+    })
+    expect(text).toContain('alice')
+    expect(text).toContain('carrie')
+    expect(text).toContain('resets in 3m')
+    expect(text).toContain('not a quota wall')
+    expect(text).toContain('Staying on')
+    expect(text).toContain('no failover')
+  })
+
+  it('degrades honestly when the account is unknown (broker unreachable)', () => {
+    const text = renderThrottleNotice({
+      account: null,
+      agent: 'carrie',
+      throttledUntilMs: NOW + THROTTLE_DEFAULT_WAIT_MS,
+      resetParsed: false,
+      now: new Date(NOW),
+    })
+    expect(text).toContain('the active account')
+    expect(text).toContain('retrying in ~60s')
+  })
+})
+
+describe('renderThrottleEscalationNotice — corroborated-wall announcement', () => {
+  it('names the account, the trigger agent, and the roll target', () => {
+    const text = renderThrottleEscalationNotice({
+      account: 'alice',
+      agent: 'carrie',
+      rolledTo: 'bob',
+    })
+    expect(text).toContain('alice')
+    expect(text).toContain('carrie')
+    expect(text).toContain('bob')
+    expect(text).toContain('actually a wall')
+  })
+
+  it('renders the all-blocked variant when no fallback had quota', () => {
+    const text = renderThrottleEscalationNotice({
+      account: 'alice',
+      agent: 'carrie',
+      rolledTo: null,
+    })
+    expect(text).toContain('all blocked')
+    expect(text).toContain('/auth add')
+  })
+})
+
+describe('rate_limited escalation card wording (model-unavailable integration)', () => {
+  it('formatModelUnavailableCard names the rate limit, not quota exhaustion', () => {
+    const card = formatModelUnavailableCard(
+      { kind: 'rate_limited', resetAt: new Date(NOW + 30 * 60_000), raw: 'x' },
+      'carrie',
+      { now: new Date(NOW), autoFallbackInFlight: true },
+    )
+    expect(card).toContain('account rate-limited')
+    expect(card).toContain('resets in 30m')
+    expect(card).not.toContain('quota exhausted')
+  })
+})
+
+describe('parseResetTime (exported for the throttle tier)', () => {
+  it('parses "retry after N seconds" relative to the injected clock', () => {
+    const d = parseResetTime('retry after 45 seconds', new Date(NOW))
+    expect(d?.getTime()).toBe(NOW + 45_000)
+  })
+
+  it('returns undefined for prose with no reset hint', () => {
+    expect(parseResetTime('temporarily limiting requests', new Date(NOW))).toBeUndefined()
+  })
+})