switchroom 0.18.9 → 0.18.10

package/telegram-plugin/gateway/session-model-file.ts

@@ -7,17 +7,26 @@
  *   - `.session-model` — the DURABLE session override written on every
  *     positively-confirmed `/model` switch. One-line JSON
  *     `{"model","configuredDefaultAtWrite","ts"}`. It is NOT consumed by a
- *     keep-path boot; start.sh deletes it on revert / invalidation /
- *     corruption / 7-day staleness, and the gateway deletes it on
- *     `/model default`.
+ *     keep-path boot; it survives every restart/deploy/crash and is cleared
+ *     only by explicit user action (`/model default`) or invalidation
+ *     (corruption / the configured yaml default changed) — every clearing
+ *     path notifies the operator chat via `.session-model-alert` (#3039).
  *
  *   - `.relaunch-model-intent` — the ONE-SHOT intent bit for the next boot.
  *     One-line JSON `{"intent":"keep"|"revert","reason","ts"}`, atomic
- *     write, last-writer-wins. Boot default is REVERT (operator decision:
- *     a raw `docker restart` / host reboot / crash must revert to the yaml
- *     model), so every switchroom-managed KEEP path must stamp keep-intent
- *     BEFORE the bounce. start.sh consumes it (rm -f) every boot; a stale
- *     (>10 min by the embedded ts) or corrupt intent counts as no intent.
+ *     write, last-writer-wins. Boot default is KEEP (#3039 — operator
+ *     decision 2026-07-11, superseding the earlier revert-by-default): a
+ *     raw `docker restart` / host reboot / deploy / crash keeps a valid
+ *     override. Only an explicit fresh "revert" intent reverts. start.sh
+ *     consumes the file (rm -f) every boot; a stale (>10 min by the
+ *     embedded ts) or corrupt intent counts as no intent (→ keep).
+ *
+ *   - `.session-effort` — the DURABLE effort override (#3039), same shape
+ *     and lifecycle as `.session-model` with `level` in place of `model`:
+ *     `{"level","configuredDefaultAtWrite","ts"}`. Written on every
+ *     positively-confirmed `/effort` apply, resolved by start.sh into the
+ *     relaunch's `--effort`, cleared only by `/effort default` or
+ *     invalidation (with a boot alert).
  *
  * The `model` token is always a canonical `claude --model` token (alias,
  * `claude-*` id, or `sr-*` id) — NEVER a display label like "Opus 4.8".
@@ -41,20 +50,18 @@ export interface SessionModelRecord {
 }
 
 /**
- * Restart reasons whose semantics are "revert the session model to the
- * configured default". Everything else `triggerSelfRestart` fires with is a
- * switchroom-managed relaunch (watchdog recovery, drain-cap bounce,
- * turn-complete deferred restart, fleet-fallback resume, sr-to-claude model
- * switch, grant restarts) and KEEPS the override — the whole point of the
- * stickiness contract. Enumerated in the RFC §3; default-keep here is safe
- * because only gateway code calls triggerSelfRestart, and a bounce nobody
- * stamped (crash, raw docker restart, deploy) reverts by boot default anyway.
+ * Classify a triggerSelfRestart reason into the intent the boot should honor.
+ *
+ * Since #3039 (operator contract 2026-07-11) EVERY restart reason keeps the
+ * override: a restart — user-tapped, watchdog, deploy, or crash — is not
+ * "clear my model". The override is cleared only by explicit user action
+ * (`/model default`) or invalidation at boot, both of which run their own
+ * paths. The 'revert' intent value remains recognised by start.sh (and this
+ * classifier's signature keeps it) so an older gateway's stamp still parses,
+ * but current code never emits it.
  */
-const REVERT_RESTART_REASONS: ReadonlySet<string> = new Set(['inline-button-restart'])
-
-/** Classify a triggerSelfRestart reason into the intent the boot should honor. */
-export function intentForRestartReason(reason: string): RelaunchModelIntent {
-  return REVERT_RESTART_REASONS.has(reason) ? 'revert' : 'keep'
+export function intentForRestartReason(_reason: string): RelaunchModelIntent {
+  return 'keep'
 }
 
 function atomicWrite(path: string, content: string): void {
@@ -132,6 +139,10 @@ export function readSessionModelFile(agentDir: string): SessionModelRecord | nul
 export function clearSessionModelFile(agentDir: string): void {
   try {
     rmSync(join(agentDir, SESSION_MODEL_FILE), { force: true })
+    // #3042 item 4: also drop the kept-alert dedup sentinel so a future
+    // override of the same name re-alerts on its first kept boot.
+    rmSync(join(agentDir, '.session-model-kept-notified'), { force: true })
+    rmSync(join(agentDir, '.session-model-boot-attempts'), { force: true })
   } catch {
     /* best-effort */
   }
@@ -154,8 +165,8 @@ export function restoreSessionModelFileRaw(agentDir: string, raw: string | null)
  * Stamp the one-shot relaunch intent. MUST be called synchronously BEFORE
  * the restart signal/dispatch it describes (write-before-kill invariant —
  * the next start.sh boot reads this to decide keep vs revert). Best-effort:
- * a failed write means the boot falls back to the default (revert), which
- * is the safe side.
+ * a failed write means the boot falls back to the default (keep, #3039) —
+ * the user's choice is preserved either way.
  */
 export function writeRelaunchModelIntent(
   agentDir: string,
@@ -174,6 +185,61 @@ export function writeRelaunchModelIntent(
   }
 }
 
+/**
+ * Reason prefix the gateway's SIGTERM/SIGINT shutdown handler stamps on its
+ * deploy-survival keep-intent (#3017/#3018). Distinguishable on purpose:
+ * a gateway-only bounce (supervisor relaunch, bare gateway-unit restart)
+ * leaves that stamp UNCONSUMED on disk — start.sh only runs on a container
+ * boot — and the next gateway boot uses this prefix to recognise and clear
+ * the stale stamp (see clearStaleGatewayShutdownIntent).
+ */
+export const GATEWAY_SHUTDOWN_INTENT_REASON_PREFIX = 'gateway-shutdown:'
+
+export interface RelaunchModelIntentRecord {
+  intent: RelaunchModelIntent
+  reason: string
+  ts: number
+}
+
+/** Parsed `.relaunch-model-intent`, or null when absent / corrupt / malformed. */
+export function readRelaunchModelIntent(agentDir: string): RelaunchModelIntentRecord | null {
+  try {
+    const raw = readFileSync(join(agentDir, RELAUNCH_MODEL_INTENT_FILE), 'utf8')
+    const parsed = JSON.parse(raw) as Partial<RelaunchModelIntentRecord>
+    if (
+      (parsed.intent !== 'keep' && parsed.intent !== 'revert') ||
+      typeof parsed.reason !== 'string' ||
+      typeof parsed.ts !== 'number'
+    ) {
+      return null
+    }
+    return { intent: parsed.intent, reason: parsed.reason, ts: parsed.ts }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Boot-time cleanup for the gateway-only-bounce hole (#3018 finding 4).
+ *
+ * A container-level stop/deploy consumes `.relaunch-model-intent` in start.sh
+ * BEFORE any gateway boots. So if a freshly-booting GATEWAY still sees an
+ * intent that a gateway shutdown handler stamped (reason carries
+ * GATEWAY_SHUTDOWN_INTENT_REASON_PREFIX), the preceding bounce was
+ * gateway-only — the container never restarted and the stamp is stale.
+ * Left in place, it could convert a genuine crash within the 10-min
+ * freshness window into a "keep", breaking the crash-reverts policy.
+ * Clear it. Never touches a triggerSelfRestart / user-slash stamp (those
+ * use their own un-prefixed reasons and precede a container bounce).
+ * Returns true when a stale stamp was cleared.
+ */
+export function clearStaleGatewayShutdownIntent(agentDir: string): boolean {
+  const rec = readRelaunchModelIntent(agentDir)
+  if (rec == null || !rec.reason.startsWith(GATEWAY_SHUTDOWN_INTENT_REASON_PREFIX)) return false
+  clearRelaunchModelIntent(agentDir)
+  return true
+}
+
 /** Remove a stamped intent (rollback of a failed dispatch). Best-effort. */
 export function clearRelaunchModelIntent(agentDir: string): void {
   try {
@@ -196,3 +262,80 @@ export function readConfiguredDefaultModel(agentDir: string): string | null {
     return null
   }
 }
+
+// ─── Durable session-effort override (#3039) ────────────────────────────────
+//
+// The `/effort` sibling of `.session-model`. Same lifecycle: written on every
+// positively-confirmed effort apply, honored by start.sh on every boot
+// (`--effort <level>`), cleared only by `/effort default` or invalidation
+// (configured `thinking_effort:` changed / corrupt file — both alert once).
+
+export const SESSION_EFFORT_FILE = '.session-effort'
+
+/**
+ * The level allowlist, duplicated from effort-command.ts to avoid a cycle
+ * (effort-command must stay gateway-agnostic; this module already imports
+ * from model-command). Kept in sync by the cross-check regression test.
+ */
+const EFFORT_LEVEL_RE = /^(low|medium|high|xhigh|max)$/
+
+export interface SessionEffortRecord {
+  level: string
+  /** The cascade-resolved `thinking_effort` at write time ('' when unset). */
+  configuredDefaultAtWrite: string
+  ts: number
+}
+
+/** Parse `.session-effort` content. Null on corrupt JSON / bad shape / non-allowlisted level. */
+export function parseSessionEffort(text: string): SessionEffortRecord | null {
+  try {
+    const raw = JSON.parse(text) as Partial<SessionEffortRecord>
+    if (
+      typeof raw.level !== 'string' ||
+      typeof raw.configuredDefaultAtWrite !== 'string' ||
+      typeof raw.ts !== 'number' ||
+      !EFFORT_LEVEL_RE.test(raw.level)
+    ) {
+      return null
+    }
+    return { level: raw.level, configuredDefaultAtWrite: raw.configuredDefaultAtWrite, ts: raw.ts }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Write the durable effort override. Throws on a non-allowlisted level —
+ * the value is passed verbatim to `claude --effort` at the next boot.
+ */
+export function writeSessionEffortFile(
+  agentDir: string,
+  level: string,
+  configuredDefaultAtWrite: string | null,
+): void {
+  if (!EFFORT_LEVEL_RE.test(level)) {
+    throw new Error(`refusing to persist non-allowlisted effort level: ${JSON.stringify(level)}`)
+  }
+  atomicWrite(
+    join(agentDir, SESSION_EFFORT_FILE),
+    `${JSON.stringify({ level, configuredDefaultAtWrite: configuredDefaultAtWrite ?? '', ts: Date.now() })}\n`,
+  )
+}
+
+/** Parsed durable effort override, or null when absent/corrupt. */
+export function readSessionEffortFile(agentDir: string): SessionEffortRecord | null {
+  try {
+    return parseSessionEffort(readFileSync(join(agentDir, SESSION_EFFORT_FILE), 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/** Delete the durable effort override (`/effort default`). Best-effort. */
+export function clearSessionEffortFile(agentDir: string): void {
+  try {
+    rmSync(join(agentDir, SESSION_EFFORT_FILE), { force: true })
+  } catch {
+    /* best-effort */
+  }
+}

package/telegram-plugin/gateway/stop-command.ts

@@ -0,0 +1,56 @@
+/**
+ * Telegram `/stop` command + bare operator "stop" keyword (#3020) — the
+ * mid-turn kill switch. Both cancel the agent's in-flight claude turn via
+ * the same halt sequence the empty-`!` interrupt uses (safe-boundary
+ * deferral per the interrupt config, tmux C-c, obligation cancel).
+ *
+ * This module is the pure, grammY-free core — parser + reply builder —
+ * mirroring the `effort-command.ts` split so the logic is unit-testable
+ * without booting the bot. The side-effectful halt itself
+ * (`executeHaltNow`) lives in gateway.ts next to the interrupt machinery
+ * it shares.
+ *
+ * NOTE: `/stop` used to be the hostd container-stop verb; that moved to
+ * `/agentstop` (pairing with `/agentstart`) so the intuitive word can do
+ * the intuitive thing: stop what the agent is doing right now, not stop
+ * the container.
+ */
+
+/**
+ * True iff the message is a bare operator "stop" — the exact word `stop`
+ * (case-insensitive) on its own, optionally followed by a single `.` or
+ * `!`. Anything more ("stop the build", "stop it") is normal speech and
+ * must flow to the agent as an ordinary turn.
+ */
+export function parseStopKeyword(text: string): boolean {
+  return /^stop[.!]?$/i.test(text.trim())
+}
+
+export interface StopReply {
+  text: string
+}
+
+/**
+ * Build the operator-facing reply for a stop request.
+ *
+ *  - `turnInFlight === false` → honest "nothing running" (no C-c was sent).
+ *  - `turnInFlight === true`  → confirmation the in-flight turn was
+ *    cancelled. If pending-session-command slots (#3017/#3018) hold queued
+ *    commands, say so — a queued `/model`/`/effort` survives the halt and
+ *    still applies at idle, and silence here would read as "my /model got
+ *    killed too".
+ *
+ * Plain text (no HTML) — queued labels carry arbitrary model names.
+ */
+export function buildStopReply(turnInFlight: boolean, queuedSessionCmds: string[]): StopReply {
+  if (!turnInFlight) {
+    return { text: 'Nothing running — no in-flight turn to cancel.' }
+  }
+  const lines = ['⏹ Turn cancelled.']
+  if (queuedSessionCmds.length > 0) {
+    lines.push(
+      `Queued command${queuedSessionCmds.length > 1 ? 's' : ''} (${queuedSessionCmds.join(', ')}) survive${queuedSessionCmds.length > 1 ? '' : 's'} and will apply once the session is idle.`,
+    )
+  }
+  return { text: lines.join('\n') }
+}

package/telegram-plugin/photo-precheck.ts

@@ -0,0 +1,201 @@
+/**
+ * photo-precheck.ts — pre-send validation for images attached via the
+ * reply tool's `files` param (#3033, layer 2 of the media-dimension
+ * defense-in-depth).
+ *
+ * Telegram's photo path (sendPhoto / sendMediaGroup type:photo) rejects
+ * images it can't store as photos with a 400 PHOTO_INVALID_DIMENSIONS /
+ * PHOTO_SAVE_FILE_INVALID. One bad photo fails a WHOLE sendMediaGroup
+ * album. The reactive fallback (#3022) re-sends as documents after the
+ * 400 bounces back — this module catches the offenders BEFORE the wire
+ * so good photos still ship as an album and the bad one goes out as a
+ * document on the first attempt.
+ *
+ * Bounds (deterministic, documented):
+ *   - width + height ≤ 10000 px      (Bot API documented cap)
+ *   - aspect ratio   ≤ 10 : 1        (docs say 20:1, but the 2026-07-11
+ *     clerk incident had 600x8717 — ratio 14.5:1, sum 9317 — rejected
+ *     with PHOTO_INVALID_DIMENSIONS, so the documented limit is not what
+ *     the server enforces for uploads. 10:1 is conservative: real phone
+ *     screenshots are ≤ ~2.5:1; only page-length capture strips exceed
+ *     10:1 territory, and those are better as documents anyway.)
+ *   - file size      ≤ 10 MB         (photo-path ceiling; documents 50MB)
+ *
+ * Probe failures (unknown/truncated format) return null and the caller
+ * keeps the photo path — the reactive #3022 fallback still backstops.
+ * No image decoding, no deps: header-only parsers for PNG / JPEG / GIF /
+ * WebP, the formats behind the gateway's PHOTO_EXTS set.
+ */
+
+import { closeSync, fstatSync, openSync, readSync } from 'node:fs'
+
+export interface ImageProbe {
+  width: number
+  height: number
+  bytes: number
+}
+
+/** Photo-path bounds — see module header for provenance. */
+export const PHOTO_MAX_DIMENSION_SUM = 10000
+export const PHOTO_MAX_ASPECT_RATIO = 10
+export const PHOTO_MAX_BYTES = 10 * 1024 * 1024
+
+/** Parse PNG dimensions: 8-byte signature then IHDR (width/height BE at 16/20). */
+function pngDimensions(buf: Buffer): { width: number; height: number } | null {
+  if (buf.length < 24) return null
+  if (buf.readUInt32BE(0) !== 0x89504e47 || buf.readUInt32BE(4) !== 0x0d0a1a0a) return null
+  if (buf.toString('ascii', 12, 16) !== 'IHDR') return null
+  return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) }
+}
+
+/** Parse JPEG dimensions: walk markers to the first SOFn frame header. */
+function jpegDimensions(buf: Buffer): { width: number; height: number } | null {
+  if (buf.length < 4 || buf[0] !== 0xff || buf[1] !== 0xd8) return null
+  let off = 2
+  while (off + 9 < buf.length) {
+    if (buf[off] !== 0xff) { off++; continue }
+    const marker = buf[off + 1]!
+    // Standalone markers without a length segment.
+    if (marker === 0xd8 || (marker >= 0xd0 && marker <= 0xd7) || marker === 0x01 || marker === 0xff) {
+      off += 2
+      continue
+    }
+    const len = buf.readUInt16BE(off + 2)
+    // SOF0-SOF15 (excluding DHT 0xc4, JPG 0xc8, DAC 0xcc) carry dimensions.
+    if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+      return { height: buf.readUInt16BE(off + 5), width: buf.readUInt16BE(off + 7) }
+    }
+    if (len < 2) return null
+    off += 2 + len
+  }
+  return null
+}
+
+/** Parse GIF dimensions (logical screen descriptor, LE at offset 6/8). */
+function gifDimensions(buf: Buffer): { width: number; height: number } | null {
+  if (buf.length < 10) return null
+  const sig = buf.toString('ascii', 0, 6)
+  if (sig !== 'GIF87a' && sig !== 'GIF89a') return null
+  return { width: buf.readUInt16LE(6), height: buf.readUInt16LE(8) }
+}
+
+/** Parse WebP dimensions (VP8 / VP8L / VP8X chunk variants). */
+function webpDimensions(buf: Buffer): { width: number; height: number } | null {
+  if (buf.length < 30) return null
+  if (buf.toString('ascii', 0, 4) !== 'RIFF' || buf.toString('ascii', 8, 12) !== 'WEBP') return null
+  const chunk = buf.toString('ascii', 12, 16)
+  if (chunk === 'VP8X') {
+    // 24-bit LE minus-one canvas dimensions at 24/27.
+    const width = 1 + (buf[24]! | (buf[25]! << 8) | (buf[26]! << 16))
+    const height = 1 + (buf[27]! | (buf[28]! << 8) | (buf[29]! << 16))
+    return { width, height }
+  }
+  if (chunk === 'VP8L') {
+    if (buf[20] !== 0x2f) return null
+    const b0 = buf[21]!, b1 = buf[22]!, b2 = buf[23]!, b3 = buf[24]!
+    const width = 1 + (((b1 & 0x3f) << 8) | b0)
+    const height = 1 + (((b3 & 0x0f) << 10) | (b2 << 2) | ((b1 & 0xc0) >> 6))
+    return { width, height }
+  }
+  if (chunk === 'VP8 ') {
+    // Lossy: frame tag at 20; sync code 9d 01 2a then 14-bit LE dims.
+    if (buf[23] !== 0x9d || buf[24] !== 0x01 || buf[25] !== 0x2a) return null
+    const width = buf.readUInt16LE(26) & 0x3fff
+    const height = buf.readUInt16LE(28) & 0x3fff
+    return { width, height }
+  }
+  return null
+}
+
+/** Header-only dimension probe. Returns null when the format is unrecognized. */
+export function probeImageDimensions(buf: Buffer): { width: number; height: number } | null {
+  return pngDimensions(buf) ?? jpegDimensions(buf) ?? gifDimensions(buf) ?? webpDimensions(buf)
+}
+
+/**
+ * Fixed-size header reads — never readFileSync the whole image (a 10MB
+ * screenshot would be a multi-MB sync read on the event loop for a
+ * ~30-byte probe). PNG needs 24 bytes, GIF 10, WebP (VP8X/VP8L/VP8 )
+ * tops out at offset 30 — so 32 bytes covers every fixed-offset format.
+ * JPEG is the exception: SOFn sits past variable-length APPn segments
+ * (EXIF/ICC metadata), so when the 32-byte sniff says JPEG we re-read a
+ * 64KB window. If SOFn is buried deeper than that, the probe returns
+ * null and the caller keeps the photo route (#3022 reactive backstop).
+ */
+const HEADER_PROBE_BYTES = 32
+const JPEG_PROBE_BYTES = 64 * 1024
+
+/** Probe an image file on disk. Returns null on read failure or unknown format. */
+export function probeImageFile(path: string): ImageProbe | null {
+  let fd: number | undefined
+  try {
+    fd = openSync(path, 'r')
+    const bytes = fstatSync(fd).size
+    const headBuf = Buffer.alloc(HEADER_PROBE_BYTES)
+    const headRead = readSync(fd, headBuf, 0, HEADER_PROBE_BYTES, 0)
+    let probe = headBuf.subarray(0, headRead)
+    if (headRead >= 2 && probe[0] === 0xff && probe[1] === 0xd8) {
+      // JPEG: extend to a 64KB window so the marker walk can skip
+      // APPn metadata segments and reach SOFn.
+      const jpegBuf = Buffer.alloc(Math.min(JPEG_PROBE_BYTES, bytes))
+      const jpegRead = readSync(fd, jpegBuf, 0, jpegBuf.length, 0)
+      probe = jpegBuf.subarray(0, jpegRead)
+    }
+    const dims = probeImageDimensions(probe)
+    if (!dims || dims.width <= 0 || dims.height <= 0) return null
+    return { ...dims, bytes }
+  } catch {
+    return null
+  } finally {
+    if (fd !== undefined) {
+      try { closeSync(fd) } catch { /* best-effort */ }
+    }
+  }
+}
+
+/**
+ * Why this image cannot go down Telegram's photo path — or null when it
+ * fits the bounds. The reason string is operator/agent-legible (it lands
+ * in the gateway log and, via the reactive path, in tool errors).
+ */
+export function photoSendViolation(probe: ImageProbe): string | null {
+  const { width, height, bytes } = probe
+  if (width + height > PHOTO_MAX_DIMENSION_SUM) {
+    return `dimensions ${width}x${height} exceed width+height<=${PHOTO_MAX_DIMENSION_SUM}`
+  }
+  const ratio = Math.max(width, height) / Math.min(width, height)
+  if (ratio > PHOTO_MAX_ASPECT_RATIO) {
+    return `aspect ratio ${ratio.toFixed(1)}:1 (${width}x${height}) exceeds ${PHOTO_MAX_ASPECT_RATIO}:1 photo bound`
+  }
+  if (bytes > PHOTO_MAX_BYTES) {
+    return `file size ${(bytes / (1024 * 1024)).toFixed(1)}MB exceeds ${PHOTO_MAX_BYTES / (1024 * 1024)}MB photo ceiling`
+  }
+  return null
+}
+
+/**
+ * Suffix for the reply tool's result text when files were rerouted from
+ * the photo path to sendDocument (precheck or reactive fallback). The
+ * agent only sees the tool result — without this it may claim an inline
+ * image rendered when it actually went out as a file attachment.
+ * Returns '' when nothing was rerouted.
+ */
+export function rerouteResultSuffix(reroutes: Array<{ path: string; reason: string }>): string {
+  if (reroutes.length === 0) return ''
+  const details = reroutes
+    .map((r) => `${r.path.split('/').pop() ?? r.path}: ${r.reason}`)
+    .join('; ')
+  return ` (${reroutes.length} file(s) sent as document, not inline photo: ${details})`
+}
+
+/**
+ * Decide the send route for a photo-extension file. `photo` = safe for
+ * sendPhoto/sendMediaGroup; `document` = pre-route as document (reason
+ * says why); probe failure = `photo` (reactive #3022 fallback backstops).
+ */
+export function classifyPhotoFile(path: string): { route: 'photo' } | { route: 'document'; reason: string } {
+  const probe = probeImageFile(path)
+  if (!probe) return { route: 'photo' }
+  const violation = photoSendViolation(probe)
+  return violation ? { route: 'document', reason: violation } : { route: 'photo' }
+}

package/telegram-plugin/quota-watch.ts

@@ -149,6 +149,111 @@ export function buildQuotaClaimKey(
   return `quota-watch:${accountLabel}:${transition}:${chatId}`;
 }
 
+// ─── Broker-initiated fleet-roll announcement (#3031 PR 3) ───────────────────
+
+/**
+ * Reserved state-map key for the last-announced broker roll. Same reserved-key
+ * trick as FLEET_ALL_EXHAUSTED_KEY: not a valid account label, so it never
+ * collides with per-account entries, and the per-account loop never sees it.
+ * `lastNotifiedAt` stores the roll's `at` timestamp (edge-trigger latch).
+ */
+export const FLEET_ROLL_ANNOUNCE_KEY = "__fleet_roll_announce__";
+
+/**
+ * Don't announce a roll older than this — a gateway booting hours after a
+ * roll would otherwise resurrect stale news (mirrors the late-recovery
+ * discipline). CLAMPED to the broker claim window (#3035 review, finding 1):
+ * if this ceiling exceeded the claim window, a gateway with an empty
+ * quota-watch.json running its boot tick after the claim expired but before
+ * this ceiling (e.g. T+40m under the old 60m/30m split) would pass both the
+ * latch AND the expired claim → duplicate roll card. Equal horizons close
+ * that gap by construction: any roll still young enough to announce is
+ * still inside the claim window that deduped the first announcement.
+ */
+export const FLEET_ROLL_MAX_AGE_MS = QUOTA_WATCH_CLAIM_WINDOW_MS;
+
+/**
+ * Suppress the per-account 🟡 throttling push when a roll announcement for
+ * the SAME account fired this recently — the roll card already told the
+ * operator that account walled and the fleet moved off it; a trailing
+ * "approaching limit" push for it is noise. Matches the broker claim window
+ * so the two dedup horizons agree.
+ */
+export const QUOTA_WATCH_ROLL_DEDUP_MS = QUOTA_WATCH_CLAIM_WINDOW_MS;
+
+/** Shape of `listState().last_fleet_roll` as the watch consumes it. */
+export interface FleetRollInfo {
+  from: string;
+  to: string;
+  at: number;
+  exhausted_until?: number;
+  window?: "5h" | "7d";
+  pct?: number;
+  /**
+   * Trigger attribution (#3031 PR 2): "soft-avoid" = proactive
+   * serving-preference roll off an account APPROACHING its limits;
+   * "hard-exhaustion" = the probe saw a genuine quota wall. Absent on
+   * pre-PR-2 brokers — rendered as hard exhaustion.
+   */
+  reason?: "soft-avoid" | "hard-exhaustion";
+}
+
+export type FleetRollAnnounceDecision =
+  | { kind: "notify"; message: string; newState: QuotaWatchAccountState }
+  | { kind: "skip"; reason: string };
+
+/**
+ * Edge-triggered decision for the broker-roll announcement. Fires at most
+ * once per roll event (latched on the roll's `at` timestamp), never for
+ * rolls older than `maxAgeMs`, and never re-fires in steady state.
+ */
+export function evaluateFleetRollAnnounce(args: {
+  roll: FleetRollInfo | null | undefined;
+  prev: QuotaWatchAccountState;
+  now: number;
+  maxAgeMs?: number;
+}): FleetRollAnnounceDecision {
+  const { roll, prev, now } = args;
+  const maxAgeMs = args.maxAgeMs ?? FLEET_ROLL_MAX_AGE_MS;
+  if (!roll) return { kind: "skip", reason: "no-roll" };
+  if (prev.lastNotifiedAt >= roll.at) return { kind: "skip", reason: "already-announced" };
+  if (now - roll.at > maxAgeMs) return { kind: "skip", reason: "stale-roll" };
+  return {
+    kind: "notify",
+    message: buildFleetRollMessage(roll, now),
+    newState: { lastNotifiedHealth: "healthy", lastNotifiedAt: roll.at },
+  };
+}
+
+/**
+ * Causal + reassuring announcement for a broker-initiated proactive roll.
+ * Hard exhaustion: "Switched fleet to <new> — <window> at <pct>% on <old>
+ * (resets <time>). Work continues uninterrupted."
+ * Soft-avoid (#3031 PR 2 `reason`): reads as PROACTIVE — the old account is
+ * approaching its limits, not walled; no mark/reset framing.
+ */
+export function buildFleetRollMessage(roll: FleetRollInfo, now: number): string {
+  const winLabel =
+    roll.window === "5h" ? "5-hour window" : roll.window === "7d" ? "7-day window" : "quota window";
+  const pctPart = typeof roll.pct === "number" ? ` at ${fmtPct(roll.pct)}` : "";
+  const resetPart =
+    typeof roll.exhausted_until === "number" && roll.exhausted_until > now
+      ? ` (resets ${formatRelative(new Date(roll.exhausted_until), new Date(now))})`
+      : "";
+  const softAvoid = roll.reason === "soft-avoid";
+  const causeLine = softAvoid
+    ? `Proactive switch — \`${codeSpanSafe(roll.from)}\` is approaching its limits (${winLabel}${pctPart})${resetPart}, so the fleet moved early instead of hitting the wall.`
+    : `${winLabel}${pctPart} on \`${codeSpanSafe(roll.from)}\`${resetPart}.`;
+  return [
+    `🔁 **Switched fleet to \`${codeSpanSafe(roll.to)}\`**`,
+    ``,
+    causeLine,
+    `Work continues uninterrupted — agents and scheduled jobs now serve from \`${codeSpanSafe(roll.to)}\`.`,
+    ``,
+    `_Automatic broker failover${softAvoid ? " (proactive, before exhaustion)" : ""}. Run /auth for fleet status; \`/auth use ${codeSpanSafe(roll.from)}\` to switch back once it ${softAvoid ? "has headroom again" : "refills"}._`,
+  ].join("\n");
+}
+
 // ─── Decision logic ───────────────────────────────────────────────────────────
 
 export type QuotaWatchTransition =
@@ -177,7 +282,7 @@ export type QuotaWatchDecision =
       accountLabel: string;
       newAccountState: QuotaWatchAccountState;
       transition: QuotaWatchTransition;
-      reason: "boot-tick-recovery" | "late-recovery";
+      reason: "boot-tick-recovery" | "late-recovery" | "roll-announced";
     }
   | { kind: "skip"; accountLabel: string; reason: string };
 
@@ -257,6 +362,14 @@ export function evaluateQuotaWatchAccount(args: {
   bootTick?: boolean;
   /** Staleness / late-recovery thresholds; 0 disables each. */
   tuning?: Pick<QuotaWatchTuning, "maxStaleMs" | "lateRecoveryMs">;
+  /**
+   * Most recent broker-initiated fleet roll, if any (#3031 PR 3). A fresh
+   * roll OFF this account suppresses the 🟡 entered-throttling push — the
+   * roll announcement already told the operator this account walled, so a
+   * trailing "approaching limit" for it is redundant. Latched silently
+   * (reconcile) so edge-trigger semantics hold: no steady-state re-notify.
+   */
+  lastRoll?: Pick<FleetRollInfo, "from" | "at"> | null;
 }): QuotaWatchDecision {
   const { agentName, snap, prev, now } = args;
   const bootTick = args.bootTick ?? false;
@@ -300,6 +413,28 @@ export function evaluateQuotaWatchAccount(args: {
       lastNotifiedHealth: "throttling",
       lastNotifiedAt: now,
     };
+    // Roll-dedupe (#3031 PR 3): a fresh broker-roll announcement for this
+    // same account already covered the news — latch silently. FIRST
+    // post-roll episode only (#3035 review, finding 3): if this account's
+    // watch state has already advanced SINCE the roll (prev.lastNotifiedAt
+    // >= roll.at — e.g. it recovered to healthy post-roll and is now
+    // re-entering throttling), that is a genuinely NEW episode the roll
+    // card said nothing about, so it must notify normally.
+    const lastRoll = args.lastRoll;
+    if (
+      lastRoll &&
+      lastRoll.from === label &&
+      now - lastRoll.at <= QUOTA_WATCH_ROLL_DEDUP_MS &&
+      prev.lastNotifiedAt < lastRoll.at
+    ) {
+      return {
+        kind: "reconcile",
+        accountLabel: label,
+        newAccountState: newState,
+        transition: "entered-throttling",
+        reason: "roll-announced",
+      };
+    }
     return {
       kind: "notify",
       accountLabel: label,
@@ -536,8 +671,12 @@ export function buildThrottlingMessage(agentName: string, snap: AccountSnapshot)
     ? ""
     : `\nThis is a non-active account. Consider \`/auth use ${codeSpanSafe(snap.label)}\` to switch, or keep it as a fallback reserve.`;
 
+  // Early warning, not an incident (#3031 PR 3): say what happens NEXT so
+  // the operator knows no action is required — if utilization keeps climbing
+  // to the failover threshold, the broker rolls the fleet to another account
+  // automatically and announces the switch.
   const altNote = snap.isActive
-    ? `\nConsider \`/auth use <other-account>\` if you have a healthier account, or wait for the ${winLabel} window to refill${resetStr}.`
+    ? `\nNo action needed: if usage keeps climbing, the fleet will prefer another account once this reaches the failover threshold (you'll get a switch announcement). Or switch early with \`/auth use <other-account>\`, or wait for the ${winLabel} window to refill${resetStr}.`
     : "";
 
   return [