switchroom 0.18.28 → 0.18.30

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

@@ -67,3 +67,102 @@ export function tzAbbrev(ms: number, tz: string): string {
       .find((p) => p.type === 'timeZoneName')?.value ?? tz
   )
 }
+
+/**
+ * Resolve the agent's configured timezone from the process environment, the
+ * SAME cascade `bin/timezone-hook.sh` and the config resolver use:
+ * `SWITCHROOM_TIMEZONE` → `TZ` → `UTC`. Centralised so the inbound-tag,
+ * forwarded_date, and recent-buffer callsites can't drift.
+ */
+export function resolveEnvTimezone(env: NodeJS.ProcessEnv = process.env): string {
+  return env.SWITCHROOM_TIMEZONE ?? env.TZ ?? 'UTC'
+}
+
+/**
+ * Full model-facing local wall-clock stamp, e.g.
+ * `Thursday 2026-07-16 04:09 PM AEST`.
+ *
+ * The deterministic replacement for the UTC ISO strings the model used to see
+ * on inbound channel tags (`ts="…Z"`), `forwarded_date`, and the
+ * `get_recent_messages` buffer. am/pm form in the agent's CONFIGURED timezone,
+ * with NO "UTC" / trailing-Z — so the LLM can never read one of these as UTC
+ * "now" and reason an offset wrong.
+ *
+ * Format matches the CORE of `bin/timezone-hook.sh`'s stamp —
+ * `%A %Y-%m-%d %I:%M %p %Z` (weekday, ISO date, am/pm, zone abbrev) — so the
+ * inbound-tag time and the UserPromptSubmit local-time hint read the same way.
+ * The hook additionally appends a ` (UTC±HH:MM)` numeric-offset LABEL that this
+ * helper deliberately omits: the abbrev (AEST/EDT) already disambiguates, and
+ * keeping the output free of any "UTC" substring makes the deterministic
+ * no-UTC-current-time guard trivially strict for every callsite. So it is NOT
+ * a byte-for-byte match — same core shape, minus the offset tail.
+ *
+ * Pure / total: an invalid IANA `tz` (misconfigured agent) degrades to the
+ * same am/pm shape rendered in UTC rather than throwing out of the inbound
+ * path — a bad zone must never crash a turn.
+ */
+export function fmtLocalStamp(ms: number, tz: string): string {
+  try {
+    const at = new Date(ms)
+    const weekday = new Intl.DateTimeFormat('en-US', {
+      timeZone: tz,
+      weekday: 'long',
+    }).format(at)
+    // localDay (en-CA) yields YYYY-MM-DD and throws first on a bad zone.
+    const date = localDay(ms, tz)
+    const time = new Intl.DateTimeFormat('en-US', {
+      timeZone: tz,
+      hour: '2-digit',
+      minute: '2-digit',
+      hour12: true,
+    }).format(at) // "04:09 PM"
+    return `${weekday} ${date} ${time} ${tzAbbrev(ms, tz)}`
+  } catch {
+    // Invalid IANA zone — degrade to am/pm in UTC rather than crash the turn.
+    if (tz !== 'UTC') return fmtLocalStamp(ms, 'UTC')
+    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/backstop-delivery.test.ts

@@ -0,0 +1,250 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import {
+  BackstopDeliveryLedger,
+  backstopReceiptIds,
+  backstopDelivered,
+  runBackstopDelivery,
+} from '../gateway/backstop-delivery.js'
+import {
+  backstopSendOutcomeGated,
+  finalizeBackstopSendGated,
+  computeTurnStatus,
+} from '../gateway/turn-record-status.js'
+
+/**
+ * #3276 — the turn-flush backstop delivered by editing the ephemeral progress
+ * card and counted that card-edit id as an answer delivery, so the turn record
+ * said `complete` while the card was GC'd and nothing durable reached the chat.
+ *
+ * These assert the deterministic OUTCOMES the fix guarantees:
+ *  - a delivered answer is a FRESH non-card chat id (guard 7),
+ *  - `complete` IFF such an id exists; card-only "success" ⇒ `send_failed`,
+ *  - a per-turn backstop double-fire latch (guard 5),
+ *  - a bounded retry resumes mid-chunk and never re-sends chunk 0 (guard 6),
+ *  - terminal failure reports `delivered:false` so the caller leaves the
+ *    delivery obligation OPEN (finding 1).
+ */
+
+describe('guard 7 — receipt gate: a delivered answer is a FRESH non-card chat id', () => {
+  it('primary: a fresh chat id is recorded whose id ≠ any card id', () => {
+    const cardId = 500
+    const sentIds = [777] // a fresh sendMessage id, not the card
+    const fresh = backstopReceiptIds(sentIds, cardId)
+    expect(fresh).toEqual([777])
+    expect(fresh).not.toContain(cardId)
+    expect(backstopDelivered(sentIds, cardId)).toBe(true)
+  })
+
+  it('card-present: the delivered id excludes backstopCardMessageId', () => {
+    const cardId = 18944
+    // The pre-fix backstop pushed the card id into sentIds via editMessageText.
+    const raw = [18944]
+    expect(backstopReceiptIds(raw, cardId)).toEqual([])
+    expect(backstopDelivered(raw, cardId)).toBe(false)
+  })
+
+  it('mixed: only the fresh ids survive the gate', () => {
+    const cardId = 18944
+    expect(backstopReceiptIds([18944, 18950, 18951], cardId)).toEqual([18950, 18951])
+  })
+})
+
+describe('status honesty — complete IFF a real non-card id exists', () => {
+  it('card-only delivery ⇒ send_failed, never complete', () => {
+    const cardId = 18944
+    const turn: { finalAnswerDelivered: boolean; deliveryOutcome?: 'delivered' | 'failed' | 'suppressed' } = {
+      finalAnswerDelivered: true,
+    }
+    finalizeBackstopSendGated(turn, {
+      threw: false,
+      sentIds: [18944], // only the card was edited
+      chunkCount: 1,
+      cardMessageId: cardId,
+    })
+    expect(turn.deliveryOutcome).toBe('failed')
+    expect(computeTurnStatus(turn)).toBe('send_failed')
+  })
+
+  it('fresh chat id delivered ⇒ complete', () => {
+    const turn: { finalAnswerDelivered: boolean; deliveryOutcome?: 'delivered' | 'failed' | 'suppressed' } = {
+      finalAnswerDelivered: true,
+    }
+    finalizeBackstopSendGated(turn, {
+      threw: false,
+      sentIds: [18950],
+      chunkCount: 1,
+      cardMessageId: 18944,
+    })
+    expect(turn.deliveryOutcome).toBe('delivered')
+    expect(computeTurnStatus(turn)).toBe('complete')
+  })
+
+  it('partial multi-chunk (fewer fresh ids than chunks) ⇒ send_failed', () => {
+    expect(
+      backstopSendOutcomeGated({ threw: false, sentIds: [18950], chunkCount: 2, cardMessageId: null }),
+    ).toBe('failed')
+  })
+
+  it('throw ⇒ failed regardless of ids', () => {
+    expect(
+      backstopSendOutcomeGated({ threw: true, sentIds: [18950], chunkCount: 1, cardMessageId: null }),
+    ).toBe('failed')
+  })
+
+  it('empty split (0 chunks) ⇒ failed, not delivered', () => {
+    expect(
+      backstopSendOutcomeGated({ threw: false, sentIds: [], chunkCount: 0, cardMessageId: null }),
+    ).toBe('failed')
+  })
+})
+
+describe('guard 5 — once-per-turn backstop double-fire latch', () => {
+  it('claim returns true exactly once per turnId', () => {
+    const ledger = new BackstopDeliveryLedger()
+    expect(ledger.claim('#18925')).toBe(true)
+    expect(ledger.claim('#18925')).toBe(false)
+    // A different turn is independent.
+    expect(ledger.claim('#18929')).toBe(true)
+  })
+
+  it('release re-opens the latch after a terminal failure', () => {
+    const ledger = new BackstopDeliveryLedger()
+    ledger.claim('#t')
+    ledger.release('#t')
+    expect(ledger.claim('#t')).toBe(true)
+  })
+})
+
+describe('guard 6 — per-chunk idempotency ledger: retry never re-sends chunk 0', () => {
+  it('resumes at the first unsent chunk after a partial send', () => {
+    const ledger = new BackstopDeliveryLedger()
+    const turnId = '#partial'
+    const chunkCount = 3
+    ledger.markPending(turnId, 0)
+    ledger.recordChunk(turnId, 0, [1001])
+    ledger.markPending(turnId, 1)
+    ledger.recordChunk(turnId, 1, [1002])
+    ledger.markPending(turnId, 2) // in-flight, never acked
+
+    expect(ledger.hasChunk(turnId, 0)).toBe(true)
+    expect(ledger.hasChunk(turnId, 1)).toBe(true)
+    expect(ledger.hasChunk(turnId, 2)).toBe(false)
+    expect(ledger.unsentIndices(turnId, chunkCount)).toEqual([2])
+
+    ledger.recordChunk(turnId, 2, [1003])
+    expect(ledger.sentIds(turnId)).toEqual([1001, 1002, 1003])
+    expect(ledger.sentIds(turnId)[0]).toBe(1001)
+  })
+
+  it('sentIds are returned in chunk-index order regardless of record order', () => {
+    const ledger = new BackstopDeliveryLedger()
+    ledger.recordChunk('#o', 2, [3])
+    ledger.recordChunk('#o', 0, [1])
+    ledger.recordChunk('#o', 1, [2])
+    expect(ledger.sentIds('#o')).toEqual([1, 2, 3])
+  })
+
+  it('entries() zip a resplit chunk (2 ids for 1 input chunk) in order', () => {
+    const ledger = new BackstopDeliveryLedger()
+    ledger.recordChunk('#z', 0, [10])
+    ledger.recordChunk('#z', 1, [11, 12]) // chunk 1 length-resplit into 2 sends
+    expect(ledger.entries('#z')).toEqual([
+      { index: 0, messageIds: [10] },
+      { index: 1, messageIds: [11, 12] },
+    ])
+  })
+})
+
+/**
+ * Integration oracles over `runBackstopDelivery` — the exact orchestration that
+ * replaced the card-coupled send. It drives the real retry/ledger/receipt code
+ * with an injected `sendChunk`, asserting on what reaches `recordOutbound` and
+ * on the `delivered`/`exhausted` decision the gateway feeds to the obligation
+ * ledger + turn record.
+ */
+describe('runBackstopDelivery — integration oracle over the delivery wiring', () => {
+  it('records a FRESH non-card id in history; delivered=true (#3276 primary)', async () => {
+    const ledger = new BackstopDeliveryLedger()
+    const cardId = 18944
+    const recorded: Array<{ ids: number[]; texts: string[] }> = []
+    const sendChunk = vi.fn(async (i: number) => [18950 + i]) // fresh chat ids
+    const res = await runBackstopDelivery(
+      ledger,
+      '#18925',
+      ['the answer'],
+      cardId,
+      { sendChunk, recordOutbound: (ids, texts) => recorded.push({ ids, texts }) },
+    )
+    expect(res.delivered).toBe(true)
+    expect(res.exhausted).toBe(false)
+    expect(recorded).toHaveLength(1)
+    // A real fresh chat id landed in history whose id ≠ the progress-card id.
+    expect(recorded[0].ids).toEqual([18950])
+    expect(recorded[0].ids).not.toContain(cardId)
+    expect(backstopReceiptIds(recorded[0].ids, cardId)).toEqual([18950])
+  })
+
+  it('card-only "delivery" can never happen — the receipt gate excludes the card id', async () => {
+    const ledger = new BackstopDeliveryLedger()
+    const cardId = 18944
+    // Even if a buggy send echoed the card id, the receipt gate drops it.
+    const sendChunk = vi.fn(async () => [cardId])
+    const res = await runBackstopDelivery(ledger, '#c', ['x'], cardId, { sendChunk })
+    expect(res.delivered).toBe(false)
+    expect(res.exhausted).toBe(true)
+  })
+
+  it('retry resumes mid-chunk — chunk 0 is NOT re-sent on attempt 2 (guard 6, finding 1)', async () => {
+    const ledger = new BackstopDeliveryLedger()
+    const calls: number[] = []
+    let failedOnce = false
+    const sendChunk = vi.fn(async (i: number) => {
+      calls.push(i)
+      if (i === 2 && !failedOnce) {
+        failedOnce = true
+        throw new Error('FLOOD_WAIT_ACTIVE')
+      }
+      return [700 + i]
+    })
+    const res = await runBackstopDelivery(ledger, '#resume', ['c0', 'c1', 'c2'], null, { sendChunk }, 3)
+
+    expect(res.delivered).toBe(true)
+    expect(res.sentIds).toEqual([700, 701, 702])
+    // chunk 0 and 1 sent exactly once; chunk 2 attempted twice (fail, then ok).
+    expect(calls.filter(i => i === 0)).toHaveLength(1) // <-- chunk 0 never re-sent
+    expect(calls.filter(i => i === 1)).toHaveLength(1)
+    expect(calls.filter(i => i === 2)).toHaveLength(2)
+    expect(res.attempts).toBe(2)
+  })
+
+  it('terminal failure ⇒ delivered=false / exhausted=true after maxAttempts (obligation left open)', async () => {
+    const ledger = new BackstopDeliveryLedger()
+    const sendChunk = vi.fn(async () => { throw new Error('FLOOD_WAIT_ACTIVE') })
+    const res = await runBackstopDelivery(ledger, '#dead', ['only chunk'], null, { sendChunk }, 3)
+    expect(res.delivered).toBe(false)
+    expect(res.exhausted).toBe(true)
+    expect(res.attempts).toBe(3) // exhausted the bounded retry
+    expect(res.sentIds).toEqual([]) // nothing landed
+    // This is the exact input the gateway uses: delivered=false ⇒ it records
+    // send_failed AND leaves the obligation OPEN (noteTurnEnded, not close).
+    expect(backstopSendOutcomeGated({
+      threw: !res.delivered, sentIds: res.sentIds, chunkCount: res.chunkCount, cardMessageId: null,
+    })).toBe('failed')
+  })
+
+  it('recordOutbound texts are ALIGNED to sent ids even when a chunk resplits (finding 5)', async () => {
+    const ledger = new BackstopDeliveryLedger()
+    const recorded: Array<{ ids: number[]; texts: string[] }> = []
+    // chunk 1 lands TWO ids (a length-resplit); a naive chunks.slice zip would
+    // misalign. entries()-based zip repeats the source text per landed id.
+    const sendChunk = vi.fn(async (i: number) => (i === 1 ? [11, 12] : [10]))
+    await runBackstopDelivery(
+      ledger, '#zip', ['A', 'B'], null,
+      { sendChunk, recordOutbound: (ids, texts) => recorded.push({ ids, texts }) },
+    )
+    expect(recorded[0].ids).toEqual([10, 11, 12])
+    expect(recorded[0].texts).toEqual(['A', 'B', 'B'])
+    expect(recorded[0].ids).toHaveLength(recorded[0].texts.length)
+  })
+})

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()
+  })
+})