switchroom 0.18.11 → 0.18.13

package/telegram-plugin/tests/retry-api-call.test.ts

@@ -15,8 +15,14 @@ import {
   createSwallowingRetryApiCall,
   retryWithThreadFallback,
   isHtmlParseRejectError,
+  isMessageTooLongError,
+  isPhotoDimensionRejectError,
   isLocalResourceError,
+  isFloodWaitActiveError,
   LOCAL_RESOURCE_EXHAUSTED,
+  FLOOD_WAIT_ACTIVE,
+  DEFAULT_MAX_FLOOD_SLEEP_MS,
+  type FloodWaitActiveError,
   type RetryObserver,
 } from '../retry-api-call.js'
 import { errors, makeGrammyError } from './fake-bot-api.js'
@@ -571,3 +577,395 @@ describe('#2923 — LOCAL resource exhaustion is NOT retried (avoids flood ban)'
     expect(seen).toEqual([42])
   })
 })
+
+describe('#3084 — a long flood ban fails FAST instead of sleeping for hours', () => {
+  /**
+   * Deterministic fake clock: `sleep` never waits, it just advances a counter.
+   * Nothing here touches a real timer, so "did we try to sleep 4.6 hours?" is
+   * an assertion on the fake clock, not a stopwatch.
+   */
+  function fakeClock() {
+    let elapsedMs = 0
+    const slept: number[] = []
+    return {
+      get elapsedMs() {
+        return elapsedMs
+      },
+      slept,
+      sleep: async (ms: number) => {
+        slept.push(ms)
+        elapsedMs += ms
+      },
+    }
+  }
+
+  // The real value overlord's gateway logged on 2026-07-11.
+  const REAL_BAN_SEC = 16_739
+
+  it('does NOT sleep a 4.6-hour retry_after (clock never advances past the ceiling)', async () => {
+    const clock = fakeClock()
+    let calls = 0
+    const retry = createRetryApiCall({ maxRetries: 3, sleep: clock.sleep })
+
+    await expect(
+      retry(async () => {
+        calls++
+        throw errors.floodWait(REAL_BAN_SEC)
+      }),
+    ).rejects.toThrow(FLOOD_WAIT_ACTIVE)
+
+    expect(calls).toBe(1) // failed fast on the first 429 — no retry storm
+    expect(clock.slept).toEqual([]) // never even attempted the sleep
+    expect(clock.elapsedMs).toBe(0)
+    expect(clock.elapsedMs).toBeLessThanOrEqual(DEFAULT_MAX_FLOOD_SLEEP_MS)
+  })
+
+  it('carries retry_after / untilTs / original on the thrown marker', async () => {
+    const clock = fakeClock()
+    const before = Date.now()
+    const retry = createRetryApiCall({ maxRetries: 3, sleep: clock.sleep })
+
+    const err = await retry(async () => {
+      throw errors.floodWait(REAL_BAN_SEC)
+    }).catch((e: unknown) => e)
+
+    expect(isFloodWaitActiveError(err)).toBe(true)
+    const flood = err as FloodWaitActiveError
+    expect(flood.retryAfterSec).toBe(REAL_BAN_SEC)
+    expect(flood.untilTs).toBeGreaterThanOrEqual(before + REAL_BAN_SEC * 1000)
+    expect(flood.original).toBeInstanceOf(GrammyError)
+  })
+
+  it('STILL records the flood window via onFloodWait before throwing (#2923 breaker)', async () => {
+    const clock = fakeClock()
+    const seen: number[] = []
+    const order: string[] = []
+    const retry = createRetryApiCall({
+      maxRetries: 3,
+      sleep: clock.sleep,
+      onFloodWait: (s) => {
+        seen.push(s)
+        order.push('recorded')
+      },
+      observer: {
+        onGiveUp: () => {
+          order.push('gave_up')
+        },
+      },
+    })
+
+    await expect(
+      retry(async () => {
+        throw errors.floodWait(REAL_BAN_SEC)
+      }),
+    ).rejects.toThrow(FLOOD_WAIT_ACTIVE)
+
+    // The breaker MUST learn about the window — that is what suppresses the
+    // restart boot-card that would otherwise extend the ban.
+    expect(seen).toEqual([REAL_BAN_SEC])
+    expect(order).toEqual(['recorded', 'gave_up'])
+  })
+
+  it('a throwing onFloodWait hook still yields the marker, not the hook error', async () => {
+    const clock = fakeClock()
+    const retry = createRetryApiCall({
+      maxRetries: 3,
+      sleep: clock.sleep,
+      onFloodWait: () => {
+        throw new Error('disk full while persisting flood state')
+      },
+    })
+    await expect(
+      retry(async () => {
+        throw errors.floodWait(REAL_BAN_SEC)
+      }),
+    ).rejects.toThrow(FLOOD_WAIT_ACTIVE)
+  })
+
+  it('a SHORT retry_after under the ceiling still sleeps-and-retries and succeeds', async () => {
+    const clock = fakeClock()
+    let n = 0
+    const retry = createRetryApiCall({ maxRetries: 3, sleep: clock.sleep })
+
+    // 30s — the everyday rate-limit blip. Behaviour must be unchanged.
+    const out = await retry(async () => {
+      if (n++ === 0) throw errors.floodWait(30)
+      return 'ok'
+    })
+
+    expect(out).toBe('ok')
+    expect(n).toBe(2)
+    expect(clock.slept).toEqual([30_000])
+  })
+
+  it('the historic 28s and 75s waits are still slept through (no regression)', async () => {
+    for (const sec of [28, 75]) {
+      const clock = fakeClock()
+      let n = 0
+      const retry = createRetryApiCall({ maxRetries: 3, sleep: clock.sleep })
+      const out = await retry(async () => {
+        if (n++ === 0) throw errors.floodWait(sec)
+        return 'ok'
+      })
+      expect(out).toBe('ok')
+      expect(clock.slept).toEqual([sec * 1000])
+    }
+  })
+
+  it('sleeps exactly AT the ceiling, throws just above it', async () => {
+    const atCeiling = DEFAULT_MAX_FLOOD_SLEEP_MS / 1000
+
+    const clockAt = fakeClock()
+    let n = 0
+    const retryAt = createRetryApiCall({ maxRetries: 3, sleep: clockAt.sleep })
+    expect(
+      await retryAt(async () => {
+        if (n++ === 0) throw errors.floodWait(atCeiling)
+        return 'ok'
+      }),
+    ).toBe('ok')
+    expect(clockAt.slept).toEqual([DEFAULT_MAX_FLOOD_SLEEP_MS])
+
+    const clockOver = fakeClock()
+    const retryOver = createRetryApiCall({ maxRetries: 3, sleep: clockOver.sleep })
+    await expect(
+      retryOver(async () => {
+        throw errors.floodWait(atCeiling + 1)
+      }),
+    ).rejects.toThrow(FLOOD_WAIT_ACTIVE)
+    expect(clockOver.slept).toEqual([])
+  })
+
+  it('honours a caller-supplied maxFloodSleepMs ceiling', async () => {
+    const clock = fakeClock()
+    const retry = createRetryApiCall({
+      maxRetries: 3,
+      sleep: clock.sleep,
+      maxFloodSleepMs: 5_000,
+    })
+    // 30s would sleep under the DEFAULT ceiling; with a 5s ceiling it throws.
+    await expect(
+      retry(async () => {
+        throw errors.floodWait(30)
+      }),
+    ).rejects.toThrow(FLOOD_WAIT_ACTIVE)
+    expect(clock.slept).toEqual([])
+  })
+
+  it('maxRetries semantics unchanged for sustained SHORT floods', async () => {
+    const clock = fakeClock()
+    let calls = 0
+    const retry = createRetryApiCall({ maxRetries: 3, sleep: clock.sleep })
+
+    await expect(
+      retry(async () => {
+        calls++
+        throw errors.floodWait(10)
+      }),
+    ).rejects.toThrow('retryApiCall: max retries exceeded')
+
+    expect(calls).toBe(3)
+    expect(clock.slept).toEqual([10_000, 10_000, 10_000])
+  })
+
+  it('the swallowing wrapper absorbs the marker (no unhandled rejection)', async () => {
+    const clock = fakeClock()
+    const lines: string[] = []
+    const retry = createRetryApiCall({ maxRetries: 3, sleep: clock.sleep })
+    const swallow = createSwallowingRetryApiCall(retry, (l) => lines.push(l))
+
+    const out = await swallow(
+      async () => {
+        throw errors.floodWait(REAL_BAN_SEC)
+      },
+      { verb: 'sendMessage' },
+    )
+
+    expect(out).toBeUndefined()
+    expect(lines.join('')).toContain(FLOOD_WAIT_ACTIVE)
+  })
+})
+
+describe('#3084 — the fast throw must not become a re-drive amplifier', () => {
+  const REAL_BAN_SEC = 16_739
+
+  /**
+   * EXACT duck-type predicate used by the card surfaces to arm their 429
+   * cooldown — copied verbatim from `worker-activity-feed.ts`
+   * (`extractRetryAfterSecs`) and `issues-card.ts`. They do NOT use
+   * `instanceof GrammyError`. If the marker doesn't satisfy this, they
+   * classify it 'transient', arm no cooldown, and their 5-6s heartbeats
+   * re-drive the send into the open ban.
+   */
+  function extractRetryAfterSecs(err: unknown): number | null {
+    if (err == null || typeof err !== 'object') return null
+    const e = err as { error_code?: unknown; parameters?: { retry_after?: unknown } }
+    if (e.error_code !== 429) return null
+    const ra = e.parameters?.retry_after
+    if (typeof ra === 'number' && Number.isFinite(ra) && ra > 0) return ra
+    return null
+  }
+
+  it('the marker satisfies the card surfaces\' 429 cooldown duck-type', async () => {
+    const retry = createRetryApiCall({ maxRetries: 3, sleep: async () => {} })
+    const err = await retry(async () => {
+      throw errors.floodWait(REAL_BAN_SEC)
+    }).catch((e: unknown) => e)
+
+    // worker-activity-feed / issues-card would now arm a FULL-window cooldown
+    // instead of treating this as a generic 'transient' error.
+    expect(extractRetryAfterSecs(err)).toBe(REAL_BAN_SEC)
+  })
+
+  it('the marker is still NOT a GrammyError (resend-fallback probes must not match)', async () => {
+    const retry = createRetryApiCall({ maxRetries: 3, sleep: async () => {} })
+    const err = await retry(async () => {
+      throw errors.floodWait(REAL_BAN_SEC)
+    }).catch((e: unknown) => e)
+
+    expect(err).not.toBeInstanceOf(GrammyError)
+    expect(isHtmlParseRejectError(err)).toBe(false)
+    expect(isMessageTooLongError(err)).toBe(false)
+    expect(isPhotoDimensionRejectError(err)).toBe(false)
+  })
+
+  it('a card heartbeat ticking across the whole 4.6h ban issues ONE Bot API call', async () => {
+    // The regression that must be impossible. Before the pre-call gate: the
+    // marker throws in ~1ms, the 6s heartbeat re-drives, and we fire ~2,760
+    // fresh requests into the still-open per-bot ban — feeding the exact flood
+    // counter #2923 exists to starve. Strictly worse than the original hang.
+    let now = 1_000_000
+    let state: { untilTs: number } | null = null
+    let apiCalls = 0
+
+    const retry = createRetryApiCall({
+      maxRetries: 3,
+      sleep: async () => {},
+      // The #2923 breaker: record the window...
+      onFloodWait: (sec) => {
+        state = { untilTs: now + sec * 1000 }
+      },
+      // ...and the #3084 gate: refuse to send into it.
+      floodWaitRemainingMs: () => (state ? Math.max(0, state.untilTs - now) : 0),
+    })
+
+    const HEARTBEAT_MS = 6_000
+    const ticks = Math.ceil((REAL_BAN_SEC * 1000) / HEARTBEAT_MS) // ~2,790
+    let markerThrows = 0
+
+    for (let i = 0; i < ticks; i++) {
+      // A worker-feed style heartbeat: best-effort edit, swallow failures,
+      // and (deliberately, to model the WORST case) arm no cooldown of its own.
+      await retry(async () => {
+        apiCalls++
+        throw errors.floodWait(REAL_BAN_SEC)
+      }).catch((e: unknown) => {
+        if (isFloodWaitActiveError(e)) markerThrows++
+      })
+      now += HEARTBEAT_MS
+    }
+
+    expect(ticks).toBeGreaterThan(2_700) // we really did simulate the full ban
+    expect(markerThrows).toBe(ticks) // every tick got a clean degraded state
+    // …and the Bot API was touched a HANDFUL of times, not once per tick.
+    // Without the pre-call gate this is ~2,790 requests fired into an open
+    // per-bot ban. With it: the first tick (which discovers the ban) plus the
+    // few tail ticks that run after the simulated window has elapsed and
+    // legitimately re-probe. Bounded and small is the whole contract.
+    expect(apiCalls).toBeLessThanOrEqual(5)
+    expect(apiCalls).toBeGreaterThanOrEqual(1)
+    expect(apiCalls / ticks).toBeLessThan(0.01) // <1% of ticks reach the API
+  })
+
+  it('resumes issuing calls once the window expires (the gate is not a latch)', async () => {
+    let now = 1_000_000
+    let state: { untilTs: number } | null = null
+    let apiCalls = 0
+
+    const retry = createRetryApiCall({
+      maxRetries: 3,
+      sleep: async () => {},
+      onFloodWait: (sec) => {
+        state = { untilTs: now + sec * 1000 }
+      },
+      floodWaitRemainingMs: () => (state ? Math.max(0, state.untilTs - now) : 0),
+    })
+
+    await expect(
+      retry(async () => {
+        apiCalls++
+        throw errors.floodWait(300)
+      }),
+    ).rejects.toThrow(FLOOD_WAIT_ACTIVE)
+    expect(apiCalls).toBe(1)
+
+    // Mid-window: gated, no call.
+    now += 100_000
+    await expect(retry(async () => 'ok')).rejects.toThrow(FLOOD_WAIT_ACTIVE)
+    expect(apiCalls).toBe(1)
+
+    // Window expired: the very next call goes through and succeeds.
+    now += 300_000
+    expect(
+      await retry(async () => {
+        apiCalls++
+        return 'ok'
+      }),
+    ).toBe('ok')
+    expect(apiCalls).toBe(2)
+  })
+
+  it('a SHORT open window is not short-circuited (sleep-and-retry still rides it out)', async () => {
+    // A 30s window is under the ceiling: the normal path may still succeed
+    // (the server may have cleared it), so we must NOT gate it.
+    let apiCalls = 0
+    let n = 0
+    const retry = createRetryApiCall({
+      maxRetries: 3,
+      sleep: async () => {},
+      floodWaitRemainingMs: () => 30_000,
+    })
+    const out = await retry(async () => {
+      apiCalls++
+      if (n++ === 0) throw errors.floodWait(30)
+      return 'ok'
+    })
+    expect(out).toBe('ok')
+    expect(apiCalls).toBe(2)
+  })
+
+  it('FAILS OPEN — a throwing/garbage flood probe never silences the bot', async () => {
+    const throwing = createRetryApiCall({
+      maxRetries: 3,
+      sleep: async () => {},
+      floodWaitRemainingMs: () => {
+        throw new Error('EACCES: unreadable flood-wait.json')
+      },
+    })
+    expect(await throwing(async () => 'ok')).toBe('ok')
+
+    // Garbage from a corrupt marker file must be treated as "no window".
+    // Infinity in particular would otherwise mute the bot forever.
+    for (const garbage of [NaN, -1, 0, Infinity]) {
+      const retry = createRetryApiCall({
+        maxRetries: 3,
+        sleep: async () => {},
+        floodWaitRemainingMs: () => garbage,
+      })
+      expect(await retry(async () => 'ok')).toBe('ok')
+    }
+  })
+
+  it('with no flood probe wired at all, behaviour is exactly as before', async () => {
+    let apiCalls = 0
+    let n = 0
+    const retry = createRetryApiCall({ maxRetries: 3, sleep: async () => {} })
+    const out = await retry(async () => {
+      apiCalls++
+      if (n++ === 0) throw errors.floodWait(30)
+      return 'ok'
+    })
+    expect(out).toBe('ok')
+    expect(apiCalls).toBe(2)
+  })
+})

package/telegram-plugin/tests/scoped-approval.test.ts

@@ -270,6 +270,33 @@ describe('isDestructiveBashCommand — fail-closed denylist', () => {
     expect(timeBoxRule('Bash', bashInput('git status `rm -rf x`'))).toBeNull()
   })
 
+  it('flags destructive git checkout / stash forms that discard work (fail-closed)', () => {
+    for (const cmd of [
+      // checkout that discards uncommitted working-tree changes
+      'git checkout .', 'git checkout -f', 'git checkout -f main', 'git checkout --force',
+      'git checkout -- file.ts', 'git checkout HEAD -- .', 'git checkout HEAD~1 -- src/x.ts',
+      // `./` and `./<path>` are common spellings of `.` — same whole-tree /
+      // subtree discard; git refnames forbid a branch starting with `./`,
+      // so gating these carries no false-positive risk.
+      'git checkout ./', 'git checkout ./src',
+      // stash forms that irreversibly remove stash state
+      'git stash drop', 'git stash drop stash@{2}', 'git stash clear', 'git stash pop',
+    ]) {
+      expect(isDestructiveBashCommand(cmd), cmd).toBe(true)
+    }
+  })
+
+  it('does NOT flag safe git checkout / stash forms (no over-broadening)', () => {
+    for (const cmd of [
+      // branch switches / creation are reversible
+      'git checkout main', 'git checkout -b feature', 'git checkout feature.branch',
+      // stash inspection / non-removing forms keep the stash
+      'git stash', 'git stash list', 'git stash show', 'git stash apply',
+    ]) {
+      expect(isDestructiveBashCommand(cmd), cmd).toBe(false)
+    }
+  })
+
   it('does NOT flag ordinary safe commands', () => {
     for (const cmd of [
       'git status', 'git log --oneline -5', 'git diff', 'npm test', 'npm run build',

package/telegram-plugin/tests/secret-detect-chunk-overlap.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect } from 'vitest'
+import { detectSecrets } from '../secret-detect/index.js'
+import { chunk, CHUNK_THRESHOLD, WINDOW_SIZE, OVERLAP } from '../secret-detect/chunker.js'
+
+/**
+ * OUTCOME test for tp-support F2 — the sliding-window overlap must exceed a
+ * real PEM private key so a boundary-straddling key in a >32 KB payload is
+ * still fully contained in (and therefore detected by) at least one window.
+ *
+ * The old 1 KB overlap was smaller than a 4096-bit RSA PEM (~3.2 KB), so a
+ * ~3.2 KB key straddling a 16 KB window boundary fell into the gap between
+ * consecutive windows and was scanned by NEITHER — it slipped past the
+ * scrubber unmasked. This pins the fix behaviorally: the key is detected.
+ *
+ * Proof-of-bite: reverting OVERLAP to 1024 (its pre-fix value) makes the
+ * boundary-straddling assertion below fail — the key lands in the gap.
+ */
+
+// A representative ~3.2 KB PEM private key (4096-bit RSA armor size). Body is
+// obviously-fake filler; only the BEGIN/END markers + non-empty body matter
+// for the `pem_private_key` regex. Assembled at runtime per CLAUDE.md.
+const PEM_BEGIN = '-----BEGIN RSA PRIVATE KEY-----'
+const PEM_END = '-----END RSA PRIVATE KEY-----'
+const PEM_BODY = 'A'.repeat(3100)
+const PEM = `${PEM_BEGIN}\n${PEM_BODY}\n${PEM_END}`
+
+describe('chunker overlap ≥ real PEM key size (tp-support F2)', () => {
+  it('overlap safely exceeds a 4096-bit RSA PEM (~3.2 KB)', () => {
+    // Guarantee: a secret is only missed if its length EXCEEDS OVERLAP.
+    expect(OVERLAP).toBeGreaterThanOrEqual(4 * 1024)
+    expect(PEM.length).toBeGreaterThan(1024) // the finding's ">1KB" threshold
+    expect(OVERLAP).toBeGreaterThan(PEM.length) // key fits inside the overlap
+  })
+
+  it('detects a >1KB PEM key straddling a window boundary in a >32KB payload', () => {
+    // Place the PEM so it straddles the first window boundary (16 KB): it
+    // starts before the boundary and ends after it. With the fixed 8 KB
+    // overlap the whole key sits inside the second window [8K, 24K]; with the
+    // old 1 KB overlap it fell into the gap between [0,16K] and [15.36K,31.74K].
+    const pemStart = WINDOW_SIZE - 1384 // 15000: before the 16384 boundary
+    const leading = 'a'.repeat(pemStart)
+    const trailing = 'a'.repeat(20000)
+    const text = leading + PEM + trailing
+
+    // Sanity: the payload is over the chunk threshold (so chunking is active)
+    // and the PEM genuinely straddles a real window boundary.
+    expect(text.length).toBeGreaterThan(CHUNK_THRESHOLD)
+    const windows = chunk(text)
+    expect(windows.length).toBeGreaterThan(1)
+    const pemEnd = pemStart + PEM.length
+    // Straddles the first boundary: starts before it, ends after it.
+    expect(pemStart).toBeLessThan(WINDOW_SIZE)
+    expect(pemEnd).toBeGreaterThan(WINDOW_SIZE)
+    // No single window before the fix (1 KB overlap) would have contained it,
+    // yet with the current overlap at least one window does.
+    const containing = windows.filter(
+      (w) => pemStart >= w.offset && pemEnd <= w.offset + w.text.length,
+    )
+    expect(containing.length).toBeGreaterThan(0)
+
+    // The actual outcome: the detector flags the straddling PEM.
+    const hits = detectSecrets(text)
+    expect(hits.some((h) => h.rule_id === 'pem_private_key')).toBe(true)
+  })
+})

package/telegram-plugin/tests/secret-detect-oauth-code.test.ts

@@ -210,10 +210,11 @@ describe('pendingReauthFlows intercept — deleteMessage sequencing (Blocker 1)'
     const window = src.slice(interceptIdx, interceptIdx + 2000)
     // Allow the optional 4th `log` argument added in #561 (diagnostic
     // sink for redaction failures) — required is the first three args.
-    // `bot.api` may be cast (e.g. `bot.api as never`) for the local
-    // BotApi-vs-grammy-Api type mismatch cleanup in #623; `msgId` may
-    // be narrowed (`msgId ?? null`).
-    expect(window).toMatch(/redactAuthCodeMessage\(bot\.api(?:\s+as\s+\w+)?,\s*chat_id,\s*msgId(?:\s*\?\?\s*null)?(?:,\s*[^)]+)?\)/)
+    // The first arg is the injected BotApi surface: historically `bot.api`
+    // (optionally cast, #623), now the gated `redactAuthCodeApi` adapter whose
+    // reaction routes through the send gate + flood breaker (#3155). `msgId`
+    // may be narrowed (`msgId ?? null`).
+    expect(window).toMatch(/redactAuthCodeMessage\((?:bot\.api|redactAuthCodeApi)(?:\s+as\s+\w+)?,\s*chat_id,\s*msgId(?:\s*\?\?\s*null)?(?:,\s*[^)]+)?\)/)
   })
 
   it('redaction lands AFTER the success/error reply renders', () => {

package/telegram-plugin/tests/session-model-file.test.ts

@@ -15,6 +15,8 @@ import {
   readSessionModelFileRaw,
   restoreSessionModelFileRaw,
   clearSessionModelFile,
+  clearSessionModelBootAttempts,
+  SESSION_MODEL_BOOT_ATTEMPTS_FILE,
   writeRelaunchModelIntent,
   clearRelaunchModelIntent,
   readConfiguredDefaultModel,
@@ -229,3 +231,51 @@ describe('intentForRestartReason is keep-for-everything (#3039)', () => {
     }
   })
 })
+
+describe('clearSessionModelBootAttempts (#3043 item 2: bridge-register clears the crashloop counter)', () => {
+  const bootAttemptsPath = () => join(dir, SESSION_MODEL_BOOT_ATTEMPTS_FILE)
+
+  // Faithful model of start.sh.hbs "Override crashloop self-heal": each boot
+  // within 150s of the previous stamp bumps the count; a stale stamp resets to
+  // 1. Reproduced here so the accumulate-vs-reset OUTCOME is asserted, not just
+  // the delete call.
+  function simulateBootStamp(nowSec: number): number {
+    let count = 0
+    let prev = 0
+    if (existsSync(bootAttemptsPath())) {
+      const [c, p] = readFileSync(bootAttemptsPath(), 'utf8').trim().split(/\s+/)
+      count = Number(c) || 0
+      prev = Number(p) || 0
+    }
+    count = nowSec - prev < 150 ? count + 1 : 1
+    writeFileSync(bootAttemptsPath(), `${count} ${nowSec}\n`)
+    return count
+  }
+
+  it('WITHOUT a bridge register, three fast boots accumulate toward the 3-strike clear', () => {
+    // Three operator hand-bounces, each <150s apart, with no register between.
+    expect(simulateBootStamp(1000)).toBe(1)
+    expect(simulateBootStamp(1010)).toBe(2)
+    expect(simulateBootStamp(1020)).toBe(3) // start.sh would now clear a HEALTHY override — the false positive
+  })
+
+  it('a bridge register between boots resets the counter, so a healthy agent never reaches 3', () => {
+    expect(simulateBootStamp(1000)).toBe(1)
+    // Boot 1 came all the way up and the bridge registered → gateway clears it.
+    clearSessionModelBootAttempts(dir)
+    expect(existsSync(bootAttemptsPath())).toBe(false)
+
+    // Next fast boot starts fresh at 1 (no accumulation), and register clears again.
+    expect(simulateBootStamp(1010)).toBe(1)
+    clearSessionModelBootAttempts(dir)
+    expect(simulateBootStamp(1020)).toBe(1)
+    // The healthy agent's counter never climbs to the 3-strike clear.
+    const [count] = readFileSync(bootAttemptsPath(), 'utf8').trim().split(/\s+/)
+    expect(Number(count)).toBeLessThan(3)
+  })
+
+  it('is best-effort — no throw when the counter file is absent', () => {
+    expect(existsSync(bootAttemptsPath())).toBe(false)
+    expect(() => clearSessionModelBootAttempts(dir)).not.toThrow()
+  })
+})