switchroom 0.18.7 → 0.18.8

package/telegram-plugin/stream-controller.ts

@@ -21,7 +21,7 @@
 
 import { createDraftStream, type DraftStreamHandle } from './draft-stream.js'
 import { richMessage, isParseEntitiesError } from './rich-send.js'
-import { maybeRenderOutbound } from './render/rich-render.js'
+import { renderOutboundChunks } from './render/rich-render.js'
 
 /**
  * Minimal bot.api surface the controller needs. Real callers pass grammy's
@@ -223,81 +223,199 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
   // `format:'text'` stream (plain sendMessage, no rich wrapper).
   // sendRichMessage does NOT accept link_preview_options (rich messages
   // control previews via entity detection), so strip it for the rich path.
-  const doSend = (text: string, opts: StreamSendOpts) => {
-    if (literalText) return bot.api.sendMessage(chatId, text, opts)
-    // Flag-gated rich render (`SWITCHROOM_RICH_RENDER`, default OFF — returns
-    // the text untouched as markdown when off, so this is a no-op for every
-    // agent until an operator opts in). A `plain` result (oversized/unsafe
-    // content renderSafe declined to emit as rich) sends WITHOUT the wrapper.
-    const rendered = maybeRenderOutbound(text)
-    if (rendered.mode === 'plain') return bot.api.sendMessage(chatId, rendered.text, opts)
+  // Render the outbound body into 1+ wire-cap-respecting pieces. The common
+  // case is a SINGLE piece whose output is identical to the pre-existing
+  // `maybeRenderOutbound` path; a body whose markdown-escaping pushed the
+  // rendered form past the cap splits into several pieces, each of which fits
+  // its own wire cap and never bisects a fenced block / table row (see
+  // `renderOutboundChunks`). Flag OFF (default) and a literal `format:'text'`
+  // stream both yield a single passthrough piece — no behavioural change.
+  const renderPieces = (text: string): { text: string; rich: boolean }[] => {
+    if (literalText) return [{ text, rich: false }]
+    // A `plain`-mode piece (oversized/unsafe content renderSafe declined to
+    // emit as rich) sends WITHOUT the rich wrapper.
+    return renderOutboundChunks(text).map((r) => ({ text: r.text, rich: r.mode !== 'plain' }))
+  }
+  // Send ONE rendered piece. Rich pieces go through sendRichMessage (with
+  // link_preview_options stripped — rich messages control previews via entity
+  // detection); plain pieces (and literal streams) through sendMessage.
+  const sendPiece = (piece: { text: string; rich: boolean }, opts: StreamSendOpts) => {
+    if (!piece.rich) return bot.api.sendMessage(chatId, piece.text, opts)
     const richOpts = { ...opts }
     delete richOpts.link_preview_options
-    return bot.api.sendRichMessage(chatId, richMessage(rendered.text), richOpts)
+    return bot.api.sendRichMessage(chatId, richMessage(piece.text), richOpts)
   }
-  const doEdit = (id: number, text: string, opts: StreamSendOpts) => {
-    if (literalText) return bot.api.editMessageText(chatId, id, text, opts)
-    const rendered = maybeRenderOutbound(text)
-    if (rendered.mode === 'plain') return bot.api.editMessageText(chatId, id, rendered.text, opts)
-    return bot.api.editMessageText(chatId, id, richMessage(rendered.text), opts)
+  const editPiece = (id: number, piece: { text: string; rich: boolean }, opts: StreamSendOpts) => {
+    if (!piece.rich) return bot.api.editMessageText(chatId, id, piece.text, opts)
+    return bot.api.editMessageText(chatId, id, richMessage(piece.text), opts)
+  }
+
+  // Overflow-tail bookkeeping, shared across the send + edit closures for the
+  // whole stream lifetime. A body large enough to split into several
+  // wire-cap pieces anchors on piece[0] (edited in place by draft-stream) and
+  // parks pieces[1..n] as follow-up messages. The draft-stream edit callback
+  // fires on EVERY throttled flush as a streamed answer grows, so we MUST NOT
+  // re-send those tails each tick (that flooded the chat with duplicates — the
+  // blocker this fix closes). Instead we remember each tail's message_id the
+  // first time it is emitted and edit it in place on later flushes; a tail that
+  // did not exist on a prior flush (the piece count grew) is sent fresh once.
+  // End state after finalize: anchor + one message per tail piece, no dupes.
+  const tailIds: number[] = []
+  const tailLastText: string[] = []
+
+  // Emit or update a single tail piece (0-based index `ti` = piece index - 1).
+  // Sends a fresh message the first time; edits in place (skipping unchanged
+  // text) thereafter. A non-parse failure is logged as a partial-delivery
+  // warning and swallowed so the remaining tail pieces still get a chance to
+  // land — never a silent drop, never an abort of pieces K..N (concern C1).
+  const upsertTail = async (ti: number, piece: { text: string; rich: boolean }): Promise<void> => {
+    const existingId = tailIds[ti]
+    if (existingId != null) {
+      if (tailLastText[ti] === piece.text) return // unchanged — skip the API call
+      try {
+        await retry(() => editPiece(existingId, piece, baseOpts), { threadId, chat_id: chatId })
+        tailLastText[ti] = piece.text
+        onEdit?.(existingId, piece.text.length)
+      } catch (err) {
+        if (!literalText && piece.rich && isParseEntitiesError(err)) {
+          warn?.(
+            `stream-controller: tail-piece #${ti + 1} edit parse-entities rejected — retrying same id=${existingId} as plain text (${err instanceof Error ? err.message : String(err)})`,
+          )
+          await retry(
+            () => bot.api.editMessageText(chatId, existingId, piece.text, baseOpts),
+            { threadId, chat_id: chatId },
+          )
+          tailLastText[ti] = piece.text
+          onEdit?.(existingId, piece.text.length)
+        } else {
+          // Best-effort continue: leave tailLastText[ti] stale so the next
+          // flush retries this piece, and surface the partial delivery loudly.
+          warn?.(
+            `stream-controller: tail-piece #${ti + 1} edit FAILED (id=${existingId}) — partial delivery, this piece may be stale (${err instanceof Error ? err.message : String(err)})`,
+          )
+        }
+      }
+      return
+    }
+    // First emission of this tail piece → a fresh follow-up message.
+    try {
+      const sent = await retry(() => sendPiece(piece, sendOpts), { threadId, chat_id: chatId })
+      tailIds[ti] = sent.message_id
+      tailLastText[ti] = piece.text
+      onSend?.(sent.message_id, piece.text.length)
+    } catch (err) {
+      if (!literalText && piece.rich && isParseEntitiesError(err)) {
+        warn?.(
+          `stream-controller: tail-piece #${ti + 1} send parse-entities rejected — sending as plain text (${err instanceof Error ? err.message : String(err)})`,
+        )
+        const sent = await retry(
+          () => bot.api.sendMessage(chatId, piece.text, sendOpts),
+          { threadId, chat_id: chatId },
+        )
+        tailIds[ti] = sent.message_id
+        tailLastText[ti] = piece.text
+        onSend?.(sent.message_id, piece.text.length)
+      } else {
+        // Best-effort continue: no id recorded, so the next flush re-attempts
+        // this piece rather than silently dropping pieces K..N (concern C1).
+        warn?.(
+          `stream-controller: tail-piece #${ti + 1} send FAILED — partial delivery, this and later pieces may be missing this flush (${err instanceof Error ? err.message : String(err)})`,
+        )
+      }
+    }
   }
 
   return createDraftStream(
     async (text) => {
+      // Render → 1+ cap-respecting pieces. The FIRST piece's message_id anchors
+      // the stream (later edits target it); any overflow pieces are parked as
+      // follow-up messages via upsertTail. For the common single-piece case
+      // this is exactly one send.
+      const pieces = renderPieces(text)
+      const head = pieces[0]
+      let anchorId: number | undefined
       try {
         const sent = await retry(
-          () => doSend(text, sendOpts),
+          () => sendPiece(head, sendOpts),
           { threadId, chat_id: chatId },
         )
-        onSend?.(sent.message_id, text.length)
-        return sent.message_id
+        anchorId = sent.message_id
       } catch (err) {
-        if (!literalText && isParseEntitiesError(err)) {
-          // First send rejected because the markdown couldn't be parsed.
-          // There is no message_id to edit (the send 400'd before any
-          // message was created), so a single fresh send as PLAIN text
-          // (no rich wrapper, so the parser never runs) is the correct
-          // recovery — see issue #657. The raw markdown source is itself
-          // readable, so we send it verbatim.
+        if (!literalText && head.rich && isParseEntitiesError(err)) {
+          // Piece rejected because its markdown couldn't be parsed. There is
+          // no message_id to edit (the send 400'd before any message was
+          // created), so recover with a single fresh PLAIN send of the same
+          // body (no rich wrapper, so the parser never runs) — see issue #657.
           warn?.(
             `stream-controller: send parse-entities rejected — retrying once as plain text (${err instanceof Error ? err.message : String(err)})`,
           )
+          // Resend the RAW source verbatim (readable, and the exact
+          // pre-existing #657 contract) rather than the escaped/rendered
+          // body. For a single-piece stream (the common case) this is the
+          // whole message; for a rare oversize split the head falls back to
+          // its own body and each tail to its own body below.
+          const fallbackBody = pieces.length === 1 ? text : head.text
           const sent = await retry(
-            () => bot.api.sendMessage(chatId, text, sendOpts),
+            () => bot.api.sendMessage(chatId, fallbackBody, sendOpts),
             { threadId, chat_id: chatId },
           )
-          onSend?.(sent.message_id, text.length)
-          return sent.message_id
+          anchorId = sent.message_id
+        } else {
+          throw err
         }
-        throw err
       }
+      // C2: report the ACTUAL emitted anchor-piece length, not the full body
+      // length — the anchor only holds the head piece, and the tails report
+      // their own lengths via upsertTail.
+      onSend?.(anchorId as number, head.text.length)
+      // Park overflow pieces (first-time send records their ids for reuse).
+      for (let pi = 1; pi < pieces.length; pi++) {
+        await upsertTail(pi - 1, pieces[pi])
+      }
+      return anchorId as number
     },
     async (id, text) => {
+      const pieces = renderPieces(text)
+      const head = pieces[0]
+      // Edit the anchor message in place with the FIRST piece.
       try {
         await retry(
-          () => doEdit(id, text, baseOpts),
+          () => editPiece(id, head, baseOpts),
           { threadId, chat_id: chatId },
         )
-        onEdit?.(id, text.length)
+        // C2: report the actual head-piece length, not the full body length.
+        onEdit?.(id, head.text.length)
       } catch (err) {
-        if (!literalText && isParseEntitiesError(err)) {
+        if (!literalText && head.rich && isParseEntitiesError(err)) {
           // Edit rejected because the markdown couldn't be parsed — DO NOT
           // send a fresh message. The whole point of issue #657 is that the
           // previous implementation sent a duplicate message every time a
           // parse rejection fired. Retry the edit on the SAME message_id as
-          // PLAIN text (no rich wrapper, so the parser never runs). The raw
-          // markdown source is itself readable, so we send it verbatim.
+          // PLAIN text (no rich wrapper, so the parser never runs).
           warn?.(
             `stream-controller: edit parse-entities rejected — retrying same id=${id} as plain text (${err instanceof Error ? err.message : String(err)})`,
           )
+          // Re-edit the SAME id with the RAW source verbatim (the exact #657
+          // contract). For a single-piece stream (common case) this is the
+          // whole body; a rare oversize split edits the head piece's body.
+          const fallbackBody = pieces.length === 1 ? text : head.text
           await retry(
-            () => bot.api.editMessageText(chatId, id, text, baseOpts),
+            () => bot.api.editMessageText(chatId, id, fallbackBody, baseOpts),
             { threadId, chat_id: chatId },
           )
-          onEdit?.(id, text.length)
-          return
+          onEdit?.(id, head.text.length)
+        } else {
+          throw err
         }
-        throw err
+      }
+      // Oversize tail: the anchor message holds only the first piece. On EVERY
+      // edit flush we UPDATE the parked tail messages in place (or send a tail
+      // that only just came into existence) — we never re-send tails already
+      // emitted on a prior flush. This is the fix for the duplicate-flood
+      // blocker: the previous code re-sent pieces[1..n] as brand-new messages
+      // on each throttled edit tick.
+      for (let pi = 1; pi < pieces.length; pi++) {
+        await upsertTail(pi - 1, pieces[pi])
       }
     },
     {

package/telegram-plugin/tests/activity-card-store.test.ts

@@ -30,6 +30,7 @@
  */
 import { describe, it, expect } from 'vitest'
 import {
+  BOOT_UNPIN_MAX_ATTEMPTS,
   loadActivityCards,
   persistActivityCards,
   writeActivityCardRecord,
@@ -314,9 +315,10 @@ describe('runActivityCardBootReaper — transport-boundary outcome tests', () =>
     expect(loadActivityCards(PATH, fs)).toEqual([])
   })
 
-  it('a failing unpin (already unpinned / no rights) is non-fatal and does not re-run the edit', async () => {
+  it('retry-safe (#3001): a failing unpin is non-fatal, does not re-run the edit, and RETAINS the record for a next-boot unpin retry', async () => {
     const { fs } = memFs()
-    writeActivityCardRecord(PATH, fs, card())
+    const rec = card()
+    writeActivityCardRecord(PATH, fs, rec)
     let editCalls = 0
     const res = await runActivityCardBootReaper({
       path: PATH,
@@ -328,9 +330,52 @@ describe('runActivityCardBootReaper — transport-boundary outcome tests', () =>
       unpinCard: async () => {
         throw new Error('message to unpin not found')
       },
+      log: () => {},
     })
     expect(res).toEqual({ finalized: 1, vanished: 0, unpinned: 0, total: 1 })
     expect(editCalls).toBe(1)
+    // The record is retained (not forfeited) so the next boot retries the
+    // idempotent unpin — flagged so it can never re-run the finalize edit.
+    expect(loadActivityCards(PATH, fs)).toEqual([
+      { ...rec, finalizeAttempted: true, unpinAttempts: 1 },
+    ])
+
+    // Second boot: the retained record retries ONLY the unpin (edit stays
+    // at-most-once); on success the record is finally dropped.
+    let secondBootEdits = 0
+    const res2 = await runActivityCardBootReaper({
+      path: PATH,
+      fs,
+      finalizeCard: async () => {
+        secondBootEdits++
+        return { ok: true }
+      },
+      unpinCard: async () => ({ ok: true }),
+      log: () => {},
+    })
+    expect(secondBootEdits).toBe(0)
+    expect(res2).toEqual({ finalized: 0, vanished: 0, unpinned: 1, total: 1 })
+    expect(loadActivityCards(PATH, fs)).toEqual([])
+  })
+
+  it('retry-safe (#3001): the unpin retry is forfeited at BOOT_UNPIN_MAX_ATTEMPTS', async () => {
+    const { fs } = memFs()
+    writeActivityCardRecord(
+      PATH,
+      fs,
+      card({ finalizeAttempted: true, unpinAttempts: BOOT_UNPIN_MAX_ATTEMPTS - 1 }),
+    )
+    const res = await runActivityCardBootReaper({
+      path: PATH,
+      fs,
+      finalizeCard: async () => ({ ok: true }),
+      unpinCard: async () => {
+        throw new Error('still no rights')
+      },
+      log: () => {},
+    })
+    // Final attempt failed — record forfeited so it cannot re-fail every boot.
+    expect(res).toEqual({ finalized: 0, vanished: 0, unpinned: 0, total: 1 })
     expect(loadActivityCards(PATH, fs)).toEqual([])
   })
 

package/telegram-plugin/tests/approval-card-restart-outcome.test.ts

@@ -0,0 +1,218 @@
+/**
+ * Outcome-based composition test for the approval/restart continuation
+ * contract in `reference/jobs/approve-what-my-agent-can-touch.md`:
+ *
+ *   - "An approval card survives a gateway restart. A tap on a still-valid
+ *      card after a restart works; a card that expired during the outage is
+ *      re-offered on the operator's return."
+ *   - "Cards time out (60-min default) and the timeout wakes the agent as a
+ *      timeout, not a denial ... An expired card is re-offered when the
+ *      operator returns."
+ *
+ * The sibling suites pin each module in isolation (pending-card-store.test.ts,
+ * pending-card-expiry.test.ts with mocked deps, approval-timeout-inbound-
+ * builders.test.ts) and pending-card-durability-wiring.test.ts pins the
+ * gateway wiring at the source-text level. This suite wires the REAL modules
+ * together — file-backed durable store + real missed-approvals store + real
+ * expiry sweep + real timeout builders — across a simulated gateway bounce
+ * (store re-instantiation from the same state dir), asserting the promised
+ * OUTCOMES rather than any one module's contract.
+ *
+ * SCOPE CAVEAT: the expiry predicate / remove / deliver / recordMiss closures
+ * below are TEST-SUPPLIED stand-ins for gateway.ts's inline closures (which
+ * close over module-level gateway state and can't be imported without a
+ * production refactor). This suite therefore proves the modules COMPOSE
+ * correctly; that gateway.ts actually wires them this way is pinned
+ * separately by pending-card-durability-wiring.test.ts's source greps. The
+ * user-visible acceptance twin is
+ * `uat/scenarios/vault-card-survives-gateway-restart-dm.test.ts`.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import {
+  createPendingCardStore,
+  type PersistedApprovalCard,
+  type PersistedVaultAccessCard,
+} from '../gateway/pending-card-store.js'
+import { createMissedApprovalsStore } from '../gateway/missed-approvals-store.js'
+import { expirePendingCard, sweepExpiredEntries } from '../gateway/pending-card-expiry.js'
+import { buildVaultAccessTimeoutInbound } from '../gateway/approval-timeout-inbound-builders.js'
+import type { InboundMessage } from '../gateway/ipc-protocol.js'
+
+// Test-local stand-in for the 60-min default the spec names. The production
+// TTL comes from approvalTtlMs() in gateway/permission-timeout.ts; this suite
+// does NOT assert that config plumbing — only how the modules behave around
+// whatever TTL the sweep predicate encodes.
+const TTL_MS = 60 * 60_000
+const NOW = 1_700_000_000_000
+
+function accessCard(overrides: Partial<PersistedVaultAccessCard> = {}): PersistedVaultAccessCard {
+  return {
+    family: 'vault_request_access',
+    stageId: 'stage-1',
+    agent: 'test-agent',
+    chatId: '12345',
+    cardMessageId: 777,
+    stagedAt: NOW - 60_000, // staged a minute ago — still valid
+    key: 'example/api-key',
+    scope: 'read',
+    ttlSeconds: 30 * 86_400,
+    ...overrides,
+  }
+}
+
+describe('approval/restart continuation — spec outcomes across a gateway bounce', () => {
+  let stateDir: string
+
+  beforeEach(() => {
+    stateDir = mkdtempSync(join(tmpdir(), 'approval-card-restart-outcome-'))
+  })
+  afterEach(() => {
+    rmSync(stateDir, { recursive: true, force: true })
+  })
+
+  it('a still-valid card record survives the bounce intact, and removing it clears the durable store', () => {
+    // Gateway process #1 stages the card.
+    const before = createPendingCardStore(stateDir)
+    const card = accessCard()
+    before.add(card)
+
+    // ── gateway restarts: all in-memory maps are gone ──
+    const after = createPendingCardStore(stateDir)
+    const restored = after.loadAll()
+    expect(restored).toHaveLength(1)
+    // Metadata roundtrips byte-identical — stagedAt included, so the expiry
+    // deadline the sweep computes from it is unchanged by the bounce.
+    expect(restored[0]).toEqual(card)
+
+    // Post-restart resolution path (what a tap handler does with the store):
+    // remove() drops the durable record so a later boot can't resurrect it.
+    // The tap handler's Telegram/grant side is NOT exercised here — that's
+    // the UAT twin's job.
+    after.remove(card.stageId)
+    expect(after.loadAll()).toHaveLength(0)
+  })
+
+  it('a card that expired during the outage wakes the agent ONCE as timeout-not-denial and records the re-offer', () => {
+    // Staged well past the TTL before the bounce.
+    const expired = accessCard({ stageId: 'stage-expired', stagedAt: NOW - TTL_MS - 60_000 })
+    createPendingCardStore(stateDir).add(expired)
+
+    // ── restart: restore into the in-memory map, then the reaper sweeps ──
+    const store = createPendingCardStore(stateDir)
+    const missed = createMissedApprovalsStore(stateDir)
+    const map = new Map<string, PersistedVaultAccessCard>(
+      store.loadAll().map(e => [e.stageId, e as PersistedVaultAccessCard]),
+    )
+    expect(map.size).toBe(1)
+
+    const delivered: InboundMessage[] = []
+    const sweep = () =>
+      sweepExpiredEntries(
+        map,
+        (v, now) => v.stagedAt < now - TTL_MS,
+        (stageId, v) => {
+          expirePendingCard({
+            remove: () => {
+              map.delete(stageId)
+              store.remove(stageId)
+            },
+            editCard: () => {},
+            buildInbound: () =>
+              buildVaultAccessTimeoutInbound({
+                agent: v.agent,
+                chatId: v.chatId,
+                stageId,
+                timeoutMinutes: Math.round(TTL_MS / 60_000),
+                nowMs: NOW,
+                key: v.key,
+                scope: v.scope,
+              }),
+            deliver: m => {
+              delivered.push(m)
+              return true
+            },
+            recordMiss: () =>
+              missed.add({
+                requestId: `approval-card:${stageId}`,
+                toolName: 'vault_request_access',
+                action: `vault access to ${v.key}`,
+                chatId: v.chatId,
+                timedOutAt: NOW,
+              }),
+            log: () => {},
+          })
+        },
+        NOW,
+        () => {},
+      )
+
+    sweep()
+
+    // Exactly one wake, and it is a TIMEOUT, never a denial.
+    expect(delivered).toHaveLength(1)
+    expect(delivered[0].text).toMatch(/TIMEOUT, not a denial/)
+    expect(delivered[0].text).toContain('example/api-key')
+    expect(delivered[0].meta?.source).toBe('vault_grant_timeout')
+
+    // The re-offer is durably recorded for the operator's return.
+    const pending = missed.listPending()
+    expect(pending).toHaveLength(1)
+    expect(pending[0].requestId).toBe('approval-card:stage-expired')
+
+    // Durable record is gone — a later boot can't resurrect the card.
+    expect(store.loadAll()).toHaveLength(0)
+
+    // A second boot's sweep restores from the (now empty) durable store and
+    // therefore fires nothing — the remove() step cleared BOTH the in-memory
+    // map and the store, so no later process can re-deliver the wake. (The
+    // intra-process single-shot ordering guarantee — remove() before any
+    // fallible side effect — is pinned behaviorally in
+    // pending-card-expiry.test.ts, not here.)
+    const rebootMap = new Map<string, PersistedVaultAccessCard>(
+      createPendingCardStore(stateDir)
+        .loadAll()
+        .map(e => [e.stageId, e as PersistedVaultAccessCard]),
+    )
+    expect(rebootMap.size).toBe(0)
+    let secondBootExpiries = 0
+    sweepExpiredEntries(
+      rebootMap,
+      (v, now) => v.stagedAt < now - TTL_MS,
+      () => {
+        secondBootExpiries += 1
+      },
+      NOW,
+      () => {},
+    )
+    expect(secondBootExpiries).toBe(0)
+    expect(delivered).toHaveLength(1)
+  })
+
+  it('the post-restart sweep never expires a still-valid card (no false timeout on bounce)', () => {
+    const valid = accessCard({ stageId: 'stage-valid', stagedAt: NOW - 60_000 })
+    createPendingCardStore(stateDir).add(valid)
+
+    const store = createPendingCardStore(stateDir)
+    const map = new Map<string, PersistedApprovalCard>(store.loadAll().map(e => [e.stageId, e]))
+
+    let expiredCount = 0
+    sweepExpiredEntries(
+      map,
+      (v, now) => v.stagedAt < now - TTL_MS,
+      () => {
+        expiredCount += 1
+      },
+      NOW,
+      () => {},
+    )
+
+    expect(expiredCount).toBe(0)
+    expect(map.size).toBe(1) // the card stays live and tappable
+    expect(store.loadAll()).toHaveLength(1)
+  })
+})

package/telegram-plugin/tests/boot-card-flood-suppress.test.ts

@@ -0,0 +1,111 @@
+/**
+ * #2923 — boot-card flood-wait suppression. When a Telegram per-bot flood ban
+ * is active, a restart's boot card is a NON-ESSENTIAL send straight into the
+ * open window that can reset/extend the ban. startBootCard must SKIP the send
+ * (and log) while the flood-wait is active, and post normally once it lifts.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { startBootCard } from '../gateway/boot-card.js'
+import type { BotApiForBootCard } from '../gateway/boot-card.js'
+import { computeFloodWait, writeFloodState, floodStatePath, makeFloodWaitRecorder } from '../flood-circuit-breaker.js'
+import { createRetryApiCall } from '../retry-api-call.js'
+import { errors } from './fake-bot-api.js'
+
+let dir: string
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'boot-card-flood-'))
+})
+afterEach(() => rmSync(dir, { recursive: true, force: true }))
+
+function makeBot() {
+  const sends: string[] = []
+  const bot: BotApiForBootCard = {
+    sendMessage: async (chatId, _text, _opts) => {
+      sends.push(chatId)
+      return { message_id: 1001 }
+    },
+    editMessageText: async () => ({}),
+  }
+  return { bot, sends }
+}
+
+function mkOpts(floodPath: string, nowMs: number, overrides: Record<string, unknown> = {}) {
+  return {
+    agentName: 'TestAgent',
+    agentSlug: 'test-agent',
+    version: 'v0.0.0-test',
+    agentDir: dir,
+    gatewayInfo: { pid: 1, startedAtMs: nowMs },
+    restartReason: 'graceful' as const,
+    agentLiveWindowMs: 0,
+    settleWindowMs: 1_000_000,
+    floodStatePath: floodPath,
+    nowMs: () => nowMs,
+    ...overrides,
+  } as unknown as Parameters<typeof startBootCard>[3]
+}
+
+it('SUPPRESSES the boot card while a flood-wait is active', async () => {
+  const p = floodStatePath(dir)
+  const now = 1_000_000
+  writeFloodState(p, computeFloodWait(null, 68 * 60, now)) // ~68 min ban
+  const logs: string[] = []
+  const { bot, sends } = makeBot()
+  const handle = await startBootCard('chat1', undefined, bot, mkOpts(p, now), undefined, (l) =>
+    logs.push(l),
+  )
+  expect(sends).toEqual([]) // nothing sent into the open ban window
+  expect(handle.messageId).toBe(-1)
+  expect(logs.join('')).toMatch(/SUPPRESSED/)
+})
+
+it('POSTS the boot card once the flood-wait has lifted', async () => {
+  const p = floodStatePath(dir)
+  const banStart = 1_000_000
+  writeFloodState(p, computeFloodWait(null, 60, banStart))
+  const afterBan = banStart + 60_000 + 1
+  const { bot, sends } = makeBot()
+  await startBootCard('chat1', undefined, bot, mkOpts(p, afterBan), undefined, () => {})
+  expect(sends).toEqual(['chat1'])
+})
+
+it('POSTS normally when no flood state file exists (back-compat)', async () => {
+  const p = floodStatePath(dir) // never written
+  const { bot, sends } = makeBot()
+  await startBootCard('chat1', undefined, bot, mkOpts(p, 1_000_000), undefined, () => {})
+  expect(sends).toEqual(['chat1'])
+})
+
+it('INTEGRATION: a 429 through the real retry path suppresses a later boot card', async () => {
+  // Wire the two halves exactly as gateway.ts does: the retry wrapper's
+  // onFloodWait recorder and the boot card BOTH point at the same file.
+  const p = floodStatePath(dir)
+  const now = 5_000_000
+  const retry = createRetryApiCall({
+    sleep: async () => {}, // don't actually wait out the flood
+    onFloodWait: makeFloodWaitRecorder(p, () => now),
+  })
+
+  // Drive a real GrammyError 429 through the wrapper (first call floods, then
+  // succeeds) — this is what records the window on disk.
+  let n = 0
+  await retry(async () => {
+    if (n++ === 0) throw errors.floodWait(4116) // ~68 min ban
+    return 'ok'
+  })
+
+  // Now a restart's boot card must be suppressed via the SAME file.
+  const { bot, sends } = makeBot()
+  const logs: string[] = []
+  const handle = await startBootCard('chat1', undefined, bot, mkOpts(p, now), undefined, (l) =>
+    logs.push(l),
+  )
+  expect(sends).toEqual([]) // not posted into the open ban window
+  expect(handle.messageId).toBe(-1)
+  expect(logs.join('')).toMatch(/SUPPRESSED/)
+})