switchroom 0.18.13 → 0.18.15

package/telegram-plugin/render/rich-render.ts

@@ -1,21 +1,24 @@
-// Flag-gated wiring for the Bot API 10.1 rich renderer (parse.ts + render.ts)
-// into the live outbound send path.
+// Wiring for the Bot API 10.1 rich renderer (parse.ts + render.ts) into the
+// live outbound send path.
 //
 // The renderer (`render/render.ts`, PR #2930) and parser (`render/parse.ts`)
 // have full unit coverage but were, until this module, wired into NOTHING —
-// no outbound message ever flowed through them. This module is the single,
-// feature-flagged bridge: the gateway's rich send path (stream-controller.ts)
-// runs the assistant's raw markdown through `parse → renderSafe` before it
-// reaches `sendRichMessage`, but ONLY when the flag is on.
+// no outbound message ever flowed through them. This module is the single
+// bridge: the gateway's rich send path (stream-controller.ts) runs the
+// assistant's raw markdown through `parse → renderSafe` before it reaches
+// `sendRichMessage`, unless the escape hatch below disables it.
 //
-// Feature flag — `SWITCHROOM_RICH_RENDER`, default OFF:
-//   Mirrors the `SWITCHROOM_VISIBLE_ANSWER_STREAM` convention
-//   (`answer-stream-flag.ts`): an env var read at runtime, default off, opted
-//   in PER AGENT via the `env:` block in `switchroom.yaml` (propagated into
-//   the container `environment:` by `src/agents/compose.ts`). When off,
-//   `maybeRenderOutbound` returns the input untouched, so the live send path
-//   is byte-for-byte unchanged — no agent's behaviour moves until an operator
-//   explicitly flips the flag for a specific agent. Accepts `1/true/on/yes`.
+// Escape hatch — `SWITCHROOM_RICH_RENDER`, default ON:
+//   ON BY DEFAULT in every install — an escape hatch, not an opt-in feature,
+//   mirroring the send gate's convention (`sendGateEnabledFromEnv` in
+//   `send-gate.ts`, default-on since #3153; also `midTurnFloorEnabled`,
+//   `SWITCHROOM_RATE_LIMIT_OVERAGE=0`). Enabled unless the var is explicitly
+//   set to a falsey/off value (`0`/`false`/`off`/`no`, case-insensitive,
+//   trimmed) — per agent via the `env:` block in `switchroom.yaml`
+//   (propagated into the container `environment:` by
+//   `src/agents/compose.ts`). When disabled, `maybeRenderOutbound` returns
+//   the input untouched, so the live send path is byte-for-byte the
+//   pre-renderer behaviour (raw transcript markdown to `sendRichMessage`).
 //
 // Why route through `renderSafe` and not bare `render`:
 //   `renderSafe` guarantees the returned body is never a rich-markdown string
@@ -38,17 +41,19 @@ import { RICH_MESSAGE_MAX_CHARS, splitMarkdownChunks } from "../format.js";
  */
 export const PLAIN_TEXT_MAX_CHARS = 4096;
 
-/** Parse the `SWITCHROOM_RICH_RENDER` flag value. Default OFF; accepts the
- *  same truthy tokens as the other switchroom env flags. Pure so the default
- *  + parsing are unit-testable. */
+/** Parse the `SWITCHROOM_RICH_RENDER` kill-switch value. Default ON; disabled
+ *  only by an explicit falsey/off token (`0`/`false`/`off`/`no`,
+ *  case-insensitive, trimmed) — the same disable vocabulary as
+ *  `sendGateEnabledFromEnv`. Unset, empty, or unrecognised values → ON. Pure
+ *  so the default + parsing are unit-testable. */
 export function parseRichRenderEnabled(raw: string | undefined): boolean {
-  if (raw == null) return false;
+  if (raw == null) return true;
   const v = raw.trim().toLowerCase();
-  return v === "1" || v === "true" || v === "on" || v === "yes";
+  return !(v === "0" || v === "false" || v === "off" || v === "no");
 }
 
 /** Is the rich renderer enabled in this process? Reads the env flag live so a
- *  test can set/unset it per-case; defaults OFF. */
+ *  test can set/unset it per-case; defaults ON (escape hatch, not opt-in). */
 export function richRenderEnabled(
   env: NodeJS.ProcessEnv = process.env,
 ): boolean {
@@ -65,13 +70,14 @@ export function renderOutbound(
 }
 
 /**
- * Flag-gated transform for the live send path.
+ * Kill-switch-gated transform for the live send path.
  *
- *   - flag OFF (default): returns the input untouched, `mode: "markdown"` —
- *     identical to the pre-existing behaviour (raw transcript markdown sent
- *     straight to `sendRichMessage`). No behavioural change for any agent.
- *   - flag ON: returns `parse → renderSafe` output. `mode: "plain"` signals
- *     the caller to send WITHOUT the rich wrapper (oversized/unsafe content).
+ *   - enabled (default): returns `parse → renderSafe` output. `mode: "plain"`
+ *     signals the caller to send WITHOUT the rich wrapper (oversized/unsafe
+ *     content).
+ *   - disabled (`SWITCHROOM_RICH_RENDER=0`): returns the input untouched,
+ *     `mode: "markdown"` — identical to the pre-renderer behaviour (raw
+ *     transcript markdown sent straight to `sendRichMessage`).
  */
 export function maybeRenderOutbound(
   text: string,
@@ -83,7 +89,7 @@ export function maybeRenderOutbound(
 }
 
 /**
- * Flag-gated, CAP-ENFORCING transform for the live send path.
+ * Kill-switch-gated, CAP-ENFORCING transform for the live send path.
  *
  * `maybeRenderOutbound` returns ONE `RenderResult` and can only ever fit a
  * body into a single wire message. But `renderSafe`'s markdown re-escaping
@@ -104,11 +110,13 @@ export function maybeRenderOutbound(
  * plain degradation would have thrown away: the smaller pieces individually
  * escape under `maxLen` and come back as `markdown`.
  *
- *   - flag OFF (default): `[{ text, mode: "markdown", degradations: [] }]` —
- *     a single passthrough piece, identical to `maybeRenderOutbound`.
- *   - flag ON, body fits: `[renderSafe(...)]` — a single piece, identical to
- *     `maybeRenderOutbound` (byte-for-byte for the common case).
- *   - flag ON, body oversize: 2+ cap-respecting pieces in send order.
+ *   - disabled (`SWITCHROOM_RICH_RENDER=0`):
+ *     `[{ text, mode: "markdown", degradations: [] }]` — a single passthrough
+ *     piece, identical to `maybeRenderOutbound`.
+ *   - enabled (default), body fits: `[renderSafe(...)]` — a single piece,
+ *     identical to `maybeRenderOutbound` (byte-for-byte for the common case).
+ *   - enabled (default), body oversize: 2+ cap-respecting pieces in send
+ *     order.
  */
 export function renderOutboundChunks(
   text: string,

package/telegram-plugin/runtime-metrics.ts

@@ -164,6 +164,37 @@ export type RuntimeMetricEvent =
       agent: string
       prompt_key: string
     }
+  /**
+   * Every terminal rate-limit-family operator event (429 burst / 529
+   * overload), classified by origin BEFORE the gateway acts on it — fires
+   * even when the user-facing card is cooldown-suppressed, so the count is
+   * honest. `classification` says where the limit lives (see
+   * `RateLimit429Classification` in throttle-tier.ts): `account-scoped` =
+   * Anthropic throttled the account (throttle tier ran), `litellm-local` =
+   * the LiteLLM proxy's own tpm/rpm/router limiter tripped (calm path, no
+   * account attribution), `generic-transient` = other server-side 429/529
+   * wording. `action` is what the gateway DECIDED (throttle / failover /
+   * calm), emitted PRE-execution: the actual failover fire is dedup-gated
+   * downstream (fleetFallbackGate), so N long-reset 429s inside one dedup
+   * window emit N `action: 'failover'` metrics for ONE real roll — count
+   * decisions here, count rolls via the broker/fallback announcements.
+   * Correlating `account-scoped` fires against fleet token throughput is
+   * the operator's evidence base for setting LiteLLM `tpm_limit` caps; the
+   * `litellm-local` count then shows those caps actually absorbing load.
+   * Limit/reset fields are best-effort parses of the error body (null when
+   * absent).
+   */
+  | {
+      kind: 'rate_limit_429_classified'
+      agent: string
+      classification: 'account-scoped' | 'litellm-local' | 'generic-transient'
+      action: 'throttle' | 'failover' | 'calm'
+      reset_at_ms: number | null
+      reset_in_ms: number | null
+      limit_type: string | null
+      limit: number | null
+      current_usage: number | null
+    }
 
 /**
  * The JSONL sink lives under the runtime state dir so it's per-agent

package/telegram-plugin/session-tail.ts

@@ -41,7 +41,7 @@ function isMultiAgentEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
   return env.PROGRESS_CARD_MULTI_AGENT !== '0'
 }
 import { classifyClaudeError, type OperatorEventKind } from './operator-events.js'
-import { isTransientUpstreamSignal } from './model-unavailable.js'
+import { isLitellmProxyLocal429, isTransientUpstreamSignal } from './model-unavailable.js'
 import { createToolLabelSidecar, type ToolLabelSidecar, type SidecarOptions } from './tool-label-sidecar.js'
 import { isModelSentinel } from './model-label.js'
 
@@ -684,9 +684,21 @@ export function detectErrorInTranscriptLine(
     // model-unavailable.ts) — an ambiguous 429 that merely says "limit" stays
     // quota-exhausted, biasing toward surfacing a real wall. Other statuses fall
     // through to the shared classifier.
+    //
+    // A 429 carrying LiteLLM-proxy-LOCAL limiter wording ("Deployment over
+    // user-defined ratelimit", "Rate limit exceeded for api_key: …" — the
+    // canonical `litellmProxyLocal429Signals` list) is the proxy's own
+    // `tpm_limit`/`rpm_limit` cap tripping BEFORE the request reached
+    // Anthropic. Nothing about the account is exhausted — blanket-labeling it
+    // quota-exhausted would fire the model-unavailable card + mark-exhausted +
+    // fleet failover for a purely proxy-local condition. It is rate-limited
+    // (calm path). Precedence when BOTH wordings appear is owned by
+    // `classify429Detail` gateway-side; here both branches yield the same
+    // 'rate-limited' kind, so order is immaterial.
     const kind: OperatorEventKind =
       status === 429
-        ? isTransientUpstreamSignal(`${text}\n${errStr}`)
+        ? isTransientUpstreamSignal(`${text}\n${errStr}`) ||
+          isLitellmProxyLocal429(`${text}\n${errStr}`)
           ? 'rate-limited'
           : 'quota-exhausted'
         : classifyClaudeError({ type: errStr, status, message: text })

package/telegram-plugin/stream-controller.ts

@@ -228,8 +228,9 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
   // `maybeRenderOutbound` path; a body whose markdown-escaping pushed the
   // rendered form past the cap splits into several pieces, each of which fits
   // its own wire cap and never bisects a fenced block / table row (see
-  // `renderOutboundChunks`). Flag OFF (default) and a literal `format:'text'`
-  // stream both yield a single passthrough piece — no behavioural change.
+  // `renderOutboundChunks`). Rendering disabled (SWITCHROOM_RICH_RENDER=0)
+  // and a literal `format:'text'` stream both yield a single passthrough
+  // piece — byte-for-byte the pre-renderer send path.
   const renderPieces = (text: string): { text: string; rich: boolean }[] => {
     if (literalText) return [{ text, rich: false }]
     // A `plain`-mode piece (oversized/unsafe content renderSafe declined to

package/telegram-plugin/tests/auto-fallback-fleet.test.ts

@@ -118,6 +118,78 @@ describe('runFleetAutoFallback', () => {
     }
   });
 
+  it('parsedResetAt (429 throttle tier) names the recovery when the old probe carried no reset', async () => {
+    const failover = vi.fn(async () => ({ rolledTo: 'you@x', rolled: ['ken@x'] }));
+    const out = await runFleetAutoFallback({
+      state: state('ken@x', ['ken@x', 'you@x']),
+      quotas: [
+        // ken: walled, but the probe carried NO reset time — pre-fix the
+        // announcement's recovery line was silently dropped.
+        qOk({ fiveHourUtilizationPct: 100, representativeClaim: 'five_hour' }),
+        qOk({ fiveHourUtilizationPct: 8, sevenDayUtilizationPct: 20 }),
+      ],
+      failover,
+      triggerAgent: 'carrie',
+      now: NOW,
+      tz: 'UTC',
+      // Parsed from the error prose ("resets 5:50am") by the gateway.
+      parsedResetAt: new Date('2026-05-15T05:50:00Z'),
+    });
+
+    expect(out.kind).toBe('switched');
+    if (out.kind === 'switched') {
+      expect(out.announcement).toContain('recovers');
+      expect(out.announcement).toContain('in 4h 57m');
+    }
+  });
+
+  it('rateLimitTrigger: swaps even when the old account probes HEALTHY (the >threshold leg must execute)', async () => {
+    // A terminal transient 429 NEGATES the usage-limit reading, so healthy
+    // utilization is the EXPECTED state for the rate-limited account. The
+    // healthy-idempotency guard must not self-cancel this swap into a
+    // "probed healthy / Stale event?" no-op.
+    const failover = vi.fn(async () => ({ rolledTo: 'you@x', rolled: ['ken@x'] }));
+    const out = await runFleetAutoFallback({
+      state: state('ken@x', ['ken@x', 'you@x']),
+      quotas: [
+        qOk({ fiveHourUtilizationPct: 12, sevenDayUtilizationPct: 30 }), // healthy!
+        qOk({ fiveHourUtilizationPct: 8, sevenDayUtilizationPct: 20 }),
+      ],
+      failover,
+      triggerAgent: 'carrie',
+      now: NOW,
+      tz: 'UTC',
+      parsedResetAt: new Date('2026-05-15T02:53:00Z'),
+      rateLimitTrigger: true,
+    });
+
+    expect(out.kind).toBe('switched');
+    expect(failover).toHaveBeenCalledTimes(1);
+    if (out.kind === 'switched') {
+      // Honest headline: a rate limit, not a utilization-derived window cap.
+      expect(out.announcement).toContain('rate limit on ken@x');
+      expect(out.announcement).not.toContain('5-hour limit');
+      // Recovery line carries the parsed reset (no window was maxed).
+      expect(out.announcement).toContain('recovers');
+      expect(out.announcement).toContain('in 2h');
+    }
+  });
+
+  it('rateLimitTrigger stays subject to the broker outcome (all-blocked passes through)', async () => {
+    const failover = vi.fn(async () => ({ rolledTo: null, rolled: [] }));
+    const out = await runFleetAutoFallback({
+      state: state('ken@x', ['ken@x']),
+      quotas: [qOk({ fiveHourUtilizationPct: 12, sevenDayUtilizationPct: 30 })],
+      failover,
+      triggerAgent: 'carrie',
+      now: NOW,
+      tz: 'UTC',
+      rateLimitTrigger: true,
+    });
+    expect(out.kind).toBe('all-blocked');
+    expect(failover).toHaveBeenCalledTimes(1);
+  });
+
   it('idempotency: skips the swap WITHOUT calling failover when active probes healthy', async () => {
     const failover = vi.fn();
     const out = await runFleetAutoFallback({

package/telegram-plugin/tests/forward-origin.test.ts

@@ -0,0 +1,309 @@
+/**
+ * Unit tests for the forwarded-message origin helpers
+ * (telegram-plugin/gateway/forward-origin.ts).
+ *
+ * These pin the pure pieces of the forward-origin metadata path that live
+ * outside gateway.ts so they can be exercised without loadAccess()/IPC:
+ *   1. parseForwardOrigin — all four Bot API 7.0 origin shapes, missing
+ *      fields, hostile (attacker-controlled) names, hidden_user marking.
+ *   2. buildForwardOriginMeta — fixed attribute order, XML escaping at the
+ *      channel-meta boundary, numbered `_2..` siblings for multi-origin
+ *      bursts (same convention as image_path_2 / attachment_file_id_2).
+ *   3. dedupeForwardOrigins — the coalescer's burst collapse: a
+ *      single-origin album emits one attr set; distinct origins keep
+ *      arrival order and get numbered.
+ *
+ * Trust model under test: origin info rides the ATTRS lane only, names are
+ * truncated + escaped (they're attacker-controlled), and hidden_user is
+ * explicitly marked so agents don't treat a self-reported display name as
+ * an authenticated identity.
+ */
+
+import { describe, expect, it } from 'vitest'
+import type { MessageOrigin } from 'grammy/types'
+import {
+  parseForwardOrigin,
+  buildForwardOriginMeta,
+  dedupeForwardOrigins,
+  forwardOriginKey,
+  forwardOriginDateIso,
+  FORWARDED_FROM_NAME_MAX,
+  type ForwardOriginInfo,
+} from '../gateway/forward-origin.js'
+
+// Synthetic fixtures only — no real Telegram ids/names (check-no-pii-secrets).
+const DATE = 1750000000 // unix seconds
+const DATE_ISO = new Date(DATE * 1000).toISOString()
+
+function userOrigin(overrides: Partial<{
+  first_name: string
+  last_name?: string
+  username?: string
+  id: number
+}> = {}): MessageOrigin {
+  return {
+    type: 'user',
+    date: DATE,
+    sender_user: {
+      id: 42,
+      is_bot: false,
+      first_name: 'Ada',
+      last_name: 'Lovelace',
+      username: 'adalove',
+      ...overrides,
+    },
+  }
+}
+
+describe('parseForwardOrigin — the four origin shapes', () => {
+  it('user: first + last name plus (@username), id and date captured', () => {
+    const info = parseForwardOrigin(userOrigin())
+    expect(info).toEqual({
+      name: 'Ada Lovelace (@adalove)',
+      type: 'user',
+      id: 42,
+      date: DATE,
+    })
+  })
+
+  it('user: first name only, no username', () => {
+    const info = parseForwardOrigin(userOrigin({ last_name: undefined, username: undefined }))
+    expect(info?.name).toBe('Ada')
+    expect(info?.id).toBe(42)
+  })
+
+  it('hidden_user: self-reported name, marked hidden_user, NO id', () => {
+    const info = parseForwardOrigin({
+      type: 'hidden_user',
+      date: DATE,
+      sender_user_name: 'Mystery Sender',
+    })
+    expect(info).toEqual({
+      name: 'Mystery Sender',
+      type: 'hidden_user',
+      date: DATE,
+    })
+    // The whole point of the type marker: no verifiable id exists.
+    expect(info?.id).toBeUndefined()
+  })
+
+  it('chat: sender_chat title plus (@username)', () => {
+    const info = parseForwardOrigin({
+      type: 'chat',
+      date: DATE,
+      sender_chat: { id: -100200300, type: 'supergroup', title: 'Ops Room', username: 'opsroom' } as never,
+    })
+    expect(info).toEqual({
+      name: 'Ops Room (@opsroom)',
+      type: 'chat',
+      id: -100200300,
+      date: DATE,
+    })
+  })
+
+  it('channel: chat.title plus (@username), message_id captured', () => {
+    const info = parseForwardOrigin({
+      type: 'channel',
+      date: DATE,
+      message_id: 555,
+      chat: { id: -100400500, type: 'channel', title: 'Release Notes', username: 'relnotes' } as never,
+    })
+    expect(info).toEqual({
+      name: 'Release Notes (@relnotes)',
+      type: 'channel',
+      id: -100400500,
+      date: DATE,
+      messageId: 555,
+    })
+  })
+})
+
+describe('parseForwardOrigin — missing / malformed fields', () => {
+  it('returns undefined for a non-forwarded message (no origin)', () => {
+    expect(parseForwardOrigin(undefined)).toBeUndefined()
+  })
+
+  it('returns undefined for an unknown future origin type', () => {
+    expect(parseForwardOrigin({ type: 'giveaway', date: DATE } as never)).toBeUndefined()
+  })
+
+  it('user origin without sender_user is dropped', () => {
+    expect(parseForwardOrigin({ type: 'user', date: DATE } as never)).toBeUndefined()
+  })
+
+  it('hidden_user with an empty name is dropped (nothing to show)', () => {
+    expect(
+      parseForwardOrigin({ type: 'hidden_user', date: DATE, sender_user_name: '' }),
+    ).toBeUndefined()
+  })
+
+  it('user with no printable name falls back to the numeric id as name', () => {
+    const info = parseForwardOrigin({
+      type: 'user',
+      date: DATE,
+      sender_user: { id: 42, is_bot: false, first_name: '' },
+    })
+    expect(info).toEqual({ name: '42', type: 'user', id: 42, date: DATE })
+  })
+
+  it('missing date yields no date (and later no forwarded_date attr)', () => {
+    const info = parseForwardOrigin({
+      type: 'hidden_user',
+      sender_user_name: 'Mystery Sender',
+    } as never)
+    expect(info?.date).toBeUndefined()
+    expect(buildForwardOriginMeta([info!]).forwarded_date).toBeUndefined()
+    expect(forwardOriginDateIso(info)).toBeNull()
+  })
+
+  it('channel origin without a title falls back to first/last name shape, then id', () => {
+    const noName = parseForwardOrigin({
+      type: 'channel',
+      date: DATE,
+      message_id: 9,
+      chat: { id: -100777888, type: 'channel' } as never,
+    })
+    expect(noName).toEqual({
+      name: '-100777888',
+      type: 'channel',
+      id: -100777888,
+      date: DATE,
+      messageId: 9,
+    })
+  })
+})
+
+describe('parseForwardOrigin — hostile names (attacker-controlled)', () => {
+  it('truncates a 4KB name to the cap (raw, ellipsis-terminated)', () => {
+    const bomb = 'x'.repeat(4096)
+    const info = parseForwardOrigin(userOrigin({ first_name: bomb, last_name: undefined, username: undefined }))
+    expect(info?.name).toHaveLength(FORWARDED_FROM_NAME_MAX)
+    expect(info?.name?.endsWith('…')).toBe(true)
+  })
+
+  it('keeps XML metacharacters RAW in the parsed record (SQLite lane)', () => {
+    const info = parseForwardOrigin(
+      userOrigin({ first_name: '<b>"Bob"&\'friends\'</b>', last_name: undefined, username: undefined }),
+    )
+    // Escaping happens at the channel-meta boundary, not at parse time —
+    // the history buffer stores what the user actually saw.
+    expect(info?.name).toBe('<b>"Bob"&\'friends\'</b>')
+  })
+})
+
+describe('buildForwardOriginMeta — channel-tag attrs', () => {
+  it('single origin: bare keys in the fixed order name, type, id, date', () => {
+    const meta = buildForwardOriginMeta([parseForwardOrigin(userOrigin())!])
+    expect(Object.keys(meta)).toEqual([
+      'forwarded_from',
+      'forwarded_from_type',
+      'forwarded_from_id',
+      'forwarded_date',
+    ])
+    expect(meta).toEqual({
+      forwarded_from: 'Ada Lovelace (@adalove)',
+      forwarded_from_type: 'user',
+      forwarded_from_id: '42',
+      forwarded_date: DATE_ISO,
+    })
+  })
+
+  it('id-less origin (hidden_user) omits forwarded_from_id entirely', () => {
+    const meta = buildForwardOriginMeta([
+      { name: 'Mystery Sender', type: 'hidden_user', date: DATE },
+    ])
+    expect(Object.keys(meta)).toEqual([
+      'forwarded_from',
+      'forwarded_from_type',
+      'forwarded_date',
+    ])
+    expect(meta.forwarded_from_type).toBe('hidden_user')
+  })
+
+  it('XML-escapes hostile names — the rendered attribute value cannot break out', () => {
+    const meta = buildForwardOriginMeta([
+      { name: '<script>"a"&\'b\'</script>', type: 'user', id: 42, date: DATE },
+    ])
+    expect(meta.forwarded_from).toBe(
+      '&lt;script&gt;&quot;a&quot;&amp;&apos;b&apos;&lt;/script&gt;',
+    )
+    // Outcome assertion: rendered into a channel tag, the value carries no
+    // raw quote/angle characters that could terminate the attribute.
+    const rendered = `<channel source="telegram" forwarded_from="${meta.forwarded_from}">`
+    expect(rendered).not.toMatch(/forwarded_from="[^"]*[<>][^"]*"/)
+    expect((rendered.match(/"/g) ?? []).length).toBe(4) // only the delimiters
+  })
+
+  it('defense in depth: a name that skipped parse-time truncation is capped here too', () => {
+    const meta = buildForwardOriginMeta([
+      { name: 'y'.repeat(4096), type: 'user', id: 42, date: DATE },
+    ])
+    // 99 chars + '…' — no 4KB payload reaches the tag.
+    expect(meta.forwarded_from).toHaveLength(FORWARDED_FROM_NAME_MAX)
+  })
+
+  it('no origins → empty record (no attrs on a normal message)', () => {
+    expect(buildForwardOriginMeta([])).toEqual({})
+  })
+})
+
+describe('coalesced bursts — dedupe + numbered siblings', () => {
+  const alice: ForwardOriginInfo = { name: 'Alice Q (@aliceq)', type: 'user', id: 42, date: DATE }
+  const relnotes: ForwardOriginInfo = {
+    name: 'Release Notes (@relnotes)',
+    type: 'channel',
+    id: -100400500,
+    date: DATE + 60,
+    messageId: 7,
+  }
+
+  it('single-origin album (N parts, one sender) collapses to ONE attr set', () => {
+    const origins = dedupeForwardOrigins([alice, { ...alice, date: DATE + 5 }, { ...alice, date: DATE + 9 }])
+    expect(origins).toHaveLength(1)
+    const meta = buildForwardOriginMeta(origins)
+    expect(meta.forwarded_from).toBe('Alice Q (@aliceq)')
+    expect(meta.forwarded_from_2).toBeUndefined()
+    // First occurrence wins — the emitted date is the first part's.
+    expect(meta.forwarded_date).toBe(DATE_ISO)
+  })
+
+  it('multi-origin burst: first origin bare, second gets _2 keys in order', () => {
+    const meta = buildForwardOriginMeta(dedupeForwardOrigins([alice, relnotes]))
+    expect(Object.keys(meta)).toEqual([
+      'forwarded_from',
+      'forwarded_from_type',
+      'forwarded_from_id',
+      'forwarded_date',
+      'forwarded_from_2',
+      'forwarded_from_type_2',
+      'forwarded_from_id_2',
+      'forwarded_date_2',
+    ])
+    expect(meta.forwarded_from_2).toBe('Release Notes (@relnotes)')
+    expect(meta.forwarded_from_type_2).toBe('channel')
+    expect(meta.forwarded_from_id_2).toBe('-100400500')
+  })
+
+  it('non-forwarded entries in the burst are skipped', () => {
+    expect(dedupeForwardOrigins([undefined, alice, undefined])).toEqual([alice])
+    expect(dedupeForwardOrigins([undefined, undefined])).toEqual([])
+  })
+
+  it('id-less origins dedupe by name; same type+id dedupes despite name drift', () => {
+    const hidden: ForwardOriginInfo = { name: 'Mystery Sender', type: 'hidden_user', date: DATE }
+    expect(dedupeForwardOrigins([hidden, { ...hidden, date: DATE + 3 }])).toHaveLength(1)
+    // Same user id, renamed mid-burst — still one origin.
+    expect(dedupeForwardOrigins([alice, { ...alice, name: 'Alice Renamed' }])).toHaveLength(1)
+    // Same numeric id but different type stays distinct.
+    expect(forwardOriginKey(alice)).not.toBe(forwardOriginKey({ ...alice, type: 'chat' }))
+  })
+
+  it('arrival order is preserved across three distinct origins', () => {
+    const hidden: ForwardOriginInfo = { name: 'Mystery Sender', type: 'hidden_user', date: DATE }
+    const meta = buildForwardOriginMeta(dedupeForwardOrigins([relnotes, hidden, alice]))
+    expect(meta.forwarded_from).toBe('Release Notes (@relnotes)')
+    expect(meta.forwarded_from_2).toBe('Mystery Sender')
+    expect(meta.forwarded_from_3).toBe('Alice Q (@aliceq)')
+    expect(meta.forwarded_from_type_3).toBe('user')
+  })
+})