switchroom 0.18.11 → 0.18.12

package/telegram-plugin/tests/dispatch-claim-scan.test.ts

@@ -0,0 +1,250 @@
+/**
+ * Tests for the #396 dispatch-claim Stop-hook scan logic — the pure
+ * `dispatch-claim-scan.mjs` helpers (mirrors the silent-end-scan test
+ * style: synthetic JSONL fixtures against a pure function rather than
+ * spawning the .mjs subprocess).
+ *
+ * The defect: a reply that TELLS the user work was dispatched
+ * ("Dispatching a worker now") while the turn contains no Agent/Task call
+ * and no backgrounded Bash. These assert OUTCOMES (block vs allow), not
+ * code paths.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  scanTurnForDispatchClaim,
+  replyClaimsDispatch,
+  applyRetryBudget,
+  turnSignature,
+} from '../hooks/dispatch-claim-scan.mjs'
+
+// ── Fixture builders ────────────────────────────────────────────────
+
+const REPLY = 'mcp__switchroom-telegram__reply'
+
+const ENQUEUE = JSON.stringify({
+  type: 'queue-operation',
+  operation: 'enqueue',
+  content: '<channel source="switchroom-telegram" chat_id="111" message_id="42">fix the bug</channel>',
+})
+
+function assistantToolUse(
+  name: string,
+  input: Record<string, unknown>,
+  opts: { isSidechain?: boolean } = {},
+) {
+  const base: Record<string, unknown> = {
+    type: 'assistant',
+    message: { content: [{ type: 'tool_use', name, input }] },
+  }
+  if (opts.isSidechain) base.isSidechain = true
+  return JSON.stringify(base)
+}
+
+function reply(text: string, opts: { isSidechain?: boolean } = {}) {
+  return assistantToolUse(REPLY, { text, chat_id: '111' }, opts)
+}
+
+function jsonl(...lines: string[]) {
+  return lines.join('\n')
+}
+
+// ── (a) claim + no dispatch tool_use → block ────────────────────────
+
+describe('scanTurnForDispatchClaim — narrate-without-execute', () => {
+  it('(a) blocks a dispatch claim with no Agent/Task call in the turn', () => {
+    const t = jsonl(ENQUEUE, reply('Dispatching a worker now to fix this bug.'))
+    const d = scanTurnForDispatchClaim(t)
+    expect(d.decided).toBe('block')
+    expect(d.reason).toBe('claim-without-dispatch')
+    expect(d.turnSig).toBeTruthy()
+  })
+
+  // ── (b) claim + Agent tool_use in turn → allow ────────────────────
+  it('(b) allows when the turn actually dispatched an Agent', () => {
+    const t = jsonl(
+      ENQUEUE,
+      reply('Dispatching a worker now to fix this bug.'),
+      assistantToolUse('Agent', { subagent_type: 'worker', description: 'fix bug' }),
+    )
+    const d = scanTurnForDispatchClaim(t)
+    expect(d.decided).toBe('allow')
+    expect(d.reason).toBe('dispatched')
+  })
+
+  it('(b2) allows when the dispatch tool is the newer Task name', () => {
+    const t = jsonl(
+      ENQUEUE,
+      reply('Spinning up a researcher to dig into this.'),
+      assistantToolUse('Task', { subagent_type: 'researcher' }),
+    )
+    expect(scanTurnForDispatchClaim(t).decided).toBe('allow')
+  })
+
+  // ── (c) claim + backgrounded Bash → allow ─────────────────────────
+  it('(c) allows when the turn launched a backgrounded Bash', () => {
+    const t = jsonl(
+      ENQUEUE,
+      reply('Kicking off the build agent in the background.'),
+      assistantToolUse('Bash', { command: 'npm run build', run_in_background: true }),
+    )
+    const d = scanTurnForDispatchClaim(t)
+    expect(d.decided).toBe('allow')
+    expect(d.reason).toBe('dispatched')
+  })
+
+  it('(c2) a FOREGROUND Bash does not count as a dispatch', () => {
+    const t = jsonl(
+      ENQUEUE,
+      reply('Dispatching a worker to handle this.'),
+      assistantToolUse('Bash', { command: 'ls', run_in_background: false }),
+    )
+    expect(scanTurnForDispatchClaim(t).decided).toBe('block')
+  })
+
+  // ── (d) conditional offer → allow ─────────────────────────────────
+  it('(d) allows a conditional offer to dispatch (question)', () => {
+    const t = jsonl(ENQUEUE, reply('Want me to dispatch a worker to fix this?'))
+    const d = scanTurnForDispatchClaim(t)
+    expect(d.decided).toBe('allow')
+    expect(d.reason).toBe('no-claim')
+  })
+
+  it('(d2) allows a conditional "I could spin up a reviewer if you like"', () => {
+    const t = jsonl(ENQUEUE, reply('I could spin up a reviewer if you want me to.'))
+    expect(scanTurnForDispatchClaim(t).decided).toBe('allow')
+  })
+
+  // ── (e) non-dispatch reply → allow ────────────────────────────────
+  it('(e) allows an ordinary non-dispatch reply', () => {
+    const t = jsonl(ENQUEUE, reply('Here is the answer: the bug is a null deref on line 12.'))
+    const d = scanTurnForDispatchClaim(t)
+    expect(d.decided).toBe('allow')
+    expect(d.reason).toBe('no-claim')
+  })
+
+  // ── (f) NO_REPLY-only turn → allow ────────────────────────────────
+  it('(f) allows a NO_REPLY-only turn', () => {
+    const t = jsonl(ENQUEUE, reply('NO_REPLY'))
+    expect(scanTurnForDispatchClaim(t).decided).toBe('allow')
+  })
+
+  // ── (g) sidechain lines ───────────────────────────────────────────
+  it('(g) sidechain Agent lines do NOT count as the parent dispatching', () => {
+    // A sub-agent's own Agent tool_use leaks in with isSidechain — it must
+    // not satisfy the PARENT's dispatch obligation. Parent reply claims a
+    // dispatch, parent itself dispatched nothing → block.
+    const t = jsonl(
+      ENQUEUE,
+      reply('Dispatching a worker now.'),
+      assistantToolUse('Agent', { subagent_type: 'worker' }, { isSidechain: true }),
+    )
+    expect(scanTurnForDispatchClaim(t).decided).toBe('block')
+  })
+
+  it('(g2) sidechain replies do NOT count as the parent making a claim', () => {
+    // A sub-agent's own reply narrating a dispatch leaks in with
+    // isSidechain; the parent made no claim → allow.
+    const t = jsonl(
+      ENQUEUE,
+      reply('Working on the fix directly.'),
+      reply('Dispatching a worker to handle the subtask.', { isSidechain: true }),
+    )
+    const d = scanTurnForDispatchClaim(t)
+    expect(d.decided).toBe('allow')
+    expect(d.reason).toBe('no-claim')
+  })
+
+  // ── (i) malformed / missing transcript → allow (fail-open) ────────
+  it('(i) fails open on an empty transcript', () => {
+    expect(scanTurnForDispatchClaim('').decided).toBe('unknown')
+  })
+
+  it('(i2) fails open when no turn-start anchor is present', () => {
+    const t = jsonl(reply('Dispatching a worker now.'))
+    expect(scanTurnForDispatchClaim(t).decided).toBe('unknown')
+  })
+
+  it('(i3) tolerates malformed JSONL lines mixed in', () => {
+    const t = jsonl(ENQUEUE, '{ not valid json', reply('Dispatching a worker now.'))
+    const d = scanTurnForDispatchClaim(t)
+    expect(d.decided).toBe('block')
+  })
+
+  // ── past-tense reference (registry-check substitute) ──────────────
+  it('does NOT block a bare past-tense reference to an earlier dispatch', () => {
+    const t = jsonl(
+      ENQUEUE,
+      reply('The worker I dispatched earlier finished; here are its results.'),
+    )
+    const d = scanTurnForDispatchClaim(t)
+    expect(d.decided).toBe('allow')
+    expect(d.reason).toBe('no-claim')
+  })
+})
+
+// ── replyClaimsDispatch unit coverage ───────────────────────────────
+
+describe('replyClaimsDispatch', () => {
+  it('matches present/progressive commitments', () => {
+    expect(replyClaimsDispatch('Dispatching a worker now.')).toBe(true)
+    expect(replyClaimsDispatch("I'll dispatch a reviewer to check this.")).toBe(true)
+    expect(replyClaimsDispatch('Spinning up a sub-agent for the research.')).toBe(true)
+    expect(replyClaimsDispatch('Kicking off a worker on that task.')).toBe(true)
+    expect(replyClaimsDispatch('Delegating this to a researcher.')).toBe(true)
+  })
+
+  it('excludes interrogative / conditional sentences', () => {
+    expect(replyClaimsDispatch('Want me to dispatch a worker?')).toBe(false)
+    expect(replyClaimsDispatch('I could dispatch a reviewer if you like.')).toBe(false)
+    expect(replyClaimsDispatch('Should I spin up a worker for this?')).toBe(false)
+  })
+
+  it('excludes pure past-tense references', () => {
+    expect(replyClaimsDispatch('The worker I dispatched earlier is done.')).toBe(false)
+    expect(replyClaimsDispatch('I launched a reviewer last turn.')).toBe(false)
+  })
+
+  it('ignores unrelated prose and bare silent markers', () => {
+    expect(replyClaimsDispatch('The fix is a null-deref guard on line 12.')).toBe(false)
+    expect(replyClaimsDispatch('NO_REPLY')).toBe(false)
+    expect(replyClaimsDispatch('')).toBe(false)
+  })
+
+  it('scopes conditional exclusion to the sentence carrying the verb', () => {
+    // First sentence is a real commitment; a later unrelated question must
+    // not amnesty it.
+    expect(
+      replyClaimsDispatch('Dispatching a worker now. Anything else you need?'),
+    ).toBe(true)
+  })
+})
+
+// ── (h) retry budget: exactly one re-prompt per turn ────────────────
+
+describe('applyRetryBudget — exactly one re-prompt per turn', () => {
+  const sig = turnSignature(ENQUEUE)
+
+  it('(h) blocks on the first Stop, then fails open on the second same-turn Stop', () => {
+    const first = applyRetryBudget({}, sig, 1)
+    expect(first.block).toBe(true)
+    expect(first.nextState?.retryCount).toBe(1)
+    expect(first.nextState?.turnSig).toBe(sig)
+
+    // Second Stop fire on the SAME turn reads back the persisted state.
+    const second = applyRetryBudget(first.nextState, sig, 1)
+    expect(second.block).toBe(false)
+  })
+
+  it('resets the budget for a genuinely new turn (different signature)', () => {
+    const spent = { turnSig: sig, retryCount: 1 }
+    const newTurn = applyRetryBudget(spent, turnSignature('a different inbound'), 1)
+    expect(newTurn.block).toBe(true)
+    expect(newTurn.nextState?.retryCount).toBe(1)
+  })
+
+  it('tolerates a null / corrupt prior state', () => {
+    expect(applyRetryBudget(null, sig, 1).block).toBe(true)
+    expect(applyRetryBudget(undefined, sig, 1).block).toBe(true)
+  })
+})

package/telegram-plugin/tests/flood-breaker-blindness.test.ts

@@ -0,0 +1,213 @@
+/**
+ * #3106 — a permissions error must not silently blind the flood breaker.
+ *
+ * The bug: `readFloodState` swallowed EVERY error and returned `null`, so an
+ * unreadable marker (EACCES) was indistinguishable from "no marker" — the
+ * probe reported "no flood window" forever and every flood protection we ship
+ * (#2923 boot-card suppression, #3084/#3094 pre-call short-circuit, #3097
+ * typing suppression) failed open SILENTLY. A restart would then post a boot
+ * card straight into an open ban.
+ *
+ * Two behaviours pull in OPPOSITE directions and both are pinned here:
+ *
+ *   - ABSENT / CORRUPT marker → still fails OPEN everywhere. A junk state file
+ *     must never become a silent gag (#3094's deliberate posture).
+ *   - UNREADABLE marker → the breaker is BLIND. Essential sends still proceed
+ *     (fail-open, so a chmod accident can never mute the agent), but it says so
+ *     LOUDLY, and non-essential sends (boot card, typing) are held back rather
+ *     than fired into a ban we cannot rule out.
+ *
+ * All paths are under `mkdtempSync(join(tmpdir(), …))` — no production state.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import {
+  mkdtempSync,
+  rmSync,
+  writeFileSync,
+  readFileSync,
+  chmodSync,
+  mkdirSync,
+  statSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  computeFloodWait,
+  writeFloodState,
+  readFloodStateResult,
+  makeFloodWaitProbe,
+  makeFloodWaitRecorder,
+  suppressNonEssentialSendMs,
+  nonEssentialSendSuppression,
+  resetFloodBlindLogThrottle,
+  floodStatePath,
+  FLOOD_STATE_MODE,
+} from '../flood-circuit-breaker.js'
+
+const NOW = 1_800_000_000_000
+const isRoot = typeof process.getuid === 'function' && process.getuid() === 0
+
+/**
+ * Make `path` genuinely unreadable to THIS process and prove it. Returns false
+ * when the process is root (root bypasses DAC — EACCES is unreachable), so the
+ * caller can skip rather than assert a lie.
+ */
+function makeUnreadable(path: string): boolean {
+  writeFileSync(path, JSON.stringify({ untilTs: NOW + 60_000, retryAfterSec: 60, recordedTs: NOW }))
+  chmodSync(path, 0o000)
+  if (isRoot) return false
+  try {
+    readFileSync(path, 'utf-8')
+    return false // somehow still readable — don't pretend we tested EACCES
+  } catch {
+    return true
+  }
+}
+
+describe('#3106 flood breaker — blind is not clear', () => {
+  let dir: string
+  let path: string
+  let logs: string[]
+  const log = (l: string) => {
+    logs.push(l)
+  }
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'flood-blind-'))
+    path = floodStatePath(dir)
+    logs = []
+    resetFloodBlindLogThrottle()
+  })
+  afterEach(() => {
+    try {
+      chmodSync(path, 0o644)
+    } catch {
+      /* may not exist */
+    }
+    rmSync(dir, { recursive: true, force: true })
+  })
+
+  // ---------------------------------------------------------------- classify
+
+  it('classifies absent / corrupt / unreadable as DIFFERENT things', () => {
+    expect(readFloodStateResult(path).status).toBe('absent')
+
+    writeFileSync(path, 'not json at all{{{')
+    expect(readFloodStateResult(path).status).toBe('corrupt')
+
+    writeFileSync(path, JSON.stringify({ untilTs: 'soon' }))
+    expect(readFloodStateResult(path).status).toBe('corrupt')
+
+    // A directory where the marker should be: readable-check fails with EISDIR,
+    // not ENOENT. uid-independent (works even under root) — "cannot read".
+    const d = join(dir, 'as-a-dir.json')
+    mkdirSync(d)
+    expect(readFloodStateResult(d).status).toBe('unreadable')
+  })
+
+  // ------------------------------------------------- UNREADABLE → not silent
+
+  it.skipIf(isRoot)(
+    'REGRESSION: an unreadable marker does NOT silently report "no flood window"',
+    () => {
+      expect(makeUnreadable(path)).toBe(true)
+
+      const res = readFloodStateResult(path)
+      // The bug was: status indistinguishable from absent, state null, nobody told.
+      expect(res.status).toBe('unreadable')
+      expect(res.error).toMatch(/EACCES/)
+
+      // The probe still FAILS OPEN (0 = proceed) — an essential reply to the
+      // user must never be gagged by a permissions error...
+      const probe = makeFloodWaitProbe(path, () => NOW, log)
+      expect(probe()).toBe(0)
+
+      // ...but it is no longer SILENT. That is the whole fix.
+      expect(logs.join('')).toMatch(/BLIND/)
+      expect(logs.join('')).toContain(path)
+    },
+  )
+
+  it.skipIf(isRoot)('an unreadable marker SUPPRESSES non-essential sends (boot card, typing)', () => {
+    expect(makeUnreadable(path)).toBe(true)
+
+    // The #2923/#3097 surfaces: we cannot rule out an open ban, so we do not
+    // post a restart card / typing ping into one.
+    expect(suppressNonEssentialSendMs(path, NOW, log)).toBeGreaterThan(0)
+    expect(logs.join('')).toMatch(/BLIND/)
+
+    const s = nonEssentialSendSuppression(path, NOW)
+    expect(s.suppress).toBe(true)
+    expect(s.suppress && s.reason).toBe('blind')
+  })
+
+  it.skipIf(isRoot)('the BLIND warning is throttled — a per-call probe cannot spam the log', () => {
+    expect(makeUnreadable(path)).toBe(true)
+    let t = NOW
+    const probe = makeFloodWaitProbe(path, () => t, log)
+    for (let i = 0; i < 50; i++) probe()
+    expect(logs.length).toBe(1)
+    t = NOW + 61_000
+    probe()
+    expect(logs.length).toBe(2)
+  })
+
+  // --------------------------------------------- ABSENT / CORRUPT → fail OPEN
+
+  it('an ABSENT marker fails OPEN and stays silent (no ban, nothing to say)', () => {
+    const probe = makeFloodWaitProbe(path, () => NOW, log)
+    expect(probe()).toBe(0)
+    expect(suppressNonEssentialSendMs(path, NOW, log)).toBe(0)
+    expect(nonEssentialSendSuppression(path, NOW).suppress).toBe(false)
+    expect(logs.join('')).not.toMatch(/BLIND/)
+  })
+
+  it('a CORRUPT marker still fails OPEN — a junk file must never gag the bot', () => {
+    for (const junk of ['', 'null', '{}', 'not json{{', JSON.stringify({ untilTs: 'x' })]) {
+      writeFileSync(path, junk)
+      const probe = makeFloodWaitProbe(path, () => NOW, log)
+      expect(probe()).toBe(0)
+      // Non-essential sends proceed too: corrupt is a CONTENT problem, and we
+      // deliberately do NOT let it suppress. (Contrast: unreadable, above.)
+      expect(suppressNonEssentialSendMs(path, NOW, log)).toBe(0)
+      expect(nonEssentialSendSuppression(path, NOW).suppress).toBe(false)
+    }
+  })
+
+  it('a REAL open window still suppresses (the #2923 behaviour is intact)', () => {
+    writeFloodState(path, computeFloodWait(null, 68 * 60, NOW), log)
+    const probe = makeFloodWaitProbe(path, () => NOW, log)
+    expect(probe()).toBe(68 * 60 * 1000)
+    const s = nonEssentialSendSuppression(path, NOW)
+    expect(s.suppress && s.reason).toBe('flood_wait')
+    // ...and lifts on its own.
+    expect(makeFloodWaitProbe(path, () => NOW + 68 * 60_000 + 1, log)()).toBe(0)
+  })
+
+  // ------------------------------------------------------- root cause: 0600
+
+  it('ROOT CAUSE: the marker is written 0644, readable by a sibling uid', () => {
+    writeFloodState(path, computeFloodWait(null, 60, NOW), log)
+    expect(statSync(path).mode & 0o777).toBe(FLOOD_STATE_MODE)
+    // Group/other read bits set — the whole point. At 0600 a marker created by
+    // a root gateway (`compose.ts:1967`, `root: true` agents) is unreadable to
+    // the same agent's non-root gateway forever.
+    expect(statSync(path).mode & 0o044).toBe(0o044)
+  })
+
+  it('SELF-HEAL: a pre-existing 0600 marker is chmodded back to 0644 on write', () => {
+    // Simulate the live overlord marker: created 0600 by an earlier build.
+    writeFileSync(path, JSON.stringify({ untilTs: NOW, retryAfterSec: 1, recordedTs: NOW }), {
+      mode: 0o600,
+    })
+    chmodSync(path, 0o600)
+    expect(statSync(path).mode & 0o777).toBe(0o600)
+
+    // The next observed 429 rewrites it — and heals the mode. (writeFileSync's
+    // `mode` option is ignored for an EXISTING file, so the explicit chmod is
+    // load-bearing.)
+    makeFloodWaitRecorder(path, () => NOW, log)(120)
+    expect(statSync(path).mode & 0o777).toBe(FLOOD_STATE_MODE)
+    expect(readFloodStateResult(path).status).toBe('ok')
+  })
+})

package/telegram-plugin/tests/flood-windows-persistence.test.ts

@@ -0,0 +1,224 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync, existsSync, statSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  readFloodWindows,
+  writeFloodWindow,
+  makeFloodWindowRecorder,
+  loadInitialFloodWindows,
+  floodWindowsPath,
+  floodStatePath,
+  writeFloodState,
+  computeFloodWait,
+  FLOOD_STATE_MODE,
+  FLOOD_WINDOWS_CORRUPT_SUPPRESS_MS,
+} from '../flood-circuit-breaker.js'
+import { createSendGate, type Clock } from '../send-gate.js'
+
+/**
+ * #3084 PR 2 — restart-proof SCOPED flood windows (part3-design §7). Verifies
+ * the write-through/round-trip contract on real temp files (isolated per the
+ * repo's vault/shared-state test discipline) and that a gate reconstructed from
+ * disk is STILL blocked — the whole point of §7 (a boot mid-ban must not resend
+ * into the open window).
+ */
+describe('#3084 scoped flood-window persistence', () => {
+  let dir: string
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'flood-win-'))
+  })
+  afterEach(() => rmSync(dir, { recursive: true, force: true }))
+
+  it('round-trips a scoped window and prunes expired entries', () => {
+    const path = floodWindowsPath(dir)
+    const now = 1_000_000
+    writeFloodWindow(path, { scopeKey: 'chat:5', untilTs: now + 60_000, retryAfterSrc: '429', observedAt: now }, now)
+    writeFloodWindow(path, { scopeKey: 'global', untilTs: now + 10_000, retryAfterSrc: '429', observedAt: now }, now)
+
+    // Before either expires: both present.
+    const live = readFloodWindows(path, now + 5_000)
+    expect(live.map((w) => w.scopeKey).sort()).toEqual(['chat:5', 'global'])
+
+    // After the global one expires: only chat:5 survives (prune-on-read).
+    const later = readFloodWindows(path, now + 20_000)
+    expect(later.map((w) => w.scopeKey)).toEqual(['chat:5'])
+  })
+
+  it('EXTENDS never shortens a window on a later, shorter re-record (boot-never-shortens)', () => {
+    const path = floodWindowsPath(dir)
+    const now = 1_000_000
+    // A long ban is recorded.
+    writeFloodWindow(path, { scopeKey: 'global', untilTs: now + 600_000, retryAfterSrc: '429', observedAt: now }, now)
+    // A later, SHORTER 429 (or a restart re-observing a smaller retry_after)
+    // must not pull the expiry earlier.
+    writeFloodWindow(
+      path,
+      { scopeKey: 'global', untilTs: now + 1_000 + 5_000, retryAfterSrc: '429', observedAt: now + 1_000 },
+      now + 1_000,
+    )
+    const w = readFloodWindows(path, now + 2_000).find((x) => x.scopeKey === 'global')
+    expect(w?.untilTs).toBe(now + 600_000)
+  })
+
+  it('loadInitialFloodWindows combines the global flood-wait.json window with scoped windows', () => {
+    const now = 1_000_000
+    const statePath = floodStatePath(dir)
+    const winPath = floodWindowsPath(dir)
+    writeFloodState(statePath, computeFloodWait(null, 300, now)) // global, +300s
+    writeFloodWindow(winPath, { scopeKey: 'chat:9', untilTs: now + 120_000, retryAfterSrc: '429', observedAt: now }, now)
+
+    const initial = loadInitialFloodWindows(statePath, winPath, now)
+    const scopes = initial.map((w) => w.scopeKey).sort()
+    expect(scopes).toEqual(['chat:9', 'global'])
+    expect(initial.find((w) => w.scopeKey === 'global')?.untilTs).toBe(now + 300_000)
+  })
+
+  it('gate opens a window on a 429 → persists → a NEW gate built from disk is still blocked', async () => {
+    const winPath = floodWindowsPath(dir)
+    const statePath = floodStatePath(dir)
+    const recorder = makeFloodWindowRecorder(winPath, () => 0)
+
+    // Gate 1: a critical send hits a 429 (FLOOD_WAIT_ACTIVE) which opens +
+    // persists scope windows via onWindowOpen.
+    const clock1: Clock = { now: () => 0, sleep: () => Promise.resolve() }
+    const gate1 = createSendGate({
+      enabled: true,
+      clock: clock1,
+      onWindowOpen: (scopeKey, untilTs) => recorder(scopeKey, untilTs),
+    })
+    const floodErr = Object.assign(new Error('FLOOD_WAIT_ACTIVE'), {
+      retryAfterSec: 600,
+      untilTs: 600_000,
+      error_code: 429 as const,
+      parameters: { retry_after: 600 },
+      original: null,
+    })
+    await expect(
+      gate1.gate(
+        async () => {
+          throw floodErr
+        },
+        { chat_id: '7', priorityClass: 'critical' },
+      ),
+    ).rejects.toBe(floodErr)
+
+    // The window is on disk.
+    const persisted = readFloodWindows(winPath, 0)
+    expect(persisted.map((w) => w.scopeKey).sort()).toEqual(['chat:7', 'global'])
+
+    // Gate 2 (simulated restart): built BEFORE any outbound call from the
+    // persisted windows. A cosmetic send on chat:7 must still shed.
+    const clock2: Clock = { now: () => 0, sleep: () => Promise.resolve() }
+    const gate2 = createSendGate({
+      enabled: true,
+      clock: clock2,
+      initialWindows: loadInitialFloodWindows(statePath, winPath, 0),
+    })
+    const res = await gate2.gate(async () => 'should-not-run', {
+      chat_id: '7',
+      priorityClass: 'cosmetic',
+    })
+    expect(res).toBeUndefined()
+    expect(gate2.stats().global.shed).toBe(1)
+
+    // And a critical into the still-long window fails fast — restart did not
+    // reset the ban.
+    await expect(
+      gate2.gate(async () => 'nope', { chat_id: '7', priorityClass: 'critical' }),
+    ).rejects.toThrow('FLOOD_WAIT_ACTIVE')
+  })
+
+  it('H2: writes flood-windows.json world-READABLE (0o644), not 0o600', () => {
+    // A 0o600 marker is unreadable to a gateway running under a DIFFERENT uid
+    // (root vs agent uid share the state dir), which silently defeats the
+    // restart-proof windows — a restart under the other uid boots blind and
+    // resends into the ban. Must match `flood-wait.json` (FLOOD_STATE_MODE).
+    const path = floodWindowsPath(dir)
+    const now = 2_000_000
+    writeFloodWindow(path, { scopeKey: 'global', untilTs: now + 60_000, retryAfterSrc: '429', observedAt: now }, now)
+    expect(statSync(path).mode & 0o777).toBe(FLOOD_STATE_MODE)
+    expect(FLOOD_STATE_MODE).toBe(0o644)
+  })
+
+  it('M1: a CORRUPT flood-windows.json fails SAFE (conservative global window), not open', () => {
+    const path = floodWindowsPath(dir)
+    const now = 3_000_000
+    writeFileSync(path, '{ this is not valid json ][', 'utf-8')
+    const logs: string[] = []
+    const windows = readFloodWindows(path, now, (l) => logs.push(l))
+    // NOT [] (fail-open) — a bounded conservative global window instead.
+    expect(windows).toHaveLength(1)
+    expect(windows[0]!.scopeKey).toBe('global')
+    expect(windows[0]!.untilTs).toBe(now + FLOOD_WINDOWS_CORRUPT_SUPPRESS_MS)
+    // Logged loudly.
+    expect(logs.join('')).toMatch(/failing SAFE/)
+  })
+
+  it('M1: a non-array flood-windows.json fails SAFE', () => {
+    const path = floodWindowsPath(dir)
+    const now = 3_500_000
+    writeFileSync(path, '{"scopeKey":"global"}', 'utf-8') // object, not array
+    const windows = readFloodWindows(path, now, () => {})
+    expect(windows).toEqual([
+      {
+        scopeKey: 'global',
+        untilTs: now + FLOOD_WINDOWS_CORRUPT_SUPPRESS_MS,
+        retryAfterSrc: expect.stringContaining('failsafe'),
+        observedAt: now,
+      },
+    ])
+  })
+
+  it('M1: an UNREADABLE flood-windows.json (read error, not ENOENT) fails SAFE', () => {
+    // Root bypasses file-mode EACCES, so simulate a non-ENOENT read failure
+    // deterministically by making the windows path a DIRECTORY — readFileSync
+    // throws EISDIR, the same "file exists but I can't read it" class as EACCES.
+    const path = floodWindowsPath(dir)
+    const now = 4_000_000
+    mkdirSync(path)
+    const logs: string[] = []
+    const windows = readFloodWindows(path, now, (l) => logs.push(l))
+    expect(windows).toHaveLength(1)
+    expect(windows[0]!.scopeKey).toBe('global')
+    expect(windows[0]!.untilTs).toBe(now + FLOOD_WINDOWS_CORRUPT_SUPPRESS_MS)
+    expect(logs.join('')).toMatch(/unreadable/)
+  })
+
+  it('M1: a genuinely ABSENT file is still "no windows" (ENOENT ≠ corrupt)', () => {
+    const path = floodWindowsPath(dir) // never written
+    expect(readFloodWindows(path, 5_000_000, () => {})).toEqual([])
+  })
+
+  it('M3: flag-OFF gate opens NO window and writes NO flood-windows.json', () => {
+    // The gateway wires onFloodWait → openFloodWindow('global', …)
+    // unconditionally; with the flag OFF that must be a pure no-op — no in-memory
+    // suppression, no fs side effect (a poison-perms file created before the
+    // feature is ever enabled).
+    const path = floodWindowsPath(dir)
+    const recorder = makeFloodWindowRecorder(path, () => 0)
+    const clock: Clock = { now: () => 0, sleep: () => Promise.resolve() }
+    const gate = createSendGate({
+      enabled: false,
+      clock,
+      onWindowOpen: (scopeKey, untilTs) => recorder(scopeKey, untilTs),
+    })
+    gate.openFloodWindow('global', 600_000)
+    expect(existsSync(path)).toBe(false)
+  })
+
+  it('a boot loading initial windows never shortens an on-disk window', async () => {
+    const clock: Clock = { now: () => 0, sleep: () => Promise.resolve() }
+    // Boot with a long window applied at construction.
+    const gate = createSendGate({
+      enabled: true,
+      clock,
+      initialWindows: [{ scopeKey: 'global', untilTs: 600_000 }],
+    })
+    // Re-opening the SAME scope with a shorter untilTs must not shorten it.
+    gate.openFloodWindow('global', 10_000)
+    // A critical still fails fast against the ORIGINAL long window.
+    const e = await gate.gate(async () => 'x', { priorityClass: 'critical' }).catch((err) => err)
+    expect((e as { untilTs: number }).untilTs).toBe(600_000)
+  })
+})