switchroom 0.18.28 → 0.18.30

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-record-status.ts

@@ -79,6 +79,51 @@ export function backstopSendOutcome(args: {
   return 'delivered'
 }
 
+/**
+ * Resolve a backstop send's outcome using the #3276 RECEIPT gate: success
+ * requires at least one FRESH, non-card chat message id. This supersedes the
+ * naive chunk-count comparison for the turn-flush backstop, where a delivery
+ * that landed only onto the (soon-swept) progress card must count as a failure,
+ * not `complete`.
+ *
+ *   threw                              → failed
+ *   no fresh non-card id delivered     → failed  (card-only "success")
+ *   fewer fresh ids than chunks split  → failed  (partial delivery)
+ *   >=1 fresh id AND all chunks landed → delivered
+ *
+ * `cardMessageId` is the taken-over progress-card id (or null); any id equal to
+ * it is excluded from the delivered set before counting.
+ */
+export function backstopSendOutcomeGated(args: {
+  threw: boolean
+  sentIds: readonly number[]
+  chunkCount: number
+  cardMessageId: number | null
+}): DeliveryOutcome {
+  if (args.threw) return 'failed'
+  if (args.chunkCount === 0) return 'failed'
+  const freshCount = args.sentIds.filter(
+    id => args.cardMessageId == null || id !== args.cardMessageId,
+  ).length
+  // Guard 7: a card-only delivery (zero fresh ids) is a hard failure.
+  if (freshCount === 0) return 'failed'
+  if (freshCount < args.chunkCount) return 'failed'
+  return 'delivered'
+}
+
+/**
+ * Stamp a turn's `deliveryOutcome` from a resolved backstop send using the
+ * #3276 receipt gate (fresh non-card ids only). Mutates and returns the outcome.
+ */
+export function finalizeBackstopSendGated(
+  turn: { deliveryOutcome?: DeliveryOutcome },
+  send: { threw: boolean; sentIds: readonly number[]; chunkCount: number; cardMessageId: number | null },
+): DeliveryOutcome {
+  const outcome = backstopSendOutcomeGated(send)
+  turn.deliveryOutcome = outcome
+  return outcome
+}
+
 /**
  * Stamp a turn's `deliveryOutcome` from a resolved backstop send. This is the
  * exact accounting the turn-flush IIFE's `finally` performs — factored here so

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/history.ts

@@ -142,6 +142,40 @@ const MAX_LIMIT = 50
 let db: SqliteDatabase | null = null
 let dbPath: string | null = null
 
+/**
+ * Loud, unconditional failure logging for the history writer.
+ *
+ * Recording bugs are silent by construction: every gateway call site wraps
+ * `recordOutbound` / `recordInbound` in a `try { … } catch {}` (or a catch that
+ * logs a caller-shaped message), and several of those catches are EMPTY. When a
+ * write throws or drops a row, the caller's empty catch hides it — the exact
+ * failure mode behind the 2026-07-16 incident (turn-flush deliveries 18944 /
+ * 18958 delivered to Telegram but absent from history.db, blinding
+ * `getRecentOutboundCount` / `hasOutboundDeliveredSince`). We therefore log HERE,
+ * inside the writer, BEFORE any throw — so even a caller's `catch {}` cannot
+ * suppress the diagnostic. Deterministic surfacing, not prompt discipline.
+ */
+function warnHistory(msg: string): void {
+  try {
+    process.stderr.write(`telegram history: ${msg}\n`)
+  } catch {
+    /* stderr write must never itself break the record path */
+  }
+}
+
+/**
+ * A Telegram message_id is a positive 32-bit-ish integer. A null / undefined /
+ * NaN / non-integer id can only arrive from a malformed send result (e.g. an
+ * API wrapper that resolved without a real message object). Inserting it either
+ * violates the NOT NULL PRIMARY KEY (throws → swallowed by an empty caller
+ * catch) or silently corrupts the key space. We filter such ids out and log
+ * loudly instead — a delivered-but-unrecorded row is a durability defect the
+ * operator must see, not a silent drop.
+ */
+function isValidMessageId(id: unknown): id is number {
+  return typeof id === 'number' && Number.isInteger(id) && id > 0
+}
+
 /**
  * Open (or create) the history DB and run migrations + retention sweep.
  * Idempotent — safe to call once at server startup.
@@ -271,6 +305,72 @@ export function initHistory(stateDir: string, retentionDays = 30): void {
     const cutoff = Math.floor(Date.now() / 1000) - retentionDays * 86400
     db.prepare('DELETE FROM messages WHERE ts < ?').run(cutoff)
   }
+
+  // Boot-time writer self-check (2026-07-16 incident hardening). "history
+  // capture enabled" was logged at every boot — including the 02:17 and 04:58
+  // restarts around the incident — yet a whole class of deliveries never
+  // reached the DB. A successful `new Database(...)` + schema DDL does NOT prove
+  // the row-insert path is functional (a read-only mount, a full disk, an
+  // orphaned inode after an in-place dir replace, or a corrupt page all pass DDL
+  // but fail INSERT). So we prove it with a real INSERT + SELECT + DELETE
+  // round-trip on a sentinel row, and log LOUDLY if it fails. This turns a
+  // silent, hours-later-discovered writer outage into a deterministic boot
+  // signal the operator can see immediately.
+  const check = verifyHistoryWritable()
+  if (!check.ok) {
+    warnHistory(
+      `WRITER SELF-CHECK FAILED at boot (path=${path}): ${check.error ?? 'unknown'} — ` +
+        `history recording is NOT durable; get_recent_messages recovery and the ` +
+        `reply-backstop already-replied suppression will be blind. Investigate the ` +
+        `DB path/mount/permissions before trusting delivery accounting.`,
+    )
+  }
+}
+
+/**
+ * Prove the history writer's INSERT path actually works, not just that the DB
+ * opened and the schema DDL ran. Performs a real INSERT + SELECT + DELETE of a
+ * sentinel row keyed on a reserved chat_id that no live chat can collide with,
+ * and cleans it up unconditionally. Returns `{ ok:false, error }` (never throws)
+ * so the boot path and an operator self-check tool can both call it safely.
+ *
+ * This is the deterministic mechanism the 2026-07-16 incident lacked: a
+ * writer that opens fine but cannot persist rows (read-only mount, full disk,
+ * orphaned inode, corruption) is caught HERE at boot instead of being inferred
+ * hours later from missing rows.
+ *
+ * No-op safe: returns `{ ok:false }` with an explanatory error if
+ * `initHistory` was never called.
+ */
+export function verifyHistoryWritable(): { ok: boolean; error?: string } {
+  if (db == null) return { ok: false, error: 'initHistory() not called' }
+  const SENTINEL_CHAT = '__history_selfcheck__'
+  const sentinelId = Date.now()
+  try {
+    // Clear any stale sentinel from a prior crashed self-check first.
+    db.prepare('DELETE FROM messages WHERE chat_id = ?').run(SENTINEL_CHAT)
+    db.prepare(
+      `INSERT OR REPLACE INTO messages
+         (chat_id, thread_id, message_id, role, ts, text)
+       VALUES (?, NULL, ?, 'assistant', ?, ?)`,
+    ).run(SENTINEL_CHAT, sentinelId, Math.floor(Date.now() / 1000), 'selfcheck')
+    const row = db
+      .prepare('SELECT text FROM messages WHERE chat_id = ? AND message_id = ?')
+      .get(SENTINEL_CHAT, sentinelId) as { text?: string } | undefined
+    if (row?.text !== 'selfcheck') {
+      return { ok: false, error: 'sentinel row not read back after insert' }
+    }
+    return { ok: true }
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) }
+  } finally {
+    // Never leave the sentinel behind, even if the SELECT/assert path threw.
+    try {
+      db.prepare('DELETE FROM messages WHERE chat_id = ?').run(SENTINEL_CHAT)
+    } catch {
+      /* best-effort cleanup */
+    }
+  }
 }
 
 /**
@@ -404,6 +504,13 @@ interface RecordInboundArgs {
  */
 export function recordInbound(args: RecordInboundArgs): void {
   if (args.message_id == null) return
+  if (!isValidMessageId(args.message_id)) {
+    warnHistory(
+      `recordInbound: dropping row with invalid message_id=${String(args.message_id)} ` +
+        `(chat=${args.chat_id}) — a delivered inbound will be absent from history`,
+    )
+    return
+  }
   const stmt = requireDb().prepare(`
     INSERT OR REPLACE INTO messages
       (chat_id, thread_id, message_id, role, user, user_id, ts, text, attachment_kind, group_id, reply_to_message_id, reply_to_text, forwarded_from, forwarded_from_type, forwarded_from_id, forwarded_date, forwarded_message_id)
@@ -453,7 +560,35 @@ interface RecordOutboundArgs {
 export function recordOutbound(args: RecordOutboundArgs): void {
   if (args.message_ids.length === 0) return
   const ts = args.ts ?? Math.floor(Date.now() / 1000)
-  const groupId = args.message_ids[0]!
+  // Filter out invalid ids (null/undefined/NaN/non-positive) BEFORE the insert.
+  // A malformed send result (an API wrapper that resolved without a real message
+  // object) would otherwise inject a NULL/NaN message_id: the NOT NULL PRIMARY
+  // KEY throws, and the caller's `catch {}` swallows it — the delivered reply is
+  // then absent from history AND the failure is invisible. This was the shape of
+  // the 2026-07-16 turn-flush loss (18944/18958 delivered, never recorded). We
+  // log loudly and record only the valid rows instead of losing them silently.
+  const validRows: Array<{ id: number; text: string; attachKind: string | null }> = []
+  for (let i = 0; i < args.message_ids.length; i++) {
+    const id = args.message_ids[i]
+    if (!isValidMessageId(id)) {
+      warnHistory(
+        `recordOutbound: dropping chunk ${i} with invalid message_id=${String(id)} ` +
+          `(chat=${args.chat_id}) — a delivered outbound will be absent from history, ` +
+          `blinding the reply-backstop already-replied suppression`,
+      )
+      continue
+    }
+    validRows.push({
+      id,
+      // Outbound redaction: the agent→user direction has no other secret scrub,
+      // so this is the chokepoint that keeps an agent-echoed secret out of the
+      // message store. Masks the secret bytes in place; surrounding text kept.
+      text: redact(args.texts[i] ?? ''),
+      attachKind: args.attachment_kinds?.[i] ?? null,
+    })
+  }
+  if (validRows.length === 0) return
+  const groupId = validRows[0]!.id
   const stmt = requireDb().prepare(`
     INSERT OR REPLACE INTO messages
       (chat_id, thread_id, message_id, role, user, user_id, ts, text, attachment_kind, group_id)
@@ -463,30 +598,25 @@ export function recordOutbound(args: RecordOutboundArgs): void {
   // writes if the process dies mid-loop. The transaction signature is
   // typed as variadic-unknown for genericity; cast the typed callback
   // through the wider shape.
-  const tx = requireDb().transaction(((rows: Array<[number, string, string | null]>) => {
-    for (const [msgId, text, attachKind] of rows) {
-      stmt.run(
-        args.chat_id,
-        args.thread_id ?? null,
-        msgId,
-        ts,
-        text,
-        attachKind,
-        groupId,
-      )
+  const tx = requireDb().transaction(((rows: Array<{ id: number; text: string; attachKind: string | null }>) => {
+    for (const r of rows) {
+      stmt.run(args.chat_id, args.thread_id ?? null, r.id, ts, r.text, r.attachKind, groupId)
     }
   }) as (...args: unknown[]) => unknown)
-  // Outbound redaction: the agent→user direction has no other secret
-  // scrub, so this is the chokepoint that keeps an agent-echoed secret out
-  // of the message store (e.g. an agent quoting a token it read from a file
-  // or a not-yet-vaulted value). Masks the secret bytes in place; the
-  // surrounding reply text is preserved.
-  const rows: Array<[number, string, string | null]> = args.message_ids.map((id, i) => [
-    id,
-    redact(args.texts[i] ?? ''),
-    args.attachment_kinds?.[i] ?? null,
-  ])
-  tx(rows)
+  // Surface a write failure LOUDLY before rethrowing. Callers wrap this in a
+  // `catch {}` / caller-shaped catch; without this log an insert failure (disk
+  // full, read-only mount, lock exhaustion) would be completely invisible —
+  // exactly the diagnostic gap the 2026-07-16 incident exposed. Rethrow so the
+  // caller's existing control flow is unchanged.
+  try {
+    tx(validRows)
+  } catch (err) {
+    warnHistory(
+      `recordOutbound: INSERT failed (chat=${args.chat_id} ids=[${validRows.map((r) => r.id).join(',')}]): ` +
+        `${err instanceof Error ? err.message : String(err)} — this outbound will be absent from history`,
+    )
+    throw err
+  }
 }
 
 interface RecordEditArgs {

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`