switchroom 0.18.8 → 0.18.10

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()
+  })
+})

package/telegram-plugin/tests/photo-precheck.test.ts

@@ -0,0 +1,240 @@
+/**
+ * Pins the #3033 layer-2 pre-send photo validation:
+ *   1. header-only dimension probes for PNG / JPEG / GIF / WebP
+ *   2. the photo-path bounds (width+height cap, aspect-ratio cap, size cap)
+ *   3. classifyPhotoFile routing (violation → document; probe miss → photo)
+ *
+ * Incident anchor: clerk 2026-07-11 sent a 600x8717 newsletter screenshot
+ * in a media group — ratio 14.5:1, WITHIN the documented 20:1 Bot API
+ * limit — and Telegram rejected it with PHOTO_INVALID_DIMENSIONS, failing
+ * the whole album. The bounds here must classify that image as a document.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import {
+  probeImageDimensions,
+  probeImageFile,
+  photoSendViolation,
+  classifyPhotoFile,
+  rerouteResultSuffix,
+  PHOTO_MAX_BYTES,
+} from '../photo-precheck.js'
+
+function pngBuffer(width: number, height: number): Buffer {
+  const buf = Buffer.alloc(33)
+  buf.writeUInt32BE(0x89504e47, 0)
+  buf.writeUInt32BE(0x0d0a1a0a, 4)
+  buf.writeUInt32BE(13, 8) // IHDR length
+  buf.write('IHDR', 12, 'ascii')
+  buf.writeUInt32BE(width, 16)
+  buf.writeUInt32BE(height, 20)
+  return buf
+}
+
+function jpegBuffer(width: number, height: number): Buffer {
+  // SOI, APP0 (JFIF stub), SOF0 with dimensions.
+  const app0 = Buffer.from([0xff, 0xe0, 0x00, 0x10, 0x4a, 0x46, 0x49, 0x46, 0x00, 0x01, 0x01, 0x00, 0x00, 0x01, 0x00, 0x01, 0x00, 0x00])
+  const sof0 = Buffer.alloc(2 + 2 + 5 + 3)
+  sof0[0] = 0xff; sof0[1] = 0xc0
+  sof0.writeUInt16BE(10, 2) // segment length
+  sof0[4] = 8 // precision
+  sof0.writeUInt16BE(height, 5)
+  sof0.writeUInt16BE(width, 7)
+  sof0[9] = 1
+  return Buffer.concat([Buffer.from([0xff, 0xd8]), app0, sof0])
+}
+
+function gifBuffer(width: number, height: number): Buffer {
+  const buf = Buffer.alloc(13)
+  buf.write('GIF89a', 0, 'ascii')
+  buf.writeUInt16LE(width, 6)
+  buf.writeUInt16LE(height, 8)
+  return buf
+}
+
+function webpVp8xBuffer(width: number, height: number): Buffer {
+  const buf = Buffer.alloc(30)
+  buf.write('RIFF', 0, 'ascii')
+  buf.writeUInt32LE(22, 4)
+  buf.write('WEBP', 8, 'ascii')
+  buf.write('VP8X', 12, 'ascii')
+  buf.writeUInt32LE(10, 16)
+  const w = width - 1
+  const h = height - 1
+  buf[24] = w & 0xff; buf[25] = (w >> 8) & 0xff; buf[26] = (w >> 16) & 0xff
+  buf[27] = h & 0xff; buf[28] = (h >> 8) & 0xff; buf[29] = (h >> 16) & 0xff
+  return buf
+}
+
+describe('probeImageDimensions', () => {
+  it('reads PNG IHDR dimensions', () => {
+    expect(probeImageDimensions(pngBuffer(600, 8717))).toEqual({ width: 600, height: 8717 })
+  })
+
+  it('reads JPEG SOF0 dimensions past an APP0 segment', () => {
+    expect(probeImageDimensions(jpegBuffer(1179, 2556))).toEqual({ width: 1179, height: 2556 })
+  })
+
+  it('reads GIF logical screen dimensions', () => {
+    expect(probeImageDimensions(gifBuffer(320, 240))).toEqual({ width: 320, height: 240 })
+  })
+
+  it('reads WebP VP8X canvas dimensions', () => {
+    expect(probeImageDimensions(webpVp8xBuffer(1920, 1080))).toEqual({ width: 1920, height: 1080 })
+  })
+
+  it('returns null for unknown formats and truncated buffers', () => {
+    expect(probeImageDimensions(Buffer.from('not an image at all, sorry'))).toBeNull()
+    expect(probeImageDimensions(Buffer.from([0x89, 0x50]))).toBeNull()
+    expect(probeImageDimensions(Buffer.alloc(0))).toBeNull()
+  })
+})
+
+describe('photoSendViolation bounds', () => {
+  it('accepts a normal phone screenshot (1179x2556)', () => {
+    expect(photoSendViolation({ width: 1179, height: 2556, bytes: 500_000 })).toBeNull()
+  })
+
+  it('rejects the clerk incident image 600x8717 (ratio 14.5:1, within documented 20:1)', () => {
+    const v = photoSendViolation({ width: 600, height: 8717, bytes: 400_000 })
+    expect(v).toMatch(/aspect ratio/)
+  })
+
+  it('rejects width+height over 10000', () => {
+    const v = photoSendViolation({ width: 6000, height: 5000, bytes: 400_000 })
+    expect(v).toMatch(/width\+height/)
+  })
+
+  it('rejects files over the 10MB photo ceiling', () => {
+    const v = photoSendViolation({ width: 1000, height: 1000, bytes: PHOTO_MAX_BYTES + 1 })
+    expect(v).toMatch(/exceeds 10MB/)
+  })
+
+  it('accepts exactly-at-bound values', () => {
+    expect(photoSendViolation({ width: 5000, height: 5000, bytes: PHOTO_MAX_BYTES })).toBeNull()
+    expect(photoSendViolation({ width: 800, height: 8800, bytes: 1 })).toMatch(/aspect ratio/) // 11:1
+    expect(photoSendViolation({ width: 900, height: 9000, bytes: 1 })).toBeNull() // exactly 10:1
+  })
+})
+
+describe('probeImageFile + classifyPhotoFile', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'photo-precheck-'))
+
+  it('probes a PNG file on disk', () => {
+    const p = join(dir, 'tall.png')
+    writeFileSync(p, pngBuffer(600, 8717))
+    expect(probeImageFile(p)).toEqual({ width: 600, height: 8717, bytes: 33 })
+  })
+
+  it('routes an out-of-bounds photo to document with a reason', () => {
+    const p = join(dir, 'tall2.png')
+    writeFileSync(p, pngBuffer(600, 8717))
+    const cls = classifyPhotoFile(p)
+    expect(cls.route).toBe('document')
+    if (cls.route === 'document') expect(cls.reason).toMatch(/aspect ratio 14\.5:1/)
+  })
+
+  it('keeps an in-bounds photo on the photo route', () => {
+    const p = join(dir, 'ok.png')
+    writeFileSync(p, pngBuffer(1179, 2556))
+    expect(classifyPhotoFile(p)).toEqual({ route: 'photo' })
+  })
+
+  // #3038 item 3 — probeImageFile now does fixed-size header reads
+  // (openSync + 32 bytes; 64KB window for JPEG) instead of readFileSync.
+  // Pin correctness on the same fixture set across every format.
+  it('probes JPEG / GIF / WebP files on disk (fixed-size read path)', () => {
+    const j = join(dir, 'shot.jpg')
+    writeFileSync(j, jpegBuffer(1179, 2556))
+    expect(probeImageFile(j)).toMatchObject({ width: 1179, height: 2556 })
+
+    const g = join(dir, 'anim.gif')
+    writeFileSync(g, gifBuffer(320, 240))
+    expect(probeImageFile(g)).toMatchObject({ width: 320, height: 240 })
+
+    const w = join(dir, 'pic.webp')
+    writeFileSync(w, webpVp8xBuffer(1920, 1080))
+    expect(probeImageFile(w)).toMatchObject({ width: 1920, height: 1080 })
+  })
+
+  it('probes the 600x8717 incident image without reading the whole multi-MB file', () => {
+    // Header + 5MB of body: the probe must report full file size but
+    // still read dimensions from the fixed-size header window.
+    const p = join(dir, 'incident.png')
+    const body = Buffer.alloc(5 * 1024 * 1024)
+    writeFileSync(p, Buffer.concat([pngBuffer(600, 8717), body]))
+    const probe = probeImageFile(p)
+    expect(probe).toEqual({ width: 600, height: 8717, bytes: 33 + body.length })
+    expect(classifyPhotoFile(p).route).toBe('document')
+  })
+
+  it('finds JPEG SOFn past a large metadata segment (within the 64KB window)', () => {
+    // SOI + a 40KB APP1 (EXIF-sized) segment, then SOF0. The 32-byte
+    // sniff alone cannot see SOF0; the JPEG re-read must.
+    const segLen = 40 * 1024
+    const app1 = Buffer.alloc(2 + 2 + segLen)
+    app1[0] = 0xff; app1[1] = 0xe1
+    app1.writeUInt16BE(2 + segLen, 2)
+    const sof0 = Buffer.alloc(10)
+    sof0[0] = 0xff; sof0[1] = 0xc0
+    sof0.writeUInt16BE(8, 2)
+    sof0[4] = 8
+    sof0.writeUInt16BE(2556, 5)
+    sof0.writeUInt16BE(1179, 7)
+    const p = join(dir, 'exif.jpg')
+    writeFileSync(p, Buffer.concat([Buffer.from([0xff, 0xd8]), app1, sof0]))
+    expect(probeImageFile(p)).toMatchObject({ width: 1179, height: 2556 })
+  })
+
+  it('returns null (photo route kept) when JPEG SOFn is beyond the 64KB window', () => {
+    // Two 40KB APPn segments push SOF0 past the 64KB probe window
+    // (a single segment length is 16-bit capped at 65535).
+    const segLen = 40 * 1024
+    const app1 = Buffer.alloc(2 + 2 + segLen)
+    app1[0] = 0xff; app1[1] = 0xe1
+    app1.writeUInt16BE(2 + segLen, 2)
+    const sof0 = Buffer.alloc(10)
+    sof0[0] = 0xff; sof0[1] = 0xc0
+    sof0.writeUInt16BE(8, 2)
+    sof0[4] = 8
+    sof0.writeUInt16BE(8717, 5)
+    sof0.writeUInt16BE(600, 7)
+    const p = join(dir, 'deep-exif.jpg')
+    writeFileSync(p, Buffer.concat([Buffer.from([0xff, 0xd8]), app1, app1, sof0]))
+    expect(probeImageFile(p)).toBeNull()
+    // Probe miss → photo route → #3022 reactive fallback backstops.
+    expect(classifyPhotoFile(p)).toEqual({ route: 'photo' })
+  })
+
+  it('keeps the photo route when the file is unreadable or unrecognized (reactive fallback backstops)', () => {
+    expect(classifyPhotoFile(join(dir, 'missing.png'))).toEqual({ route: 'photo' })
+    const junk = join(dir, 'junk.png')
+    writeFileSync(junk, Buffer.from('definitely not a png'))
+    expect(classifyPhotoFile(junk)).toEqual({ route: 'photo' })
+  })
+})
+
+describe('rerouteResultSuffix (#3038 — reply result tells the agent about reroutes)', () => {
+  it('returns empty string when nothing was rerouted', () => {
+    expect(rerouteResultSuffix([])).toBe('')
+  })
+
+  it('formats a single reroute with basename and reason', () => {
+    const s = rerouteResultSuffix([
+      { path: '/tmp/x/tall.png', reason: 'aspect ratio 14.5:1 (600x8717) exceeds 10:1 photo bound' },
+    ])
+    expect(s).toBe(' (1 file(s) sent as document, not inline photo: tall.png: aspect ratio 14.5:1 (600x8717) exceeds 10:1 photo bound)')
+  })
+
+  it('joins multiple reroutes and counts them', () => {
+    const s = rerouteResultSuffix([
+      { path: '/a/one.png', reason: 'r1' },
+      { path: '/b/two.jpg', reason: 'r2' },
+    ])
+    expect(s).toMatch(/^ \(2 file\(s\) sent as document/)
+    expect(s).toContain('one.png: r1; two.jpg: r2')
+  })
+})

package/telegram-plugin/tests/photo-reroute-wiring.test.ts

@@ -0,0 +1,85 @@
+/**
+ * #3038 polish — pins the gateway wiring for the photo→document reroute
+ * honesty surfaces added after PR #3037:
+ *
+ *   1. executeReply's tool result appends `rerouteResultSuffix(...)` so
+ *      the agent learns files went out as documents, not inline photos
+ *      (it otherwise only sees "sent (id: N)" and may tell the user an
+ *      inline screenshot rendered).
+ *   2. attachment_kinds history records what was ACTUALLY sent: a
+ *      photo-extension file in the `sentAsDocument` set is recorded as
+ *      'document', covering both the precheck reroute and the #3022
+ *      reactive fallback paths.
+ *
+ * The gateway IIFE is too entangled to instantiate in-process; source-
+ * level assertions follow the `buffer-gate-broadened.test.ts` pattern.
+ * The pure formatting/probe logic is unit-tested in
+ * `photo-precheck.test.ts`.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const gatewaySrc = readFileSync(
+  resolve(__dirname, '..', 'gateway', 'gateway.ts'),
+  'utf-8',
+)
+
+// Slice executeReply's file-send + result + history block: from the
+// photo-precheck anchor to the recordOutbound call for replies.
+const sliceStart = gatewaySrc.indexOf('const photoPrecheck = new Map')
+const sliceEnd = gatewaySrc.indexOf('history recordOutbound (reply) failed')
+const slice = gatewaySrc.slice(sliceStart, sliceEnd)
+
+describe('reroute signal reaches the reply tool result (#3038 item 1)', () => {
+  it('slices resolve (anchors present in executeReply)', () => {
+    expect(sliceStart).toBeGreaterThan(-1)
+    expect(sliceEnd).toBeGreaterThan(sliceStart)
+  })
+
+  it('imports rerouteResultSuffix from photo-precheck', () => {
+    expect(gatewaySrc).toMatch(/import \{ classifyPhotoFile, rerouteResultSuffix \} from '\.\.\/photo-precheck\.js'/)
+  })
+
+  it('appends rerouteResultSuffix(documentReroutes) to the result text', () => {
+    // The suffix must be part of the `result` expression the tool returns.
+    const resultIdx = slice.indexOf('const result =')
+    expect(resultIdx).toBeGreaterThan(-1)
+    const resultExpr = slice.slice(resultIdx, slice.indexOf('\n\n', resultIdx))
+    expect(resultExpr).toContain('rerouteResultSuffix(documentReroutes)')
+  })
+
+  it('precheck reroutes populate documentReroutes AND sentAsDocument', () => {
+    const precheckBlock = slice.slice(0, slice.indexOf('sendableAsPhoto ='))
+    expect(precheckBlock).toContain("if (cls.route === 'document')")
+    expect(precheckBlock).toContain('documentReroutes.push({ path: f, reason: cls.reason })')
+    expect(precheckBlock).toContain('sentAsDocument.add(f)')
+  })
+
+  it('reactive fallbacks (album + per-file, #3022) also record the reroute', () => {
+    // Album-wide fallback loop.
+    const albumIdx = slice.indexOf('albumReason')
+    expect(albumIdx).toBeGreaterThan(-1)
+    // Per-file sendPhoto→sendDocument fallback: sendAsDocument followed by
+    // both bookkeeping calls.
+    const perFile = slice.indexOf('sent = await sendAsDocument(f)')
+    expect(perFile).toBeGreaterThan(-1)
+    const afterPerFile = slice.slice(perFile, perFile + 400)
+    expect(afterPerFile).toContain('sentAsDocument.add(f)')
+    expect(afterPerFile).toContain('documentReroutes.push')
+  })
+})
+
+describe('attachment_kinds records what was actually sent (#3038 item 2)', () => {
+  it('history kind consults sentAsDocument, not just the raw extension', () => {
+    const historyIdx = slice.indexOf('const attachKinds')
+    expect(historyIdx).toBeGreaterThan(-1)
+    const historyBlock = slice.slice(historyIdx)
+    expect(historyBlock).toContain("PHOTO_EXTS.has(ext) && !sentAsDocument.has(f) ? 'photo' : 'document'")
+    // Both the human-readable text label and the kinds array use the
+    // resolved kind.
+    expect(historyBlock).toMatch(/texts\.push\(`\(\$\{kind\}/)
+    expect(historyBlock).toContain('attachKinds.push(kind)')
+  })
+})

package/telegram-plugin/tests/quota-watch.test.ts

@@ -20,6 +20,11 @@ import {
   emptyAccountState,
   isLiveCorroboration,
   type CorroborationProbe,
+  evaluateFleetRollAnnounce,
+  buildFleetRollMessage,
+  FLEET_ROLL_MAX_AGE_MS,
+  QUOTA_WATCH_ROLL_DEDUP_MS,
+  type FleetRollInfo,
 } from "../quota-watch.js";
 import type { AccountSnapshot } from "../auth-snapshot-format.js";
 import type { QuotaUtilization } from "../quota-check.js";
@@ -946,3 +951,223 @@ describe("evaluateQuotaWatchAccount — total enumeration (144 cells)", () => {
     expect(cells).toBe(144);
   });
 });
+
+// ── #3031 PR 3 — broker-roll announcement ────────────────────────────────────
+
+describe("evaluateFleetRollAnnounce (#3031 PR 3)", () => {
+  const ROLL: FleetRollInfo = {
+    from: "alice@example.com",
+    to: "bob@example.com",
+    at: NOW - 60_000,
+    exhausted_until: NOW + 2 * 3600_000,
+    window: "5h",
+    pct: 99.8,
+  };
+
+  it("fires once for a fresh, never-announced roll (latched on roll.at)", () => {
+    const d = evaluateFleetRollAnnounce({ roll: ROLL, prev: emptyAccountState(), now: NOW });
+    expect(d.kind).toBe("notify");
+    if (d.kind !== "notify") return;
+    expect(d.newState.lastNotifiedAt).toBe(ROLL.at);
+  });
+
+  it("skips when already announced (edge trigger — no steady-state re-notify)", () => {
+    const d1 = evaluateFleetRollAnnounce({ roll: ROLL, prev: emptyAccountState(), now: NOW });
+    expect(d1.kind).toBe("notify");
+    if (d1.kind !== "notify") return;
+    const d2 = evaluateFleetRollAnnounce({ roll: ROLL, prev: d1.newState, now: NOW + 15 * 60_000 });
+    expect(d2.kind).toBe("skip");
+    if (d2.kind !== "skip") return;
+    expect(d2.reason).toBe("already-announced");
+  });
+
+  it("re-fires for a NEW roll event (later at) after a prior announce", () => {
+    const d1 = evaluateFleetRollAnnounce({ roll: ROLL, prev: emptyAccountState(), now: NOW });
+    if (d1.kind !== "notify") throw new Error("expected notify");
+    const later: FleetRollInfo = { ...ROLL, at: NOW + 6 * 3600_000, from: "bob@example.com", to: "carol@example.com" };
+    const d2 = evaluateFleetRollAnnounce({ roll: later, prev: d1.newState, now: NOW + 6 * 3600_000 + 5_000 });
+    expect(d2.kind).toBe("notify");
+  });
+
+  it("skips a stale roll (boot long after the event resurrects no old news)", () => {
+    const d = evaluateFleetRollAnnounce({
+      roll: { ...ROLL, at: NOW - FLEET_ROLL_MAX_AGE_MS - 1 },
+      prev: emptyAccountState(),
+      now: NOW,
+    });
+    expect(d.kind).toBe("skip");
+    if (d.kind !== "skip") return;
+    expect(d.reason).toBe("stale-roll");
+  });
+
+  it("skips when the broker reports no roll (old broker / never rolled)", () => {
+    expect(evaluateFleetRollAnnounce({ roll: null, prev: emptyAccountState(), now: NOW }).kind).toBe("skip");
+    expect(evaluateFleetRollAnnounce({ roll: undefined, prev: emptyAccountState(), now: NOW }).kind).toBe("skip");
+  });
+});
+
+describe("buildFleetRollMessage (#3031 PR 3) — causal + reassuring shape", () => {
+  it("names the new account, the binding window + pct on the old account, and the reset", () => {
+    const msg = buildFleetRollMessage(
+      {
+        from: "alice@example.com",
+        to: "bob@example.com",
+        at: NOW - 60_000,
+        exhausted_until: NOW + 2 * 3600_000,
+        window: "5h",
+        pct: 99.8,
+      },
+      NOW,
+    );
+    expect(msg).toContain("Switched fleet to");
+    expect(msg).toContain("bob@example.com");
+    expect(msg).toContain("alice@example.com");
+    expect(msg).toContain("5-hour window");
+    expect(msg).toContain("100%"); // fmtPct rounds 99.8
+    expect(msg).toContain("resets");
+    expect(msg).toContain("Work continues uninterrupted");
+  });
+
+  it("degrades gracefully without window/pct/reset data", () => {
+    const msg = buildFleetRollMessage(
+      { from: "alice@example.com", to: "bob@example.com", at: NOW - 60_000 },
+      NOW,
+    );
+    expect(msg).toContain("quota window");
+    expect(msg).not.toContain("resets");
+    expect(msg).toContain("Work continues uninterrupted");
+  });
+});
+
+describe("evaluateQuotaWatchAccount — roll-announcement dedupe (#3031 PR 3)", () => {
+  it("latches entered-throttling SILENTLY when a fresh roll off the same account was announced", () => {
+    const d = evaluateQuotaWatchAccount({
+      agentName: "lawgpt",
+      snap: THROTTLING_5H,
+      prev: PREV_NEVER_NOTIFIED,
+      now: NOW,
+      lastRoll: { from: "alice@example.com", at: NOW - 60_000 },
+    });
+    expect(d.kind).toBe("reconcile");
+    if (d.kind !== "reconcile") return;
+    expect(d.reason).toBe("roll-announced");
+    expect(d.transition).toBe("entered-throttling");
+    // Latch advances — no steady-state re-notify on the next tick.
+    expect(d.newAccountState.lastNotifiedHealth).toBe("throttling");
+    const next = evaluateQuotaWatchAccount({
+      agentName: "lawgpt",
+      snap: THROTTLING_5H,
+      prev: d.newAccountState,
+      now: NOW + 15 * 60_000,
+      lastRoll: { from: "alice@example.com", at: NOW - 60_000 },
+    });
+    expect(next.kind).toBe("skip");
+  });
+
+  it("does NOT dedupe a roll for a DIFFERENT account", () => {
+    const d = evaluateQuotaWatchAccount({
+      agentName: "lawgpt",
+      snap: THROTTLING_5H,
+      prev: PREV_NEVER_NOTIFIED,
+      now: NOW,
+      lastRoll: { from: "someone-else@example.com", at: NOW - 60_000 },
+    });
+    expect(d.kind).toBe("notify");
+  });
+
+  it("does NOT dedupe a roll older than the dedup window", () => {
+    const d = evaluateQuotaWatchAccount({
+      agentName: "lawgpt",
+      snap: THROTTLING_5H,
+      prev: PREV_NEVER_NOTIFIED,
+      now: NOW,
+      lastRoll: { from: "alice@example.com", at: NOW - QUOTA_WATCH_ROLL_DEDUP_MS - 1 },
+    });
+    expect(d.kind).toBe("notify");
+  });
+
+  it("throttling message says what happens next (early warning, not incident)", () => {
+    const d = evaluateQuotaWatchAccount({
+      agentName: "lawgpt",
+      snap: makeSnap("alice@example.com", makeQuota(85, 40), /*isActive*/ true),
+      prev: PREV_NEVER_NOTIFIED,
+      now: NOW,
+    });
+    expect(d.kind).toBe("notify");
+    if (d.kind !== "notify") return;
+    expect(d.message).toContain("No action needed");
+    expect(d.message).toContain("fleet will prefer another account");
+  });
+});
+
+// ── #3035 review fixes ───────────────────────────────────────────────────────
+
+describe("#3035 review fixes", () => {
+  it("finding 1 — roll announce ceiling never exceeds the broker claim window (no duplicate-card gap)", async () => {
+    const mod = await import("../quota-watch.js");
+    expect(FLEET_ROLL_MAX_AGE_MS).toBeLessThanOrEqual(mod.QUOTA_WATCH_CLAIM_WINDOW_MS);
+  });
+
+  it("finding 3 — roll-dedupe suppresses ONLY the first post-roll episode: a recover-then-re-throttle after the roll notifies", () => {
+    const rollAt = NOW - 20 * 60_000; // inside the 30-min dedup window
+    // Post-roll, the account recovered to healthy and the watch state
+    // advanced (lastNotifiedAt AFTER roll.at). A fresh throttling entry is
+    // a genuinely NEW episode the roll card said nothing about.
+    const prevRecoveredPostRoll = {
+      lastNotifiedHealth: "healthy" as const,
+      lastNotifiedAt: rollAt + 5 * 60_000,
+    };
+    const d = evaluateQuotaWatchAccount({
+      agentName: "lawgpt",
+      snap: THROTTLING_5H,
+      prev: prevRecoveredPostRoll,
+      now: NOW,
+      lastRoll: { from: "alice@example.com", at: rollAt },
+    });
+    expect(d.kind).toBe("notify");
+    if (d.kind !== "notify") return;
+    expect(d.transition).toBe("entered-throttling");
+  });
+
+  it("finding 3 — first post-roll episode (state pre-dates the roll) still latches silently", () => {
+    const rollAt = NOW - 60_000;
+    const d = evaluateQuotaWatchAccount({
+      agentName: "lawgpt",
+      snap: THROTTLING_5H,
+      prev: { lastNotifiedHealth: "healthy" as const, lastNotifiedAt: rollAt - 3600_000 },
+      now: NOW,
+      lastRoll: { from: "alice@example.com", at: rollAt },
+    });
+    expect(d.kind).toBe("reconcile");
+    if (d.kind !== "reconcile") return;
+    expect(d.reason).toBe("roll-announced");
+  });
+});
+
+describe("buildFleetRollMessage — reason attribution (#3031 PR 2 reason field)", () => {
+  const BASE: FleetRollInfo = {
+    from: "alice@example.com",
+    to: "bob@example.com",
+    at: NOW - 60_000,
+    window: "7d",
+    pct: 96,
+  };
+
+  it("soft-avoid reads as proactive 'approaching limits', not exhaustion", () => {
+    const msg = buildFleetRollMessage({ ...BASE, reason: "soft-avoid" }, NOW);
+    expect(msg).toContain("Proactive switch");
+    expect(msg).toContain("approaching its limits");
+    expect(msg).toContain("proactive, before exhaustion");
+    expect(msg).toContain("7-day window at 96%");
+    expect(msg).toContain("Work continues uninterrupted");
+  });
+
+  it("hard-exhaustion (explicit or absent reason — pre-PR-2 broker) keeps the walled framing", () => {
+    for (const roll of [{ ...BASE, reason: "hard-exhaustion" as const }, BASE]) {
+      const msg = buildFleetRollMessage(roll, NOW);
+      expect(msg).not.toContain("Proactive switch");
+      expect(msg).not.toContain("approaching its limits");
+      expect(msg).toContain("7-day window at 96% on");
+    }
+  });
+});