switchroom 0.18.14 → 0.18.17

package/telegram-plugin/tests/throttle-tier.test.ts

@@ -12,6 +12,8 @@
 
 import { describe, it, expect } from 'vitest'
 import {
+  build429ClassifiedMetric,
+  classify429Detail,
   decideThrottleTier,
   evaluateThrottleNotice,
   isAccountScopedThrottle,
@@ -136,6 +138,180 @@ describe('decideThrottleTier — decision matrix', () => {
   })
 })
 
+// Verbatim LiteLLM proxy-local 429 shapes (provenance on
+// `litellmProxyLocal429Signals`, model-unavailable.ts).
+const LITELLM_TPM_CAP =
+  'Deployment over user-defined ratelimit. tpm limit=8000. current usage=8241. ' +
+  'id=abc123def, model_group=claude-fable-5'
+const LITELLM_KEY_LIMIT =
+  'Rate limit exceeded for api_key: hashed-key-1a2b3c. Limit type: tokens. ' +
+  'Current limit: 8000, Remaining: 0. Limit resets at: 2026-07-12 08:05:00 UTC'
+const LITELLM_ROUTER_COOLDOWN =
+  'No deployments available for selected model, Try again in 27.5 seconds. ' +
+  "Passed model=claude-fable-5. pre-call-checks=False, cooldown_list=['abc123def']"
+// v3 limiter, descriptor NOT in the enumerated signal list — matched by the
+// litellmV3LimiterSignalPair co-occurrence rule (model-unavailable.ts).
+const LITELLM_TEAM_MODEL_LIMIT =
+  'Rate limit exceeded for model_per_team: team-1a2b3c:claude-fable-5. ' +
+  'Limit type: tokens. Current limit: 50000, Remaining: 0. ' +
+  'Limit resets at: 2026-07-12 08:05:00 UTC'
+
+describe('decideThrottleTier — LiteLLM-proxy-local 429s never enter the tier', () => {
+  // OUTCOME pin: `none` is what keeps a proxy-local cap trip off the
+  // account-scoped machinery — no broker mark-throttled, no throttle-tier
+  // runner fire, no failover escalation. The gateway additionally gates on
+  // classify429Detail, but the decision module must agree.
+  it.each([
+    ['deployment tpm cap', LITELLM_TPM_CAP],
+    ['virtual-key tpm_limit', LITELLM_KEY_LIMIT],
+    ['router cooldown', LITELLM_ROUTER_COOLDOWN],
+    ['team model cap (non-enumerated v3 descriptor)', LITELLM_TEAM_MODEL_LIMIT],
+  ])('%s → none (calm path owns it)', (_name, detail) => {
+    expect(decideThrottleTier({ detail, now: NOW, thresholdMs: THRESHOLD })).toEqual({
+      action: 'none',
+    })
+  })
+})
+
+describe('classify429Detail — three-way origin classification', () => {
+  it('classifies LiteLLM limiter wordings as litellm-local', () => {
+    expect(classify429Detail(LITELLM_TPM_CAP)).toBe('litellm-local')
+    expect(classify429Detail(LITELLM_KEY_LIMIT)).toBe('litellm-local')
+    expect(classify429Detail(LITELLM_ROUTER_COOLDOWN)).toBe('litellm-local')
+    // Non-enumerated v3 descriptor — the co-occurrence pair, not a list
+    // entry, carries this one.
+    expect(classify429Detail(LITELLM_TEAM_MODEL_LIMIT)).toBe('litellm-local')
+  })
+
+  it('classifies Anthropic account-affirming wording as account-scoped', () => {
+    expect(classify429Detail(TRANSIENT('resets in 3m'))).toBe('account-scoped')
+    expect(
+      classify429Detail('would exceed your account’s rate limit'),
+    ).toBe('account-scoped')
+  })
+
+  it('classifies server-side / bare rate-limit wording as generic-transient', () => {
+    expect(
+      classify429Detail('Server is temporarily limiting requests (not your usage limit)'),
+    ).toBe('generic-transient')
+    expect(classify429Detail('overloaded_error 529')).toBe('generic-transient')
+    expect(classify429Detail('rate_limit_error: try again later')).toBe('generic-transient')
+  })
+
+  it('TIE-BREAK: account-affirming wording wins over LiteLLM wording when both appear', () => {
+    // The pass-through shape: LiteLLM wraps a FORWARDED upstream Anthropic
+    // account 429 (exception mapping / limiter prose in the same body).
+    // LiteLLM never emits the account wording itself, so its presence means
+    // Anthropic really throttled the account — the broker throttle mark and
+    // the throttle tier must still run.
+    const mixed =
+      `litellm.RateLimitError: ${LITELLM_TPM_CAP} — upstream said: ` +
+      "This request would exceed your account's rate limit. Please try again later."
+    expect(classify429Detail(mixed)).toBe('account-scoped')
+    // And the tier decision still engages (not 'none').
+    expect(
+      decideThrottleTier({ detail: mixed, now: NOW, thresholdMs: THRESHOLD }).action,
+    ).not.toBe('none')
+  })
+
+  it('a bare litellm.RateLimitError wrapper WITHOUT limiter wording stays generic-transient', () => {
+    // The exception-mapping prefix alone is not proxy-local evidence.
+    expect(
+      classify429Detail('litellm.RateLimitError: RateLimitError: 429 try again later'),
+    ).toBe('generic-transient')
+  })
+
+  it('never throws on weird input', () => {
+    expect(classify429Detail('')).toBe('generic-transient')
+    expect(classify429Detail(undefined as unknown as string)).toBe('generic-transient')
+    expect(classify429Detail(9000 as unknown as string)).toBe('generic-transient')
+    expect(classify429Detail('A'.repeat(200_000))).toBe('generic-transient')
+  })
+})
+
+describe('build429ClassifiedMetric — instrumentation payload', () => {
+  it('litellm-local deployment cap → limit fields + calm action', () => {
+    const m = build429ClassifiedMetric({
+      agent: 'carrie',
+      detail: LITELLM_TPM_CAP,
+      classification: 'litellm-local',
+      action: 'calm',
+      now: NOW,
+    })
+    expect(m).toEqual({
+      kind: 'rate_limit_429_classified',
+      agent: 'carrie',
+      classification: 'litellm-local',
+      action: 'calm',
+      reset_at_ms: null,
+      reset_in_ms: null,
+      limit_type: 'tpm',
+      limit: 8000,
+      current_usage: 8241,
+    })
+  })
+
+  it('litellm-local NON-enumerated v3 descriptor (model_per_team) → full metric payload', () => {
+    // Finding-pin: a team-level model cap must produce the metric (it used
+    // to miss every signal → quota-exhausted → no metric at all).
+    const m = build429ClassifiedMetric({
+      agent: 'carrie',
+      detail: LITELLM_TEAM_MODEL_LIMIT,
+      classification: 'litellm-local',
+      action: 'calm',
+      now: NOW,
+    })
+    expect(m.kind).toBe('rate_limit_429_classified')
+    expect(m.classification).toBe('litellm-local')
+    expect(m.limit_type).toBe('tokens')
+    expect(m.limit).toBe(50_000)
+    expect(m.reset_at_ms).toBe(Date.UTC(2026, 6, 12, 8, 5, 0))
+  })
+
+  it('litellm-local v3 key limit → tokens limit type + parsed "Limit resets at" UTC reset', () => {
+    const m = build429ClassifiedMetric({
+      agent: 'carrie',
+      detail: LITELLM_KEY_LIMIT,
+      classification: 'litellm-local',
+      action: 'calm',
+      now: NOW,
+    })
+    expect(m.limit_type).toBe('tokens')
+    expect(m.limit).toBe(8000)
+    expect(m.reset_at_ms).toBe(Date.UTC(2026, 6, 12, 8, 5, 0))
+    expect(m.reset_in_ms).toBe(Date.UTC(2026, 6, 12, 8, 5, 0) - NOW)
+  })
+
+  it('account-scoped 429 → Anthropic-parsed reset, no limit fields', () => {
+    const m = build429ClassifiedMetric({
+      agent: 'carrie',
+      detail: TRANSIENT('resets in 3m'),
+      classification: 'account-scoped',
+      action: 'throttle',
+      now: NOW,
+    })
+    expect(m.classification).toBe('account-scoped')
+    expect(m.action).toBe('throttle')
+    expect(m.reset_at_ms).toBe(NOW + 3 * 60_000)
+    expect(m.reset_in_ms).toBe(3 * 60_000)
+    expect(m.limit_type).toBeNull()
+    expect(m.limit).toBeNull()
+    expect(m.current_usage).toBeNull()
+  })
+
+  it('never throws on weird detail; nulls out unparseable resets', () => {
+    const m = build429ClassifiedMetric({
+      agent: 'carrie',
+      detail: undefined as unknown as string,
+      classification: 'generic-transient',
+      action: 'calm',
+      now: NOW,
+    })
+    expect(m.reset_at_ms).toBeNull()
+    expect(m.reset_in_ms).toBeNull()
+  })
+})
+
 describe('isAccountScopedThrottle — the tier gate', () => {
   it("matches account-affirming wording (both apostrophe variants + 'not your account')", () => {
     expect(isAccountScopedThrottle("would exceed your account's rate limit")).toBe(true)

package/telegram-plugin/tests/worker-activity-feed.test.ts

@@ -7,6 +7,7 @@ import {
   type BotApiForWorkerFeed,
 } from '../worker-activity-feed.js'
 import { STATUS_ROLLING_LINES, STATUS_LINE_MAX } from '../status-no-truncate.js'
+import { SEND_GATE_SHED } from '../send-gate.js'
 
 describe('isWorkerActivityFeedEnabled (default ON)', () => {
   it('defaults to true when the env var is unset', () => {
@@ -1336,3 +1337,209 @@ describe('narrative dedup — non-adjacent repeats collapse (A,B,A)', () => {
     expect(last.text).toContain('step-repeat')
   })
 })
+
+// ─── send-gate shed contract (#3174) ────────────────────────────────────────
+//
+// The feed's send/edit adapters transit the deterministic send gate
+// (telegram-plugin/send-gate.ts, #3084), wired at the robustApiCall layer. The
+// gate SHEDS a call — resolves `undefined` WITHOUT hitting the API — when a
+// flood window is open (or a `useful` send exceeds its queue TTL, or a cosmetic
+// edit finds no free token). Before this fix the first-paint path dereferenced
+// `sent.message_id` on that `undefined`, throwing every heartbeat tick (~6s) for
+// the whole ban — 578 `undefined is not an object (evaluating 'sent.message_id')`
+// crashes in one 6h flood ban on 2026-07-12. These tests pin the shed contract:
+// (a) an open flood window parks the handle and makes ZERO api calls; (b) an
+// undefined send is treated as NOT-delivered (no crash, no phantom message id);
+// (c)/(d) an undefined edit is not recorded as on-screen (shed honesty, mirroring
+// PR #3173) so the update re-sends once the gate clears.
+
+interface GateBot extends BotApiForWorkerFeed {
+  /** Times sendMessage was INVOKED (attempts), delivered or shed. */
+  sendCalls: number
+  /** Times editMessageText was INVOKED (attempts), delivered or shed. */
+  editCalls: number
+  /** DELIVERED sends (gate admitted). */
+  sent: Array<{ text: string }>
+  /** DELIVERED edits (gate admitted). */
+  edits: Array<{ messageId: number; text: string }>
+  /**
+   * One-shot: shed the next send even with the window closed. Faithful to the
+   * gate: a worker-feed SEND is `useful` (never `cosmetic`), so a gate that
+   * can't admit it resolves `undefined` (queue-TTL `expired`) — NEVER the
+   * cosmetic-only SEND_GATE_SHED sentinel. The feed's send-shed detection is
+   * structural (`typeof sent.message_id !== 'number'`), catching either.
+   */
+  shedNextSend: boolean
+  /**
+   * One-shot: shed the next EDIT even with the window closed. Faithful to the
+   * gate: worker-feed edits are `cosmetic`, so a gate shed resolves the
+   * distinguishable SEND_GATE_SHED sentinel (#3110 F1) — NOT `undefined` (which
+   * the gate reserves for a benign no-op drop whose payload IS on screen).
+   */
+  shedNextEdit: boolean
+}
+
+/**
+ * A bot adapter that models the send gate: it SHEDS (without recording a
+ * delivery) whenever the injected flood probe reports an open window, or a
+ * one-shot `shedNext*` flag is set (the race where the window opens between the
+ * feed's probe read and the send). Faithful to the post-#3110 contract: a shed
+ * EDIT resolves the SEND_GATE_SHED sentinel (cosmetic shed), a shed SEND
+ * resolves `undefined` (`useful` queue-TTL expiry). A DELIVERED edit resolves a
+ * non-shed value (`{}` — grammy returns `true`/`Message`).
+ */
+function makeGateBot(floodRemaining: () => number): GateBot {
+  let nextId = 1000
+  const gb: GateBot = {
+    sendCalls: 0,
+    editCalls: 0,
+    sent: [],
+    edits: [],
+    shedNextSend: false,
+    shedNextEdit: false,
+    sendMessage: async (_chatId, text) => {
+      gb.sendCalls++
+      if (floodRemaining() > 0 || gb.shedNextSend) {
+        gb.shedNextSend = false
+        return undefined as unknown as { message_id: number }
+      }
+      gb.sent.push({ text })
+      return { message_id: nextId++ }
+    },
+    editMessageText: async (_chatId, messageId, text) => {
+      gb.editCalls++
+      if (floodRemaining() > 0 || gb.shedNextEdit) {
+        gb.shedNextEdit = false
+        return SEND_GATE_SHED as unknown as undefined
+      }
+      gb.edits.push({ messageId, text })
+      return {}
+    },
+  }
+  return gb
+}
+
+describe('worker-feed send-gate shed contract', () => {
+  it('makes ZERO api calls while a flood window is open, then paints full state after it closes', async () => {
+    let clock = 0
+    const untilTs = 6 * 60 * 60 * 1000 // a 6h ban, as observed 2026-07-12
+    const probe = () => Math.max(0, untilTs - clock)
+    const bot = makeGateBot(probe)
+    const feed = createWorkerActivityFeed({
+      bot,
+      now: () => clock,
+      firstPaintMinMs: 0,
+      floodWaitRemainingMs: probe,
+    })
+
+    // Drive the heartbeat cadence hammering the feed for the whole ban.
+    for (let i = 0; i < 30; i++) {
+      clock += 6000
+      await feed.update('w1', 'chat', view({ elapsedMs: clock }))
+    }
+    // Parked on the window — never even called the API (the whole point).
+    expect(bot.sendCalls).toBe(0)
+    expect(bot.sent).toHaveLength(0)
+    expect(feed.has('w1')).toBe(false)
+
+    // Window closes: the next tick paints full state exactly once.
+    clock = untilTs + 1000
+    await feed.update('w1', 'chat', view({ elapsedMs: clock }))
+    expect(bot.sendCalls).toBe(1)
+    expect(bot.sent).toHaveLength(1)
+    expect(bot.sent[0].text).toContain('🛠 **Worker**')
+    expect(feed.has('w1')).toBe(true)
+  })
+
+  it('treats an undefined send result as not-delivered — no crash, no phantom message id', async () => {
+    let clock = 10_000
+    const logs: string[] = []
+    const bot = makeGateBot(() => 0) // probe reads clear …
+    bot.shedNextSend = true // … but the gate sheds this send (race)
+    const feed = createWorkerActivityFeed({
+      bot,
+      now: () => clock,
+      firstPaintMinMs: 0,
+      floodWaitRemainingMs: () => 0,
+      log: (m) => logs.push(m),
+    })
+
+    await feed.update('w1', 'chat', view())
+    expect(bot.sendCalls).toBe(1) // it attempted the send
+    expect(bot.sent).toHaveLength(0) // but nothing was delivered
+    expect(feed.messageIdOf('w1')).toBeNull() // and no phantom message id recorded
+    expect(feed.has('w1')).toBe(false)
+    // Regression pin: the old code dereferenced `undefined.message_id` and logged
+    // it as a hard "send failed"; the shed is now a recognized, clean skip.
+    expect(logs.some((l) => l.startsWith('worker-feed: send failed'))).toBe(false)
+    expect(logs.some((l) => l.includes('shed by send gate'))).toBe(true)
+
+    // The next paint (gate no longer shedding) lands cleanly.
+    clock = 20_000
+    await feed.update('w1', 'chat', view())
+    expect(bot.sent).toHaveLength(1)
+    expect(feed.has('w1')).toBe(true)
+  })
+
+  it('does not record a shed cosmetic edit as on-screen — the update re-sends after the gate clears', async () => {
+    let clock = 10_000
+    const bot = makeGateBot(() => 0)
+    const feed = createWorkerActivityFeed({
+      bot,
+      now: () => clock,
+      firstPaintMinMs: 0,
+      minEditIntervalMs: 0,
+      floodWaitRemainingMs: () => 0,
+    })
+
+    await feed.update('w1', 'chat', view({ toolCount: 1 }))
+    expect(bot.sent).toHaveLength(1)
+
+    // Gate sheds the edit (undefined) — it is NOT on screen.
+    clock = 20_000
+    bot.shedNextEdit = true
+    await feed.update('w1', 'chat', view({ toolCount: 2 }))
+    expect(bot.editCalls).toBe(1)
+    expect(bot.edits).toHaveLength(0)
+
+    // Shed honesty: the SAME update re-sends once the gate clears — the shed
+    // payload was never recorded as `lastBody`, so it is not dropped as a dup.
+    clock = 30_000
+    await feed.update('w1', 'chat', view({ toolCount: 2 }))
+    expect(bot.edits).toHaveLength(1)
+    expect(bot.edits[0].text).toContain('2 tools')
+  })
+
+  it('does not falsely finalize on a shed terminal edit — re-drives the finalize once the gate clears', async () => {
+    let clock = 10_000
+    const bot = makeGateBot(() => 0)
+    const feed = createWorkerActivityFeed({
+      bot,
+      now: () => clock,
+      firstPaintMinMs: 0,
+      minEditIntervalMs: 0,
+      floodWaitRemainingMs: () => 0,
+    })
+
+    await feed.update('w1', 'chat', view({ toolCount: 1 }))
+    expect(bot.sent).toHaveLength(1)
+
+    // Gate sheds the terminal edit (undefined).
+    clock = 20_000
+    bot.shedNextEdit = true
+    await feed.finish('w1', view({ state: 'done', toolCount: 5 }))
+    expect(bot.editCalls).toBe(1)
+    expect(bot.edits).toHaveLength(0)
+    // NOT finalized: the handle survives (pendingFinish staged) rather than
+    // being torn down with the card frozen on its last running render.
+    expect(feed.has('w1')).toBe(true)
+
+    // Re-drive with the gate clear: the terminal recap lands and the handle
+    // finalizes.
+    clock = 30_000
+    await feed.finish('w1', view({ state: 'done', toolCount: 5 }))
+    expect(bot.edits).toHaveLength(1)
+    expect(bot.edits[0].text).toContain('_done · 5 tools')
+    expect(feed.has('w1')).toBe(false)
+  })
+})

package/telegram-plugin/throttle-tier.ts

@@ -33,7 +33,12 @@
 
 import { escapeMarkdown } from './card-format.js'
 import { formatResetRelative } from './quota-check.js'
-import { parseResetTime } from './model-unavailable.js'
+import {
+  isLitellmProxyLocal429,
+  parseLitellmLimitDetail,
+  parseResetTime,
+} from './model-unavailable.js'
+import type { RuntimeMetricEvent } from './runtime-metrics.js'
 
 // ─── Account-scoped throttle wording ─────────────────────────────────────────
 
@@ -65,6 +70,98 @@ export function isAccountScopedThrottle(text: string): boolean {
   return accountScopedThrottleSignals.some((s) => lower.includes(s))
 }
 
+// ─── Three-way 429 classification ────────────────────────────────────────────
+
+/**
+ * Where a terminal 429-family failure originated:
+ *   - `account-scoped`   — Anthropic throttled THIS account ("would exceed
+ *     your account's rate limit"). Eligible for the throttle tier below
+ *     (broker mark-throttled / failover).
+ *   - `litellm-local`    — the LiteLLM proxy's OWN limiter tripped
+ *     (`tpm_limit`/`rpm_limit` cap, router cooldown — see
+ *     `litellmProxyLocal429Signals` in model-unavailable.ts). The request
+ *     never reached Anthropic; account state must not be touched.
+ *   - `generic-transient` — everything else in the rate-limit family
+ *     (server-side 429/529 wording, bare `rate_limit_error`). Calm path.
+ */
+export type RateLimit429Classification =
+  | 'account-scoped'
+  | 'litellm-local'
+  | 'generic-transient'
+
+/**
+ * Classify a terminal `rate-limited` operator event's detail text.
+ *
+ * TIE-BREAK (both wordings present): account-scoped wins, and only on its
+ * EXPLICIT wording. Rationale: LiteLLM never emits the account-affirming
+ * strings itself, so when they co-occur with LiteLLM wording the detail is a
+ * genuine upstream Anthropic account 429 that traversed (and was wrapped by)
+ * the proxy — e.g. the pass-through's "litellm.RateLimitError: …would exceed
+ * your account's rate limit…" exception mapping. Classifying that as
+ * proxy-local would drop the broker throttle mark and walk every retry
+ * straight back into the same account throttle. The reverse risk is nil: a
+ * purely proxy-local 429 (limiter fired BEFORE any upstream call) cannot
+ * contain Anthropic's account wording.
+ *
+ * BOUND: operator events forwarded over IPC carry `detail` truncated to
+ * 1000 chars (bridge.ts `sendOperatorEvent`'s `.slice(0, 1000)`;
+ * `OPERATOR_EVENT_DETAIL_MAX` in gateway/ipc-server.ts), so on that path the
+ * tie-break sees only the first 1000 chars of the body. In practice both
+ * wordings sit well inside that window (real Anthropic and LiteLLM bodies
+ * are <400 chars), and a truncated-away account marker would merely
+ * downgrade account-scoped → litellm-local/generic-transient — the calm
+ * path, never a wrong account mark.
+ *
+ * Never throws on weird input (both matchers are total).
+ */
+export function classify429Detail(text: string): RateLimit429Classification {
+  if (isAccountScopedThrottle(text)) return 'account-scoped'
+  if (isLitellmProxyLocal429(text)) return 'litellm-local'
+  return 'generic-transient'
+}
+
+/**
+ * Build the `rate_limit_429_classified` runtime metric for one terminal
+ * rate-limited operator event — the instrumentation that lets an operator
+ * correlate Anthropic ACCOUNT 429s with fleet TPM (the prerequisite for
+ * enabling LiteLLM `tpm_limit` caps; see docs/auth.md § LiteLLM-proxy-local
+ * 429s). Pure builder so the payload shape is unit-testable; the gateway
+ * emits the result via emitRuntimeMetric (PostHog + JSONL dual sink).
+ *
+ * `action` is what the gateway decided for this event:
+ *   - `throttle` / `failover` — the account-scoped throttle tier's decision
+ *   - `calm` — the existing calm rate-limited path (litellm-local and
+ *     generic-transient always land here; no broker mark, no failover)
+ *
+ * Reset detail is best-effort: the Anthropic-shaped `parseResetTime` first,
+ * then LiteLLM's own shapes ("Limit resets at: … UTC" / "Try again in Ns")
+ * via `parseLitellmLimitDetail`. Limit fields parse only from LiteLLM
+ * wording (Anthropic bodies carry no numeric limit).
+ */
+export function build429ClassifiedMetric(opts: {
+  agent: string
+  detail: string
+  classification: RateLimit429Classification
+  action: 'throttle' | 'failover' | 'calm'
+  now: number
+}): Extract<RuntimeMetricEvent, { kind: 'rate_limit_429_classified' }> {
+  const detail = typeof opts.detail === 'string' ? opts.detail : ''
+  const litellm = parseLitellmLimitDetail(detail, new Date(opts.now))
+  const anthropicResetMs = parseResetTime(detail, new Date(opts.now))?.getTime() ?? null
+  const resetAtMs = anthropicResetMs ?? litellm.resetAtMs
+  return {
+    kind: 'rate_limit_429_classified',
+    agent: opts.agent,
+    classification: opts.classification,
+    action: opts.action,
+    reset_at_ms: resetAtMs,
+    reset_in_ms: resetAtMs != null ? Math.max(0, resetAtMs - opts.now) : null,
+    limit_type: litellm.limitType,
+    limit: litellm.limit,
+    current_usage: litellm.currentUsage,
+  }
+}
+
 /**
  * Default retry-in-place ceiling: a transient 429 whose reset is within this
  * window waits on the account instead of failing the fleet over. Override

package/telegram-plugin/worker-activity-feed.ts

@@ -39,6 +39,7 @@ import {
 } from './card-format.js'
 import { STATUS_ROLLING_LINES } from './status-no-truncate.js'
 import { renderStatusCard, formatStepSuffix } from './tool-activity-summary.js'
+import { isSendGateShed } from './send-gate.js'
 
 /** Worker-activity feed is ON by default; an operator opts out with
  *  SWITCHROOM_WORKER_ACTIVITY_FEED=0. */
@@ -195,6 +196,24 @@ export interface WorkerActivityFeedOpts {
   firstPaintMinMs?: number
   /** stderr-style log sink. Defaults to noop. */
   log?: (msg: string) => void
+  /**
+   * Remaining ms of the currently-open per-bot flood window, read from the
+   * SAME persisted marker the gateway's `robustApiCall` and held-card sweep
+   * consult (`makeFloodWaitProbe(FLOOD_STATE_PATH)`). Two independent reads of
+   * one source of truth — not a second notion of "is the channel open".
+   *
+   * Why the feed needs it (#3084 follow-up): the feed's send/edit adapters run
+   * through the send gate, which SHEDS (resolves `undefined`) any call made
+   * while a flood window is open. Without this probe the heartbeat re-fires a
+   * shed send every `heartbeatTickMs` (~6s) for the WHOLE ban — thousands of
+   * gate admissions, and (pre-fix) a `sent.message_id` crash on the `undefined`
+   * every tick. With it, a running/first-paint tick that sees an open window
+   * parks the handle in cooldown for the window's remaining and makes ZERO api
+   * calls until it closes, mirroring the held-card sweep's pre-send probe.
+   * Defaults to `() => 0` (no window) so tests and non-gateway callers are
+   * unchanged.
+   */
+  floodWaitRemainingMs?: () => number
   /**
    * Heartbeat timer factory. Injectable for tests. Defaults to the real
    * `setInterval`, `.unref()`'d so it never keeps the process alive.
@@ -363,6 +382,7 @@ export interface WorkerActivityFeed {
 export function createWorkerActivityFeed(opts: WorkerActivityFeedOpts): WorkerActivityFeed {
   const log = opts.log ?? (() => {})
   const nowFn = opts.now ?? Date.now
+  const floodWaitRemainingMs = opts.floodWaitRemainingMs ?? (() => 0)
   const minEditInterval = opts.minEditIntervalMs ?? 2500
   const firstPaintMin = opts.firstPaintMinMs ?? 8000
   const heartbeatTickMs = opts.heartbeatTickMs ?? 6000
@@ -419,6 +439,22 @@ export function createWorkerActivityFeed(opts: WorkerActivityFeedOpts): WorkerAc
     log(`worker-feed: ${label} 429 — backing off ${retryAfter}s`)
   }
 
+  /**
+   * Park a handle in cooldown for the remaining of an open flood window (if
+   * any), so the heartbeat's `nowFn() < h.cooldownUntil` guard suppresses every
+   * further send/edit until the ban closes. Returns true when a window was open
+   * (caller should abandon the current attempt). Two reads of the SAME on-disk
+   * marker `robustApiCall` gates on — never a second notion of "channel open".
+   */
+  function parkIfFloodWindowOpen(h: WorkerHandle): boolean {
+    const remaining = floodWaitRemainingMs()
+    if (remaining <= 0) return false
+    // Only extend the cooldown — never shorten one a 429 already set longer.
+    const until = nowFn() + remaining + COOLDOWN_JITTER_MS
+    if (until > h.cooldownUntil) h.cooldownUntil = until
+    return true
+  }
+
   function accumulateNarrative(h: WorkerHandle, view: WorkerActivityView): void {
     const line = view.latestSummary.trim()
     if (line.length === 0) return
@@ -453,6 +489,12 @@ export function createWorkerActivityFeed(opts: WorkerActivityFeedOpts): WorkerAc
     h.lastView = merged
     if (h.dispatchAtMs == null) h.dispatchAtMs = nowFn() - view.elapsedMs
     if (nowFn() < h.cooldownUntil) return
+    // A flood window is open: the send gate would SHED every call made now
+    // (resolving `undefined`). Park in cooldown for the window's remaining and
+    // make ZERO api calls until it closes — the heartbeat re-drives the paint
+    // with full state on the first tick past the window. Same source of truth
+    // as robustApiCall's own pre-call probe.
+    if (parkIfFloodWindowOpen(h)) return
     const body = renderWorkerActivity(merged, liveSuffix)
 
     // First paint: hold off until the worker has run long enough to be
@@ -461,6 +503,17 @@ export function createWorkerActivityFeed(opts: WorkerActivityFeedOpts): WorkerAc
       if (view.elapsedMs < firstPaintMin) return
       try {
         const sent = await opts.bot.sendMessage(h.chatId, body, sendOptsFor(h))
+        // Shed contract (#3084): the gate resolves `undefined` for a send it
+        // shed (open flood window) or dropped as stale (`useful` TTL). That is
+        // NOT a delivered message — dereferencing `sent.message_id` here was
+        // the `undefined is not an object` crash that fired every ~6s for a
+        // whole 6h ban. Treat it as not-delivered: record no message_id, park
+        // on any open window, and let the heartbeat re-drive the paint.
+        if (sent == null || typeof sent.message_id !== 'number') {
+          parkIfFloodWindowOpen(h)
+          log(`worker-feed: first paint shed by send gate agent=${h.agentId} — not delivered`)
+          return
+        }
         h.messageId = sent.message_id
         h.lastBody = body
         h.lastEditAt = nowFn()
@@ -480,7 +533,19 @@ export function createWorkerActivityFeed(opts: WorkerActivityFeedOpts): WorkerAc
     if (nowFn() - h.lastEditAt < minEditInterval) return
 
     try {
-      await opts.bot.editMessageText(h.chatId, h.messageId, body, sendOptsFor(h))
+      const res = await opts.bot.editMessageText(h.chatId, h.messageId, body, sendOptsFor(h))
+      // Shed honesty (#3084, mirrors #3173): a cosmetic edit the gate shed
+      // resolves the distinguishable SEND_GATE_SHED sentinel (#3110 F1 — NOT a
+      // bare `undefined`, which the gate reserves for a benign no-op drop whose
+      // payload IS already on screen). The shed payload is NOT on screen, so do
+      // not record it as `lastBody`, or the next tick's dedup would skip
+      // re-sending the very update the gate dropped. Park on any open window and
+      // let the heartbeat re-drive once it closes. A benign `undefined`/`true`
+      // falls through below and is correctly recorded as delivered.
+      if (isSendGateShed(res)) {
+        parkIfFloodWindowOpen(h)
+        return
+      }
       h.lastBody = body
       h.lastEditAt = nowFn()
       log(
@@ -534,12 +599,11 @@ export function createWorkerActivityFeed(opts: WorkerActivityFeedOpts): WorkerAc
       h.pendingFinish = null
       return
     }
-    if (nowFn() < h.cooldownUntil) {
-      // Honour the flood-wait; a terminal edit isn't worth a ban. But
-      // unlike the prior "stale but harmless" surrender, STAGE the terminal
-      // view so the heartbeat re-drives the finalize edit the instant the
-      // cooldown expires — a transport hiccup can no longer leave a
-      // finished worker's card stuck on its last running render.
+    // A flood window is open (or a prior 429 set a cooldown): honour it — a
+    // terminal edit isn't worth extending a ban. STAGE the terminal view so the
+    // heartbeat re-drives the finalize the instant the window/cooldown expires,
+    // so a finished worker's card can't get stuck on its last running render.
+    if (parkIfFloodWindowOpen(h) || nowFn() < h.cooldownUntil) {
       h.pendingFinish = view
       return
     }
@@ -549,7 +613,18 @@ export function createWorkerActivityFeed(opts: WorkerActivityFeedOpts): WorkerAc
       return
     }
     try {
-      await opts.bot.editMessageText(h.chatId, h.messageId, body, sendOptsFor(h))
+      const res = await opts.bot.editMessageText(h.chatId, h.messageId, body, sendOptsFor(h))
+      // Shed honesty (#3084): a shed terminal edit resolves the distinguishable
+      // SEND_GATE_SHED sentinel (#3110 F1 — NOT a bare `undefined`, which is the
+      // gate's benign no-op drop) — it did NOT land. Keep `pendingFinish` staged
+      // so the heartbeat re-drives it once the window closes; do NOT clear it or
+      // record `lastBody` (that would be a false finalization — card frozen on
+      // its running render while we believe it's done). Park on any open window.
+      if (isSendGateShed(res)) {
+        parkIfFloodWindowOpen(h)
+        h.pendingFinish = view
+        return
+      }
       h.lastBody = body
       h.lastEditAt = nowFn()
       h.pendingFinish = null