switchroom 0.18.29 → 0.18.31

package/telegram-plugin/operator-events.ts

@@ -14,12 +14,14 @@
 
 import { escapeMarkdown } from './format.js'
 import { stripRawErrorBytes } from './raw-error-scrub.js'
+import { isLitellmProxyAuthMisconfig } from './model-unavailable.js'
 
 // ─── Taxonomy ────────────────────────────────────────────────────────────────
 
 export type OperatorEventKind =
   | 'credentials-expired'
   | 'credentials-invalid'
+  | 'proxy-misconfig'
   | 'credit-exhausted'
   | 'quota-exhausted'
   | 'rate-limited'
@@ -92,6 +94,20 @@ function classifyInner(raw: unknown): OperatorEventKind {
   // Anthropic SDK: error_code field (newer SDK shape)
   const sdkCode = extractString(obj, 'error_code') ?? ''
 
+  // LiteLLM-proxy AUTH misconfig — checked BEFORE the generic
+  // authentication_error branch. The proxy's internal fallback chain
+  // re-dispatches without the client's OAuth Authorization header onto a
+  // keyless deployment, so Anthropic returns a 401 authentication_error
+  // ("x-api-key header is required"). That is a HOST-side infra misconfig for
+  // the operator to fix — NOT an end-user login wall. Mapping it to
+  // credentials-invalid mis-fired a "🔑 re-authenticate" card at non-operator
+  // users who cannot re-auth anything (incident 2026-07-16). Route it to the
+  // operator-only infra kind instead. Scanned across type/code/message so the
+  // marker is caught wherever the proxy stamps it.
+  if (isLitellmProxyAuthMisconfig(`${errorType}\n${errorCode}\n${sdkCode}\n${message}`)) {
+    return 'proxy-misconfig'
+  }
+
   // Map known Anthropic error types/codes first.
   // Source: https://docs.anthropic.com/en/api/errors
   if (
@@ -263,6 +279,27 @@ export function renderOperatorEvent(ev: OperatorEvent): RenderResult {
         },
       }
 
+    // Operator-only infra fault. Deliberately NO "Reauth" button and NO
+    // login language: the OAuth credential is fine — the local LiteLLM proxy
+    // re-dispatched an internal fallback without forwarding the OAuth header
+    // onto a keyless deployment, so Anthropic 401'd it. The fix is in the
+    // proxy fallback config (host-side), not a re-auth. Dismiss-only.
+    case 'proxy-misconfig':
+      return {
+        text: [
+          `🛠️ **Model-gateway auth misconfig** for **${agent}**.`,
+          detail ? `_${detail}_` : '',
+          `The local LiteLLM proxy re-dispatched a fallback without forwarding the OAuth header (keyless deployment → Anthropic 401). Fix the proxy fallback config — this is NOT a login problem.`,
+        ]
+          .filter(Boolean)
+          .join('\n'),
+        keyboard: {
+          inline_keyboard: [
+            [{ text: '❌ Dismiss', callback_data: `op:dismiss:${encodeURIComponent(ev.agent)}` }],
+          ],
+        },
+      }
+
     case 'credit-exhausted':
       return {
         text: [
@@ -487,4 +524,80 @@ export function resetAllCooldowns(): void {
   cooldownMap.clear()
 }
 
+// ─── Audience routing (Ken's deterministic error-surfacing policy) ────────────
+
+/**
+ * Kinds that are OPERATOR-ACTIONABLE and NOT user-actionable: a credential /
+ * infra fault whose remedy (re-auth, switch account slot, fix the proxy
+ * fallback config) only the operator can perform. Per Ken's standing policy
+ * (2026-07): raw or misleading auth/infra errors must not reach non-operator
+ * end users — they cannot act on them and the diagnosis is often wrong for
+ * them (e.g. a proxy misconfig rendered as "your login expired"). These route
+ * to the operator surface ONLY; a non-operator user gets at most a brief
+ * plain-language "couldn't complete, it's on our side" notice.
+ *
+ * NOTE: `quota-exhausted` / `rate-limited` are deliberately EXCLUDED — they
+ * carry their own auto-fallback UX + card-collapse machinery and are handled
+ * upstream; this set is scoped to the credential/infra fault classes.
+ */
+export const OPERATOR_ACTIONABLE_KINDS: ReadonlySet<OperatorEventKind> = new Set<OperatorEventKind>([
+  'credentials-expired',
+  'credentials-invalid',
+  'credit-exhausted',
+  'proxy-misconfig',
+])
+
+export function isOperatorActionableKind(kind: OperatorEventKind): boolean {
+  return OPERATOR_ACTIONABLE_KINDS.has(kind)
+}
+
+export interface OperatorEventAudience {
+  /** Chats that receive the full operator card (with any action buttons). */
+  operatorChats: string[]
+  /** Non-operator chats that receive only the plain-language failure notice. */
+  userNoticeChats: string[]
+}
+
+/**
+ * Split an operator-event's allowlist audience per Ken's routing policy.
+ *
+ * - Non-operator-actionable kinds (transient rate-limit, 5xx, crash, config
+ *   warning, …) keep their existing broadcast: every allowlist chat is an
+ *   `operatorChat`. Behavior unchanged.
+ * - Operator-actionable kinds (see {@link OPERATOR_ACTIONABLE_KINDS}) go to the
+ *   OPERATOR chat only. `operatorChatId` is the operator (in switchroom the
+ *   allowlist HEAD — `allowFrom[0]`); it stays an `operatorChat` even in a DM
+ *   agent where the operator is their own user (so the operator NEVER has an
+ *   error hidden from their own DM). Every other allowlist chat becomes a
+ *   `userNoticeChat`.
+ *
+ * Pure — no IPC, no bot. `allowFrom` order is preserved.
+ */
+export function decideOperatorEventAudience(
+  kind: OperatorEventKind,
+  allowFrom: readonly string[],
+  operatorChatId: string | undefined,
+): OperatorEventAudience {
+  if (!isOperatorActionableKind(kind)) {
+    return { operatorChats: [...allowFrom], userNoticeChats: [] }
+  }
+  const operator =
+    operatorChatId != null && allowFrom.includes(operatorChatId)
+      ? operatorChatId
+      : allowFrom[0]
+  const operatorChats = operator != null ? [operator] : []
+  const userNoticeChats = allowFrom.filter((c) => c !== operator)
+  return { operatorChats, userNoticeChats }
+}
+
+/**
+ * The ONE brief, plain-language failure notice a non-operator user gets when a
+ * turn genuinely can't be served because of an operator-actionable fault.
+ * Deliberately carries NO diagnosis, NO agent internals, NO re-auth / config
+ * instructions, and NO raw error text — just an honest "it's on our side".
+ */
+export function renderUserFacingFailureNotice(): string {
+  return "⚠️ Sorry — I couldn't complete that just now. It's a problem on our side, not anything you did. Please try again shortly."
+}
+
 // ─── Markdown escape (#2669) ──────────────────────────────────────────────────

package/telegram-plugin/pending-user-notice.ts

@@ -0,0 +1,88 @@
+/**
+ * pending-user-notice.ts — deterministic turn-outcome gate for the
+ * non-operator user failure notice (#3293 review finding 1).
+ *
+ * THE PROBLEM this closes: `emitGatewayOperatorEvent` fires whenever
+ * session-tail sees an api_error line, with no knowledge of whether the turn
+ * ultimately RECOVERS (e.g. the LiteLLM fallback 401s but a retry / another
+ * deployment serves the turn). Sending the "couldn't complete that — it's on
+ * our side" notice at error time would tell users a turn failed that actually
+ * completed. The 5-min per-kind operator-event cooldown debounces retry SPAM
+ * but cannot know the turn's outcome.
+ *
+ * THE MECHANISM: the notice is never sent at error time. It is SCHEDULED here,
+ * and resolved at the gateway's single turn-end funnel (`endCurrentTurnAtomic`):
+ *   - turn ended WITH a delivered reply  → the turn recovered → DROP the notice
+ *   - turn ended WITHOUT a delivered reply → the turn genuinely died → SEND it
+ * Operator cards are NOT gated — they stay immediate (the operator must see
+ * the infra fault even when the turn recovers).
+ *
+ * CONSERVATIVE TTL: if no turn end resolves a scheduled notice within
+ * {@link PENDING_USER_NOTICE_TTL_MS} (error arrived between turns, or the turn
+ * record was lost), the notice is silently discarded — a missed notice costs a
+ * user some confusion; a FALSE "couldn't complete" on a served turn costs
+ * trust. Bias to silence.
+ *
+ * Pure module: no IPC, no bot, no FS. Injectable `now` throughout.
+ */
+
+export interface PendingUserNotice {
+  /** Non-operator allowlist chats that should receive the notice. */
+  chatIds: string[]
+  /** The plain-language notice text (renderUserFacingFailureNotice()). */
+  text: string
+  agent: string
+  /** The operator-event kind that produced it (log/debug context only). */
+  kind: string
+  /** When the notice was scheduled (ms epoch). */
+  atMs: number
+}
+
+/** How long a scheduled notice may wait for a resolving turn end. */
+export const PENDING_USER_NOTICE_TTL_MS = 10 * 60_000
+
+export class PendingUserNoticeGate {
+  private pending: PendingUserNotice[] = []
+
+  /**
+   * Schedule a notice for turn-end resolution. Collapses per agent — a burst
+   * of error lines within one turn holds ONE pending notice, not a stack.
+   */
+  schedule(notice: PendingUserNotice): void {
+    this.prune(notice.atMs)
+    this.pending = this.pending.filter((p) => p.agent !== notice.agent)
+    this.pending.push(notice)
+  }
+
+  /**
+   * Resolve at turn end. `turnDeliveredReply` is the turn's outcome signal
+   * (the gateway passes `finalAnswerDelivered || replyCalled`):
+   *   - true  → the turn recovered; every pending notice is dropped, [] returned.
+   *   - false → the turn died without a reply; the un-expired pending notices
+   *     are returned EXACTLY ONCE for the caller to send.
+   * Either way the ledger is cleared (a notice never survives its turn end).
+   */
+  resolveTurnEnd(turnDeliveredReply: boolean, now: number = Date.now()): PendingUserNotice[] {
+    this.prune(now)
+    const out = turnDeliveredReply ? [] : [...this.pending]
+    this.pending = []
+    return out
+  }
+
+  /** True when at least one un-expired notice is pending (does not mutate). */
+  hasPending(now: number = Date.now()): boolean {
+    return this.pending.some((p) => now - p.atMs < PENDING_USER_NOTICE_TTL_MS)
+  }
+
+  private prune(now: number): void {
+    this.pending = this.pending.filter((p) => now - p.atMs < PENDING_USER_NOTICE_TTL_MS)
+  }
+
+  /** Test-only: forget everything. */
+  reset(): void {
+    this.pending = []
+  }
+}
+
+/** The process-wide gate the gateway consults. */
+export const pendingUserNoticeGate = new PendingUserNoticeGate()

package/telegram-plugin/shared/local-time.ts

@@ -123,3 +123,46 @@ export function fmtLocalStamp(ms: number, tz: string): string {
     return new Date(ms).toISOString()
   }
 }
+
+/**
+ * Leading ISO-8601-Z timestamp at the start of a log line, e.g.
+ * `2026-07-16T04:09:00.123456789Z` or `2026-07-16T04:09:00Z`. Docker log
+ * lines (as surfaced by `switchroom agent logs`) carry one of these per line.
+ * Anchored at line start; the trailing capture is the rest of the line.
+ */
+const LEADING_ISO_Z = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z)(\s|$)/
+
+/**
+ * DISPLAY-ONLY: rewrite a leading UTC ISO-8601-Z timestamp on each line of
+ * `text` into the caller's LOCAL am/pm wall clock via {@link fmtLocalStamp},
+ * so `/logs` output reads `Thursday 2026-07-16 02:09 PM AEST …` instead of a
+ * raw `…T04:09:00Z`. Applied at send time; never mutates stored logs.
+ *
+ * The leading stamp comes from `docker logs --timestamps` (requested by the
+ * /logs path via `switchroom agent logs --timestamps`) — docker's stamp is
+ * ALWAYS UTC ISO-Z, which is what makes this conversion deterministic. App-
+ * emitted stamps inside the line body (e.g. Python's `%H:%M:%S,mmm`) are
+ * deliberately NOT converted: post-#3275 containers run with local TZ baked,
+ * so those are already local wall clock — re-shifting them as UTC would be
+ * wrong. The `tz` passed by /logs is the GATEWAY/operator zone
+ * (`resolveEnvTimezone` of the gateway process), not the target agent's
+ * zone — intended, since /logs is an operator-facing surface.
+ *
+ * Pure / total — matches ONLY a well-formed leading ISO-Z stamp and preserves
+ * every other line (and any line whose timestamp doesn't parse) verbatim, so a
+ * non-timestamped or partial log line is passed through untouched. `\r`
+ * line endings are preserved.
+ */
+export function renderLogTimestampsLocal(text: string, tz: string): string {
+  if (!text) return text
+  return text
+    .split('\n')
+    .map((line) => {
+      const m = LEADING_ISO_Z.exec(line)
+      if (!m) return line
+      const ms = Date.parse(m[1])
+      if (Number.isNaN(ms)) return line
+      return `${fmtLocalStamp(ms, tz)}${m[2] === '' ? '' : ' '}${line.slice(m[0].length)}`
+    })
+    .join('\n')
+}

package/telegram-plugin/tests/catch-all-forwarded-history.test.ts

@@ -0,0 +1,103 @@
+/**
+ * Outcome regression for the forwarded-message history row (#3300 / #3162).
+ *
+ * SCOPE (honest): this suite pins the PERSISTENCE leg of the end-to-end
+ * chain — `parseForwardOrigin` (#3162) feeding `recordInbound` against the
+ * real bun:sqlite history store. The ROUTING leg (an update reaching the
+ * pipeline at all — the layer where the 2026-07-16 silent drop happened) is
+ * pinned by `catch-all-unhandled-message.test.ts`, which drives the real
+ * production catch-all module on a real grammy composer. Together the two
+ * suites cover the chain; this one alone also passes on pre-#3300 code
+ * because #3162's persistence was always correct — it was simply never
+ * reached for the dropped message.
+ *
+ * Runs under bun (history.ts uses bun:sqlite; gateway.ts itself is a
+ * side-effecting module that cannot be imported into a test).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test'
+import { mkdtempSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import {
+  initHistory,
+  recordInbound,
+  query as queryHistory,
+  _resetForTests as resetHistory,
+} from '../history.js'
+import { parseForwardOrigin } from '../gateway/forward-origin.js'
+
+let stateDir: string
+
+beforeEach(() => {
+  resetHistory()
+  stateDir = mkdtempSync(join(tmpdir(), 'catch-all-forward-'))
+  initHistory(stateDir, 0) // 0 disables the init-time prune so we can seed cleanly
+})
+
+afterEach(() => {
+  resetHistory()
+  rmSync(stateDir, { recursive: true, force: true })
+})
+
+describe('(a) a forwarded plain-text message records a history row with forwarded_from', () => {
+  it('parses the server-stamped forward_origin and persists forwarded_from', () => {
+    const chat_id = '777'
+    const message_id = 8100
+    // Telegram Bot API 7.0 forward_origin, server-stamped (untrusted body,
+    // trusted attrs) — a plain-text message forwarded from a user.
+    const forwardOrigin = parseForwardOrigin({
+      type: 'user',
+      date: 1_700_000_000,
+      sender_user: { id: 424242, is_bot: false, first_name: 'Ken', last_name: 'Thompson' },
+    })
+    expect(forwardOrigin).toBeDefined()
+    expect(forwardOrigin!.name).toBe('Ken Thompson')
+
+    recordInbound({
+      chat_id,
+      thread_id: null,
+      message_id,
+      user: 'ken',
+      user_id: '777',
+      ts: 1_700_000_100,
+      text: 'here is the brief I forwarded',
+      forwarded_from: forwardOrigin!.name,
+      forwarded_from_type: forwardOrigin!.type,
+      forwarded_from_id: forwardOrigin!.id != null ? String(forwardOrigin!.id) : null,
+    })
+
+    const rows = queryHistory({ chat_id, limit: 10 })
+    expect(rows).toHaveLength(1)
+    const row = rows[0]
+    // A delivered turn is present (the message was NOT dropped) AND carries
+    // forwarded provenance.
+    expect(row.role).toBe('user')
+    expect(row.text).toBe('here is the brief I forwarded')
+    expect(row.forwarded_from).toBe('Ken Thompson')
+    expect(row.forwarded_from_type).toBe('user')
+    expect(row.forwarded_from_id).toBe('424242')
+  })
+
+  it('a non-forwarded message leaves forwarded_from NULL (no false provenance)', () => {
+    const chat_id = '778'
+    // undefined forward_origin → parseForwardOrigin returns undefined.
+    const forwardOrigin = parseForwardOrigin(undefined)
+    expect(forwardOrigin).toBeUndefined()
+
+    recordInbound({
+      chat_id,
+      thread_id: null,
+      message_id: 8200,
+      user: 'ken',
+      user_id: '778',
+      ts: 1_700_000_200,
+      text: 'a normal message',
+      forwarded_from: forwardOrigin ?? null,
+    })
+
+    const rows = queryHistory({ chat_id, limit: 10 })
+    expect(rows).toHaveLength(1)
+    expect(rows[0].forwarded_from).toBeNull()
+  })
+})

package/telegram-plugin/tests/catch-all-unhandled-message.test.ts

@@ -0,0 +1,264 @@
+/**
+ * Regression tests for the terminal catch-all message handler + diagnostic
+ * update tap (#3300).
+ *
+ * THE CLASS OF BUG: the gateway registered ONLY content-specific handlers —
+ * `bot.on('message:text')`, `:photo`, `:document`, … `:paid_media`. grammy
+ * ^1.44 routes `bot.on` as filtering middleware (`on → filter(pred, handler)
+ * → branch(pred, handler, pass)`, verified in grammy/out/composer.js); when
+ * NO registered filter matches an inbound `message`, grammy SILENTLY drops
+ * it — no log, no ack, no history row. Live signature (2026-07-16, klanker
+ * DM): message_id 19090 was allocated between an outbound reply and the next
+ * inbound with ZERO gateway trace while polling stayed healthy.
+ *
+ * THE FIX under test is the REAL production module
+ * (`gateway/unhandled-message.ts`) — the same `installUpdateTap` /
+ * `installUnhandledMessageCatchAll` gateway.ts wires — driven through a real
+ * grammy 1.44 Bot via `bot.handleUpdate`, with a real `bot.on('message:text')`
+ * registered BEFORE the catch-all exactly like the gateway's registration
+ * order. (gateway.ts itself is a side-effecting module that cannot be
+ * imported into a unit test — the extraction into unhandled-message.ts exists
+ * precisely so the registered composer path is testable; a structural suite
+ * below guards that gateway.ts actually wires it in that order.)
+ *
+ * Outcomes asserted:
+ *   (b) an unregistered content type reaches the catch-all, is logged, and
+ *       yields a turn with the placeholder text naming the content type;
+ *   (c) a plain text message is consumed by the specific handler and does
+ *       NOT double-handle in the catch-all;
+ *   service-noise messages (forum topic lifecycle etc.) are logged but do
+ *       NOT become turns;
+ *   the tap observes every update and rate-limits with a suppression summary.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { Bot, type Context } from 'grammy'
+import type { Update } from 'grammy/types'
+import { makeMessageUpdate, resetUpdateCounters } from './update-factory.js'
+import {
+  installUpdateTap,
+  installUnhandledMessageCatchAll,
+  planUnhandledMessage,
+  SERVICE_NOISE_KEYS,
+  TAP_MAX_LINES_PER_MINUTE,
+} from '../gateway/unhandled-message.js'
+
+interface DeliveredTurn {
+  via: 'text' | 'catch-all'
+  text: string
+  update_id: number
+}
+
+/**
+ * Wire a real grammy Bot in the gateway's registration order using the REAL
+ * production install functions: tap first, specific `message:text` handler,
+ * terminal catch-all LAST. `onInbound` records what would flow into
+ * handleInboundCoalesced.
+ */
+function buildHarness() {
+  const delivered: DeliveredTurn[] = []
+  const logLines: string[] = []
+
+  const bot = new Bot('12345:TEST_TOKEN_NOT_REAL')
+  bot.botInfo = {
+    id: 999,
+    is_bot: true,
+    first_name: 'TestBot',
+    username: 'test_bot',
+    can_join_groups: true,
+    can_read_all_group_messages: false,
+    supports_inline_queries: false,
+    can_connect_to_business: false,
+    has_main_web_app: false,
+  }
+
+  // REAL production tap (same call gateway.ts makes).
+  installUpdateTap(bot, line => logLines.push(line))
+
+  // Specific handler — representative of the gateway's message:text
+  // registration, placed BEFORE the catch-all exactly as in gateway.ts.
+  bot.on('message:text', async ctx => {
+    delivered.push({ via: 'text', text: ctx.message.text, update_id: ctx.update.update_id })
+  })
+
+  // REAL production catch-all, registered LAST (same call gateway.ts makes).
+  installUnhandledMessageCatchAll(
+    bot,
+    async (ctx: Context, text: string) => {
+      delivered.push({ via: 'catch-all', text, update_id: ctx.update.update_id })
+    },
+    line => logLines.push(line),
+  )
+
+  return { bot, delivered, logLines }
+}
+
+/** A message update carrying content that no `message:*` filter covers. */
+function makeContentUpdate(update_id: number, content: Record<string, unknown>): Update {
+  return {
+    update_id,
+    message: {
+      message_id: 5000 + update_id,
+      chat: { id: 777, type: 'private' },
+      from: { id: 777, is_bot: false, first_name: 'Test' },
+      date: Math.floor(Date.now() / 1000),
+      ...content,
+    },
+  } as unknown as Update
+}
+
+describe('terminal catch-all — real module on a real grammy 1.44 composer (#3300)', () => {
+  beforeEach(() => resetUpdateCounters())
+
+  it('(c) a plain-text message is consumed by message:text and does NOT reach the catch-all', async () => {
+    const { bot, delivered, logLines } = buildHarness()
+    await bot.handleUpdate(makeMessageUpdate({ text: 'hello brief', update_id: 42 }))
+
+    expect(delivered).toHaveLength(1)
+    expect(delivered[0]).toMatchObject({ via: 'text', text: 'hello brief' })
+    // No catch-all log line — specific handler won (no double-handling).
+    expect(logLines.filter(l => l.includes('catch-all inbound'))).toHaveLength(0)
+  })
+
+  it('(b) an unregistered content type reaches the catch-all, is logged, and yields a placeholder turn', async () => {
+    const { bot, delivered, logLines } = buildHarness()
+    await bot.handleUpdate(makeContentUpdate(99, { unknown_future_type: { some: 'payload' } }))
+
+    // Logged with content KEYS + ids only (never the payload body).
+    const catchAllLines = logLines.filter(l => l.includes('catch-all inbound'))
+    expect(catchAllLines).toHaveLength(1)
+    expect(catchAllLines[0]).toContain('update_id=99')
+    expect(catchAllLines[0]).toContain('content_keys=[unknown_future_type]')
+    expect(catchAllLines[0]).not.toContain('payload')
+
+    // Produced a delivered turn with placeholder text naming the content type.
+    expect(delivered).toHaveLength(1)
+    expect(delivered[0]).toMatchObject({
+      via: 'catch-all',
+      text: '(unhandled message content: unknown_future_type)',
+    })
+  })
+
+  it('a caption on an unhandled content type is used as the turn text (best-effort)', async () => {
+    const { bot, delivered } = buildHarness()
+    await bot.handleUpdate(
+      makeContentUpdate(120, { some_new_media: { id: 'x' }, caption: 'read this brief' }),
+    )
+    expect(delivered).toHaveLength(1)
+    expect(delivered[0]).toMatchObject({ via: 'catch-all', text: 'read this brief' })
+  })
+
+  it('known-noise service messages are LOGGED but produce NO agent turn', async () => {
+    const { bot, delivered, logLines } = buildHarness()
+    await bot.handleUpdate(
+      makeContentUpdate(130, { forum_topic_created: { name: 'spam topic', icon_color: 1 } }),
+    )
+    await bot.handleUpdate(
+      makeContentUpdate(131, { new_chat_members: [{ id: 5, is_bot: false, first_name: 'X' }] }),
+    )
+
+    // No turns delivered — service noise never reaches the agent.
+    expect(delivered).toHaveLength(0)
+    // But both were explicitly logged (never silently dropped).
+    const noiseLines = logLines.filter(l => l.includes('action=log-only'))
+    expect(noiseLines).toHaveLength(2)
+    expect(noiseLines[0]).toContain('content_keys=[forum_topic_created]')
+    expect(noiseLines[1]).toContain('content_keys=[new_chat_members]')
+  })
+
+  it('the diagnostic tap observes EVERY update (pass-through, both routed and caught)', async () => {
+    const { bot, logLines } = buildHarness()
+    await bot.handleUpdate(makeMessageUpdate({ text: 'routed', update_id: 1 }))
+    await bot.handleUpdate(makeContentUpdate(2, { unknown_future_type: {} }))
+
+    const rx = logLines.filter(l => l.includes('rx update_id='))
+    expect(rx).toHaveLength(2)
+    expect(rx[0]).toContain('rx update_id=1 type=message')
+    expect(rx[1]).toContain('rx update_id=2 type=message')
+  })
+})
+
+describe('planUnhandledMessage — service-noise classification', () => {
+  it('every SERVICE_NOISE_KEYS entry classifies log-only', () => {
+    for (const key of SERVICE_NOISE_KEYS) {
+      const plan = planUnhandledMessage({ message_id: 1, chat: {}, date: 0, [key]: {} })
+      expect(plan.action, `key ${key} should be log-only`).toBe('log-only')
+    }
+  })
+
+  it('an unknown content type classifies as a turn (fail-toward-delivery)', () => {
+    const plan = planUnhandledMessage({ message_id: 1, chat: {}, date: 0, mystery_type: {} })
+    expect(plan).toMatchObject({
+      action: 'turn',
+      text: '(unhandled message content: mystery_type)',
+    })
+  })
+
+  it('a message mixing noise with real content still becomes a turn', () => {
+    const plan = planUnhandledMessage({
+      message_id: 1, chat: {}, date: 0,
+      boost_added: {}, mystery_media: {}, caption: 'look',
+    })
+    expect(plan).toMatchObject({ action: 'turn', text: 'look' })
+  })
+})
+
+describe('installUpdateTap — rate limit', () => {
+  it('caps lines per minute and emits ONE suppression summary on window rollover', async () => {
+    const logLines: string[] = []
+    let now = 1_000_000
+    const mw: Array<(ctx: unknown, next: () => Promise<void>) => Promise<void>> = []
+    const fakeBot = { use: (fn: (ctx: unknown, next: () => Promise<void>) => Promise<void>) => { mw.push(fn) } }
+    installUpdateTap(fakeBot as never, l => logLines.push(l), () => now)
+
+    const fire = (update_id: number) =>
+      mw[0]({ update: { update_id }, message: undefined } as never, async () => {})
+
+    for (let i = 0; i < TAP_MAX_LINES_PER_MINUTE + 50; i++) await fire(i)
+    expect(logLines.filter(l => l.includes('rx update_id='))).toHaveLength(TAP_MAX_LINES_PER_MINUTE)
+
+    // Roll the window: the 50 suppressed lines surface as ONE summary.
+    now += 61_000
+    await fire(9999)
+    const summaries = logLines.filter(l => l.includes('suppressed 50 update lines'))
+    expect(summaries).toHaveLength(1)
+    // And logging resumes in the fresh window.
+    expect(logLines.filter(l => l.includes('rx update_id=9999'))).toHaveLength(1)
+  })
+})
+
+// ─── Structural guard on the real gateway.ts wiring ────────────────────────
+// The functional harness above proves the composer contract using the REAL
+// production install functions; this guards that gateway.ts wires those same
+// functions in the required order. Hardened beyond a naive regex: it fails
+// if the install call disappears (e.g. refactored away) OR if ANY
+// `bot.on('message…')` registration appears after the catch-all install.
+describe('gateway.ts catch-all registration invariant', () => {
+  const SRC = readFileSync(new URL('../gateway/gateway.ts', import.meta.url), 'utf8')
+
+  it('imports and installs the real catch-all + tap from unhandled-message.ts', () => {
+    expect(SRC).toContain("from './unhandled-message.js'")
+    expect(SRC).toContain('installUpdateTap(bot,')
+    expect(SRC).toContain('installUnhandledMessageCatchAll(')
+  })
+
+  it('the catch-all install is AFTER every message handler registration', () => {
+    const installIdx = SRC.indexOf('installUnhandledMessageCatchAll(')
+    expect(installIdx).toBeGreaterThan(0)
+    const after = SRC.slice(installIdx)
+    // No message-filter registration of any spelling may follow the terminal
+    // catch-all — grammy ordering is the no-double-handling guarantee.
+    // (`message_reaction` etc. are DIFFERENT update types, not `message`
+    // filters — the pattern requires `message` exactly or `message:<sub>`.)
+    expect(after).not.toMatch(/bot\.on\(\s*['"`]message(:|['"`])/)
+    // And there must be exactly one catch-all install (no duplicate turns).
+    expect(SRC.indexOf('installUnhandledMessageCatchAll(', installIdx + 1)).toBe(-1)
+  })
+
+  it('routes the catch-all through handleInboundCoalesced (same gating + forward-origin path)', () => {
+    const installIdx = SRC.indexOf('installUnhandledMessageCatchAll(')
+    const body = SRC.slice(installIdx, installIdx + 400)
+    expect(body).toMatch(/handleInboundCoalesced\(ctx, text, undefined\)/)
+  })
+})