switchroom 0.18.29 → 0.18.31

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

@@ -84,6 +84,110 @@ export function isClaudeModel(name: string): boolean {
   return lower.startsWith('claude-')
 }
 
+/**
+ * The outcome of a `/model` apply-boot, derived purely from the DETERMINISTIC
+ * post-boot signals (never optimistic):
+ *
+ *   - `reason`     — the clean-shutdown marker reason that keyed this boot as a
+ *                    `/model` apply-boot, e.g.
+ *                    `user: /model fable (session-only relaunch, menu)`.
+ *   - `launched`   — the contents of `.active-session-model`: the model start.sh
+ *                    actually passed to `claude --model` this boot.
+ *   - `configured` — the resolved configured default model.
+ *
+ * Three outcomes:
+ *   - `applied`      — the launched model differs from the configured default, so
+ *                      the switch landed (a session-only override).
+ *   - `default`      — the operator asked for the configured default (`/model
+ *                      default`, or `/model <configured>`) and got it.
+ *   - `not-applied`  — the operator asked for a NON-default model, but the boot
+ *                      came back on the configured default: the switch SILENTLY
+ *                      failed to apply. The consume-once carrier was consumed by a
+ *                      boot that never launched the target (e.g. a wedged apply-boot
+ *                      that hit boot.lock_stale_recovered_boot_mismatch and reverted
+ *                      to the default). This is the case that previously emitted a
+ *                      MISLEADING green "✅ Now running <default> (the configured
+ *                      default)" card with no signal that the requested switch was
+ *                      lost. It self-corrects across boots: a later boot that
+ *                      genuinely launches the target reports `applied`.
+ */
+export type ModelSwitchConfirmation =
+  | { kind: 'applied'; launched: string }
+  | { kind: 'default'; launched: string }
+  | { kind: 'not-applied'; target: string; revertedTo: string }
+
+/**
+ * Extract the requested `/model <target>` token from a clean-shutdown reason
+ * (e.g. `user: /model fable (session-only relaunch, menu)` → `fable`). Returns
+ * null when the reason carries no `/model <token>` (a non-switch reason).
+ */
+export function parseModelSwitchTarget(reason: string): string | null {
+  const m = reason.match(/\/model\s+(\S+)/)
+  return m ? m[1] : null
+}
+
+/**
+ * Reduce a model token to a comparable FAMILY key so an alias and its resolved
+ * full id compare equal (`sonnet` ≡ `claude-sonnet-5` ≡ `claude-sonnet-5-<date>`).
+ *
+ * This is the normalization the silent-revert classifier needs: `target` from
+ * the clean-shutdown reason is the RAW user token (an alias like `sonnet`),
+ * while `.active-session-model` / the configured default may be the RESOLVED
+ * full id start.sh wrote on a revert-with-alert path (config-default-changed at
+ * start.sh.hbs:1228, proxy-down at :1234). A naive string compare would flag
+ * `/model sonnet` on a `claude-sonnet-5`-default agent as "didn't apply" even
+ * though sonnet IS the default.
+ *
+ * NB `resolveMainModel` (scaffold.ts:1358) is NOT sufficient here — it only
+ * remaps the `default` alias / unset to the switchroom default; it passes
+ * `sonnet`/`opus`/etc. through unchanged. The alias↔full-id equivalence is a
+ * FAMILY reduction (same rule model-label.ts uses one-way), done here:
+ *   - `claude-<family>-…` → `<family>`  (e.g. `claude-sonnet-5` → `sonnet`)
+ *   - a bare alias / any other token     → itself, lowercased (`sonnet`, `sr-glm-5`)
+ * sr-* ids never carry a `claude-` prefix, so they stay verbatim — correct,
+ * since the reason token and `.active-session-model` both hold the same
+ * already-expanded sr-* id and compare equal directly.
+ */
+export function modelFamilyToken(token: string): string {
+  const t = token.trim().toLowerCase()
+  if (t.startsWith('claude-')) {
+    const family = t.slice('claude-'.length).split('-').filter((p) => p.length > 0)[0]
+    return family ?? t
+  }
+  return t
+}
+
+/**
+ * Classify a `/model` apply-boot outcome from the post-boot signals. Pure so the
+ * confirmation-card decision is unit-testable without booting the gateway. The
+ * `not-applied` branch is the fix for the silent-revert bug: a non-default switch
+ * that reverted to the configured default must warn, not print a green ✅.
+ */
+export function classifyModelSwitchConfirmation(input: {
+  reason: string
+  launched: string
+  configured: string
+}): ModelSwitchConfirmation {
+  const { reason, launched, configured } = input
+  const isApplyBoot = launched.length > 0 && launched !== configured
+  if (isApplyBoot) return { kind: 'applied', launched }
+  // launched === configured (or empty): either an intended default/revert, or a
+  // NON-default switch that silently reverted to the configured default.
+  const target = parseModelSwitchTarget(reason)
+  const revertedTo = launched.length > 0 ? launched : configured
+  // Family-normalize both sides so an alias target (`sonnet`) matches its
+  // resolved full-id revert (`claude-sonnet-5`) — otherwise a `/model sonnet`
+  // that reverted to the sonnet default would emit a WRONG "didn't apply" card.
+  if (
+    target != null &&
+    target.toLowerCase() !== 'default' &&
+    modelFamilyToken(target) !== modelFamilyToken(revertedTo)
+  ) {
+    return { kind: 'not-applied', target, revertedTo }
+  }
+  return { kind: 'default', launched: revertedTo }
+}
+
 export type ParsedModelCommand =
   | { kind: 'show' }
   | { kind: 'set'; model: string }

package/telegram-plugin/gateway/session-model-file.ts

@@ -38,6 +38,15 @@ import { isValidModelArg } from './model-command.js'
 
 export const SESSION_MODEL_FILE = '.session-model'
 export const CONFIGURED_DEFAULT_MODEL_FILE = '.configured-default-model'
+/**
+ * Bounded-retry attempt counter for the session-model carrier (#3284).
+ * start.sh increments this on every boot that reads `.session-model` and
+ * applies it, and gives up (reverts + alerts) once it exceeds its bound. The
+ * gateway clears BOTH this file and the carrier on a healthy boot (see
+ * consumeSessionModelCarrierOnHealthyBoot) — the "healthy" signal a wedged
+ * boot cannot fake. Kept in sync with start.sh.hbs.
+ */
+export const SESSION_MODEL_BOOT_ATTEMPTS_FILE = '.session-model-boot-attempts'
 
 export interface SessionModelRecord {
   model: string
@@ -125,6 +134,37 @@ export function clearSessionModelFile(agentDir: string): void {
   }
 }
 
+/**
+ * Consume the session-model carrier on a HEALTHY boot (#3284).
+ *
+ * Called once this gateway has ACQUIRED the boot lock (boot.lock_acquired) —
+ * the deterministic signal that THIS boot is the surviving healthy session,
+ * which a boot that wedges before lock-acquire cannot fake. Deletes BOTH the
+ * consume-once carrier and the bounded-retry attempt counter, so:
+ *   - the next ordinary restart (deploy, /restart, crash) finds no carrier and
+ *     reverts to the configured default (session-scoped semantics preserved);
+ *   - a transient wedge BEFORE this point leaves the carrier in place, so the
+ *     retry boot re-applies the intended model instead of silently reverting.
+ *
+ * This is what moved out of start.sh's old delete-before-apply: start.sh no
+ * longer consumes the carrier itself, it only APPLIES it and lets this healthy
+ * signal do the consume. Best-effort — a failure here just means the carrier is
+ * re-read (and re-applied, harmlessly) on the next boot, still bounded by the
+ * counter. Idempotent.
+ */
+export function consumeSessionModelCarrierOnHealthyBoot(agentDir: string): void {
+  try {
+    rmSync(join(agentDir, SESSION_MODEL_FILE), { force: true })
+  } catch {
+    /* best-effort */
+  }
+  try {
+    rmSync(join(agentDir, SESSION_MODEL_BOOT_ATTEMPTS_FILE), { force: true })
+  } catch {
+    /* best-effort */
+  }
+}
+
 /** Restore a rollback snapshot taken with readSessionModelFileRaw. */
 export function restoreSessionModelFileRaw(agentDir: string, raw: string | null): void {
   if (raw == null) {

package/telegram-plugin/gateway/turn-flush-suppression.ts

@@ -0,0 +1,82 @@
+/**
+ * Turn-flush pre-delivery suppression decision (S1 fix, fable red-team
+ * 2026-07-17 — `~klanker/work/fable-redteam-delivery-20260717/REDTEAM.md`).
+ *
+ * Before the turn-flush backstop posts the captured terminal answer, it asks:
+ * "did a reply already land for this turn in the last ~2s?" (a race guard for
+ * a reply whose IPC signal hadn't registered when `decideTurnFlush` ran, and
+ * for answer-stream materializations that already delivered the answer text).
+ *
+ * The OLD predicate — `getRecentOutboundCount(chatId, 2) > 0` — counted ANY
+ * assistant row in the WHOLE chat: a background worker's `progress_update`, a
+ * command ack / restart notice, or a reply in a DIFFERENT forum topic all
+ * suppressed the flush, and the branch then CLOSED the delivery obligation —
+ * the user's real answer was dropped with no re-present. This module scopes
+ * the predicate to a SUBSTANTIVE (≥ `FINAL_ANSWER_MIN_CHARS`) outbound in the
+ * SAME thread, via the injected `hasSubstantiveOutbound` (the gateway wires
+ * `hasOutboundDeliveredSince`, whose thread/length semantics are pinned by
+ * `history.test.ts`).
+ *
+ * Residual (documented, accepted): a ≥200-char same-thread non-answer outbound
+ * (e.g. an unusually long progress update) inside the 2s window still
+ * suppresses — the history schema has no message-kind column to discriminate
+ * further. That residual is why the CALLER must NOT close the obligation on
+ * suppression: a genuine reply closes its own obligation idempotently, while a
+ * false-positive suppression leaves it open for the liveness floor / sweep.
+ */
+
+import { FINAL_ANSWER_MIN_CHARS } from '../final-answer-detect.js'
+
+/** How far back a just-landed reply can be and still suppress the flush. */
+export const FLUSH_SUPPRESSION_WINDOW_MS = 2000
+
+export interface FlushSuppressionDeps {
+  /** Durable substantive-outbound oracle — the gateway passes
+   *  `hasOutboundDeliveredSince` (thread-scoped, length-floored). */
+  hasSubstantiveOutbound(
+    chatId: string,
+    sinceMs: number,
+    threadId: number | null,
+    minChars: number,
+  ): boolean
+}
+
+export interface FlushSuppressionArgs {
+  chatId: string
+  /** The turn's origin thread. `null` = chat root / DM (matches the
+   *  `hasOutboundDeliveredSince` explicit-null semantics — never pass
+   *  `undefined`, which would match ANY thread and re-open the
+   *  cross-topic false positive this module exists to close). */
+  threadId: number | null
+  /** Length of the captured answer the flush is about to deliver. The
+   *  length floor is `min(FINAL_ANSWER_MIN_CHARS, answerLength)`: a row
+   *  can only suppress the flush if it is at least as long as the answer
+   *  itself (up to the 200-char substantive cap). A TERSE captured answer
+   *  ("Yes — done.") is therefore still suppressible by its own short
+   *  answer-stream materialization (avoiding a duplicate bubble), while a
+   *  short progress ping can never suppress a LONG composed answer. */
+  answerLength: number
+  nowMs: number
+}
+
+/**
+ * True iff the flush should be suppressed: a substantive same-thread outbound
+ * landed within the suppression window. Fails open (no suppression) on oracle
+ * errors — delivering a possible duplicate beats dropping the only copy.
+ */
+export function shouldSuppressTurnFlush(
+  deps: FlushSuppressionDeps,
+  args: FlushSuppressionArgs,
+): boolean {
+  const minChars = Math.max(1, Math.min(FINAL_ANSWER_MIN_CHARS, args.answerLength))
+  try {
+    return deps.hasSubstantiveOutbound(
+      args.chatId,
+      args.nowMs - FLUSH_SUPPRESSION_WINDOW_MS,
+      args.threadId,
+      minChars,
+    )
+  } catch {
+    return false
+  }
+}

package/telegram-plugin/gateway/unhandled-message.ts

@@ -0,0 +1,177 @@
+/**
+ * Terminal catch-all + diagnostic tap for inbound Telegram messages (#3300).
+ *
+ * THE CLASS OF BUG THIS CLOSES: the gateway registers only content-specific
+ * handlers (`bot.on('message:text')`, `:photo`, … `:paid_media`). grammy
+ * ^1.44 routes `bot.on` as filtering middleware — internally
+ * `on → filter(pred, handler) → branch(pred, handler, pass)` — and a
+ * `message` update matching NONE of the registered predicates falls through
+ * every branch and is SILENTLY discarded: no log, no ack, no history row.
+ *
+ * Live signature (2026-07-16, klanker DM): message_id 19090 was allocated
+ * between an outbound reply (19089, 21:51:11Z) and the next inbound (19091,
+ * 21:59:31Z) with ZERO gateway trace — no early_ack, no gw-trace inbound, no
+ * gate-deny, no error — while polling stayed healthy on both sides. Exactly
+ * the zero-observability failure this module makes impossible: every update
+ * is now logged on receipt (tap) and every message either produces a turn or
+ * an explicit log-only line (catch-all).
+ *
+ * Extracted into its own module (rather than inline in gateway.ts) so tests
+ * can drive the REAL registration path on a real grammy Bot — gateway.ts is
+ * a side-effecting module that cannot be imported into a unit test.
+ */
+
+import type { Bot, Context } from 'grammy'
+
+/**
+ * Top-level `message` envelope fields — identity/routing metadata, excluded
+ * when surfacing the CONTENT keys of a message (the fields that determine
+ * which `bot.on('message:*')` handler should match).
+ */
+export const MESSAGE_ENVELOPE_KEYS: ReadonlySet<string> = new Set<string>([
+  'message_id', 'message_thread_id', 'date', 'chat', 'from', 'sender_chat',
+  'forward_origin', 'reply_to_message', 'external_reply', 'quote',
+  'reply_to_story', 'edit_date', 'media_group_id', 'author_signature',
+  'is_topic_message', 'is_automatic_forward', 'via_bot', 'sender_boost_count',
+  'business_connection_id', 'effect_id', 'has_protected_content',
+  'is_from_offline', 'link_preview_options', 'show_caption_above_media',
+  'entities', 'caption_entities', 'paid_star_count',
+])
+
+/**
+ * Known-noise SERVICE message content keys: chat/topic lifecycle events that
+ * carry no user intent for the agent. These are LOGGED (never silently
+ * dropped — the whole point of #3300) but do NOT become agent turns:
+ * forum-topic lifecycle events are a recurring spam vector in supergroups,
+ * and each spurious turn costs tokens and attention.
+ *
+ * Anything NOT in this set that reaches the catch-all is delivered as a turn
+ * (fail-toward-delivery: an unknown content type plausibly carries user
+ * intent; better a placeholder turn than a lost message).
+ */
+export const SERVICE_NOISE_KEYS: ReadonlySet<string> = new Set<string>([
+  'new_chat_members', 'left_chat_member', 'new_chat_title', 'new_chat_photo',
+  'delete_chat_photo', 'group_chat_created', 'supergroup_chat_created',
+  'channel_chat_created', 'message_auto_delete_timer_changed',
+  'migrate_to_chat_id', 'migrate_from_chat_id',
+  'forum_topic_created', 'forum_topic_edited', 'forum_topic_closed',
+  'forum_topic_reopened', 'general_forum_topic_hidden',
+  'general_forum_topic_unhidden',
+  'video_chat_scheduled', 'video_chat_started', 'video_chat_ended',
+  'video_chat_participants_invited',
+  'giveaway_created', 'giveaway', 'giveaway_winners', 'giveaway_completed',
+  'boost_added', 'chat_background_set', 'write_access_allowed',
+  'proximity_alert_triggered', 'chat_set_theme',
+  'connected_website', 'direct_message_price_changed',
+])
+
+/** The CONTENT keys of a message — top-level keys minus envelope metadata. */
+export function messageContentKeys(msg: Record<string, unknown>): string[] {
+  return Object.keys(msg).filter(k => !MESSAGE_ENVELOPE_KEYS.has(k))
+}
+
+export type UnhandledMessagePlan =
+  | { action: 'turn'; text: string; contentKeys: string[] }
+  | { action: 'log-only'; contentKeys: string[] }
+
+/**
+ * Decide what the catch-all does with a message no specific handler consumed:
+ * known-noise service messages → log-only (no turn); everything else → a turn
+ * with best-effort text (`text ?? caption ?? placeholder naming the type`).
+ */
+export function planUnhandledMessage(msg: Record<string, unknown>): UnhandledMessagePlan {
+  const contentKeys = messageContentKeys(msg)
+  if (contentKeys.length > 0 && contentKeys.every(k => SERVICE_NOISE_KEYS.has(k))) {
+    return { action: 'log-only', contentKeys }
+  }
+  const contentType = contentKeys[0] ?? 'unknown'
+  const text =
+    (typeof msg.text === 'string' ? msg.text : undefined) ??
+    (typeof msg.caption === 'string' ? msg.caption : undefined) ??
+    `(unhandled message content: ${contentType})`
+  return { action: 'turn', text, contentKeys }
+}
+
+/** One compact diagnostic line per update; cap prevents log flooding. */
+export const TAP_MAX_LINES_PER_MINUTE = 300
+
+/**
+ * Install the diagnostic update tap: pass-through middleware (`bot.use` →
+ * always calls next()) logging every received update's type + content keys
+ * (never payload bodies — privacy). Rate-limited to TAP_MAX_LINES_PER_MINUTE
+ * per wall-clock minute; on rollover a single summary line reports how many
+ * were suppressed, so even a flood is never invisible.
+ *
+ * MUST be installed before all `bot.on` handlers so it observes every update.
+ */
+export function installUpdateTap(
+  bot: Pick<Bot, 'use'>,
+  log: (line: string) => void,
+  nowMs: () => number = Date.now,
+): void {
+  let windowStart = 0
+  let windowCount = 0
+  let suppressed = 0
+  bot.use(async (ctx, next) => {
+    try {
+      const now = nowMs()
+      if (now - windowStart >= 60_000) {
+        if (suppressed > 0) {
+          log(`telegram gateway: rx tap suppressed ${suppressed} update lines in the last minute (cap ${TAP_MAX_LINES_PER_MINUTE}/min)\n`)
+        }
+        windowStart = now
+        windowCount = 0
+        suppressed = 0
+      }
+      if (windowCount < TAP_MAX_LINES_PER_MINUTE) {
+        windowCount++
+        const upd = ctx.update as unknown as Record<string, unknown>
+        const updateType = Object.keys(upd).find(k => k !== 'update_id') ?? 'unknown'
+        const msg = ctx.message as unknown as Record<string, unknown> | undefined
+        const detail = msg ? ` content=[${messageContentKeys(msg).join(',')}]` : ''
+        log(`telegram gateway: rx update_id=${ctx.update.update_id} type=${updateType}${detail}\n`)
+      } else {
+        suppressed++
+      }
+    } catch {
+      // The diagnostic tap must never break the inbound pipeline.
+    }
+    await next()
+  })
+}
+
+/**
+ * Install the terminal catch-all. MUST be registered LAST among the
+ * `message`/`message:*` handlers: grammy leaf handlers never call `next()`,
+ * so a matched specific handler stops the chain (specific handler always
+ * wins) and this only fires for messages no specific handler consumed —
+ * registration order IS the no-double-handling guarantee.
+ *
+ * `onInbound` is the normal inbound pipeline (gateway.ts passes
+ * handleInboundCoalesced), which applies the same access gating and
+ * forward-origin parsing as every other content handler.
+ */
+export function installUnhandledMessageCatchAll(
+  bot: Pick<Bot, 'on'>,
+  onInbound: (ctx: Context, text: string) => Promise<void>,
+  log: (line: string) => void,
+): void {
+  bot.on('message', async ctx => {
+    try {
+      const msg = ctx.message as unknown as Record<string, unknown>
+      const plan = planUnhandledMessage(msg)
+      // Log KEYS + ids only — never the payload bodies (privacy).
+      log(
+        `telegram gateway: catch-all inbound (no specific handler) ` +
+          `update_id=${ctx.update.update_id} chat_id=${ctx.chat?.id ?? '?'} ` +
+          `message_id=${ctx.message?.message_id ?? '?'} ` +
+          `content_keys=[${plan.contentKeys.join(',')}] action=${plan.action}\n`,
+      )
+      if (plan.action === 'turn') {
+        await onInbound(ctx, plan.text)
+      }
+    } catch (err) {
+      log(`telegram gateway: catch-all handler error: ${(err as Error).message}\n`)
+    }
+  })
+}

package/telegram-plugin/llm-error-present.ts

@@ -30,6 +30,7 @@
 import {
   detectModelUnavailable,
   isLitellmProxyLocal429,
+  isLitellmProxyAuthMisconfig,
   parseResetTime,
 } from './model-unavailable.js'
 import { classify429Detail } from './throttle-tier.js'
@@ -46,6 +47,7 @@ export type LlmErrorKind =
   | 'overload_529'
   | 'quota_wall'
   | 'auth'
+  | 'infra_misconfig'
   | 'transient'
   | 'unknown'
 
@@ -150,8 +152,22 @@ export function parseLlmError(
 function classifyKindAndSource(text: string): { kind: LlmErrorKind; source: LlmErrorSource } {
   const lower = text.toLowerCase()
 
+  // 0. LiteLLM-proxy AUTH misconfig — checked BEFORE the auth branch. The
+  //    proxy's internal fallback re-dispatched WITHOUT the OAuth header onto a
+  //    keyless deployment, so Anthropic 401'd it ("x-api-key header is
+  //    required"). This is an OPERATOR-only infra fault, NOT an end-user login
+  //    wall — never the user-facing 'auth' kind (which renders a re-auth card a
+  //    non-operator user cannot act on). Source is the local proxy, not
+  //    Anthropic. See isLitellmProxyAuthMisconfig for provenance.
+  if (isLitellmProxyAuthMisconfig(text)) {
+    return { kind: 'infra_misconfig', source: 'litellm-local' }
+  }
+
   // 1. Auth — always terminal, always actionable.
   const claudeKind = classifyClaudeError({ message: text, type: text })
+  if (claudeKind === 'proxy-misconfig') {
+    return { kind: 'infra_misconfig', source: 'litellm-local' }
+  }
   if (claudeKind === 'credentials-expired' || claudeKind === 'credentials-invalid') {
     return { kind: 'auth', source: 'anthropic' }
   }
@@ -212,6 +228,8 @@ function buildCoreText(kind: LlmErrorKind, source: LlmErrorSource): string {
       return 'Usage limit reached on this Claude subscription.'
     case 'auth':
       return 'Claude login needs re-authentication.'
+    case 'infra_misconfig':
+      return 'Local model-gateway auth misconfig (proxy fallback dropped the OAuth header).'
     case 'transient':
       return source === 'network'
         ? "Couldn't reach Anthropic (network) — retrying automatically."
@@ -280,6 +298,10 @@ function buildRecommendation(parsed: ParsedLlmError, tz: string): string | undef
   switch (parsed.kind) {
     case 'auth':
       return '→ Re-authenticate this account to continue.'
+    case 'infra_misconfig':
+      // Operator-facing — NO re-auth wording (the login is fine). Points at the
+      // real remedy: the local LiteLLM proxy fallback config.
+      return '→ Fix the LiteLLM proxy fallback config (deployment missing OAuth passthrough).'
     case 'quota_wall': {
       const reset = formatResetClock(parsed.resetAt, tz)
       return reset
@@ -353,6 +375,8 @@ function kindEmoji(kind: LlmErrorKind): string {
       return '⚠️'
     case 'auth':
       return '🔑'
+    case 'infra_misconfig':
+      return '🛠️'
     case 'transient':
       return '🌐'
     case 'unknown':

package/telegram-plugin/model-unavailable.ts

@@ -195,6 +195,61 @@ export function isLitellmProxyLocal429(text: string): boolean {
   return litellmV3LimiterSignalPair.every(s => lower.includes(s))
 }
 
+/**
+ * True when `text` is a LiteLLM-proxy-LOCAL AUTH misconfiguration — the
+ * proxy-fallback keyless-401 class, NOT a genuine end-user credential wall.
+ *
+ * PROVENANCE (incident, 2026-07-16). LiteLLM's internal model-fallback chain
+ * (`gpt-oss-20b -> [gpt-oss-20b-openrouter, claude-sonnet-5]`) re-dispatches a
+ * failed primary WITHOUT forwarding the client's OAuth `Authorization` header.
+ * The `claude-sonnet-5` deployment is deliberately keyless (passthrough auth —
+ * it expects the forwarded OAuth), so Anthropic rejects the header-less
+ * fallback with a 401 `authentication_error` whose message is
+ * "x-api-key header is required". Switchroom agents authenticate the unmodified
+ * `claude` CLI with an OAuth Bearer token and NEVER an `x-api-key`, so that
+ * demand can only originate from the proxy dropping the header on a keyless
+ * fallback deployment — a host-side infra misconfig for the OPERATOR to fix,
+ * never a login problem an end user (or even the operator's OAuth) can act on.
+ *
+ * Misclassifying it (as `classifyClaudeError` did → `credentials-invalid` →
+ * a "🔑 re-authenticate" card) is doubly wrong: wrong AUDIENCE (a non-operator
+ * user like Lisa cannot re-auth anything) and wrong DIAGNOSIS (the login is
+ * fine; the proxy fallback config is not). Detecting it here lets both
+ * classifiers route it to the operator-only infra surface instead.
+ *
+ * Detection (deterministic wording, mirrors `isLitellmProxyLocal429`):
+ *   - the definitive "x-api-key header is required" marker (impossible for our
+ *     OAuth flow — only the keyless-proxy path emits it), OR
+ *   - an `authentication_error` CO-OCCURRING with the proxy-FALLBACK-specific
+ *     structural pair: "fallback" re-dispatch provenance AND an explicit
+ *     "x-api-key" mention.
+ *
+ * PRECISION over recall (#3293 review finding 2): an earlier draft matched any
+ * `authentication_error` + (litellm|proxy) + (fallback|x-api-key|api_key) —
+ * broad enough that a GENUINE OAuth expiry wrapped in a proxy envelope that
+ * merely mentions "api_key" would misdiagnose as proxy-misconfig (still
+ * operator-visible, but the recommendation would point at the proxy config
+ * instead of a re-auth). Both classes route operator-only now, so an ambiguous
+ * envelope deliberately KEEPS the credentials-invalid/-expired diagnosis;
+ * only the unambiguous keyless-fallback signature classifies as misconfig.
+ * Never throws on weird input.
+ */
+export function isLitellmProxyAuthMisconfig(text: string): boolean {
+  if (typeof text !== 'string' || text.length === 0) return false
+  const sample = text.length > 16_384 ? text.slice(0, 16_384) : text
+  const lower = sample.toLowerCase()
+  // Definitive marker — see provenance above.
+  if (lower.includes('x-api-key header is required')) return true
+  // Structural signature: an authentication_error carrying BOTH the fallback
+  // re-dispatch provenance AND an explicit x-api-key mention. A proxy envelope
+  // that merely mentions litellm/proxy/api_key stays on the credentials
+  // diagnosis (ambiguous → not misconfig).
+  const isAuthErr =
+    lower.includes('authentication_error') || lower.includes('authenticationerror')
+  if (!isAuthErr) return false
+  return lower.includes('fallback') && lower.includes('x-api-key')
+}
+
 /**
  * Best-effort extraction of the limit detail LiteLLM embeds in its
  * proxy-local 429 bodies, for instrumentation (the `rate_limit_429_classified`