switchroom 0.19.1 → 0.19.3

package/telegram-plugin/tests/flushed-turn-supersede.test.ts

@@ -21,8 +21,10 @@ import { describe, it, expect } from 'vitest'
 import {
   decideSupersede,
   decideSupersedeCorrection,
+  flushedAnswerMatchesReply,
   FlushedTurnSupersedeRegistry,
   DEFAULT_SUPERSEDE_TTL_MS,
+  SUPERSEDE_MATCH_MIN_CONTAINMENT_CHARS,
   type FlushedTurnRecord,
 } from '../flushed-turn-supersede.js'
 
@@ -264,3 +266,118 @@ describe('FlushedTurnSupersedeRegistry — record / peek / take lifecycle', () =
     expect(reg.peek('chat1', undefined, { liveTurnId: 'turn-A', now: 5000 }).reason).toBe('no-record')
   })
 })
+
+/**
+ * #3429 — async handback edit-in-place supersede of a flush-delivered message
+ * can fail to surface client-side.
+ *
+ * The flush ends its turn synchronously BEFORE recording, so EVERY superseding
+ * reply is a late reply — and an async sub-agent handback landing within the
+ * 60 s TTL with no live gateway turn resolves the flush-delivered ENDED turn
+ * as its owner via the latest-ended tier, the SAME identity as the turn's own
+ * canonical late replay. Identity-only supersede then consumed the record and
+ * EDITED the flushed message in place with the handback's unrelated content
+ * (msgs 10482/10486, 2026-07-20) — Telegram edits never push-notify, so the
+ * handback silently failed to surface AND the flushed answer was destroyed.
+ *
+ * The content gate: `replyText` is compared against the record's flushed text
+ * (`flushedAnswerMatchesReply` — whitespace-normalized equality, or containment
+ * with a minimum-length guard on the contained side). Same answer → supersede
+ * (the wanted correction); different content → 'new-content', send fresh,
+ * record NOT consumed.
+ */
+describe('#3429 — flushedAnswerMatchesReply (content discriminator)', () => {
+  const ANSWER = 'The deploy is green: all 12 services rolled out and health checks pass.'
+  const FLUSH_BLOB = `Let me check the rollout status.\n\n${ANSWER}`
+
+  it('matches whitespace-normalized equality', () => {
+    expect(flushedAnswerMatchesReply(ANSWER, ANSWER)).toBe(true)
+    expect(flushedAnswerMatchesReply(`${ANSWER}\n`, ANSWER.replace(': ', ':  '))).toBe(true)
+  })
+
+  it('matches the classic containment class: flush = narration+answer ⊇ clean reply', () => {
+    expect(flushedAnswerMatchesReply(FLUSH_BLOB, ANSWER)).toBe(true)
+  })
+
+  it('matches reverse containment: reply ⊇ partially-delivered flush text', () => {
+    expect(flushedAnswerMatchesReply(ANSWER, FLUSH_BLOB)).toBe(true)
+  })
+
+  it('does NOT match genuinely different content (the handback)', () => {
+    const handback =
+      'Worker finished: PR #3430 is up with the fix for the vault broker timeout, ' +
+      'tests are green, ready for your review.'
+    expect(flushedAnswerMatchesReply(FLUSH_BLOB, handback)).toBe(false)
+  })
+
+  it('short containment below the minimum-length guard does NOT match ' +
+    '(a coincidental substring must never claim a handback)', () => {
+    const shortReply = 'rolled out'
+    expect(shortReply.length).toBeLessThan(SUPERSEDE_MATCH_MIN_CONTAINMENT_CHARS)
+    expect(FLUSH_BLOB.includes(shortReply)).toBe(true)
+    expect(flushedAnswerMatchesReply(FLUSH_BLOB, shortReply)).toBe(false)
+  })
+
+  it('short EQUAL texts still match (equality has no length floor)', () => {
+    expect(flushedAnswerMatchesReply('yes, done', 'yes, done')).toBe(true)
+  })
+})
+
+describe('#3429 — decideSupersede new-content gate', () => {
+  const FLUSHED = 'Narration first.\n\nHere is the finished summary of the incident you asked about.'
+  const HANDBACK =
+    'Sub-agent handback: the researcher finished and found three root causes, ' +
+    'written up in the report at /tmp/report.md — want the highlights?'
+
+  it('same-turn same-answer late reply still supersedes (the wanted correction)', () => {
+    const d = decideSupersede(rec({ text: FLUSHED }), {
+      liveTurnId: 'turn-A',
+      replyText: 'Here is the finished summary of the incident you asked about.',
+      now: 1_000_010,
+    })
+    expect(d.supersede).toBe(true)
+    expect(d.reason).toBe('supersede')
+    expect(d.recordText).toBe(FLUSHED)
+  })
+
+  it('CORE #3429: same turn identity + DIFFERENT content → new-content, NO supersede', () => {
+    const d = decideSupersede(rec({ text: FLUSHED }), {
+      liveTurnId: 'turn-A',
+      replyText: HANDBACK,
+      now: 1_000_010,
+    })
+    expect(d.supersede).toBe(false)
+    expect(d.reason).toBe('new-content')
+    expect(d.deleteMessageIds).toEqual([])
+    expect(d.recordText).toBe(FLUSHED)
+  })
+
+  it('legacy identity-only callers (no replyText) keep the pre-#3429 behaviour', () => {
+    const d = decideSupersede(rec({ text: FLUSHED }), { liveTurnId: 'turn-A', now: 1_000_010 })
+    expect(d.supersede).toBe(true)
+  })
+
+  it('take() does NOT consume the record on new-content — the genuine replay ' +
+    'can still correct the flushed message afterwards', () => {
+    const reg = new FlushedTurnSupersedeRegistry()
+    const now = 1_000_000
+    reg.record('chat9', undefined, { turnId: 'turn-F', messageIds: [7001], text: FLUSHED }, now)
+
+    // The handback lands first: new-content, nothing consumed, nothing deleted.
+    const d1 = reg.take('chat9', undefined, { liveTurnId: 'turn-F', replyText: HANDBACK, now: now + 10_000 })
+    expect(d1.supersede).toBe(false)
+    expect(d1.reason).toBe('new-content')
+
+    // The turn's own canonical replay lands later: record still there, supersede
+    // fires and consumes it.
+    const d2 = reg.take('chat9', undefined, {
+      liveTurnId: 'turn-F',
+      replyText: 'Here is the finished summary of the incident you asked about.',
+      now: now + 20_000,
+    })
+    expect(d2.supersede).toBe(true)
+    expect(d2.deleteMessageIds).toEqual([7001])
+    // Now consumed.
+    expect(reg.peek('chat9', undefined, { liveTurnId: 'turn-F', now: now + 21_000 }).reason).toBe('no-record')
+  })
+})

package/telegram-plugin/tests/gateway-session-model-relaunch.test.ts

@@ -16,8 +16,18 @@ import { describe, it, expect } from 'vitest'
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { dirname, resolve } from 'node:path'
+import { SESSION_MODEL_FILE } from '../gateway/session-model-file.js'
+import {
+  classifyModelSwitchConfirmation,
+  formatModelRelaunchDiagLog,
+  resolveModelSwitchBootNotice,
+} from '../gateway/model-command.js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
+const MODEL_COMMAND_SRC = readFileSync(
+  resolve(__dirname, '../gateway/model-command.ts'),
+  'utf8',
+)
 const GATEWAY_SRC = readFileSync(resolve(__dirname, '..', 'gateway', 'gateway.ts'), 'utf8')
 
 describe('gateway: the .relaunch-model-intent subsystem is retired (rev 4)', () => {
@@ -143,49 +153,203 @@ describe('gateway boot: session-model re-hydration + confirmation + alert relay'
     const win = GATEWAY_SRC.slice(idx - 200, idx + 3200)
     // F1: `launched !== configured` is the deterministic apply-boot signal.
     expect(win).toContain('const isApplyBoot = launched.length > 0 && launched !== configured')
-    expect(win).toContain('sessionModelSource.setOverride(isApplyBoot ? launched : null)')
+    expect(win).toContain('sessionModelSource.setOverride(isApplyBoot ? launched : null, { verify: true })')
     expect(win).toContain('resolveMainModel(raw ?? undefined)')
   })
 
   it('logs the applied model for diagnosability (F1)', () => {
-    expect(GATEWAY_SRC).toContain('gw /model relaunch applied agent=')
+    expect(GATEWAY_SRC).toContain('formatModelRelaunchDiagLog')
     expect(GATEWAY_SRC).toContain('gw /model relaunch scheduled agent=')
+    expect(MODEL_COMMAND_SRC).toContain('gw /model relaunch applied agent=')
   })
 
-  it('sends ONE switch-confirmation from the ACTUAL launched model, keyed on the /model reason (F1/N4)', () => {
-    const idx = GATEWAY_SRC.indexOf('const isApplyBoot = launched.length > 0')
-    expect(idx).toBeGreaterThan(0)
-    const win = GATEWAY_SRC.slice(idx, idx + 5200)
-    // Keyed on the deterministic /model switch reason, so it also fires on a
-    // launched===configured apply-boot (/model default) — N4. Never optimistic.
-    expect(win).toContain('if (modelSwitchReason != null && modelSwitchMarkerChat)')
-    expect(win).toContain('✅ Now running')
-    // N4: the launched===configured branch still confirms.
-    expect(win).toContain('(the configured default)')
+  // #3427 item 2: the following are BEHAVIORAL tests — they run the real
+  // classifier → formatter/notice pipeline and assert the EMITTED outcome
+  // (log line / card body), not that a string merely exists in the source.
+  // The thin `wires …` test at the end pins that gateway.ts actually calls
+  // this pipeline (the gateway boot IIFE cannot be unit-booted).
+
+  it('emits the NOT-APPLIED log for a silent revert (classify → formatModelRelaunchDiagLog)', () => {
+    const confirmation = classifyModelSwitchConfirmation({
+      reason: 'user: /model fable (session-only relaunch, menu)',
+      launched: 'claude-opus-4-8',
+      configured: 'claude-opus-4-8',
+    })
+    expect(confirmation.kind).toBe('not-applied')
+    const log = formatModelRelaunchDiagLog({
+      agent: 'klanker',
+      launched: 'claude-opus-4-8',
+      configured: 'claude-opus-4-8',
+      confirmation,
+      isApplyBoot: false,
+    })
+    expect(log).toContain('gw /model relaunch NOT-APPLIED agent=klanker')
+    expect(log).toContain('target=fable')
+    expect(log).toContain('revertedTo=claude-opus-4-8')
+  })
+
+  it('emits outcome=applied for a landed switch and outcome=default for a revert', () => {
+    const applied = classifyModelSwitchConfirmation({
+      reason: 'user: /model claude-haiku-4-5 (session-only relaunch)',
+      launched: 'claude-haiku-4-5',
+      configured: 'claude-opus-4-8',
+    })
+    expect(
+      formatModelRelaunchDiagLog({
+        agent: 'a', launched: 'claude-haiku-4-5', configured: 'claude-opus-4-8',
+        confirmation: applied, isApplyBoot: true,
+      }),
+    ).toContain('override=set outcome=applied')
+    const dflt = classifyModelSwitchConfirmation({
+      reason: 'user: /model default (revert relaunch)',
+      launched: 'claude-opus-4-8',
+      configured: 'claude-opus-4-8',
+    })
+    expect(
+      formatModelRelaunchDiagLog({
+        agent: 'a', launched: 'claude-opus-4-8', configured: 'claude-opus-4-8',
+        confirmation: dflt, isApplyBoot: false,
+      }),
+    ).toContain('override=cleared outcome=default')
+  })
+
+  it('sends the green applied card for a landed switch, the default card for an intended revert (F1/N4)', () => {
+    const applied = resolveModelSwitchBootNotice({
+      agent: 'a',
+      confirmation: classifyModelSwitchConfirmation({
+        reason: 'user: /model fable (session-only relaunch)',
+        launched: 'fable',
+        configured: 'claude-opus-4-8',
+      }),
+      hasSessionModelAlert: false,
+    })
+    expect(applied.kind).toBe('card')
+    if (applied.kind === 'card') {
+      expect(applied.body).toContain('✅ Now running `fable`')
+      expect(applied.body).toContain('session-only')
+    }
+    // N4: launched===configured on a /model default reason still confirms.
+    const dflt = resolveModelSwitchBootNotice({
+      agent: 'a',
+      confirmation: classifyModelSwitchConfirmation({
+        reason: 'user: /model default (revert relaunch)',
+        launched: 'claude-opus-4-8',
+        configured: 'claude-opus-4-8',
+      }),
+      hasSessionModelAlert: false,
+    })
+    expect(dflt.kind).toBe('card')
+    if (dflt.kind === 'card') {
+      expect(dflt.body).toContain('✅ Now running `claude-opus-4-8` (the configured default)')
+    }
   })
 
-  it('warns instead of a green ✅ when a non-default switch silently reverted to the default (silent-revert fix)', () => {
+  it('warns (⚠️, not a green ✅) when a non-default switch silently reverted to the default (silent-revert fix)', () => {
+    const notice = resolveModelSwitchBootNotice({
+      agent: 'a',
+      confirmation: classifyModelSwitchConfirmation({
+        reason: 'user: /model fable (session-only relaunch, menu)',
+        launched: 'claude-opus-4-8',
+        configured: 'claude-opus-4-8',
+      }),
+      hasSessionModelAlert: false,
+    })
+    expect(notice.kind).toBe('card')
+    if (notice.kind === 'card') {
+      expect(notice.body).toContain("⚠️ Your switch to `fable` didn't apply")
+      expect(notice.body).toContain('reverted to `claude-opus-4-8`')
+      // LOW-3: the re-issue hint keeps the target inside backticks.
+      expect(notice.body).toContain('Re-issue `/model fable`')
+      expect(notice.body).not.toContain('✅')
+    }
+  })
+
+  it('suppresses ONLY the not-applied card when a tailored .session-model-alert is present (LOW-2)', () => {
+    const reverted = classifyModelSwitchConfirmation({
+      reason: 'user: /model fable (session-only relaunch)',
+      launched: 'claude-opus-4-8',
+      configured: 'claude-opus-4-8',
+    })
+    const suppressed = resolveModelSwitchBootNotice({
+      agent: 'klanker',
+      confirmation: reverted,
+      hasSessionModelAlert: true,
+    })
+    expect(suppressed.kind).toBe('suppress')
+    if (suppressed.kind === 'suppress') {
+      expect(suppressed.log).toContain('suppressing not-applied confirmation')
+      expect(suppressed.log).toContain('agent=klanker')
+      expect(suppressed.log).toContain('target=fable')
+    }
+    // An APPLIED switch still confirms even when an (unrelated) alert exists.
+    const applied = resolveModelSwitchBootNotice({
+      agent: 'klanker',
+      confirmation: classifyModelSwitchConfirmation({
+        reason: 'user: /model fable (session-only relaunch)',
+        launched: 'fable',
+        configured: 'claude-opus-4-8',
+      }),
+      hasSessionModelAlert: true,
+    })
+    expect(applied.kind).toBe('card')
+  })
+
+  it('wires the pipeline into the boot rehydration (gateway calls classify → diag log → notice)', () => {
     const idx = GATEWAY_SRC.indexOf('const isApplyBoot = launched.length > 0')
-    const win = GATEWAY_SRC.slice(idx, idx + 5200)
-    // The confirmation card is derived from the pure classifier, not an inline
-    // isApplyBoot ternary — so a reverted non-default switch yields the ⚠️ card.
+    expect(idx).toBeGreaterThan(0)
+    const win = GATEWAY_SRC.slice(idx, idx + 4200)
     expect(win).toContain('classifyModelSwitchConfirmation({')
-    expect(win).toContain("confirmation.kind === 'applied'")
-    expect(win).toContain("confirmation.kind === 'not-applied'")
-    expect(win).toContain("⚠️ Your switch to")
-    expect(win).toContain("didn't apply")
-    // LOW-3: the re-issue hint interpolates the target inside backticks so a
-    // token containing Markdown metachars can't italicize / 400 the send.
-    expect(win).toContain('Re-issue \\`/model ${confirmation.target}\\`')
+    expect(win).toContain('formatModelRelaunchDiagLog')
+    expect(win).toContain('if (confirmation != null)')
+    expect(win).toContain('deliverModelSwitchBootNotice({')
+    expect(win).toContain("existsSync(join(smAgentDir, '.session-model-alert'))")
+    // Both notice arms (suppress → stderr, card → sendMessage) now live in
+    // model-command.ts (deliverModelSwitchBootNotice — behaviorally tested in
+    // model-command.test.ts); the gateway injects the shared boot-card deps
+    // (stderr log sink + one raw thread-aware send closure).
+    expect(win).toContain('...modelBootCardDeps')
+    expect(win).toContain('log: (line) => process.stderr.write(line)')
+    expect(win).toContain('lockedBot.api.sendMessage(chatId, body, opts)')
   })
 
-  it('dedups the not-applied card against a tailored .session-model-alert (LOW-2)', () => {
+  it('arms the #3427 requested-vs-served tripwire on an apply-boot (comparator + handler)', () => {
+    // The source is constructed with the conservative comparator…
+    expect(GATEWAY_SRC).toContain('createSessionModelSource({ servedMatchesRequested: servedModelMatchesRequested })')
+    // …and the apply-boot rehydration verify-ARMS the override (H1: the ONLY
+    // arming site) and registers the handler that logs + warns.
     const idx = GATEWAY_SRC.indexOf('const isApplyBoot = launched.length > 0')
-    const win = GATEWAY_SRC.slice(idx, idx + 5200)
-    // When start.sh wrote a specific alert for this revert, the classifier's
-    // generic not-applied card is suppressed (the alert relay is the message).
-    expect(win).toContain("existsSync(join(smAgentDir, '.session-model-alert'))")
-    expect(win).toContain("confirmation.kind === 'not-applied' && hasSessionModelAlert")
+    const win = GATEWAY_SRC.slice(idx, idx + 4500)
+    expect(win).toContain('sessionModelSource.setOverride(isApplyBoot ? launched : null, { verify: true })')
+    // The handler body lives in model-command.ts (buildServedModelDivergenceHandler,
+    // behaviorally tested in model-command.test.ts — log line + operator card);
+    // the gateway registers it ONLY on an apply-boot, fed by the shared deps.
+    expect(win).toContain(
+      'sessionModelSource.setDivergenceHandler(buildServedModelDivergenceHandler(modelBootCardDeps))',
+    )
+    const armIdx = win.indexOf('sessionModelSource.setDivergenceHandler(')
+    expect(win.slice(0, armIdx)).toContain('if (isApplyBoot) {')
+    // M2: the handler must NOT destroy the override record — a transient
+    // fallback substitution self-corrects; freshness already fixes /status.
+    // Structurally guaranteed post-extraction: the injected ModelBootCardDeps
+    // surface (agent/chat/log/sendCard) carries NO handle to the source, so
+    // the handler CANNOT call setOverride. Pin that the deps object stays free
+    // of any source handle.
+    const depsStart = win.indexOf('const modelBootCardDeps')
+    expect(depsStart).toBeGreaterThan(0)
+    const depsWin = win.slice(depsStart, win.indexOf('if (isApplyBoot)'))
+    expect(depsWin).not.toContain('sessionModelSource')
+  })
+
+  it('H1 (#3437): the command-time relaunch record does NOT verify-arm the tripwire', () => {
+    // scheduleModelRelaunch sets the pre-restart status-honesty override with a
+    // BARE setOverride — arming it would let an OLD-model assistant line in the
+    // pre-restart window false-accuse a valid NEW token. The behavioral guard
+    // lives in session-model-source.test.ts; this pins the gateway call sites.
+    const idx = GATEWAY_SRC.indexOf('scheduleModelRelaunch: async (model: string, reason: string)')
+    expect(idx).toBeGreaterThan(0)
+    const win = GATEWAY_SRC.slice(idx, idx + 2600)
+    expect(win).toContain('sessionModelSource.setOverride(model)')
+    expect(win).not.toContain('verify')
   })
 
   it('N4/reason: the /model switch reason is captured from the clean-shutdown marker', () => {
@@ -213,6 +377,32 @@ describe('gateway boot: session-model re-hydration + confirmation + alert relay'
   })
 })
 
+
+describe('gateway SESSION_MODEL_FILE stays pinned to start.sh.hbs rev5 carrier', () => {
+  it('hbs applies the same basename gateway writes (no rev4/rev5 name drift)', async () => {
+    const { SESSION_MODEL_FILE } = await import('../gateway/session-model-file.js')
+    const { readFileSync } = await import('node:fs')
+    const { resolve, dirname } = await import('node:path')
+    const { fileURLToPath } = await import('node:url')
+    expect(SESSION_MODEL_FILE).toBe('.session-model')
+    // Vitest may run with import.meta or __dirname depending on config.
+    const here = typeof __dirname !== 'undefined'
+      ? __dirname
+      : dirname(fileURLToPath(import.meta.url))
+    const hbs = readFileSync(
+      resolve(here, '../../profiles/_base/start.sh.hbs'),
+      'utf8',
+    )
+    // Bare file test on the rev5 carrier (not only -override/-alert siblings).
+    expect(hbs).toMatch(/\[\s*-f\s+[^\]]*\/\.session-model["\s\]]/)
+    expect(hbs).toContain('configuredDefaultAtWrite')
+    // Legacy migration shim still converts leftover override → .session-model.
+    expect(hbs).toContain('.session-model-override')
+    expect(hbs).toMatch(/migrated legacy one-shot carrier/)
+  })
+})
+
+
 describe('gateway: the legacy one-shot carrier is no longer written', () => {
   it('no gateway code writes .session-model-override anymore (start.sh migration shim only reads it)', () => {
     expect(GATEWAY_SRC).not.toMatch(/writeFileSync\([^)]*\.session-model-override/)

package/telegram-plugin/tests/model-command.test.ts

@@ -32,6 +32,13 @@ import {
   parseModelSwitchTarget,
   modelFamilyToken,
   MODEL_ALIASES,
+  servedModelMatchesRequested,
+  formatServedModelDivergenceLog,
+  formatServedModelDivergenceCard,
+  buildServedModelDivergenceHandler,
+  deliverModelSwitchBootNotice,
+  unvalidatedIdCaveat,
+  type ModelBootCardDeps,
   type ModelCommandDeps,
 } from "../gateway/model-command.js";
 
@@ -691,3 +698,216 @@ describe("modelFamilyToken", () => {
     expect(modelFamilyToken("sr-gemini-2.5-flash")).toBe("sr-gemini-2.5-flash");
   });
 });
+
+// ── #3427 item 4: requested-vs-served divergence (fallback-model masking) ────
+
+describe("servedModelMatchesRequested", () => {
+  it("matches a requested alias against its resolved full id (family)", () => {
+    expect(servedModelMatchesRequested("sonnet", "claude-sonnet-5")).toBe(true);
+    expect(servedModelMatchesRequested("opus", "claude-opus-4-8")).toBe(true);
+    expect(servedModelMatchesRequested("fable", "claude-fable-5")).toBe(true);
+  });
+
+  it("flags a requested alias served by a DIFFERENT family (fallback substituted)", () => {
+    expect(servedModelMatchesRequested("sonnet", "claude-opus-4-8")).toBe(false);
+    expect(servedModelMatchesRequested("haiku", "claude-sonnet-5")).toBe(false);
+  });
+
+  it("matches a full id exactly and as a date-stamped descendant", () => {
+    expect(servedModelMatchesRequested("claude-sonnet-5", "claude-sonnet-5")).toBe(true);
+    expect(servedModelMatchesRequested("claude-sonnet-5", "claude-sonnet-5-20260203")).toBe(true);
+    expect(servedModelMatchesRequested("Claude-Sonnet-5", "claude-sonnet-5")).toBe(true);
+  });
+
+  it("flags an invalid/unknown full id served by the fallback — the masking case", () => {
+    // THE #3427 item-4 case: `/model claude-sonnet-9` (nonexistent) launches,
+    // --fallback-model silently serves opus. A test that wouldn't fail on the
+    // masking is not a test: this must be a MISMATCH.
+    expect(servedModelMatchesRequested("claude-sonnet-9", "claude-opus-4-8")).toBe(false);
+    // Same-family but wrong version is still a mismatch (sonnet-9 ≠ sonnet-5).
+    expect(servedModelMatchesRequested("claude-sonnet-9", "claude-sonnet-5")).toBe(false);
+  });
+
+  it("is conservative: non-claude served ids and non-comparable requests never accuse", () => {
+    // LiteLLM/sr-* served names are not deterministically comparable.
+    expect(servedModelMatchesRequested("sr-glm-5", "glm-5")).toBe(true);
+    expect(servedModelMatchesRequested("claude-sonnet-5", "sr-glm-5")).toBe(true);
+    // Legacy friendly-label overrides ("Opus 4.8") are not comparable either.
+    expect(servedModelMatchesRequested("Opus 4.8", "claude-opus-4-8")).toBe(true);
+    // The default sentinel never diverges.
+    expect(servedModelMatchesRequested("default", "claude-opus-4-8")).toBe(true);
+  });
+
+  it("L3 (#3437): legacy id shapes (family after version) never false-accuse an alias request", () => {
+    // `claude-3-opus-20240229` → modelFamilyToken yields "3", not "opus"; the
+    // segment fallback must still match the alias.
+    expect(servedModelMatchesRequested("opus", "claude-3-opus-20240229")).toBe(true);
+    expect(servedModelMatchesRequested("haiku", "claude-3-5-haiku-20241022")).toBe(true);
+    // …while a genuinely different family still fires.
+    expect(servedModelMatchesRequested("sonnet", "claude-3-opus-20240229")).toBe(false);
+  });
+});
+
+describe("served-model divergence formatters (#3427 item 4)", () => {
+  it("log line is greppable and names requested + served", () => {
+    const log = formatServedModelDivergenceLog({
+      agent: "klanker",
+      requested: "claude-sonnet-9",
+      served: "claude-opus-4-8",
+    });
+    expect(log).toContain("gw /model served-model DIVERGENCE agent=klanker");
+    expect(log).toContain("requested=claude-sonnet-9");
+    expect(log).toContain("served=claude-opus-4-8");
+    expect(log.endsWith("\n")).toBe(true);
+  });
+
+  it("card warns, names both models in backticks, and says how to recover", () => {
+    const card = formatServedModelDivergenceCard({
+      requested: "claude-sonnet-9",
+      served: "claude-opus-4-8",
+    });
+    expect(card).toContain("⚠️");
+    expect(card).toContain("`claude-opus-4-8`");
+    expect(card).toContain("`claude-sonnet-9`");
+    expect(card).toContain("/model");
+    expect(card).not.toContain("✅");
+  });
+
+  it("M2 (#3437): the card and log name BOTH causes — never a flat 'invalid' accusation", () => {
+    // --fallback-model also substitutes on transient overload/unavailability;
+    // the signal cannot distinguish that from a bogus id, so neither surface
+    // may assert invalidity as fact.
+    const card = formatServedModelDivergenceCard({
+      requested: "claude-sonnet-9",
+      served: "claude-opus-4-8",
+    });
+    expect(card).toContain("temporarily unavailable");
+    expect(card).toContain("invalid");
+    expect(card).toContain("If it persists");
+    expect(card).toContain("Either"); // hedged alternatives, not an assertion of invalidity
+    const log = formatServedModelDivergenceLog({
+      agent: "a", requested: "claude-sonnet-9", served: "claude-opus-4-8",
+    });
+    expect(log).toContain("invalid/unknown OR model transiently unavailable");
+  });
+});
+
+describe("boot /model cards — buildServedModelDivergenceHandler / deliverModelSwitchBootNotice (#2996 extraction)", () => {
+  function makeCardDeps(overrides: Partial<ModelBootCardDeps> = {}) {
+    const logs: string[] = [];
+    const sends: Array<{ chatId: string; body: string; opts: Record<string, unknown> }> = [];
+    const deps: ModelBootCardDeps = {
+      agent: "klanker",
+      chat: { chatId: "-100123", threadId: 42 },
+      log: (line) => { logs.push(line); },
+      sendCard: (chatId, body, opts) => {
+        sends.push({ chatId, body, opts });
+        return Promise.resolve();
+      },
+      ...overrides,
+    };
+    return { deps, logs, sends };
+  }
+
+  it("divergence handler logs the DIVERGENCE line and sends the card to the marker chat + thread", () => {
+    const { deps, logs, sends } = makeCardDeps();
+    buildServedModelDivergenceHandler(deps)({ requested: "claude-sonnet-9", served: "claude-opus-4-8" });
+    expect(logs.some((l) => l.includes("gw /model served-model DIVERGENCE agent=klanker"))).toBe(true);
+    expect(sends).toHaveLength(1);
+    expect(sends[0].chatId).toBe("-100123");
+    expect(sends[0].body).toContain("`claude-opus-4-8`");
+    expect(sends[0].opts).toEqual({ parse_mode: "Markdown", message_thread_id: 42 });
+  });
+
+  it("divergence handler with NO marker chat still logs but never sends", () => {
+    const { deps, logs, sends } = makeCardDeps({ chat: null });
+    buildServedModelDivergenceHandler(deps)({ requested: "sonnet", served: "claude-opus-4-8" });
+    expect(logs.some((l) => l.includes("DIVERGENCE"))).toBe(true);
+    expect(sends).toHaveLength(0);
+  });
+
+  it("divergence card send rejection is swallowed and logged — never throws", async () => {
+    const { deps, logs } = makeCardDeps({
+      sendCard: () => Promise.reject(new Error("THREAD_NOT_FOUND")),
+    });
+    expect(() =>
+      buildServedModelDivergenceHandler(deps)({ requested: "claude-sonnet-9", served: "claude-opus-4-8" }),
+    ).not.toThrow();
+    await new Promise((r) => setTimeout(r, 0));
+    expect(logs.some((l) => l.includes("served-model divergence send failed: THREAD_NOT_FOUND"))).toBe(true);
+  });
+
+  it("boot notice: applied confirmation sends the ✅ card (thread-aware), no suppress log", () => {
+    const { deps, logs, sends } = makeCardDeps();
+    deliverModelSwitchBootNotice({
+      ...deps,
+      confirmation: { kind: "applied", launched: "claude-opus-4-8" },
+      hasSessionModelAlert: false,
+    });
+    expect(sends).toHaveLength(1);
+    expect(sends[0].body).toContain("✅ Now running `claude-opus-4-8`");
+    expect(sends[0].opts).toEqual({ parse_mode: "Markdown", message_thread_id: 42 });
+    expect(logs).toHaveLength(0);
+  });
+
+  it("boot notice: not-applied + .session-model-alert suppresses the card and writes the suppress log", () => {
+    const { deps, logs, sends } = makeCardDeps({ chat: { chatId: "-100123", threadId: null } });
+    deliverModelSwitchBootNotice({
+      ...deps,
+      confirmation: { kind: "not-applied", target: "fable", revertedTo: "claude-sonnet-5" },
+      hasSessionModelAlert: true,
+    });
+    expect(sends).toHaveLength(0);
+    expect(logs.some((l) => l.includes("suppressing not-applied confirmation") && l.includes("target=fable"))).toBe(true);
+  });
+
+  it("boot notice: no marker chat is a full no-op (matches pre-extraction inline behavior)", () => {
+    const { deps, logs, sends } = makeCardDeps({ chat: null });
+    deliverModelSwitchBootNotice({
+      ...deps,
+      confirmation: { kind: "not-applied", target: "fable", revertedTo: "claude-sonnet-5" },
+      hasSessionModelAlert: true,
+    });
+    expect(sends).toHaveLength(0);
+    expect(logs).toHaveLength(0);
+  });
+
+  it("boot notice: threadId null omits message_thread_id from send opts", () => {
+    const { deps, sends } = makeCardDeps({ chat: { chatId: "777", threadId: null } });
+    deliverModelSwitchBootNotice({
+      ...deps,
+      confirmation: { kind: "default", launched: "claude-sonnet-5" },
+      hasSessionModelAlert: false,
+    });
+    expect(sends).toHaveLength(1);
+    expect(sends[0].chatId).toBe("777");
+    expect(sends[0].opts).toEqual({ parse_mode: "Markdown" });
+  });
+});
+
+describe("unvalidatedIdCaveat — immediate fail-fast warn on free-text claude-* ids (#3427 item 4)", () => {
+  const esc = { escapeHtml: (s: string) => s };
+
+  it("warns for a full claude-* id (cannot be pre-validated)", () => {
+    const caveat = unvalidatedIdCaveat(esc, "claude-sonnet-9");
+    expect(caveat).not.toBeNull();
+    expect(caveat).toContain("claude-sonnet-9");
+    expect(caveat).toContain("fallback");
+  });
+
+  it("stays silent for aliases, sr-* ids and the default sentinel", () => {
+    expect(unvalidatedIdCaveat(esc, "opus")).toBeNull();
+    expect(unvalidatedIdCaveat(esc, "sonnet")).toBeNull();
+    expect(unvalidatedIdCaveat(esc, "sr-glm-5")).toBeNull();
+    expect(unvalidatedIdCaveat(esc, "default")).toBeNull();
+  });
+
+  it("the /model set ACK carries the caveat for a typed full id — and not for an alias", async () => {
+    const { deps } = makeDeps();
+    const full = await handleModelCommand({ kind: "set", model: "claude-sonnet-9" }, deps);
+    expect(full.text).toContain("can't be validated before launch");
+    expect(full.text).toContain("fallback");
+    const alias = await handleModelCommand({ kind: "set", model: "opus" }, deps);
+    expect(alias.text).not.toContain("can't be validated before launch");
+  });
+});