switchroom 0.18.17 → 0.18.18

package/telegram-plugin/send-gate.test.ts

@@ -1,5 +1,11 @@
 import { describe, expect, it } from 'vitest'
-import { createSendGate, sendGateEnabledFromEnv, type Clock } from './send-gate.js'
+import {
+  createSendGate,
+  sendGateEnabledFromEnv,
+  sendGateConfigFromEnv,
+  SEND_GATE_DEFAULTS,
+  type Clock,
+} from './send-gate.js'
 
 /**
  * Deterministic fake clock. `sleep()` registers a wake at `now + ms`;
@@ -117,6 +123,142 @@ describe('send-gate: feature flag', () => {
   })
 })
 
+describe('send-gate: SEND_GATE_DEFAULTS (compile-time default PIN)', () => {
+  it('pins the exact default rate limits — a drive-by change fails here', () => {
+    // Load-bearing PIN: these are the values createSendGate falls back to when a
+    // knob is unset, i.e. today's shipped behaviour. If any of these numbers
+    // changes, that is a real behaviour change and must be a deliberate,
+    // reviewed edit — not a silent drift. (#3084 send-gate config PR.)
+    expect(SEND_GATE_DEFAULTS).toEqual({
+      globalPerSec: 25,
+      globalBurst: 4,
+      perChatPerSec: 1,
+      perChatBurst: 3,
+      perGroupPerMin: 18,
+      perGroupBurst: 2,
+      editFloorMs: 1500,
+    })
+  })
+})
+
+describe('send-gate: sendGateConfigFromEnv (yaml → env → createSendGate)', () => {
+  const E = (o: Record<string, string | undefined>) => o as unknown as NodeJS.ProcessEnv
+
+  it('maps every SWITCHROOM_TG_SEND_GATE_* env to the exact createSendGate field', () => {
+    // The gateway spreads this object straight into createSendGate({...}), so
+    // asserting the returned slice IS asserting what createSendGate receives.
+    const cfg = sendGateConfigFromEnv(
+      E({
+        SWITCHROOM_TG_SEND_GATE_ENABLED: '1',
+        SWITCHROOM_TG_SEND_GATE_GLOBAL_PER_SEC: '40',
+        SWITCHROOM_TG_SEND_GATE_GLOBAL_BURST: '6',
+        SWITCHROOM_TG_SEND_GATE_PER_CHAT_PER_SEC: '2',
+        SWITCHROOM_TG_SEND_GATE_PER_CHAT_BURST: '5',
+        SWITCHROOM_TG_SEND_GATE_PER_GROUP_PER_MIN: '30',
+        SWITCHROOM_TG_SEND_GATE_PER_GROUP_BURST: '4',
+        SWITCHROOM_TG_SEND_GATE_EDIT_FLOOR_MS: '2000',
+      }),
+    )
+    expect(cfg).toEqual({
+      enabled: true,
+      globalPerSec: 40,
+      globalBurst: 6,
+      perChatPerSec: 2,
+      perChatBurst: 5,
+      perGroupPerMin: 30,
+      perGroupBurst: 4,
+      editFloorMs: 2000,
+    })
+  })
+
+  it('accepts a fractional per-sec rate (rates are not integers)', () => {
+    const cfg = sendGateConfigFromEnv(E({ SWITCHROOM_TG_SEND_GATE_PER_CHAT_PER_SEC: '0.5' }))
+    expect(cfg.perChatPerSec).toBe(0.5)
+  })
+
+  it('unset knobs are ABSENT so createSendGate applies SEND_GATE_DEFAULTS (no behaviour change)', () => {
+    const cfg = sendGateConfigFromEnv(E({}))
+    // Only enabled is present; every rate field is omitted → default fallback.
+    expect(cfg).toEqual({ enabled: true })
+    // And the gate built from it actually pours in the pinned defaults.
+    const gate = createSendGate({ ...cfg, clock: new FakeClock() })
+    // enabled default is ON (escape hatch, not opt-in).
+    expect(gate.stats().enabled).toBe(true)
+  })
+
+  it('drops malformed / wedge-inducing env values back to the default (defensive net)', () => {
+    // The LOUD rejection lives in the Zod config schema; a hand-set bad env must
+    // never wedge sends, so it falls back to undefined → compile-time default.
+    const cfg = sendGateConfigFromEnv(
+      E({
+        SWITCHROOM_TG_SEND_GATE_GLOBAL_PER_SEC: '0', // ≤0 → dropped
+        SWITCHROOM_TG_SEND_GATE_PER_CHAT_BURST: '-3', // negative → dropped
+        SWITCHROOM_TG_SEND_GATE_PER_GROUP_BURST: '2.5', // non-int → dropped
+        SWITCHROOM_TG_SEND_GATE_GLOBAL_BURST: 'nonsense', // NaN → dropped
+      }),
+    )
+    expect(cfg).toEqual({ enabled: true })
+  })
+
+  it('edit_floor_ms accepts 0 (disables the floor) but not negatives', () => {
+    expect(sendGateConfigFromEnv(E({ SWITCHROOM_TG_SEND_GATE_EDIT_FLOOR_MS: '0' })).editFloorMs).toBe(0)
+    expect(
+      sendGateConfigFromEnv(E({ SWITCHROOM_TG_SEND_GATE_EDIT_FLOOR_MS: '-1' })).editFloorMs,
+    ).toBeUndefined()
+  })
+
+  it('maps the #3111 conservative-global flood-scope break-glass flag', () => {
+    // Unset ⇒ absent (scope-precise default; createSendGate falls back to false).
+    expect(
+      sendGateConfigFromEnv(E({})).conservativeGlobalFloodScope,
+    ).toBeUndefined()
+    // On-values ⇒ true (restore pre-#3111 always-open-global posture).
+    for (const on of ['1', 'true', 'on', 'yes']) {
+      expect(
+        sendGateConfigFromEnv(E({ SWITCHROOM_TG_SEND_GATE_CONSERVATIVE_GLOBAL: on }))
+          .conservativeGlobalFloodScope,
+      ).toBe(true)
+    }
+    // Off-values ⇒ explicit false.
+    expect(
+      sendGateConfigFromEnv(E({ SWITCHROOM_TG_SEND_GATE_CONSERVATIVE_GLOBAL: '0' }))
+        .conservativeGlobalFloodScope,
+    ).toBe(false)
+    // Unrecognised ⇒ absent (defensive net).
+    expect(
+      sendGateConfigFromEnv(E({ SWITCHROOM_TG_SEND_GATE_CONSERVATIVE_GLOBAL: 'nonsense' }))
+        .conservativeGlobalFloodScope,
+    ).toBeUndefined()
+  })
+
+  describe('enabled precedence: break-glass valve > config > default-on', () => {
+    it('config send_gate.enabled decides when the env valve is unset', () => {
+      expect(sendGateConfigFromEnv(E({ SWITCHROOM_TG_SEND_GATE_ENABLED: '0' })).enabled).toBe(false)
+      expect(sendGateConfigFromEnv(E({ SWITCHROOM_TG_SEND_GATE_ENABLED: '1' })).enabled).toBe(true)
+      expect(sendGateConfigFromEnv(E({ SWITCHROOM_TG_SEND_GATE_ENABLED: 'off' })).enabled).toBe(false)
+    })
+
+    it('the SWITCHROOM_TELEGRAM_SEND_GATE valve ALWAYS wins when explicitly set', () => {
+      // valve off beats config on
+      expect(
+        sendGateConfigFromEnv(
+          E({ SWITCHROOM_TELEGRAM_SEND_GATE: '0', SWITCHROOM_TG_SEND_GATE_ENABLED: '1' }),
+        ).enabled,
+      ).toBe(false)
+      // valve on beats config off
+      expect(
+        sendGateConfigFromEnv(
+          E({ SWITCHROOM_TELEGRAM_SEND_GATE: '1', SWITCHROOM_TG_SEND_GATE_ENABLED: '0' }),
+        ).enabled,
+      ).toBe(true)
+    })
+
+    it('both unset ⇒ enabled (ON by default, unchanged)', () => {
+      expect(sendGateConfigFromEnv(E({})).enabled).toBe(true)
+    })
+  })
+})
+
 describe('send-gate: global bucket', () => {
   it('admits up to capacity immediately, then paces the rest by refill', async () => {
     const clock = new FakeClock()

package/telegram-plugin/send-gate.ts

@@ -304,6 +304,21 @@ export interface SendGateConfig {
    * `initialWindows` applied at construction (those already came from disk).
    */
   onWindowOpen?: (scopeKey: string, untilTs: number) => void
+  /**
+   * Conservative flood-scope posture (#3111). When `false` (the DEFAULT), a 429
+   * on a call bound to a specific chat opens ONLY that chat's (and, for groups,
+   * that group's) flood window — NOT a blanket `global` window — so a genuinely
+   * chat-scoped 429 (e.g. a per-group 20/min limit) cannot fail-fast CRITICAL
+   * sends to every other chat. `global` is opened only when the 429 carries no
+   * finer scope (no `chat_id`), i.e. the evidence is genuinely global.
+   *
+   * When `true`, the pre-#3111 posture is restored: EVERY 429 additionally opens
+   * the `global` window. Telegram 429s are per-bot-token, so a flood often IS
+   * global; an operator who prefers to over-suppress rather than risk a missed
+   * global ban can opt back in via
+   * `SWITCHROOM_TG_SEND_GATE_CONSERVATIVE_GLOBAL=1`.
+   */
+  conservativeGlobalFloodScope?: boolean
 }
 
 /**
@@ -462,22 +477,58 @@ export interface SendGate {
    * by PR 2 on a 429 and at boot from the persisted `flood-wait.json`.
    */
   openFloodWindow(scopeKey: string, untilTs: number): void
+  /**
+   * Open the SCOPE-PRECISE flood windows a 429 on a call with these `opts`
+   * implies (#3111). Used by the gateway's `onFloodWait` hook, which sees a
+   * SHORT slept-and-retried 429 the gate's own `FLOOD_WAIT_ACTIVE` catch never
+   * observes. Opens `global` only when `opts` carries no `chat_id` (genuinely
+   * global evidence) or the conservative posture is on — so a chat-scoped 429
+   * does not suppress unrelated chats. A pure no-op when the gate is disabled.
+   */
+  openScopedFloodWindows(opts: SendGateOpts | undefined, untilTs: number): void
   /** Snapshot of counters + current bucket fill. */
   stats(): SendGateStats
 }
 
 const GROUP_TYPES = new Set<ChatType>(['group', 'supergroup'])
 
+/**
+ * Compile-time default rate limits for the send gate's token buckets and edit
+ * floor — the values `createSendGate` falls back to when a field is omitted.
+ *
+ * Exposed so the config plumbing (`channels.telegram.send_gate.*` →
+ * `SWITCHROOM_TG_SEND_GATE_*` env → `sendGateConfigFromEnv`) defaults to the
+ * SAME numbers, and so a test can PIN them: a future accidental change to any
+ * default fails that pin. Changing a value here is a real behaviour change for
+ * every install — do it deliberately, never as a drive-by edit.
+ */
+export const SEND_GATE_DEFAULTS = {
+  /** Global bucket sustained rate (tokens/sec). */
+  globalPerSec: 25,
+  /** Global burst capacity (headroom under Telegram's ~30/s). */
+  globalBurst: 4,
+  /** Per-chat sustained rate (tokens/sec). */
+  perChatPerSec: 1,
+  /** Per-chat burst capacity. */
+  perChatBurst: 3,
+  /** Per-group sustained rate (tokens/min). */
+  perGroupPerMin: 18,
+  /** Per-group burst capacity (headroom under 20/min). */
+  perGroupBurst: 2,
+  /** Minimum ms between edits of the same message_id. */
+  editFloorMs: 1500,
+} as const
+
 export function createSendGate(config: SendGateConfig): SendGate {
   const enabled = config.enabled
   const clock = config.clock ?? systemClock
-  const globalPerSec = config.globalPerSec ?? 25
-  const globalBurst = config.globalBurst ?? 4
-  const perChatPerSec = config.perChatPerSec ?? 1
-  const perChatBurst = config.perChatBurst ?? 3
-  const perGroupPerMin = config.perGroupPerMin ?? 18
-  const perGroupBurst = config.perGroupBurst ?? 2
-  const editFloorMs = config.editFloorMs ?? 1500
+  const globalPerSec = config.globalPerSec ?? SEND_GATE_DEFAULTS.globalPerSec
+  const globalBurst = config.globalBurst ?? SEND_GATE_DEFAULTS.globalBurst
+  const perChatPerSec = config.perChatPerSec ?? SEND_GATE_DEFAULTS.perChatPerSec
+  const perChatBurst = config.perChatBurst ?? SEND_GATE_DEFAULTS.perChatBurst
+  const perGroupPerMin = config.perGroupPerMin ?? SEND_GATE_DEFAULTS.perGroupPerMin
+  const perGroupBurst = config.perGroupBurst ?? SEND_GATE_DEFAULTS.perGroupBurst
+  const editFloorMs = config.editFloorMs ?? SEND_GATE_DEFAULTS.editFloorMs
   const messageStateTtlMs = config.messageStateTtlMs ?? 60_000
   const maxMessageStates = config.maxMessageStates ?? 5_000
   const usefulTtlMs = config.usefulTtlMs ?? 120_000
@@ -485,6 +536,7 @@ export function createSendGate(config: SendGateConfig): SendGate {
   const criticalJitterMaxMs = config.criticalJitterMaxMs ?? 250
   const jitter = config.jitter ?? Math.random
   const onWindowOpen = config.onWindowOpen
+  const conservativeGlobalFloodScope = config.conservativeGlobalFloodScope ?? false
 
   const counters: BucketCounters = {
     sent: 0,
@@ -597,18 +649,35 @@ export function createSendGate(config: SendGateConfig): SendGate {
   }
 
   /**
-   * Open all scope windows implied by a call's `opts` at `untilTs` — global,
-   * plus per-chat / per-group / per-message where keyed. Called when a wrapped
-   * send surfaces a `FLOOD_WAIT_ACTIVE` (a real 429 or a pre-call
-   * short-circuit) so the ban is remembered at the finest scope we know
-   * (part3-design §7). Global is always opened as the conservative floor.
+   * Open the flood windows a 429 on this call implies at `untilTs`, at the
+   * FINEST scope the evidence supports (#3111). Called when a wrapped send
+   * surfaces a `FLOOD_WAIT_ACTIVE` (a real 429 or a pre-call short-circuit), and
+   * by the gateway's `onFloodWait` hook for a SHORT slept-and-retried 429 (via
+   * the public `openScopedFloodWindows`), so the ban is remembered at the finest
+   * scope we know (part3-design §7).
+   *
+   * SCOPE PRECISION (#3111): a call bound to a specific `chat_id` opens ONLY that
+   * chat's (and, for groups, that group's) window — NOT a blanket `global`
+   * window that would suppress unrelated chats. `global` is opened only when the
+   * call carries NO finer scope (no `chat_id`) — i.e. the evidence is genuinely
+   * global — OR when `conservativeGlobalFloodScope` restores the pre-#3111
+   * always-open-global posture. Telegram 429s are per-bot-token so a flood is
+   * OFTEN global, but a genuinely chat-scoped 429 (e.g. a per-group 20/min
+   * limit) must not fail-fast CRITICAL sends to every other chat. The
+   * per-message (`msg-edit:`) window is additive whenever a `messageId` is
+   * present. Monotonic/idempotent: `applyWindow` only ever extends.
    */
   function openScopedWindowsForOpts(opts: SendGateOpts | undefined, untilTs: number): void {
-    applyWindow('global', untilTs, true)
-    if (opts?.chat_id) {
-      applyWindow(`chat:${opts.chat_id}`, untilTs, true)
-      if (opts.chatType && GROUP_TYPES.has(opts.chatType)) {
-        applyWindow(`group:${opts.chat_id}`, untilTs, true)
+    const hasChatScope = opts?.chat_id != null && opts.chat_id !== ''
+    // Open `global` only when the 429 has no finer scope (genuinely global), or
+    // when the operator opted into the conservative always-global posture.
+    if (!hasChatScope || conservativeGlobalFloodScope) {
+      applyWindow('global', untilTs, true)
+    }
+    if (hasChatScope) {
+      applyWindow(`chat:${opts!.chat_id}`, untilTs, true)
+      if (opts!.chatType && GROUP_TYPES.has(opts!.chatType)) {
+        applyWindow(`group:${opts!.chat_id}`, untilTs, true)
       }
     }
     if (opts?.messageId != null) {
@@ -1067,7 +1136,18 @@ export function createSendGate(config: SendGateConfig): SendGate {
     }
   }
 
-  return { gate, openFloodWindow, stats }
+  /**
+   * Public, scope-precise window opener for the gateway's `onFloodWait` hook
+   * (#3111). Flag-OFF is a pure no-op (mirrors `openFloodWindow`'s M3 guard) so
+   * a 429 never mutates suppression or writes `flood-windows.json` while the gate
+   * is disabled.
+   */
+  function openScopedFloodWindows(opts: SendGateOpts | undefined, untilTs: number): void {
+    if (!enabled) return
+    openScopedWindowsForOpts(opts, untilTs)
+  }
+
+  return { gate, openFloodWindow, openScopedFloodWindows, stats }
 }
 
 /**
@@ -1081,6 +1161,119 @@ export function createSendGate(config: SendGateConfig): SendGate {
 export function sendGateEnabledFromEnv(env: NodeJS.ProcessEnv = process.env): boolean {
   const v = env.SWITCHROOM_TELEGRAM_SEND_GATE
   if (v == null) return true
+  return !isOffValue(v)
+}
+
+/** Shared parse for the default-on kill-switch grammar: `0/false/off/no`. */
+function isOffValue(v: string): boolean {
   const t = v.trim().toLowerCase()
-  return !(t === '0' || t === 'false' || t === 'off' || t === 'no')
+  return t === '0' || t === 'false' || t === 'off' || t === 'no'
+}
+
+/** Parse a strictly-positive finite number env var; blank/NaN/≤0 → undefined. */
+function parsePositiveNumber(raw: string | undefined): number | undefined {
+  if (raw == null || raw.trim() === '') return undefined
+  const n = Number(raw)
+  return Number.isFinite(n) && n > 0 ? n : undefined
+}
+
+/** Parse a positive integer env var; blank/NaN/non-int/≤0 → undefined. */
+function parsePositiveInt(raw: string | undefined): number | undefined {
+  if (raw == null || raw.trim() === '') return undefined
+  const n = Number(raw)
+  return Number.isInteger(n) && n > 0 ? n : undefined
+}
+
+/** Parse a non-negative integer env var; blank/NaN/non-int/<0 → undefined. */
+function parseNonNegativeInt(raw: string | undefined): number | undefined {
+  if (raw == null || raw.trim() === '') return undefined
+  const n = Number(raw)
+  return Number.isInteger(n) && n >= 0 ? n : undefined
+}
+
+/**
+ * Parse a boolean env flag using the repo's on/off grammar
+ * (`1/true/on/yes` → true, `0/false/off/no` → false). Blank or unrecognised →
+ * undefined so the caller keeps its built-in default (#3111).
+ */
+function parseBoolFlag(raw: string | undefined): boolean | undefined {
+  if (raw == null || raw.trim() === '') return undefined
+  const t = raw.trim().toLowerCase()
+  if (t === '1' || t === 'true' || t === 'on' || t === 'yes') return true
+  if (isOffValue(t)) return false
+  return undefined
+}
+
+/**
+ * The resolved rate-limit + enable slice `createSendGate` consumes, sourced
+ * from env (which the scaffold populates from `channels.telegram.send_gate.*`).
+ * Only fields the operator SET are present; an unset rate field is absent so
+ * `createSendGate` applies its `SEND_GATE_DEFAULTS` fallback (unset ⇒ today's
+ * exact behaviour).
+ */
+export type SendGateEnvConfig = Pick<SendGateConfig, 'enabled'> &
+  Partial<
+    Pick<
+      SendGateConfig,
+      | 'globalPerSec'
+      | 'globalBurst'
+      | 'perChatPerSec'
+      | 'perChatBurst'
+      | 'perGroupPerMin'
+      | 'perGroupBurst'
+      | 'editFloorMs'
+      | 'conservativeGlobalFloodScope'
+    >
+  >
+
+/**
+ * Resolve the send gate's `enabled` flag + tunable rate limits from env.
+ *
+ * ENABLED PRECEDENCE (least-surprising, documented):
+ *   1. `SWITCHROOM_TELEGRAM_SEND_GATE` — the operator break-glass valve. When
+ *      EXPLICITLY set it ALWAYS wins (unchanged kill-switch semantics), on or
+ *      off, regardless of config. An operator disabling the gate in an incident
+ *      must not be overridden by YAML.
+ *   2. `SWITCHROOM_TG_SEND_GATE_ENABLED` — from `channels.telegram.send_gate.
+ *      enabled`. Decides only when the valve above is unset.
+ *   3. Both unset ⇒ `true` (the gate is ON by default, unchanged).
+ *
+ * The rate knobs come solely from config (there was never an env override for
+ * them). Config values are validated LOUDLY at load by the Zod schema; this
+ * parse is a defensive net — a hand-set malformed env falls back to undefined
+ * so `createSendGate` uses its built-in default rather than wedging sends.
+ */
+export function sendGateConfigFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): SendGateEnvConfig {
+  const killSwitch = env.SWITCHROOM_TELEGRAM_SEND_GATE
+  let enabled: boolean
+  if (killSwitch != null && killSwitch.trim() !== '') {
+    enabled = !isOffValue(killSwitch)
+  } else {
+    const cfg = env.SWITCHROOM_TG_SEND_GATE_ENABLED
+    enabled = cfg != null && cfg.trim() !== '' ? !isOffValue(cfg) : true
+  }
+
+  const out: SendGateEnvConfig = { enabled }
+  const globalPerSec = parsePositiveNumber(env.SWITCHROOM_TG_SEND_GATE_GLOBAL_PER_SEC)
+  if (globalPerSec !== undefined) out.globalPerSec = globalPerSec
+  const globalBurst = parsePositiveInt(env.SWITCHROOM_TG_SEND_GATE_GLOBAL_BURST)
+  if (globalBurst !== undefined) out.globalBurst = globalBurst
+  const perChatPerSec = parsePositiveNumber(env.SWITCHROOM_TG_SEND_GATE_PER_CHAT_PER_SEC)
+  if (perChatPerSec !== undefined) out.perChatPerSec = perChatPerSec
+  const perChatBurst = parsePositiveInt(env.SWITCHROOM_TG_SEND_GATE_PER_CHAT_BURST)
+  if (perChatBurst !== undefined) out.perChatBurst = perChatBurst
+  const perGroupPerMin = parsePositiveNumber(env.SWITCHROOM_TG_SEND_GATE_PER_GROUP_PER_MIN)
+  if (perGroupPerMin !== undefined) out.perGroupPerMin = perGroupPerMin
+  const perGroupBurst = parsePositiveInt(env.SWITCHROOM_TG_SEND_GATE_PER_GROUP_BURST)
+  if (perGroupBurst !== undefined) out.perGroupBurst = perGroupBurst
+  const editFloorMs = parseNonNegativeInt(env.SWITCHROOM_TG_SEND_GATE_EDIT_FLOOR_MS)
+  if (editFloorMs !== undefined) out.editFloorMs = editFloorMs
+  // #3111 break-glass: restore the pre-#3111 always-open-global flood posture.
+  // Unset ⇒ scope-precise default (global opened only on genuinely global 429s).
+  const conservativeGlobal = parseBoolFlag(env.SWITCHROOM_TG_SEND_GATE_CONSERVATIVE_GLOBAL)
+  if (conservativeGlobal !== undefined) out.conservativeGlobalFloodScope = conservativeGlobal
+
+  return out
 }

package/telegram-plugin/session-tail.ts

@@ -333,6 +333,22 @@ export function projectTranscriptLine(line: string): SessionEvent[] {
     const message = obj.message as Record<string, unknown> | undefined
     const content = message?.content as Array<Record<string, unknown>> | undefined
     if (!Array.isArray(content)) return []
+    // #llm-error-surfacing — DETERMINISTIC TERMINAL SOURCE. Claude Code writes a
+    // usage-limit / API error as a SYNTHETIC ASSISTANT MESSAGE
+    // (`isApiErrorMessage: true`) whose `content[].text` is the raw error string
+    // ("You've hit your limit · resets … b'{\"type\":\"error\"…}'"). That text
+    // used to fan out to the reply/answer passthrough AND the turn-end "done"
+    // card as if it were the model's answer. It is NOT an answer — it is an
+    // error the operator-event pipeline (detectErrorInTranscriptLine →
+    // humanized card) owns. Suppress the text/thinking events here at the ONE
+    // authoritative source so neither downstream surface can relay the raw
+    // bytes; the humanized card is rendered independently from the same line.
+    if (obj.isApiErrorMessage === true) {
+      const mainModel = message?.model
+      return typeof mainModel === 'string' && !isModelSentinel(mainModel)
+        ? [{ kind: 'model', model: mainModel }]
+        : []
+    }
     const events: SessionEvent[] = []
     // Live model capture: `message.model` is the exact resolved model that
     // served THIS assistant API call. Emit it FIRST (before the content events)

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

@@ -0,0 +1,69 @@
+/**
+ * shared/local-time.ts — operator-facing local wall-clock formatting.
+ *
+ * These four primitives render an epoch-ms instant in an operator's CONFIGURED
+ * IANA timezone (e.g. `Australia/Melbourne`) instead of UTC, so a card reading
+ * "clears ~4:52pm AEST" is legible at a glance where a raw `…T04:52:00Z UTC`
+ * is not. They were originally file-private in `send-gate-observability.ts`
+ * (#3084 / PR 3205); extracted here so BOTH the flood-window observer and the
+ * humanized LLM-error card (`llm-error-present.ts`) render timestamps through
+ * ONE source of truth rather than two drifting copies.
+ *
+ * Pure — no I/O, no clock, no env. Every function is total (never throws) and
+ * degrades gracefully: an unknown tz falls back to the offset form or the tz
+ * string itself. `tz='UTC'` reproduces the pre-extraction behaviour exactly, so
+ * `send-gate-observability`'s snapshot-locked output is byte-identical.
+ */
+
+/** Lowercased wall-clock time in `tz`, e.g. `9:39am`. */
+export function fmtLocalClock(ms: number, tz: string): string {
+  return new Intl.DateTimeFormat('en-US', {
+    timeZone: tz,
+    hour: 'numeric',
+    minute: '2-digit',
+    hour12: true,
+  })
+    .format(new Date(ms))
+    .replace(/\s([AP])M$/, (_m, p: string) => `${p.toLowerCase()}m`)
+}
+
+/** Compact local date, e.g. `12 Jul` — used only to disambiguate day-spanning windows. */
+export function fmtLocalDate(ms: number, tz: string): string {
+  return new Intl.DateTimeFormat('en-GB', {
+    timeZone: tz,
+    day: 'numeric',
+    month: 'short',
+  }).format(new Date(ms))
+}
+
+/** Calendar day (`YYYY-MM-DD`) in `tz`, for a timezone-correct "same day?" test. */
+export function localDay(ms: number, tz: string): string {
+  return new Intl.DateTimeFormat('en-CA', {
+    timeZone: tz,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  }).format(new Date(ms))
+}
+
+/**
+ * Short tz abbreviation for `tz` at `ms`, e.g. `AEST`, `EDT`, `BST`. ICU only
+ * surfaces the common alpha abbreviation for a locale whose region matches the
+ * zone, so we try a small locale list and take the first genuine abbreviation;
+ * zones with no common abbreviation (e.g. Asia/Kolkata) fall back to the offset
+ * form (`GMT+5:30`), and `UTC` stays `UTC`.
+ */
+export function tzAbbrev(ms: number, tz: string): string {
+  const at = new Date(ms)
+  for (const loc of ['en-US', 'en-AU', 'en-GB']) {
+    const v = new Intl.DateTimeFormat(loc, { timeZone: tz, timeZoneName: 'short' })
+      .formatToParts(at)
+      .find((p) => p.type === 'timeZoneName')?.value
+    if (v && !/^(?:GMT|UTC)/i.test(v)) return v
+  }
+  return (
+    new Intl.DateTimeFormat('en-US', { timeZone: tz, timeZoneName: 'short' })
+      .formatToParts(at)
+      .find((p) => p.type === 'timeZoneName')?.value ?? tz
+  )
+}

package/telegram-plugin/tests/approval-hold-harness.ts

@@ -42,6 +42,7 @@ import {
   safeActionForRecord,
   holdReasonFor,
   heldRetryBackoffMs,
+  applyDeliveredHoldReset,
   type UndeliverableMark,
   type BlockedApprovalStore,
 } from '../gateway/approval-hold.js'
@@ -280,12 +281,11 @@ export function createHarness(opts: { cap?: number; targets?: string[] } = {}):
         const live = pending.get(requestId)
         if (live && sent) {
           live.cards.push({ chatId, messageId: sent.message_id })
-          if (live.undeliverable != null) {
-            live.undeliverable = null
-            live.redeliveryFailures = 0
-            // PR 3: the operator's decision window starts NOW — until this
-            // moment they had nothing to answer.
-            live.startedAt = clock.now()
+          // Drive the SAME reset the gateway drives (#3128) — no private copy.
+          // Deleting `startedAt = now` from `applyDeliveredHoldReset` turns the
+          // `(d2)` full-window outcome test RED, because there is one shared
+          // implementation, not a mirror the harness silently compensates with.
+          if (applyDeliveredHoldReset(live, clock.now())) {
             reconcile()
           }
         }

package/telegram-plugin/tests/approval-hold-outcome.test.ts

@@ -289,8 +289,16 @@ describe('gateway wiring — the leash', () => {
     expect(sweep).not.toContain('if (now - v.startedAt > ttl)')
   })
 
-  it('successful (re)delivery resets startedAt', () => {
-    expect(GATEWAY_SRC).toContain('live.startedAt = Date.now()')
+  it('successful (re)delivery resets startedAt through the SHARED reset (#3128)', () => {
+    // This pin is no longer the safety net for the reset — the behavioural `(d2)`
+    // test above is, and it now drives the same `applyDeliveredHoldReset` the
+    // gateway does, so deleting `startedAt = now` from that one shared function
+    // turns `(d2)` RED. This only guards the WIRING: that the gateway routes
+    // delivery through the shared reset and can't regrow a private inline copy
+    // that drifts from what the harness exercises.
+    expect(GATEWAY_SRC).toContain('applyDeliveredHoldReset(live, Date.now())')
+    // …and must NOT carry its own inline copy of the reset.
+    expect(GATEWAY_SRC).not.toContain('live.startedAt = Date.now()')
   })
 
   it('the missed-approvals re-offer no longer drops a card that never landed', () => {

package/telegram-plugin/tests/bridge-dead-watchdog.test.ts

@@ -99,6 +99,9 @@ function makeWatchdog(overrides: Partial<BridgeDeadWatchdogOpts> = {}) {
   const state = { sessionAlive: true, shuttingDown: false, escalateResult: true }
   const wd = createBridgeDeadWatchdog({
     graceMs: 90_000,
+    // The gateway serves AGENT — only AGENT's own bridge drives the
+    // watchdog (#3086). Overridable per-test.
+    selfAgentName: AGENT,
     isSessionAlive: () => state.sessionAlive,
     isShuttingDown: () => state.shuttingDown,
     escalate: (reason) => {
@@ -386,6 +389,64 @@ describe('cron / anonymous identity gating', () => {
   })
 })
 
+// ─── #3086: secondary/relay identity gating ──────────────────────────────────
+//
+// Repro of the klanker incident: a short-lived `overlord-relay` IPC client
+// registers and disconnects against klanker's gateway socket while klanker's
+// OWN bridge is registered and actively replying. Pre-fix, isRealBridgeIdentity
+// treated the relay (named, non-cron) as the real bridge, so its disconnect
+// flipped bridgeRegistered=false, re-armed the grace window, and 90s later the
+// watchdog SIGTERM'd a healthy container — killing the in-flight claude session.
+describe('#3086 secondary/relay identity gating', () => {
+  const RELAY = 'overlord-relay' // a DIFFERENT agent name than AGENT
+
+  it('a relay disconnecting while the primary bridge is alive does NOT re-arm or escalate', () => {
+    const { wd, harness, escalations } = makeWatchdog() // selfAgentName === AGENT
+    wd.arm()
+    wd.noteBridgeRegistered(AGENT) // klanker's own bridge — healthy
+    expect(harness.liveCount()).toBe(0) // grace timer stood down
+    // The relay connects then disconnects (flood-ban workaround churn).
+    wd.noteBridgeRegistered(RELAY)
+    wd.noteBridgeDisconnected(RELAY)
+    // Must NOT re-arm: the primary bridge never went away.
+    expect(harness.liveCount()).toBe(0)
+    expect(escalations).toEqual([])
+    expect(wd.hasEscalated()).toBe(false)
+  })
+
+  it('a relay register does NOT satisfy the watchdog (only the primary bridge does)', () => {
+    const { wd, harness, escalations } = makeWatchdog()
+    wd.arm()
+    wd.noteBridgeRegistered(RELAY) // relay is not THIS gateway's bridge
+    expect(harness.liveCount()).toBe(1) // still armed — primary still missing
+    harness.fireLatest()
+    // Primary bridge genuinely absent → the real failure still escalates.
+    expect(escalations).toEqual([BRIDGE_DEAD_RESTART_REASON])
+  })
+
+  it('a genuine PRIMARY bridge death still escalates (fix does not over-suppress)', () => {
+    const { wd, harness, escalations } = makeWatchdog()
+    wd.arm()
+    wd.noteBridgeRegistered(AGENT) // primary registers
+    expect(harness.liveCount()).toBe(0)
+    wd.noteBridgeDisconnected(AGENT) // primary dies for good, never reconnects
+    expect(harness.liveCount()).toBe(1) // re-armed
+    harness.fireLatest()
+    expect(escalations).toEqual([BRIDGE_DEAD_RESTART_REASON])
+  })
+
+  it('fallback: with no selfAgentName, any named non-cron client still counts (pre-#3086)', () => {
+    const { wd, harness, escalations } = makeWatchdog({ selfAgentName: '' })
+    wd.arm()
+    wd.noteBridgeRegistered(RELAY) // no identity to match against → treated as real
+    expect(harness.liveCount()).toBe(0) // satisfied the watchdog
+    wd.noteBridgeDisconnected(RELAY)
+    expect(harness.liveCount()).toBe(1) // re-armed
+    harness.fireLatest()
+    expect(escalations).toEqual([BRIDGE_DEAD_RESTART_REASON])
+  })
+})
+
 // ─── Crash-log tail ──────────────────────────────────────────────────────────
 
 describe('readFreshCrashLogTail', () => {