switchroom 0.18.12 → 0.18.14

package/telegram-plugin/tests/stream-controller-chunk-cap.test.ts

@@ -2,7 +2,8 @@
  * Wire-level regression test for the chunk-boundary cap bug
  * (fix/rich-render-chunk-boundary-cap).
  *
- * With `SWITCHROOM_RICH_RENDER` on, a near-cap body full of escapable chars
+ * With the rich renderer enabled (the default — escape hatch, not opt-in), a
+ * near-cap body full of escapable chars
  * (`_ * |`) makes `renderSafe` degrade the whole document to plain (its escaped
  * rich form exceeds RICH_MESSAGE_MAX_CHARS). BEFORE the fix, the stream
  * controller shipped that ~32k plain body through the plain `sendMessage`
@@ -13,7 +14,7 @@
  * emitted send fits its own wire cap: rich pieces <= 32768, plain pieces
  * <= 4096, and no fenced block is bisected.
  */
-import { describe, it, expect, afterEach } from "vitest";
+import { describe, it, expect } from "vitest";
 import { createStreamController } from "../stream-controller.js";
 import { createFakeBotApi } from "./fake-bot-api.js";
 import { RICH_MESSAGE_MAX_CHARS } from "../format.js";
@@ -25,12 +26,7 @@ function fenceCount(s: string): number {
 }
 
 describe("stream-controller enforces the wire cap on the post-escape body", () => {
-  afterEach(() => {
-    delete process.env.SWITCHROOM_RICH_RENDER;
-  });
-
   it("REGRESSION: near-cap escapable first send never exceeds the plain wire cap", async () => {
-    process.env.SWITCHROOM_RICH_RENDER = "1";
     const bot = createFakeBotApi({ startMessageId: 1000 });
     const unit = "a_b*c|d ";
     const body = unit.repeat(Math.floor((RICH_MESSAGE_MAX_CHARS - 20) / unit.length));
@@ -62,7 +58,6 @@ describe("stream-controller enforces the wire cap on the post-escape body", () =
     // callback. The pre-fix code re-sent all (N-1) tails as brand-new messages
     // on each edit tick, so `sent.length` grew by (N-1) every update. After the
     // fix, tails are parked once and edited in place — `sent.length` is flat.
-    process.env.SWITCHROOM_RICH_RENDER = "1";
     const bot = createFakeBotApi({ startMessageId: 3000 });
     const unit = "a_b*c|d ";
     // Near-cap body that degrades to plain and splits into several pieces.
@@ -106,17 +101,22 @@ describe("stream-controller enforces the wire cap on the post-escape body", () =
     }
   }, 30000);
 
-  it("flag OFF leaves the single-send path untouched", async () => {
-    const bot = createFakeBotApi({ startMessageId: 2000 });
-    const stream = createStreamController({
-      bot: bot as unknown as Parameters<typeof createStreamController>[0]["bot"],
-      chatId: "c1",
-      throttleMs: 0,
-    });
-    await stream.update("**hi** _there_");
-    await stream.finalize();
-    expect(bot.state.sent).toHaveLength(1);
-    expect(bot.state.sent[0].rich).toBe(true);
-    expect(bot.state.sent[0].text).toBe("**hi** _there_");
+  it("kill-switch (=0) leaves the single-send path byte-for-byte untouched", async () => {
+    process.env.SWITCHROOM_RICH_RENDER = "0";
+    try {
+      const bot = createFakeBotApi({ startMessageId: 2000 });
+      const stream = createStreamController({
+        bot: bot as unknown as Parameters<typeof createStreamController>[0]["bot"],
+        chatId: "c1",
+        throttleMs: 0,
+      });
+      await stream.update("**hi** _there_");
+      await stream.finalize();
+      expect(bot.state.sent).toHaveLength(1);
+      expect(bot.state.sent[0].rich).toBe(true);
+      expect(bot.state.sent[0].text).toBe("**hi** _there_");
+    } finally {
+      delete process.env.SWITCHROOM_RICH_RENDER;
+    }
   });
 });

package/telegram-plugin/tests/stream-reply-handler.test.ts

@@ -81,7 +81,7 @@ describe('handleStreamReply', () => {
     expect(state.activeDraftStreams.size).toBe(1)
   })
 
-  it('a non-text format ships raw GFM markdown unescaped (no parse_mode)', async () => {
+  it('a non-text format ships GFM markdown unescaped (no parse_mode)', async () => {
     const state = makeState()
     const deps = makeDeps(bot)
 
@@ -94,7 +94,10 @@ describe('handleStreamReply', () => {
     await pending
 
     expect(bot.api.sendRichMessage).toHaveBeenCalledTimes(1)
-    expect(richSendMarkdown(bot)).toBe('**hi** _there_')
+    // The default-on rich renderer (parse -> renderSafe) normalises the
+    // italic marker (`_there_` -> `*there*`, same wire entity) but the
+    // payload stays unescaped GFM markdown — no HTML, no MarkdownV2 escaping.
+    expect(richSendMarkdown(bot)).toBe('**hi** *there*')
     // No parse_mode on rich opts.
     expect(bot.api.sendRichMessage.mock.calls[0][2]?.parse_mode).toBeUndefined()
   })

package/telegram-plugin/tests/subagent-watcher-fd-leak.test.ts

@@ -0,0 +1,275 @@
+/**
+ * FD-leak regression tests for the subagent-watcher (review findings H1 + H2).
+ *
+ * H1 — directory FSWatchers were only ever closed in the global stop(). When a
+ *      Claude session's `subagents/` dir was reaped, the rescan loop skipped
+ *      the vanished path without closing its watcher, so every session leaked
+ *      one inotify FD for the gateway's lifetime.
+ *
+ * H2 — every boot-scanned file opened a per-file FSWatcher unconditionally,
+ *      including stale historical `running` entries that `checkStalls` skips
+ *      and that therefore never reach terminal cleanup — leaking their FD until
+ *      the file happened to vanish.
+ *
+ * Each test FAILS on pre-fix code (an unclosed / never-opened-guarded watcher)
+ * and PASSES with the runtime-close / open-gating fix.
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import type * as fs from 'fs'
+import { startSubagentWatcher } from '../subagent-watcher.js'
+
+interface FakeWatcher {
+  path: string
+  close: ReturnType<typeof vi.fn>
+  closed: boolean
+}
+
+/**
+ * Minimal watcher harness with a MUTABLE fake filesystem (so a test can make a
+ * directory or file vanish mid-run) and per-watcher path tracking (so we can
+ * assert exactly which watchers were opened / closed).
+ */
+function makeHarness(opts: {
+  agentDir?: string
+  dirs: Record<string, string[]>
+  fileSizes?: Record<string, number>
+  rescanMs?: number
+}) {
+  const agentDir = opts.agentDir ?? '/home/user/.switchroom/agents/myagent'
+  const rescanMs = opts.rescanMs ?? 500
+  const dirs = new Map<string, string[]>(Object.entries(opts.dirs))
+  const fileSizes = new Map<string, number>(Object.entries(opts.fileSizes ?? {}))
+  const logs: string[] = []
+  const watchers: FakeWatcher[] = []
+  let currentTime = 1_000_000
+
+  const existsSync = ((p: fs.PathLike) => {
+    const ps = String(p)
+    return dirs.has(ps) || fileSizes.has(ps)
+  }) as typeof fs.existsSync
+
+  const mockFs = {
+    existsSync,
+    readdirSync: ((p: fs.PathLike) => dirs.get(String(p)) ?? []) as unknown as typeof fs.readdirSync,
+    // No mtimeMs → boot-promotion freshness gate treats a running file as
+    // stale (dead prior-session worker), so it stays historical + unpromoted.
+    statSync: ((p: fs.PathLike) => ({ size: fileSizes.get(String(p)) ?? 0 }) as fs.Stats) as typeof fs.statSync,
+    openSync: (() => 42) as unknown as typeof fs.openSync,
+    closeSync: (() => undefined) as typeof fs.closeSync,
+    readSync: (() => 0) as unknown as typeof fs.readSync,
+    watch: ((p: fs.PathLike) => {
+      const w: FakeWatcher = {
+        path: String(p),
+        closed: false,
+        close: vi.fn(() => { w.closed = true }),
+      }
+      watchers.push(w)
+      return w as unknown as fs.FSWatcher
+    }) as unknown as typeof fs.watch,
+  }
+
+  const intervals: Array<{ fn: () => void; ms: number; ref: number; fireAt: number }> = []
+  const timeouts: Array<{ fn: () => void; ref: number; fireAt: number }> = []
+  let nextRef = 1
+
+  const watcher = startSubagentWatcher({
+    agentDir,
+    onFinish: () => {},
+    stallThresholdMs: 60_000,
+    silentSynthesisStallThresholdMs: 60_000,
+    rescanMs,
+    now: () => currentTime,
+    setInterval: (fn, ms) => {
+      const ref = nextRef++
+      intervals.push({ fn, ms, ref, fireAt: currentTime + ms })
+      return { ref }
+    },
+    clearInterval: (handle) => {
+      const { ref } = handle as { ref: number }
+      const idx = intervals.findIndex((i) => i.ref === ref)
+      if (idx !== -1) intervals.splice(idx, 1)
+    },
+    setTimeout: (fn, ms) => {
+      const ref = nextRef++
+      timeouts.push({ fn, ref, fireAt: currentTime + ms })
+      return { ref }
+    },
+    clearTimeout: (handle) => {
+      const { ref } = handle as { ref: number }
+      const idx = timeouts.findIndex((t) => t.ref === ref)
+      if (idx !== -1) timeouts.splice(idx, 1)
+    },
+    fs: mockFs,
+    log: (msg: string) => { logs.push(msg) },
+  })
+
+  const poll = (): void => {
+    // intervals[0] is the poll loop (registered first — see startSubagentWatcher).
+    intervals[0]?.fn()
+  }
+
+  return {
+    watcher,
+    watchers,
+    logs,
+    dirs,
+    fileSizes,
+    poll,
+    fileWatchers: () => watchers.filter((w) => w.path.endsWith('.jsonl')),
+    dirWatchersFor: (p: string) => watchers.filter((w) => w.path === p),
+  }
+}
+
+const PROJECTS = '/home/user/.switchroom/agents/myagent/.claude/projects'
+
+describe('subagent-watcher FD-leak (H1): dir watchers close when their session dir vanishes', () => {
+  it('closes and forgets the subagents-dir FSWatcher after the session dir is reaped', () => {
+    const projectDir = `${PROJECTS}/myproject`
+    const sessionDir = `${projectDir}/session-A`
+    const subagentsDir = `${sessionDir}/subagents`
+
+    const h = makeHarness({
+      dirs: {
+        [PROJECTS]: ['myproject'],
+        [projectDir]: ['session-A'],
+        [sessionDir]: ['subagents'],
+        [subagentsDir]: [], // empty subagents dir — still gets a dir watcher
+      },
+    })
+
+    // Boot scan already ran in the constructor; poll once to be certain the
+    // dir watcher for the subagents dir has been opened.
+    h.poll()
+    const dw = h.dirWatchersFor(subagentsDir)
+    expect(dw).toHaveLength(1)
+    expect(dw[0].closed).toBe(false)
+
+    // Claude Code reaps the whole session directory (session rotation).
+    h.dirs.delete(sessionDir)
+    h.dirs.delete(subagentsDir)
+    h.dirs.set(projectDir, []) // session-A gone from the project listing
+
+    // Next rescan tick must release the now-dangling dir watcher.
+    h.poll()
+
+    expect(dw[0].close).toHaveBeenCalledTimes(1)
+    expect(dw[0].closed).toBe(true)
+
+    h.watcher.stop()
+  })
+})
+
+describe('subagent-watcher FD-leak (H2): no per-file watcher for stale historical running entries', () => {
+  it('does not open an FSWatcher for a boot-discovered stale running JSONL', () => {
+    const projectDir = `${PROJECTS}/myproject`
+    const sessionDir = `${projectDir}/session-A`
+    const subagentsDir = `${sessionDir}/subagents`
+    const staleFile = `${subagentsDir}/agent-deadbeef.jsonl`
+
+    const h = makeHarness({
+      dirs: {
+        [PROJECTS]: ['myproject'],
+        [projectDir]: ['session-A'],
+        [sessionDir]: ['subagents'],
+        [subagentsDir]: ['agent-deadbeef.jsonl'],
+      },
+      // size 0 + no mtimeMs → registers as a stale historical `running` entry
+      // that will never be promoted and never reach terminal cleanup.
+      fileSizes: { [staleFile]: 0 },
+    })
+
+    h.poll()
+
+    // A dir watcher for the subagents dir is fine. What must NOT happen is a
+    // per-file (.jsonl) watcher for a stale historical running entry that
+    // would leak forever.
+    const fileWatchersForStale = h.fileWatchers().filter((w) => w.path === staleFile)
+    expect(fileWatchersForStale).toHaveLength(0)
+
+    h.watcher.stop()
+  })
+
+  // Positive direction of the H2 gate: the open-guard is `!entry.historical ||
+  // entry.bootPromotionPending != null`, so the negative test above (no watcher
+  // for a stale boot entry) must be balanced by proof the guard does NOT
+  // over-prune a genuinely LIVE worker. A file that first appears AFTER the boot
+  // scan is non-historical (`bootScanInProgress` is already false), so it is a
+  // live worker the user is awaiting and MUST get its own per-file FSWatcher —
+  // otherwise its tool-call / turn_end transitions would be invisible until the
+  // 1s defensive poll happened to catch them. Reviewer verified this by code-
+  // reading only; this test locks it in.
+  it('opens a per-file FSWatcher for a live (post-boot, non-historical) worker JSONL', () => {
+    const projectDir = `${PROJECTS}/myproject`
+    const sessionDir = `${projectDir}/session-A`
+    const subagentsDir = `${sessionDir}/subagents`
+    const liveFile = `${subagentsDir}/agent-live01.jsonl`
+
+    const h = makeHarness({
+      dirs: {
+        [PROJECTS]: ['myproject'],
+        [projectDir]: ['session-A'],
+        [sessionDir]: ['subagents'],
+        [subagentsDir]: [], // empty at boot → nothing marked historical
+      },
+    })
+
+    // Boot scan already ran (constructor) over the empty dir; poll once so the
+    // dir watcher for the subagents dir is definitely established.
+    h.poll()
+    expect(h.fileWatchers()).toHaveLength(0) // nothing to watch yet
+
+    // A brand-new worker dispatches AFTER boot: its JSONL appears now. Because
+    // bootScanInProgress is already false, scanSubagentsDir does NOT mark it
+    // historical → it registers as a live running entry.
+    h.dirs.set(subagentsDir, ['agent-live01.jsonl'])
+    h.fileSizes.set(liveFile, 24)
+
+    h.poll()
+
+    const fileWatchersForLive = h.fileWatchers().filter((w) => w.path === liveFile)
+    expect(fileWatchersForLive).toHaveLength(1)
+    expect(fileWatchersForLive[0].closed).toBe(false)
+
+    h.watcher.stop()
+    // stop() must close the live watcher it opened (no leak on shutdown).
+    expect(fileWatchersForLive[0].closed).toBe(true)
+  })
+})
+
+describe('subagent-watcher FD-leak (H1): a still-present session dir keeps its watcher across rescans', () => {
+  it('does NOT prune the dir watcher for a directory that is still present', () => {
+    const projectDir = `${PROJECTS}/myproject`
+    const sessionDir = `${projectDir}/session-A`
+    const subagentsDir = `${sessionDir}/subagents`
+
+    const h = makeHarness({
+      dirs: {
+        [PROJECTS]: ['myproject'],
+        [projectDir]: ['session-A'],
+        [sessionDir]: ['subagents'],
+        [subagentsDir]: [], // present + empty — gets a dir watcher, stays present
+      },
+    })
+
+    h.poll()
+    const dw = h.dirWatchersFor(subagentsDir)
+    expect(dw).toHaveLength(1)
+    expect(dw[0].closed).toBe(false)
+
+    // The session dir never vanishes. Several rescan ticks pass. The complement
+    // of the H1 close-on-vanish test: pruneVanishedDirWatchers must leave a
+    // still-existing dir's watcher untouched, and the `if (!dirWatchers.has(...))`
+    // guard must NOT open a duplicate watcher for the same dir on each rescan.
+    h.poll()
+    h.poll()
+    h.poll()
+
+    expect(dw[0].close).not.toHaveBeenCalled()
+    expect(dw[0].closed).toBe(false)
+    // Exactly one dir watcher for this path across all the rescans — no churn.
+    expect(h.dirWatchersFor(subagentsDir)).toHaveLength(1)
+
+    h.watcher.stop()
+  })
+})

package/telegram-plugin/tests/throttle-tier-wiring.test.ts

@@ -0,0 +1,290 @@
+/**
+ * Tests for gateway/throttle-tier-wiring.ts — the 429 throttle tier's
+ * side-effect runner, driven with fully injected deps (no gateway import).
+ *
+ * Pins the OUTCOMES the wiring promises:
+ *  - EVERY fire reaches the broker's mark-throttled (the escalation counter),
+ *    even when the user-facing notice is cooldown-suppressed;
+ *  - ONE notice per account per window, deduped locally AND fleet-wide via
+ *    the broker claim verb (denied claim → no send; claim error → fail open);
+ *  - the retry nudge is armed at throttled_until + slack + jitter, replaced
+ *    (not stacked) by a newer throttle, and at FIRE time:
+ *      - restarts when idle and the resume gate says 'resume';
+ *      - DEFERS to the turn-complete drain when the in-flight gate is held
+ *        by the dead throttled turn (never SIGTERM-now under a live turn);
+ *      - SKIPS entirely when a NEWER turn (started after the throttle was
+ *        armed) is live — restarting would kill live work and boot-resume
+ *        would replay the WRONG turn;
+ *  - the escalated outcome posts the corroborated-wall announcement (fleet-
+ *    deduped) and nudges the resume immediately through the same guards;
+ *  - a broker-unreachable fire degrades to notice-only without throwing.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  createThrottleTierRunner,
+  THROTTLE_RETRY_NUDGE_SLACK_MS,
+  type ThrottleBrokerClient,
+  type ThrottleTierRunnerDeps,
+} from '../gateway/throttle-tier-wiring.js'
+
+const NOW = Date.UTC(2026, 6, 12, 8, 0, 0)
+
+interface Harness {
+  deps: ThrottleTierRunnerDeps
+  calls: {
+    markThrottled: number[]
+    claims: string[]
+    notices: Array<{ chatId: string | number; markdown: string }>
+    deferrals: string[]
+    restarts: string[]
+    logs: string[]
+    timers: Array<{ ms: number; fn: () => void; cancelled: boolean }>
+  }
+  clock: { set(ms: number): void }
+  fireTimer(idx: number): void
+}
+
+function makeHarness(opts: {
+  markThrottledResult?:
+    | { account: string; throttled_until: number; escalated: boolean; rolledTo?: string | null }
+    | 'unreachable'
+    | 'throw'
+  claimGranted?: (key: string) => boolean | 'throw'
+  resumeVerdict?: 'resume' | 'skip-inflight' | 'skip-stale'
+  turnInFlight?: () => boolean
+  newestTurnStartedAt?: () => number | null
+  jitterMs?: number
+} = {}): Harness {
+  let nowMs = NOW
+  const calls: Harness['calls'] = {
+    markThrottled: [],
+    claims: [],
+    notices: [],
+    deferrals: [],
+    restarts: [],
+    logs: [],
+    timers: [],
+  }
+  const client: ThrottleBrokerClient = {
+    async markThrottled(until: number) {
+      calls.markThrottled.push(until)
+      if (opts.markThrottledResult === 'throw') throw new Error('boom')
+      const r = opts.markThrottledResult
+      if (r && r !== 'unreachable') return r
+      return { account: 'alice', throttled_until: until, escalated: false, rolledTo: null }
+    },
+    async claimNotification(key: string) {
+      calls.claims.push(key)
+      const g = opts.claimGranted?.(key) ?? true
+      if (g === 'throw') throw new Error('claim boom')
+      return { granted: g }
+    },
+  }
+  const deps: ThrottleTierRunnerDeps = {
+    agentName: 'carrie',
+    getBrokerClient: async () =>
+      opts.markThrottledResult === 'unreachable' ? null : client,
+    listNoticeChats: () => ['111', '222'],
+    sendNotice: (chatId, markdown) => calls.notices.push({ chatId, markdown }),
+    resumeDecide: () => opts.resumeVerdict ?? 'resume',
+    newestActiveTurnStartedAtMs: opts.newestTurnStartedAt ?? (() => null),
+    turnInFlight: opts.turnInFlight ?? (() => false),
+    deferRestartToTurnComplete: (_agent, reason) => calls.deferrals.push(reason),
+    restartNow: (_agent, reason) => calls.restarts.push(reason),
+    log: (m) => calls.logs.push(m),
+    now: () => nowMs,
+    schedule: (fn, ms) => {
+      const t = { ms, fn, cancelled: false }
+      calls.timers.push(t)
+      return { cancel: () => { t.cancelled = true } }
+    },
+    jitterMs: () => opts.jitterMs ?? 0,
+  }
+  return {
+    deps,
+    calls,
+    clock: { set: (ms) => { nowMs = ms } },
+    fireTimer(idx: number) {
+      const t = calls.timers[idx]
+      if (!t || t.cancelled) throw new Error('no live timer at idx ' + idx)
+      t.fn()
+    },
+  }
+}
+
+describe('throttle-tier runner — broker mark + notice dedup', () => {
+  it('every fire reaches markThrottled; the notice is sent ONCE per cooldown window', async () => {
+    const h = makeHarness()
+    const runner = createThrottleTierRunner(h.deps)
+    await runner.fire('carrie', NOW + 60_000, true)
+    h.clock.set(NOW + 30_000) // same window
+    await runner.fire('carrie', NOW + 90_000, true)
+
+    // Both hits reached the broker (the escalation counter needs them)…
+    expect(h.calls.markThrottled).toEqual([NOW + 60_000, NOW + 90_000])
+    // …but only ONE notice per chat went out.
+    expect(h.calls.notices).toHaveLength(2) // 2 chats × 1 notice
+    expect(h.calls.notices.map((n) => n.chatId)).toEqual(['111', '222'])
+    expect(h.calls.notices[0].markdown).toContain('alice')
+    expect(h.calls.notices[0].markdown).toContain('Rate-limited, staying put')
+  })
+
+  it('fleet-wide claim dedup: a denied claim suppresses that chat, an error fails open', async () => {
+    const h = makeHarness({
+      claimGranted: (key) => (key.endsWith(':111') ? false : 'throw'),
+    })
+    const runner = createThrottleTierRunner(h.deps)
+    await runner.fire('carrie', NOW + 60_000, true)
+
+    // chat 111 denied (another gateway won the claim), chat 222 errored → open.
+    expect(h.calls.claims).toEqual([
+      `throttle-notice:alice:111`,
+      `throttle-notice:alice:222`,
+    ])
+    expect(h.calls.notices.map((n) => n.chatId)).toEqual(['222'])
+  })
+
+  it('degrades to notice-only when the broker is unreachable (no throw, no claim)', async () => {
+    const h = makeHarness({ markThrottledResult: 'unreachable' })
+    const runner = createThrottleTierRunner(h.deps)
+    await runner.fire('carrie', NOW + 60_000, false)
+    expect(h.calls.markThrottled).toHaveLength(0)
+    expect(h.calls.claims).toHaveLength(0) // no account → no claim key
+    expect(h.calls.notices).toHaveLength(2)
+    expect(h.calls.notices[0].markdown).toContain('the active account')
+  })
+
+  it('a markThrottled throw is swallowed and the notice still goes out', async () => {
+    const h = makeHarness({ markThrottledResult: 'throw' })
+    const runner = createThrottleTierRunner(h.deps)
+    await expect(runner.fire('carrie', NOW + 60_000, true)).resolves.toBeUndefined()
+    expect(h.calls.notices).toHaveLength(2)
+  })
+})
+
+describe('throttle-tier runner — retry nudge scheduling + turn safety', () => {
+  it('arms the nudge at reset + slack + jitter and restarts when idle', async () => {
+    const h = makeHarness({ jitterMs: 7_000 })
+    const runner = createThrottleTierRunner(h.deps)
+    await runner.fire('carrie', NOW + 60_000, true)
+
+    expect(h.calls.timers).toHaveLength(1)
+    expect(h.calls.timers[0].ms).toBe(60_000 + THROTTLE_RETRY_NUDGE_SLACK_MS + 7_000)
+    expect(runner.inspect().nudgePending).toBe(true)
+
+    h.fireTimer(0)
+    expect(h.calls.restarts).toEqual(['throttle-retry-resume'])
+    expect(h.calls.deferrals).toHaveLength(0)
+    expect(runner.inspect().nudgePending).toBe(false)
+  })
+
+  it('a newer throttle REPLACES the pending nudge instead of stacking restarts', async () => {
+    const h = makeHarness()
+    const runner = createThrottleTierRunner(h.deps)
+    await runner.fire('carrie', NOW + 60_000, true)
+    await runner.fire('carrie', NOW + 120_000, true)
+    expect(h.calls.timers).toHaveLength(2)
+    expect(h.calls.timers[0].cancelled).toBe(true)
+    expect(h.calls.timers[1].cancelled).toBe(false)
+  })
+
+  it('DEFERS to the turn-complete drain when the dead throttled turn still holds the gate', async () => {
+    const h = makeHarness({
+      turnInFlight: () => true,
+      // The in-flight turn started BEFORE the throttle was armed — it IS the
+      // dead turn (a 429-killed turn never writes its turn-end marker).
+      newestTurnStartedAt: () => NOW - 60_000,
+    })
+    const runner = createThrottleTierRunner(h.deps)
+    await runner.fire('carrie', NOW + 60_000, true)
+    h.fireTimer(0)
+    expect(h.calls.restarts).toHaveLength(0) // never SIGTERM-now under a live gate
+    expect(h.calls.deferrals).toEqual(['throttle-retry-resume'])
+  })
+
+  it('SKIPS entirely when a NEWER live turn supersedes the dead one', async () => {
+    let nowAtNudge = NOW
+    const h = makeHarness({
+      turnInFlight: () => true,
+      // Started AFTER the throttle was armed — live user work.
+      newestTurnStartedAt: () => nowAtNudge + 30_000,
+    })
+    const runner = createThrottleTierRunner(h.deps)
+    await runner.fire('carrie', NOW + 60_000, true)
+    nowAtNudge = NOW // armedAt == NOW; newest = NOW+30s > armedAt
+    h.fireTimer(0)
+    expect(h.calls.restarts).toHaveLength(0)
+    expect(h.calls.deferrals).toHaveLength(0)
+    expect(h.calls.logs.some((l) => l.includes('superseded'))).toBe(true)
+  })
+
+  it('honours the shared resume gate verdict (skip-inflight → no restart)', async () => {
+    const h = makeHarness({ resumeVerdict: 'skip-inflight' })
+    const runner = createThrottleTierRunner(h.deps)
+    await runner.fire('carrie', NOW + 60_000, true)
+    h.fireTimer(0)
+    expect(h.calls.restarts).toHaveLength(0)
+    expect(h.calls.logs.some((l) => l.includes('skip-inflight'))).toBe(true)
+  })
+})
+
+describe('throttle-tier runner — escalated outcome (corroborated wall)', () => {
+  it('posts the fleet-deduped escalation announcement and resumes immediately', async () => {
+    const h = makeHarness({
+      markThrottledResult: {
+        account: 'alice',
+        throttled_until: NOW + 60_000,
+        escalated: true,
+        rolledTo: 'bob',
+      },
+    })
+    const runner = createThrottleTierRunner(h.deps)
+    await runner.fire('carrie', NOW + 60_000, true)
+
+    // Announcement (not the staying-put notice), per chat, claim-deduped.
+    expect(h.calls.claims).toEqual([
+      `throttle-escalation:alice:111`,
+      `throttle-escalation:alice:222`,
+    ])
+    expect(h.calls.notices).toHaveLength(2)
+    expect(h.calls.notices[0].markdown).toContain('actually a wall')
+    expect(h.calls.notices[0].markdown).toContain('bob')
+
+    // Immediate resume (fleet just swapped accounts) — no delayed nudge armed.
+    expect(h.calls.restarts).toEqual(['throttle-escalation-resume'])
+    expect(h.calls.timers).toHaveLength(0)
+  })
+
+  it('escalated with rolledTo=null (all blocked) announces but does NOT restart', async () => {
+    const h = makeHarness({
+      markThrottledResult: {
+        account: 'alice',
+        throttled_until: NOW + 60_000,
+        escalated: true,
+        rolledTo: null,
+      },
+    })
+    const runner = createThrottleTierRunner(h.deps)
+    await runner.fire('carrie', NOW + 60_000, true)
+    expect(h.calls.notices[0].markdown).toContain('all blocked')
+    expect(h.calls.restarts).toHaveLength(0)
+  })
+
+  it('escalated resume respects the live-turn guards too', async () => {
+    const h = makeHarness({
+      markThrottledResult: {
+        account: 'alice',
+        throttled_until: NOW + 60_000,
+        escalated: true,
+        rolledTo: 'bob',
+      },
+      turnInFlight: () => true,
+      newestTurnStartedAt: () => NOW - 60_000, // the dead turn holds the gate
+    })
+    const runner = createThrottleTierRunner(h.deps)
+    await runner.fire('carrie', NOW + 60_000, true)
+    expect(h.calls.restarts).toHaveLength(0)
+    expect(h.calls.deferrals).toEqual(['throttle-escalation-resume'])
+  })
+})