switchroom 0.19.2 → 0.19.4

package/telegram-plugin/gateway/auth-command.ts

@@ -44,7 +44,19 @@ export type ParsedAuthCommand =
   | { kind: 'list' }
   | { kind: 'use'; label: string }
   | { kind: 'rotate' }
-  | { kind: 'add'; label: string }
+  | {
+      kind: 'add'
+      label: string
+      /**
+       * Re-auth an EXISTING account label in place (broker `addAccount(...,
+       * replace=true)`). Set by the `/auth readd <label>` verb (and
+       * `/auth add <label> --replace`). Plain `/auth add` leaves it false —
+       * the broker rejects a duplicate label, which is the desired guard for
+       * a fresh add. `/auth readd` is the path to widen scope on the 3 pooled
+       * accounts without renaming them.
+       */
+      replace: boolean
+    }
   | { kind: 'cancel' }
   | {
       kind: 'provider-add'
@@ -149,12 +161,25 @@ export function parseAuthCommand(text: string): ParsedAuthCommand | null {
       if (!label) return { kind: 'help', reason: 'Usage: /auth use <label>' }
       return { kind: 'use', label }
     }
-    case 'add': {
-      const label = parts[1]
-      if (!label) return { kind: 'help', reason: 'Usage: /auth add <label>' }
+    case 'add':
+    case 'readd': {
+      // `readd` is `add` with replace=true; `add --replace` is the same.
+      const positional = parts.slice(1).filter((t) => !t.startsWith('--'))
+      const flags = new Set(
+        parts.slice(1).filter((t) => t.startsWith('--')).map((t) => t.toLowerCase()),
+      )
+      const label = positional[0]
+      const usage = verb === 'readd' ? 'Usage: /auth readd <label>' : 'Usage: /auth add <label>'
+      if (!label) return { kind: 'help', reason: usage }
       const err = validateAuthAddLabel(label)
       if (err) return { kind: 'help', reason: err }
-      return { kind: 'add', label }
+      for (const f of flags) {
+        if (f !== '--replace') {
+          return { kind: 'help', reason: `Unknown flag \`${codeSpanSafe(f)}\` for \`/auth ${verb}\`.` }
+        }
+      }
+      const replace = verb === 'readd' || flags.has('--replace')
+      return { kind: 'add', label, replace }
     }
     case 'cancel':
       return { kind: 'cancel' }
@@ -451,6 +476,7 @@ export async function handleAuthCommand(
         `  \`/auth use <label>\` — admin: swap the fleet to <label>\n` +
         `  \`/auth rotate\` — admin: cycle to next non-exhausted fallback\n` +
         `  \`/auth add <label>\` — admin: OAuth-add a new Anthropic account from chat\n` +
+        `  \`/auth readd <label>\` — admin: re-auth an EXISTING account in place (widen scope)\n` +
         `  \`/auth google add <email>\` — admin: Telegram-native Google account add/re-auth\n` +
         `  \`/auth microsoft add <email>\` — admin: Telegram-native Microsoft account add/re-auth\n` +
         `  \`/auth cancel\` — abort an \`/auth add\` or provider add in progress\n` +
@@ -819,6 +845,113 @@ function isAdmin(ctx: AuthCommandContext): boolean {
   return ctx.isAdmin === true
 }
 
+/**
+ * The scope every `server:` mode agent needs from a pooled account for
+ * fable/Claude 7-day usage reporting. Absence is the whole reason
+ * `/auth readd` exists (setup-token tokens can't carry it).
+ */
+export const REQUIRED_USAGE_SCOPE = 'user:profile'
+
+/**
+ * Precheck for the gateway `/auth add`/`readd` dispatch. Returns a
+ * user-facing error string when the request is incoherent against current
+ * broker state, else null.
+ *
+ *   - `readd` (replace=true) of a label that does NOT exist → error (there's
+ *     nothing to re-auth; the operator wants `/auth add`).
+ *   - plain `add` (replace=false) of a label that ALREADY exists → error
+ *     (the broker would reject the duplicate anyway; fail fast with a clear
+ *     message pointing at `/auth readd`).
+ *
+ * Kept pure so it's unit-testable without a live broker.
+ */
+export function readdPrecheckError(
+  label: string,
+  replace: boolean,
+  labelExists: boolean,
+): string | null {
+  if (replace && !labelExists) {
+    return (
+      `**/auth readd:** no account named \`${codeSpanSafe(label)}\` to re-auth. ` +
+      `Run \`/auth show\` for the current list, or \`/auth add ${codeSpanSafe(label)}\` to add it fresh.`
+    )
+  }
+  if (!replace && labelExists) {
+    return (
+      `**/auth add:** \`${codeSpanSafe(label)}\` already exists. ` +
+      `Use \`/auth readd ${codeSpanSafe(label)}\` to re-authenticate it in place (e.g. to widen scope).`
+    )
+  }
+  return null
+}
+
+/**
+ * Broker-backed precheck for the `/auth add` / `/auth readd` chat verb.
+ * Resolves a broker client (via the caller-supplied getter), queries live
+ * account state, and returns the {@link readdPrecheckError} message (or null
+ * when the request is valid) so the gateway can fail fast before spinning up
+ * a tmux/OAuth flow.
+ *
+ * Best-effort by design: if the broker is unreachable (getter returns null or
+ * `listState` throws) this returns null and lets `addAccountViaBroker` enforce
+ * existence at add time. Kept here — beside `readdPrecheckError` — so the
+ * gateway carries only a thin call site (switchroom#2996 line-ratchet: no new
+ * inline bodies in gateway.ts).
+ */
+export async function runReaddPrecheck(
+  getClient: () => Promise<AuthBrokerClient | null>,
+  label: string,
+  replace: boolean,
+): Promise<string | null> {
+  try {
+    const client = await getClient()
+    if (!client) return null
+    const state = await client.listState()
+    const exists = state.accounts.some((a) => a.label === label)
+    return readdPrecheckError(label, replace, exists)
+  } catch {
+    // broker unreachable — skip precheck; addAccountViaBroker enforces.
+    return null
+  }
+}
+
+/**
+ * Render the "granted scopes" tail for a successful `/auth add`/`readd`.
+ * Reads the scopes STRUCTURALLY from `credentials.claudeAiOauth.scopes`
+ * (never scraped from the pane). Returns the text plus a `warn` flag set
+ * when {@link REQUIRED_USAGE_SCOPE} is absent, so the caller can surface a
+ * loud warning at add time instead of a silent `/usage` failure later.
+ */
+export function formatGrantedScopesReply(scopes: string[] | undefined): {
+  text: string
+  hasUsageScope: boolean
+} {
+  const list = Array.isArray(scopes) ? scopes.filter((s) => typeof s === 'string') : []
+  const hasUsageScope = list.includes(REQUIRED_USAGE_SCOPE)
+  if (list.length === 0) {
+    return {
+      text:
+        `\n⚠️ **No scopes reported** on the new token — could not confirm \`${REQUIRED_USAGE_SCOPE}\`. ` +
+        `7-day usage reporting may not work. Re-run \`/auth readd\` if usage is missing.`,
+      hasUsageScope: false,
+    }
+  }
+  const rendered = list.map((s) => `\`${codeSpanSafe(s)}\``).join(', ')
+  if (hasUsageScope) {
+    return {
+      text: `\nGranted scopes: ${rendered}\n✓ \`${REQUIRED_USAGE_SCOPE}\` present — 7-day usage reporting is unlocked.`,
+      hasUsageScope: true,
+    }
+  }
+  return {
+    text:
+      `\nGranted scopes: ${rendered}\n` +
+      `⚠️ **\`${REQUIRED_USAGE_SCOPE}\` is MISSING** — 7-day usage reporting will not work for this account. ` +
+      `This usually means the narrow \`setup-token\` minter was used. Re-run \`/auth readd <label>\` with the broad login to fix.`,
+    hasUsageScope: false,
+  }
+}
+
 /**
  * Choose the next account `auth rotate` should set active. Walks
  * `fallback_order` starting *after* the currently-active label,

package/telegram-plugin/gateway/gateway.ts

@@ -366,10 +366,10 @@ import { createFleetFallbackResumeGate } from '../fleet-fallback-resume.js'
 import { resolveExhaustUntil } from './exhaust-until.js'
 import {
   pendingAuthAddFlows,
-  startAccountAuthSession,
   submitAccountAuthCode,
   cancelAccountAuthSession,
   cleanScratchDir as cleanAuthAddScratchDir,
+  handleAuthAddOrCancel,
 } from './auth-add-flow.js'
 import {
   pendingLoopbackFlows,
@@ -483,6 +483,7 @@ import {
 } from '../turn-flush-safety.js'
 import {
   resolveReplyOwnerTurnId,
+  type AnswerDeliveredLatch,
 } from '../reply-owner-resolve.js'
 // PR A — deterministic answer-ready quiescence flush (late-delivery fix).
 import {
@@ -539,8 +540,10 @@ import {
   handleModelCommand,
   classifyModelSwitchConfirmation,
   formatModelRelaunchDiagLog,
-  formatModelSwitchConfirmationBody,
-  formatModelRelaunchSuppressNotAppliedLog,
+  servedModelMatchesRequested,
+  buildServedModelDivergenceHandler,
+  deliverModelSwitchBootNotice,
+  type ModelBootCardDeps,
   buildModelMenu,
   handleModelMenuCallback,
   isValidModelArg,
@@ -3412,18 +3415,33 @@ export type CurrentTurn = {
   // false ONLY at turn start, mirroring `activityEverOpened`'s sticky-true
   // contract.
   finalAnswerEverDelivered: boolean
-  // 2026-07 double-reply-on-DM fix (Part 2 — race backstop). Set true
-  // SYNCHRONOUSLY at turn-flush FIRE time (before the ~500 ms async send and
-  // before `flushedTurnSupersede.record`) when the flush delivers a SUBSTANTIVE
-  // (≥`FLUSH_SUBSTANTIVE_MIN_CHARS`) terminal answer, and also set when a
-  // substantive `reply` sends. It persists on the ended turn in
+  // 2026-07 double-reply-on-DM fix (Part 2 — race backstop), SOURCE-TAGGED
+  // since #3426. Set to 'flush' SYNCHRONOUSLY at turn-flush FIRE time (before
+  // the ~500 ms async send and before `flushedTurnSupersede.record`) and at
+  // supersede-record consumption (the resurrection window); set to 'reply'
+  // when a substantive `reply` sends. It persists on the ended turn in
   // `recentTurnsById`, so a LATE reply landing in the flush's post-fire
   // pre-record race window (where `flushedTurnSupersede` finds no record to
   // delete yet) resolves this turn via the unified owner resolver, sees the
-  // latch already set, and suppresses itself — closing the residual window Part
-  // 1's supersede cannot reach. Scoped to the substantive floor so an interim
-  // sub-floor ack NEITHER sets nor trips it. Reset false at turn start.
-  answerDelivered: boolean
+  // 'flush' latch already set, and suppresses itself — closing the residual
+  // window Part 1's supersede cannot reach. The 'reply' tag deliberately does
+  // NOT suppress a late reply (#3426): a substantive interim ack followed by
+  // an async sub-agent handback (which lands with NO live gateway turn and
+  // resolves this ended turn as owner via the latest-ended tier) must deliver,
+  // not silently drop. Scoped to the substantive floor so an interim sub-floor
+  // ack NEITHER sets nor trips it. Reset false at turn start.
+  answerDelivered: AnswerDeliveredLatch
+  // #3429 — the text the turn-flush backstop delivered (or is mid-delivering)
+  // as this turn's answer. Stamped SYNCHRONOUSLY alongside the 'flush' latch
+  // arm (stream-render fire site; outbound-send-path supersede-consumption
+  // resurrection site) and cleared wherever that latch is reset. Lets the
+  // late-reply suppression discriminate BY CONTENT between the flushed answer
+  // landing again (suppress — the flush race) and a genuinely new async
+  // handback attributed to this flush-delivered ended turn (deliver fresh —
+  // suppressing/editing it is the #3429 silent client-side drop), including in
+  // the post-fire pre-record window where no supersede record exists yet.
+  // Null when no flush armed this turn. Reset null at turn start.
+  flushedAnswerText: string | null
   // 2026-07 double-reply-on-DM fix (F2 — recency bound). Wall-clock ms the turn
   // ENDED (stamped once by `endCurrentTurnAtomic`), or null while still live.
   // The `findLatestEndedTurnForChat` supersede tier carries DESTRUCTIVE
@@ -3673,8 +3691,9 @@ const currentTurnMap = new CurrentTurnMap<CurrentTurn>()
 // is seq-stamped and `resolve()` prefers the NEWER observation, so neither
 // source can go stale behind the other (session-model-source.ts, pinned by
 // tests/session-model-source.test.ts). buildAgentMetadata reads resolve();
-// the /model command paths write via setOverride.
-const sessionModelSource = createSessionModelSource()
+// the /model command paths write via setOverride. The comparator arms the
+// #3427 requested-vs-served tripwire (handler registered at boot rehydration).
+const sessionModelSource = createSessionModelSource({ servedMatchesRequested: servedModelMatchesRequested })
 // Captures the most-recently-started turn's sessionChatId. Unlike currentTurn,
 // this is NOT cleared by the silence poke (firePoke/clearTurnStarted). It lets
 // the Bug B fallback in executeReply route to the correct chat even when the
@@ -20859,68 +20878,17 @@ bot.command("auth", async ctx => {
   // handleAuthCommand which only needs the narrow broker surface.
   const chatId = String(ctx.chat?.id ?? '')
   if (parsed.kind === 'add' || parsed.kind === 'cancel') {
-    if (!isAuthAdmin({ isAdmin })) {
-      await switchroomReply(
-        ctx,
-        `**Not authorized.** \`/auth ${parsed.kind}\` is admin-only.\n` +
-          `Set \`admin: true\` on this agent in switchroom.yaml to unlock ` +
-          `(the same flag that gates \`/agents\`, \`/restart\`, ` +
-          `\`/update\` etc.).`,
-        { html: true },
-      )
-      return
-    }
-    // PR3 supergroup-mode: key auth-add flows by (chat, thread) so
-    // separate flows in two topics of one supergroup can't collide.
-    // In DM chats message_thread_id is undefined → key collapses to
-    // `chatId:_`, identical to today's behavior.
-    const authAddKey = chatKey(chatId, ctx.message?.message_thread_id ?? null) as string
-    if (parsed.kind === 'cancel') {
-      const existing = pendingAuthAddFlows.get(authAddKey)
-      if (!existing) {
-        await switchroomReply(ctx, "_No pending \`/auth add\` flow in this chat._", { html: true })
-        return
-      }
-      cancelAccountAuthSession(existing)
-      pendingAuthAddFlows.delete(authAddKey)
-      await switchroomReply(ctx, "Cancelled.", { html: true })
-      return
-    }
-    // parsed.kind === 'add'
-    if (pendingAuthAddFlows.has(authAddKey)) {
-      await switchroomReply(
-        ctx,
-        "_An \`/auth add\` flow is already in progress for this chat. " +
-          "Finish the paste, or send \`/auth cancel\` to abort._",
-        { html: true },
-      )
-      return
-    }
-    try {
-      const { loginUrl, scratchDir, tmuxSocket, tmuxSession } = await startAccountAuthSession(parsed.label)
-      pendingAuthAddFlows.set(authAddKey, {
-        label: parsed.label,
-        scratchDir,
-        tmuxSocket,
-        tmuxSession,
-        startedAt: Date.now(),
-      })
-      await switchroomReply(
-        ctx,
-        `**Adding account** \`${parsed.label}\`\n\n` +
-          `1. Open this URL on your phone:\n${loginUrl}\n\n` +
-          `2. Log into Anthropic, copy the code Claude shows.\n` +
-          `3. Paste it back here.\n\n` +
-          `Send \`/auth cancel\` to abort.`,
-        { html: true },
-      )
-    } catch (err) {
-      await switchroomReply(
-        ctx,
-        `**/auth add failed:** ${escapeHtmlForTg((err as Error)?.message ?? String(err))}`,
-        { html: true },
-      )
-    }
+    // Gateway-routed `/auth add|readd|cancel` — extracted to
+    // handleAuthAddOrCancel in auth-add-flow.ts (switchroom#2996 ratchet).
+    await handleAuthAddOrCancel({
+      parsed,
+      isAdmin,
+      currentAgent,
+      chatId,
+      threadId: ctx.message?.message_thread_id ?? null,
+      reply: (text: string) => switchroomReply(ctx, text, { html: true }),
+      escapeHtml: escapeHtmlForTg,
+    })
     return
   }
 
@@ -23909,7 +23877,23 @@ async function startGateway(): Promise<void> {  // #2996 P0c: the boot IIFE, now
                 // real post-boot signal (`.active-session-model`), never from a
                 // scraped pane or an optimistic record.
                 const isApplyBoot = launched.length > 0 && launched !== configured
-                sessionModelSource.setOverride(isApplyBoot ? launched : null)
+                // { verify: true } (#3427 item 4 / H1): ONLY this site arms the
+                // requested-vs-served tripwire — `launched` IS the token of the
+                // session now serving. Command-time setOverride never arms.
+                sessionModelSource.setOverride(isApplyBoot ? launched : null, { verify: true })
+                // Boot /model cards (#3427): the divergence tripwire warn and
+                // the switch confirmation share one deps surface; the card
+                // logic lives in model-command.ts (#2996 ratchet).
+                const modelBootCardDeps: ModelBootCardDeps = {
+                  agent: getMyAgentName(),
+                  chat: modelSwitchMarkerChat,
+                  log: (line) => process.stderr.write(line),
+                  // allow-raw-bot-api: one-shot boot /model cards (divergence warn + switch confirmation), same shape as the session-model alert relay below
+                  sendCard: (chatId, body, opts) => lockedBot.api.sendMessage(chatId, body, opts),
+                }
+                if (isApplyBoot) {
+                  sessionModelSource.setDivergenceHandler(buildServedModelDivergenceHandler(modelBootCardDeps))
+                }
                 // F1/N4: classify + log + one confirmation card. Formatters live
                 // in model-command.ts so this file does not inflate (#2996 ratchet).
                 const confirmation = modelSwitchReason != null
@@ -23928,30 +23912,13 @@ async function startGateway(): Promise<void> {  // #2996 P0c: the boot IIFE, now
                     isApplyBoot,
                   }),
                 )
-                if (confirmation != null && modelSwitchMarkerChat) {
-                  const chat = modelSwitchMarkerChat
-                  const hasSessionModelAlert = existsSync(join(smAgentDir, '.session-model-alert'))
-                  if (confirmation.kind === 'not-applied' && hasSessionModelAlert) {
-                    process.stderr.write(
-                      formatModelRelaunchSuppressNotAppliedLog({
-                        agent: getMyAgentName(),
-                        target: confirmation.target,
-                      }),
-                    )
-                  } else {
-                    const body = formatModelSwitchConfirmationBody(confirmation)
-                    // allow-raw-bot-api: one-shot boot confirmation, same shape as the session-model alert relay below
-                    void lockedBot.api
-                      .sendMessage(chat.chatId, body, {
-                        parse_mode: 'Markdown',
-                        ...(chat.threadId != null ? { message_thread_id: chat.threadId } : {}),
-                      })
-                      .catch((err: unknown) =>
-                        process.stderr.write(
-                          `telegram gateway: model-switch confirmation send failed: ${(err as Error)?.message ?? String(err)}\n`,
-                        ),
-                      )
-                  }
+                if (confirmation != null) {
+                  // #3427 item 2: card-vs-suppress decision is pure + behaviorally tested.
+                  deliverModelSwitchBootNotice({
+                    ...modelBootCardDeps,
+                    confirmation,
+                    hasSessionModelAlert: existsSync(join(smAgentDir, '.session-model-alert')),
+                  })
                 }
               } catch { /* leave override as-is on a bad read */ }
             }

package/telegram-plugin/gateway/inbound-interceptors.ts

@@ -18,6 +18,7 @@
 import type { Context } from 'grammy'
 import type { ReactionTypeEmoji } from 'grammy/types'
 import { parseStopKeyword, buildStopReply } from './stop-command.js'
+import { formatGrantedScopesReply } from './auth-command.js'
 import { decideInterruptTiming, resolveSafeBoundaryEnabled } from './interrupt-defer.js'
 import { naturalAction } from '../permission-title.js'
 import { richMessage } from '../rich-send.js'
@@ -463,15 +464,24 @@ export async function interceptAuthAdd(
     deps.pendingAuthAddFlows.delete(p.interceptKey)
     try {
       const credentials = await deps.submitAccountAuthCode(pendingAdd, p.text.trim())
+      const replace = pendingAdd.replace === true
       try {
-        await deps.addAccountViaBroker(pendingAdd.label, credentials, { replace: false })
+        await deps.addAccountViaBroker(pendingAdd.label, credentials, { replace })
         // success — wipe scratch dir now that the broker owns the creds
         deps.cleanAuthAddScratchDir(pendingAdd.scratchDir)
+        // Read the minted scopes STRUCTURALLY (never scraped) and surface
+        // them so a scope regression (missing user:profile) is caught at add
+        // time, not at /usage time.
+        const scopeReply = formatGrantedScopesReply(
+          (credentials as { claudeAiOauth?: { scopes?: string[] } }).claudeAiOauth?.scopes,
+        )
+        const verb = replace ? 're-authenticated' : 'added'
         await deps.switchroomReply(
           p.ctx,
-          `✓ Account \`${pendingAdd.label}\` added.\n` +
+          `✓ Account \`${pendingAdd.label}\` ${verb}.\n` +
             `The fleet's active account hasn't changed. Send ` +
-            `\`/auth use ${deps.escapeHtmlForTg(pendingAdd.label)}\` to switch to it.`,
+            `\`/auth use ${deps.escapeHtmlForTg(pendingAdd.label)}\` to switch to it.` +
+            scopeReply.text,
           { html: true },
         )
       } catch (brokerErr) {

package/telegram-plugin/gateway/model-command.ts

@@ -293,6 +293,187 @@ export function formatModelRelaunchSuppressNotAppliedLog(input: {
   )
 }
 
+/**
+ * The single boot-time notification decision for a classified /model switch
+ * (#3427 item 2): either the ONE confirmation card (green applied/default or
+ * the ⚠️ not-applied warn), or — LOW-2 dedup — a suppress log when start.sh
+ * wrote a TAILORED `.session-model-alert` for this boot that already explains
+ * why the switch didn't apply (the alert relay is the more specific message,
+ * so the generic not-applied card would double-warn). Pure so the decision is
+ * unit-testable end-to-end (classify → notice) without booting the gateway;
+ * gateway.ts only sends `card` bodies / writes `suppress` logs.
+ */
+export type ModelSwitchBootNotice =
+  | { kind: 'card'; body: string }
+  | { kind: 'suppress'; log: string }
+
+export function resolveModelSwitchBootNotice(input: {
+  agent: string
+  confirmation: ModelSwitchConfirmation
+  hasSessionModelAlert: boolean
+}): ModelSwitchBootNotice {
+  const { agent, confirmation, hasSessionModelAlert } = input
+  if (confirmation.kind === 'not-applied' && hasSessionModelAlert) {
+    return {
+      kind: 'suppress',
+      log: formatModelRelaunchSuppressNotAppliedLog({ agent, target: confirmation.target }),
+    }
+  }
+  return { kind: 'card', body: formatModelSwitchConfirmationBody(confirmation) }
+}
+
+/**
+ * Requested-vs-served divergence gate (#3427 item 4). `--fallback-model` masks
+ * a shape-valid but UNKNOWN requested Claude id: claude silently serves the
+ * fallback while `.active-session-model` (and the boot confirmation) carry the
+ * requested token, until the first assistant transcript line reclaims /status.
+ * That window used to self-heal SILENTLY — the operator was never told their
+ * requested id was bogus. This comparator lets the session-model source flag
+ * the divergence deterministically at the FIRST possible post-launch signal
+ * (the first assistant line's `message.model`).
+ *
+ * Deliberately conservative — return true ("matches") whenever the pair is not
+ * DETERMINISTICALLY comparable, so a false accusation is impossible:
+ *   - served non-`claude-*` ids (sr-* / LiteLLM-mapped names) are skipped: the
+ *     proxy may echo an alias, a mapped id, or the raw route name;
+ *   - a requested alias (opus/sonnet/haiku/fable) family-matches its resolved
+ *     full id (`sonnet` ≡ `claude-sonnet-5-…`) via modelFamilyToken;
+ *   - a requested full `claude-*` id must be served exactly, or as a
+ *     date-stamped descendant (`claude-sonnet-5` ≡ `claude-sonnet-5-20260203`);
+ *   - anything else (sr-* requests, legacy friendly labels like "Opus 4.8")
+ *     is not comparable → true.
+ */
+export function servedModelMatchesRequested(requested: string, served: string): boolean {
+  const req = requested.trim().toLowerCase()
+  const srv = served.trim().toLowerCase()
+  if (!srv.startsWith('claude-')) return true
+  if ((MODEL_ALIASES as readonly string[]).includes(req)) {
+    if (req === 'default') return true
+    if (modelFamilyToken(srv) === req) return true
+    // L3 (#3437 review): legacy id shapes put the family AFTER the version
+    // (`claude-3-opus-20240229` → first segment "3", not "opus"). Accept any
+    // dash-segment equal to the alias — widens toward "match" only, so it can
+    // suppress a real accusation in weird shapes but never create a false one.
+    return srv.slice('claude-'.length).split('-').includes(req)
+  }
+  if (req.startsWith('claude-')) {
+    return srv === req || srv.startsWith(req + '-')
+  }
+  return true
+}
+
+/**
+ * Greppable stderr line for a requested-vs-served divergence (#3427 item 4).
+ * Names BOTH candidate causes (M2): `--fallback-model` substitutes for an
+ * invalid/unknown id AND for a transiently-unavailable one — the signal alone
+ * cannot distinguish them, so the log must not assert "invalid".
+ */
+export function formatServedModelDivergenceLog(input: {
+  agent: string
+  requested: string
+  served: string
+}): string {
+  return (
+    'telegram gateway: gw /model served-model DIVERGENCE agent=' +
+    input.agent +
+    ' requested=' +
+    input.requested +
+    ' served=' +
+    input.served +
+    ' (--fallback-model substituted: requested id invalid/unknown OR model transiently unavailable)\n'
+  )
+}
+
+/** Operator card for a requested-vs-served divergence (#3427 item 4, M2-softened). */
+export function formatServedModelDivergenceCard(input: {
+  requested: string
+  served: string
+}): string {
+  return (
+    '⚠️ The first reply was served by `' +
+    input.served +
+    '`, not the requested `' +
+    input.requested +
+    '` — claude substituted the fallback model. Either the requested id is invalid/unknown, or the model was temporarily unavailable for that call (a transient substitution self-corrects on later replies). If it persists, re-issue `/model <valid id>` or `/model default`. `/status` always shows the model actually serving calls.'
+  )
+}
+
+/** The boot marker chat that initiated a /model switch (thread-aware). */
+export interface ModelBootCardTarget {
+  chatId: string
+  threadId: number | null
+}
+
+/**
+ * Injected side-effect surface for the boot-time /model cards (#3427): the
+ * served-model divergence warn and the switch confirmation share ONE raw
+ * Markdown send closure plus a stderr log sink. Lives here (not inline in
+ * gateway.ts's boot IIFE) so gateway.ts does not inflate (#2996 ratchet).
+ */
+export interface ModelBootCardDeps {
+  agent: string
+  /** null → no initiating chat known; cards are skipped, logs still write. */
+  chat: ModelBootCardTarget | null
+  log: (line: string) => void
+  sendCard: (
+    chatId: string,
+    body: string,
+    opts: { parse_mode: 'Markdown'; message_thread_id?: number },
+  ) => Promise<unknown>
+}
+
+/** One-shot fire-and-forget card to the marker chat; send failures log, never throw. */
+function sendModelBootCard(deps: ModelBootCardDeps, chat: ModelBootCardTarget, body: string, failLabel: string): void {
+  void deps
+    .sendCard(chat.chatId, body, {
+      parse_mode: 'Markdown',
+      ...(chat.threadId != null ? { message_thread_id: chat.threadId } : {}),
+    })
+    .catch((err: unknown) =>
+      deps.log(`telegram gateway: ${failLabel} send failed: ${(err as Error)?.message ?? String(err)}\n`),
+    )
+}
+
+/**
+ * Build the divergence-tripwire handler gateway.ts registers at the boot
+ * rehydration site (#3427 item 4): the first LIVE assistant line serving a
+ * different model (invalid id OR transient unavailability — --fallback-model
+ * substituted) logs + warns the operator. The override is KEPT (M2): freshness
+ * rules already make /status show the served model, and a transient
+ * substitution self-corrects without destroying the switch record.
+ */
+export function buildServedModelDivergenceHandler(
+  deps: ModelBootCardDeps,
+): (d: { requested: string; served: string }) => void {
+  return (d) => {
+    deps.log(formatServedModelDivergenceLog({ agent: deps.agent, requested: d.requested, served: d.served }))
+    if (deps.chat == null) return
+    sendModelBootCard(deps, deps.chat, formatServedModelDivergenceCard(d), 'served-model divergence')
+  }
+}
+
+/**
+ * Deliver the boot-time model-switch confirmation (#3427 item 2): resolve the
+ * card-vs-suppress decision (pure — resolveModelSwitchBootNotice) and either
+ * log the suppress line or send the card. No-op when no initiating chat is
+ * known — matching the pre-extraction inline gateway.ts behavior (the
+ * suppress log only ever wrote when a marker chat existed).
+ */
+export function deliverModelSwitchBootNotice(
+  deps: ModelBootCardDeps & { confirmation: ModelSwitchConfirmation; hasSessionModelAlert: boolean },
+): void {
+  if (deps.chat == null) return
+  const notice = resolveModelSwitchBootNotice({
+    agent: deps.agent,
+    confirmation: deps.confirmation,
+    hasSessionModelAlert: deps.hasSessionModelAlert,
+  })
+  if (notice.kind === 'suppress') {
+    deps.log(notice.log)
+    return
+  }
+  sendModelBootCard(deps, deps.chat, notice.body, 'model-switch confirmation')
+}
 
 export type ParsedModelCommand =
   | { kind: 'show' }
@@ -634,6 +815,23 @@ function relaunchErrorReply(
   return { text: `❌ Could not schedule model switch: ${deps.escapeHtml(msg)}`, html: true }
 }
 
+/**
+ * Fail-fast caveat (#3427 item 4) for a free-text full `claude-*` id: the
+ * gateway cannot pre-validate an arbitrary id against the API (Claude-native
+ * constraint — no raw API probes), so if the id is bogus `--fallback-model`
+ * silently serves the fallback. Say so IMMEDIATELY in the switch ack, and
+ * point at the first-reply tripwire that will catch it. Aliases and sr-* ids
+ * are vouched by their own gates (MODEL_ALIASES / the LiteLLM route probe),
+ * so only typed `claude-*` ids carry the caveat. Exported for tests.
+ */
+export function unvalidatedIdCaveat(
+  deps: Pick<ModelCommandDeps, 'escapeHtml'>,
+  model: string,
+): string | null {
+  if (!model.trim().toLowerCase().startsWith('claude-')) return null
+  return `_\`${deps.escapeHtml(model)}\` can't be validated before launch — if it isn't a real Claude model id, claude will silently serve the configured fallback model instead. I check the first reply and will warn if that happens._`
+}
+
 /** Schedule a carrier relaunch onto `model`, returning the deterministic ack. */
 async function scheduleRelaunchReply(
   deps: ModelCommandDeps,
@@ -645,7 +843,11 @@ async function scheduleRelaunchReply(
   } catch (err) {
     return relaunchErrorReply(deps, model, err)
   }
-  return { text: [switchingLine(deps, model), PERSIST_NOTE].join('\n'), html: true }
+  const caveat = unvalidatedIdCaveat(deps, model)
+  return {
+    text: [switchingLine(deps, model), ...(caveat ? [caveat] : []), PERSIST_NOTE].join('\n'),
+    html: true,
+  }
 }
 
 /** Schedule the `/model default` clear + revert relaunch, returning its ack. */