switchroom 0.18.17 → 0.18.19

package/telegram-plugin/tests/premium-recovery.test.ts

@@ -0,0 +1,165 @@
+/**
+ * Unit tests for the "premium model recovered" ping.
+ *
+ *  - `decidePremiumRecovery` is the PURE recovery predicate: fires iff a marker
+ *    is pending AND the broker shows the premium tier servable again (at least
+ *    one account neither `exhausted` nor `premium_walled`) — the exact
+ *    complement of the `all-blocked` condition that fired the downgrade. This
+ *    IS the deterministic recovery signal: both fields are the broker's live-
+ *    authoritative verdicts, so the ping never depends on model judgement.
+ *  - `renderPremiumRecoveryPing` pins the honest, session-scoped wording +
+ *    button label.
+ *  - `premiumRecoveryClaimKey` keys the fleet-wide dedup on agent + token.
+ *  - the `.premium-recovery` carrier round-trips + is shape-gated (parity with
+ *    the `.session-model` / `.session-effort` carriers).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, rmSync, writeFileSync, existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  decidePremiumRecovery,
+  renderPremiumRecoveryPing,
+  premiumRecoveryClaimKey,
+} from '../premium-recovery.js'
+import {
+  writePremiumRecoveryFile,
+  readPremiumRecoveryFile,
+  clearPremiumRecoveryFile,
+  parsePremiumRecovery,
+  PREMIUM_RECOVERY_FILE,
+} from '../gateway/session-model-file.js'
+
+describe('decidePremiumRecovery — deterministic recovery predicate', () => {
+  it('no marker → never fires', () => {
+    expect(
+      decidePremiumRecovery({ hasMarker: false, accounts: [{ exhausted: false, premiumWalled: false }] }),
+    ).toEqual({ fire: false, reason: 'no-marker' })
+  })
+
+  it('marker pending but EVERY account still walled/exhausted → no fire (still-walled)', () => {
+    const d = decidePremiumRecovery({
+      hasMarker: true,
+      accounts: [
+        { exhausted: true, premiumWalled: false },
+        { exhausted: false, premiumWalled: true },
+        { exhausted: true, premiumWalled: true },
+      ],
+    })
+    expect(d).toEqual({ fire: false, reason: 'still-walled' })
+  })
+
+  it('marker pending AND one account can serve the premium tier again → fire', () => {
+    const d = decidePremiumRecovery({
+      hasMarker: true,
+      accounts: [
+        { exhausted: true, premiumWalled: true },
+        { exhausted: false, premiumWalled: false }, // recovered
+      ],
+    })
+    expect(d).toEqual({ fire: true, reason: 'recovered' })
+  })
+
+  it('an account that is exhausted-but-not-premium-walled does NOT count as recovered', () => {
+    // The premium tier is only servable on an account that is BOTH not
+    // exhausted AND not premium-walled.
+    const d = decidePremiumRecovery({
+      hasMarker: true,
+      accounts: [{ exhausted: true, premiumWalled: false }],
+    })
+    expect(d.fire).toBe(false)
+  })
+
+  it('an account that is premium-walled-but-not-exhausted does NOT count as recovered', () => {
+    const d = decidePremiumRecovery({
+      hasMarker: true,
+      accounts: [{ exhausted: false, premiumWalled: true }],
+    })
+    expect(d.fire).toBe(false)
+  })
+
+  it('empty account list with a pending marker → no fire (nothing servable)', () => {
+    expect(decidePremiumRecovery({ hasMarker: true, accounts: [] }).fire).toBe(false)
+  })
+})
+
+describe('renderPremiumRecoveryPing — honest wording', () => {
+  it('names the model, says available again, and offers a session-scoped switch', () => {
+    const p = renderPremiumRecoveryPing('fable')
+    expect(p.text).toContain('`fable`')
+    expect(p.text.toLowerCase()).toContain('available again')
+    expect(p.text.toLowerCase()).toContain('this session')
+    expect(p.buttonText).toBe('Switch to fable')
+    // Must NOT over-promise a durable pin.
+    expect(p.text.toLowerCase()).not.toContain('permanently')
+    expect(p.text.toLowerCase()).not.toContain('forever')
+  })
+})
+
+describe('premiumRecoveryClaimKey', () => {
+  it('keys the dedup on agent + token so different drops never collide', () => {
+    expect(premiumRecoveryClaimKey('klanker', 'fable')).toBe('premium-recovery:klanker:fable')
+    expect(premiumRecoveryClaimKey('klanker', 'fable')).not.toBe(
+      premiumRecoveryClaimKey('klanker', 'opus'),
+    )
+  })
+})
+
+describe('.premium-recovery carrier — round-trip + shape gate', () => {
+  let dir: string
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'premium-recovery-'))
+  })
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true })
+  })
+
+  it('write → read round-trips model + chats (a VALID marker is NOT swept)', () => {
+    writePremiumRecoveryFile(dir, 'fable', ['12345', '67890'])
+    const rec = readPremiumRecoveryFile(dir)
+    expect(rec?.premiumModel).toBe('fable')
+    expect(rec?.chats).toEqual(['12345', '67890'])
+    expect(typeof rec?.ts).toBe('number')
+    // A well-formed marker must survive a read — only corrupt files are swept.
+    expect(existsSync(join(dir, PREMIUM_RECOVERY_FILE))).toBe(true)
+  })
+
+  it('clear removes the marker', () => {
+    writePremiumRecoveryFile(dir, 'fable', ['12345'])
+    expect(existsSync(join(dir, PREMIUM_RECOVERY_FILE))).toBe(true)
+    clearPremiumRecoveryFile(dir)
+    expect(existsSync(join(dir, PREMIUM_RECOVERY_FILE))).toBe(false)
+    expect(readPremiumRecoveryFile(dir)).toBeNull()
+  })
+
+  it('refuses a non-canonical model token (shell-injection shape)', () => {
+    expect(() => writePremiumRecoveryFile(dir, 'bad name; rm -rf /', ['12345'])).toThrow()
+  })
+
+  it('refuses an empty chat list (a marker with nowhere to ping is a bug)', () => {
+    expect(() => writePremiumRecoveryFile(dir, 'fable', [])).toThrow()
+  })
+
+  it('parse rejects corrupt JSON / bad shape / bad token / empty chats', () => {
+    expect(parsePremiumRecovery('{broken')).toBeNull()
+    expect(parsePremiumRecovery(JSON.stringify({ premiumModel: 'fable', chats: [], ts: 1 }))).toBeNull()
+    expect(
+      parsePremiumRecovery(JSON.stringify({ premiumModel: 'bad;name', chats: ['1'], ts: 1 })),
+    ).toBeNull()
+    expect(
+      parsePremiumRecovery(JSON.stringify({ premiumModel: 'fable', chats: [1, 2], ts: 1 })),
+    ).toBeNull()
+    expect(parsePremiumRecovery(JSON.stringify({ premiumModel: 'fable', chats: ['1'] }))).toBeNull()
+  })
+
+  it('read returns null on a corrupt on-disk marker AND sweeps the garbled file', () => {
+    writeFileSync(join(dir, PREMIUM_RECOVERY_FILE), '{not json\n')
+    expect(existsSync(join(dir, PREMIUM_RECOVERY_FILE))).toBe(true)
+    expect(readPremiumRecoveryFile(dir)).toBeNull()
+    // LOW-1: a corrupt marker is garbage-collected on read so it can't linger
+    // forever (neither the ping path nor the manual-switch clear could ever
+    // delete it — both read null first).
+    expect(existsSync(join(dir, PREMIUM_RECOVERY_FILE))).toBe(false)
+  })
+})

package/telegram-plugin/tests/reaction-gate-routing.test.ts

@@ -130,7 +130,12 @@ describe('#3155 reactions route through the send gate (cosmetic)', () => {
     // The reaction actually reached the API (was admitted, not shed)...
     expect(setMessageReaction).toHaveBeenCalled()
     // ...and its 429 was recorded by the breaker — the whole gap this closes.
-    expect(onFloodWait).toHaveBeenCalledWith(7)
+    // #3111: the retry policy now also passes the call's opts so the gateway can
+    // open a scope-precise window (a reaction 429 implies only that chat).
+    expect(onFloodWait).toHaveBeenCalledWith(
+      7,
+      expect.objectContaining({ chat_id: 'chatA', priorityClass: 'cosmetic' }),
+    )
   })
 })
 

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

@@ -576,6 +576,27 @@ describe('#2923 — LOCAL resource exhaustion is NOT retried (avoids flood ban)'
     expect(out).toBe('ok')
     expect(seen).toEqual([42])
   })
+
+  it('passes the call opts to onFloodWait so the gateway can open a scope-precise window (#3111)', async () => {
+    const seen: { sec: number; chat_id?: string; chatType?: string }[] = []
+    const sleep = vi.fn(async () => {})
+    let n = 0
+    const retry = createRetryApiCall({
+      maxRetries: 3,
+      sleep,
+      onFloodWait: (sec, opts) => seen.push({ sec, chat_id: opts?.chat_id, chatType: opts?.chatType }),
+    })
+    const out = await retry(
+      async () => {
+        if (n++ === 0) throw errors.floodWait(7)
+        return 'ok'
+      },
+      { chat_id: '42', chatType: 'supergroup' },
+    )
+    expect(out).toBe('ok')
+    // The hook received the same chat scope the send carried — not a bare number.
+    expect(seen).toEqual([{ sec: 7, chat_id: '42', chatType: 'supergroup' }])
+  })
 })
 
 describe('#3084 — a long flood ban fails FAST instead of sleeping for hours', () => {

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

@@ -120,13 +120,12 @@ describe('handleStreamReply', () => {
     expect(bot.api.sendMessage.mock.calls[0][2]?.parse_mode).toBeUndefined()
   })
 
-  it('applies addParagraphSpacers on the rich path (multi-paragraph gap spaced)', async () => {
+  it('rich path sends the multi-paragraph `\\n\\n` gap byte-exact (no NBSP spacer)', async () => {
+    // The NBSP paragraph-spacer pass was removed in the #2669 follow-up — the
+    // rich renderer shows a plain `\n\n` gap as one blank line, so the handler
+    // passes the text through unchanged.
     const state = makeState()
-    // Spacer dep replaces every `\n\n` gap with a visible marker so we can
-    // assert the rich path ran it (mirrors the real gateway wiring).
-    const deps = makeDeps(bot, {
-      addParagraphSpacers: (t) => t.replace(/\n\n/g, '\n\nSPACER\n\n'),
-    })
+    const deps = makeDeps(bot)
 
     const pending = handleStreamReply(
       { chat_id: '1', text: 'Para one.\n\nPara two.', done: true },
@@ -137,14 +136,13 @@ describe('handleStreamReply', () => {
     await pending
 
     expect(bot.api.sendRichMessage).toHaveBeenCalledTimes(1)
-    expect(richSendMarkdown(bot)).toBe('Para one.\n\nSPACER\n\nPara two.')
+    expect(richSendMarkdown(bot)).toBe('Para one.\n\nPara two.')
+    expect(richSendMarkdown(bot)).not.toContain(String.fromCharCode(0xa0))
   })
 
-  it('does NOT apply addParagraphSpacers on the literal format=text path', async () => {
+  it('literal format=text path is byte-exact too', async () => {
     const state = makeState()
-    const deps = makeDeps(bot, {
-      addParagraphSpacers: (t) => t.replace(/\n\n/g, '\n\nSPACER\n\n'),
-    })
+    const deps = makeDeps(bot)
 
     const pending = handleStreamReply(
       { chat_id: '1', text: 'Para one.\n\nPara two.', format: 'text', done: true },
@@ -155,7 +153,6 @@ describe('handleStreamReply', () => {
     await pending
 
     expect(bot.api.sendMessage).toHaveBeenCalledTimes(1)
-    // Literal path is byte-exact — no spacer injected.
     expect(bot.api.sendMessage.mock.calls[0][1]).toBe('Para one.\n\nPara two.')
   })
 

package/telegram-plugin/tests/telegram-format.test.ts

@@ -19,8 +19,6 @@ import {
   repairEscapedWhitespace,
   escapeMarkdown,
   splitMarkdownChunks,
-  addParagraphSpacers,
-  PARAGRAPH_SPACER,
   RICH_MESSAGE_MAX_CHARS,
 } from '../format.js'
 
@@ -187,62 +185,119 @@ describe('splitMarkdownChunks', () => {
   })
 
   // -------------------------------------------------------------------------
-  // Chunk-boundary spacer hygiene. addParagraphSpacers injects a
-  // `\n\n${PARAGRAPH_SPACER}\n\n` gap between prose paragraphs. When a cut
-  // lands inside that gap, the boundary must not leave a chunk that opens or
-  // ends with a bare U+00A0 spacer line (a stray blank bubble line).
+  // Chunk-boundary blank-line hygiene. Paragraph gaps are now plain `\n\n`
+  // (the NBSP spacer was removed in the #2669 follow-up). When a cut lands in
+  // a gap, the boundary must not leave a chunk that opens or ends with a bare
+  // blank line, and no visible content may be dropped.
   // -------------------------------------------------------------------------
 
-  test('no chunk starts or ends with a bare U+00A0 spacer line (reviewer repro)', () => {
-    // The exact reviewer repro: a spacer gap straddling a small cap.
+  test('no chunk starts or ends with a bare blank line at a `\\n\\n` gap cut', () => {
     const A = 'Alpha sentence one'
     const B = 'Bravo sentence two'
-    const spaced = addParagraphSpacers(`${A}.\n\n${B}.`)
-    const chunks = splitMarkdownChunks(spaced, 33)
+    const text = `${A}.\n\n${B}.`
+    const chunks = splitMarkdownChunks(text, 33)
     expect(chunks.length).toBeGreaterThan(1)
-    const spacerOnly = new RegExp(`^[ \\t]*${PARAGRAPH_SPACER}[ \\t]*$`)
+    const blankOnly = /^[ \t]*$/
     for (const c of chunks) {
       const lines = c.split('\n')
-      expect(spacerOnly.test(lines[0])).toBe(false)
-      expect(spacerOnly.test(lines[lines.length - 1])).toBe(false)
+      expect(blankOnly.test(lines[0])).toBe(false)
+      expect(blankOnly.test(lines[lines.length - 1])).toBe(false)
     }
   })
 
   test('visible paragraph content survives the boundary (no text dropped)', () => {
     const A = 'Alpha sentence one'
     const B = 'Bravo sentence two'
-    const spaced = addParagraphSpacers(`${A}.\n\n${B}.`)
-    const chunks = splitMarkdownChunks(spaced, 33)
+    const text = `${A}.\n\n${B}.`
+    const chunks = splitMarkdownChunks(text, 33)
     const rejoined = chunks.join('\n')
     expect(rejoined).toContain(`${A}.`)
     expect(rejoined).toContain(`${B}.`)
   })
 
-  test('spacer-boundary strip is robust across several gaps and small caps', () => {
+  test('blank-line-boundary strip is robust across several gaps and small caps', () => {
     const paras = Array.from({ length: 6 }, (_, i) => `Paragraph ${i} body text here.`)
-    const spaced = addParagraphSpacers(paras.join('\n\n'))
-    const spacerOnly = new RegExp(`^[ \\t]*${PARAGRAPH_SPACER}[ \\t]*$`)
+    const text = paras.join('\n\n')
+    const blankOnly = /^[ \t]*$/
     for (const cap of [20, 31, 40, 64]) {
-      const chunks = splitMarkdownChunks(spaced, cap)
+      const chunks = splitMarkdownChunks(text, cap)
       for (const c of chunks) {
         const lines = c.split('\n')
-        expect(spacerOnly.test(lines[0])).toBe(false)
-        expect(spacerOnly.test(lines[lines.length - 1])).toBe(false)
+        expect(blankOnly.test(lines[0])).toBe(false)
+        expect(blankOnly.test(lines[lines.length - 1])).toBe(false)
       }
-      // No visible word is dropped: concatenating the chunks' non-blank,
-      // non-spacer tokens reproduces the original word sequence. (Word-level,
-      // not line-level, because a small cap may split mid-word — that's the
-      // chunker's normal space-boundary behaviour, orthogonal to spacers.)
-      const words = (s: string): string[] =>
-        s.split(/\s+/).filter((w) => w.length > 0 && w !== PARAGRAPH_SPACER)
-      // Join chunks with a space — each chunk is a separate Telegram message,
-      // so inter-chunk whitespace is irrelevant; what matters is no word is
-      // lost or fused. (A small cap may end a chunk mid-sentence at a space
-      // boundary, e.g. "...here." | "Paragraph 1...", which is normal.)
+      // No visible word is dropped: concatenating the chunks' non-blank tokens
+      // reproduces the original word sequence. (Word-level, not line-level,
+      // because a small cap may split mid-word — the chunker's normal
+      // space-boundary behaviour.)
+      const words = (s: string): string[] => s.split(/\s+/).filter((w) => w.length > 0)
       expect(words(chunks.join(' '))).toEqual(words(paras.join(' ')))
     }
   })
 
+  // -------------------------------------------------------------------------
+  // Entity-aware chunking (#finding-3): a cut must never bisect an inline
+  // span (`**bold**`, `` `code` ``, `_italic_`, `[label](href)`), which would
+  // strand an unclosed delimiter in the emitted chunk.
+  // -------------------------------------------------------------------------
+
+  test('a bold/code/link span straddling the cap is not bisected (balanced delimiters)', () => {
+    // Build a body where each inline span sits right around a small cap so the
+    // naive space/newline cut would land inside it. Every span is shorter than
+    // the smallest cap tried (the longest is the 34-char link), so a straddling
+    // span can always be kept whole — the entity-aware back-off must do so.
+    const filler = 'x'.repeat(30)
+    const body =
+      `${filler} **bold span here** ` +
+      `${filler} \`code span here\` ` +
+      `${filler} [label here](https://ex.com/a-b-c) ` +
+      `${filler} _italic span here_ ${filler}`
+    for (const cap of [40, 50, 60, 70, 80]) {
+      const chunks = splitMarkdownChunks(body, cap)
+      for (const c of chunks) {
+        // Balanced `**` and single-backtick delimiters in every chunk.
+        expect((c.match(/\*\*/g) ?? []).length % 2).toBe(0)
+        expect((c.match(/`/g) ?? []).length % 2).toBe(0)
+        // No chunk ends mid-link (an open `](` with no closing `)`), and no
+        // chunk starts with an orphan link tail.
+        const opens = (c.match(/\]\(/g) ?? []).length
+        const closesAfterOpen = (c.match(/\]\([^)\n]*\)/g) ?? []).length
+        expect(opens).toBe(closesAfterOpen)
+      }
+      // Nothing is dropped.
+      const words = (s: string): string[] => s.split(/\s+/).filter((w) => w.length > 0)
+      expect(words(chunks.join(' '))).toEqual(words(body))
+    }
+  })
+
+  test('a `***bold-italic***` / `___…___` span straddling the cap keeps SINGLE-marker balance', () => {
+    // Regression for the triple-marker case: without the `***…***` pattern, the
+    // bold pattern matches only the inner `**…**`, so a cut inside `***x***`
+    // strands the lone outer `*` (odd asterisk count → the italic is lost). A
+    // `**`-PAIR balance check misses that, so assert SINGLE-`*` / SINGLE-`_`
+    // balance in every chunk.
+    const filler = 'x'.repeat(30)
+    const body =
+      `${filler} ***bold italic here*** ` +
+      `${filler} ___under bold here___ ${filler}`
+    for (const cap of [40, 50, 60, 70]) {
+      const chunks = splitMarkdownChunks(body, cap)
+      for (const c of chunks) {
+        // SINGLE-marker balance: an even count of `*` and of `_` in every chunk
+        // (a stranded lone `*`/`_` from a bisected triple span makes it odd).
+        expect((c.match(/\*/g) ?? []).length % 2).toBe(0)
+        expect((c.match(/_/g) ?? []).length % 2).toBe(0)
+      }
+      // Each triple span survives intact in exactly one chunk.
+      const rejoined = chunks.join('\n')
+      expect(rejoined).toContain('***bold italic here***')
+      expect(rejoined).toContain('___under bold here___')
+      // Nothing dropped.
+      const words = (s: string): string[] => s.split(/\s+/).filter((w) => w.length > 0)
+      expect(words(chunks.join(' '))).toEqual(words(body))
+    }
+  })
+
   test('a boundary with NO spacer is unaffected (legacy ^\\n+ behaviour preserved)', () => {
     const text = Array.from({ length: 10 }, (_, i) => `plain line ${i}`).join('\n\n')
     const chunks = splitMarkdownChunks(text, 40)

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

@@ -0,0 +1,165 @@
+/**
+ * Integration test for the tier-downgrade GLUE (`runTierDowngrade`,
+ * tier-downgrade-wiring.ts) — the gateway orchestration the pure
+ * `decideTierDowngrade` / `renderTierDowngradeNotice` tests do NOT cover.
+ *
+ * This is the test the @overlord review asked for (the MEDIUM "reverts to
+ * fable" misinform slipped through precisely because the glue that emits the
+ * BROADCAST notice text had no test — only the pure renderer did). It drives
+ * the real runner with injected seams and PINS the broadcast notice:
+ *   - asserts the resume-on-DEFAULT wording + the manual re-issue instruction;
+ *   - FAILS on any revert-to-premium phrasing (the exact regression).
+ * It also covers the resume-gate suppression path and the carrier-before-arm
+ * ordering invariant.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  runTierDowngrade,
+  type TierDowngradeRunnerDeps,
+  type TierDowngradeOutcome,
+} from '../gateway/tier-downgrade-wiring.js'
+
+interface Recorder {
+  carrier: Array<{ dir: string; toModel: string; cfg: string }>
+  arms: number
+  markers: Array<{ dir: string; premiumModel: string }>
+  notices: string[]
+  restarts: string[]
+  logs: string[]
+}
+
+function makeDeps(
+  over: Partial<TierDowngradeRunnerDeps> & {
+    sessionOverride?: string | null
+    configuredDefault?: string | null
+    gateVerdict?: 'resume' | 'skip-inflight' | 'skip-stale'
+    carrierThrows?: boolean
+    markerThrows?: boolean
+    agentDir?: string | null
+  } = {},
+): { deps: TierDowngradeRunnerDeps; rec: Recorder } {
+  const rec: Recorder = { carrier: [], arms: 0, markers: [], notices: [], restarts: [], logs: [] }
+  // A near-identity resolver like the real resolveMainModel: the unset/`default`
+  // sentinel maps to the switchroom default, everything else is itself.
+  const resolve = (t: string): string => (t === '' || t === 'default' ? 'claude-opus-4-8' : t)
+  const deps: TierDowngradeRunnerDeps = {
+    getAgentDir: () => (over.agentDir === undefined ? '/tmp/agent' : over.agentDir),
+    getConfiguredDefault: () => (over.configuredDefault === undefined ? 'opus' : over.configuredDefault),
+    getSessionOverride: () => (over.sessionOverride === undefined ? 'fable' : over.sessionOverride),
+    resolve,
+    peekResumeGate: () => over.gateVerdict ?? 'resume',
+    writeCarrier: (dir, toModel, cfg) => {
+      if (over.carrierThrows) throw new Error('disk full')
+      rec.carrier.push({ dir, toModel, cfg })
+    },
+    armResumeGate: () => {
+      rec.arms += 1
+    },
+    writeRecoveryMarker: (dir, premiumModel) => {
+      if (over.markerThrows) throw new Error('marker write failed')
+      rec.markers.push({ dir, premiumModel })
+    },
+    broadcastNotice: (md) => rec.notices.push(md),
+    selfRestart: (agent) => rec.restarts.push(agent),
+    selfAgent: (t) => `self-${t}`,
+    log: (msg) => rec.logs.push(msg),
+    ...over,
+  }
+  return { deps, rec }
+}
+
+describe('runTierDowngrade — broadcast notice honesty (the pinned regression)', () => {
+  it('downgrade path broadcasts EXACTLY ONE notice with resume-on-default wording', () => {
+    const { deps, rec } = makeDeps({ sessionOverride: 'fable', configuredDefault: 'opus' })
+    const outcome: TierDowngradeOutcome = runTierDowngrade('klanker', deps)
+    expect(outcome).toBe('downgraded')
+    expect(rec.notices).toHaveLength(1)
+    const notice = rec.notices[0]
+    // Resume-on-DEFAULT + the manual re-issue instruction.
+    expect(notice).toContain('`opus`')
+    expect(notice).toContain('/model fable')
+    expect(notice.toLowerCase()).toContain("won't switch back on its own")
+  })
+
+  it('the notice NEVER promises a revert to the premium model (the MEDIUM regression)', () => {
+    const { deps, rec } = makeDeps({ sessionOverride: 'fable', configuredDefault: 'opus' })
+    runTierDowngrade('klanker', deps)
+    const notice = rec.notices[0].toLowerCase()
+    // The exact false phrasing from the pre-5d9bbf44 revision, and its kin.
+    expect(notice).not.toContain('reverts to `fable`')
+    expect(notice).not.toContain('revert to `fable`')
+    expect(notice).not.toMatch(/reverts? to fable/)
+    expect(notice).not.toMatch(/switch(es)? back.*on (the )?next restart/)
+    expect(notice).not.toMatch(/automatically.*(fable|premium)/)
+  })
+})
+
+describe('runTierDowngrade — side-effect ordering + outcomes', () => {
+  it('downgrade: carrier written BEFORE the arm, marker + notice + restart all fire', () => {
+    const { deps, rec } = makeDeps({ sessionOverride: 'fable', configuredDefault: 'opus' })
+    const outcome = runTierDowngrade('klanker', deps)
+    expect(outcome).toBe('downgraded')
+    expect(rec.carrier).toEqual([{ dir: '/tmp/agent', toModel: 'opus', cfg: 'opus' }])
+    expect(rec.arms).toBe(1)
+    expect(rec.markers).toEqual([{ dir: '/tmp/agent', premiumModel: 'fable' }])
+    expect(rec.restarts).toEqual(['self-klanker'])
+  })
+
+  it('carrier write THROWS → abort: NO arm, NO marker, NO notice, NO restart (skip)', () => {
+    const { deps, rec } = makeDeps({ carrierThrows: true })
+    const outcome = runTierDowngrade('klanker', deps)
+    expect(outcome).toBe('skip')
+    expect(rec.arms).toBe(0)
+    expect(rec.markers).toHaveLength(0)
+    expect(rec.notices).toHaveLength(0)
+    expect(rec.restarts).toHaveLength(0)
+  })
+
+  it('marker write THROWS → downgrade still completes (marker is best-effort)', () => {
+    const { deps, rec } = makeDeps({ markerThrows: true })
+    const outcome = runTierDowngrade('klanker', deps)
+    expect(outcome).toBe('downgraded')
+    expect(rec.arms).toBe(1)
+    expect(rec.notices).toHaveLength(1)
+    expect(rec.restarts).toEqual(['self-klanker'])
+    expect(rec.markers).toHaveLength(0)
+  })
+
+  it('resume-gate skip-inflight → restart-pending, NO notice, NO restart, NO carrier', () => {
+    const { deps, rec } = makeDeps({ gateVerdict: 'skip-inflight' })
+    const outcome = runTierDowngrade('klanker', deps)
+    expect(outcome).toBe('restart-pending')
+    expect(rec.carrier).toHaveLength(0)
+    expect(rec.arms).toBe(0)
+    expect(rec.notices).toHaveLength(0)
+    expect(rec.restarts).toHaveLength(0)
+  })
+
+  it('resume-gate skip-stale → skip (give up), NO notice/restart', () => {
+    const { deps, rec } = makeDeps({ gateVerdict: 'skip-stale' })
+    const outcome = runTierDowngrade('klanker', deps)
+    expect(outcome).toBe('skip')
+    expect(rec.notices).toHaveLength(0)
+    expect(rec.restarts).toHaveLength(0)
+  })
+
+  it('session on the configured default (override null) → skip, no downgrade', () => {
+    const { deps, rec } = makeDeps({ sessionOverride: null })
+    const outcome = runTierDowngrade('klanker', deps)
+    expect(outcome).toBe('skip')
+    expect(rec.notices).toHaveLength(0)
+  })
+
+  it('unresolved configured default → skip (never downgrade blind)', () => {
+    const { deps, rec } = makeDeps({ configuredDefault: '' })
+    const outcome = runTierDowngrade('klanker', deps)
+    expect(outcome).toBe('skip')
+    expect(rec.carrier).toHaveLength(0)
+  })
+
+  it('no agent dir → skip immediately', () => {
+    const { deps } = makeDeps({ agentDir: null })
+    expect(runTierDowngrade('klanker', deps)).toBe('skip')
+  })
+})