switchroom 0.18.15 → 0.18.17

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/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