switchroom 0.18.15 → 0.18.18

package/telegram-plugin/stream-controller.ts

@@ -19,9 +19,14 @@
  * entire server.ts top-level initialization.
  */
 
-import { createDraftStream, type DraftStreamHandle } from './draft-stream.js'
+import {
+  createDraftStream,
+  makeDraftEditShedError,
+  type DraftStreamHandle,
+} from './draft-stream.js'
 import { richMessage, isParseEntitiesError } from './rich-send.js'
 import { renderOutboundChunks } from './render/rich-render.js'
+import { isSendGateShed, type SendGateOpts } from './send-gate.js'
 
 /**
  * Minimal bot.api surface the controller needs. Real callers pass grammy's
@@ -77,9 +82,21 @@ export interface StreamSendOpts {
   disable_notification?: boolean
 }
 
+/**
+ * Options a stream-controller call passes to its retry wrapper. A structural
+ * superset of `SendGateOpts` (send-gate.ts) plus the retry policy's own
+ * `threadId`, and assignable to `RetryCallOpts` (retry-api-call.ts) — so the
+ * production wrapper (`robustApiCall` = send gate over `createRetryApiCall`)
+ * receives `messageId` / `editPayload` / `priorityClass` and the gate's
+ * per-message edit floor, last-write-wins coalescing, no-op skip and
+ * cosmetic shedding govern the draft/answer stream (#3110; part3-design §4
+ * names rapid same-message editMessageText as the #1 flood-ban trigger).
+ */
+export type RetryPolicyOpts = SendGateOpts & { threadId?: number }
+
 export type RetryPolicy = <T>(
   fn: () => Promise<T>,
-  opts?: { threadId?: number; chat_id?: string },
+  opts?: RetryPolicyOpts,
 ) => Promise<T>
 
 export interface StreamControllerConfig {
@@ -251,6 +268,70 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
     return bot.api.editMessageText(chatId, id, richMessage(piece.text), opts)
   }
 
+  // ---- Send-gate wiring for the edit path (#3110) -------------------------
+  //
+  // Every edit call passes `messageId` / `editPayload` / `priorityClass`
+  // through the retry wrapper so the send gate's per-message edit floor
+  // (>=1.5s), last-write-wins coalescing, and no-op skip govern the draft
+  // stream — previously these edits carried only `{ threadId, chat_id }`,
+  // so the gate treated them as ordinary sends and the stream's own 400 ms
+  // DM throttle drove same-message editMessageText well under the floor
+  // (the #1 documented flood-ban trigger, part3-design §4; production ban
+  // 2026-07-12 on #3110). The local per-surface throttle stays as a cheap
+  // pre-filter; the gate is the authority.
+  //
+  // Priority classes: intermediate draft edits are `cosmetic` (part3-design
+  // §2 lists "stream updates" there) — shed under pressure / an open flood
+  // window; the next flush carries full state. The FINALIZE flush (the edit
+  // that renders the completed answer) is `critical`, mirroring the reply
+  // path's preview-finalize convention (gateway.ts editPreview): never shed,
+  // waits out a short window, fails fast with a structured FLOOD_WAIT_ACTIVE
+  // on a long one. SENDS stay untagged (the gate admits untagged non-edit
+  // sends as `critical`) — a shed send would resolve the gate's shed
+  // sentinel instead of `{ message_id }` and break message-id capture, and
+  // the anchor/tail sends ARE the answer surface.
+  //
+  // `handleRef.isFinal()` is true from the moment finalize() is entered
+  // (draft-stream sets `final` before its last flush), so the closures below
+  // classify exactly the finalize flush — and anything after it — as
+  // critical. The ref is assigned right after createDraftStream returns,
+  // before any closure can run (closures only fire from update/finalize).
+  //
+  // KNOWN MISSED BENEFIT (review F5, deliberate): the gate's last-write-wins
+  // coalescing never engages for THIS surface, because draft-stream
+  // serializes its flushes — it awaits each edit before issuing the next, so
+  // at most one edit per message is ever inside the gate. Consequence: a
+  // stale draft sleeping on the gate's floor still lands (one API call the
+  // coalescer would have replaced) before the newer snapshot, and a finalize
+  // issued mid-floor can trail by up to ~2x editFloorMs (floor wait for the
+  // stale draft, then floor wait for the final). Correctness is unaffected —
+  // the latest state always lands, floor-paced — and the gate coalescing
+  // remains live protection for CONCURRENT writers to one message (e.g. a
+  // re-attached #626 controller racing its predecessor).
+  let handleRef: DraftStreamHandle | null = null
+  const editGateOpts = (id: number, payload: unknown): RetryPolicyOpts => ({
+    threadId,
+    chat_id: chatId,
+    messageId: id,
+    editPayload: payload,
+    priorityClass: handleRef?.isFinal() === true ? 'critical' : 'cosmetic',
+  })
+  // The rendered payload the gate hashes for the no-op skip / coalescing —
+  // exactly what goes over the wire (rich wrapper included), so a plain
+  // fallback of the same text never hashes equal to its rich form.
+  const piecePayload = (piece: { text: string; rich: boolean }): unknown =>
+    piece.rich ? richMessage(piece.text) : piece.text
+  // Shed detection (#3110 review F1): keyed EXACTLY off the gate's
+  // SEND_GATE_SHED sentinel — never off `undefined`, which is overloaded
+  // (gate no-op drop; robustApiCall's swallowed benign 400s like "message is
+  // not modified"). Those benign cases mean the payload is ALREADY on screen
+  // and are treated as delivered, exactly as before this wiring existed. A
+  // true shed means the edit did NOT land: draft-stream must not record the
+  // snapshot as on-screen (its dedupe would skip a later flush of the same
+  // text — the completed answer would never render), so the edit closure
+  // throws the marker error draft-stream recognizes and recovers from
+  // (`makeDraftEditShedError` → snapshot preserved for finalize, review F2).
+
   // Overflow-tail bookkeeping, shared across the send + edit closures for the
   // whole stream lifetime. A body large enough to split into several
   // wire-cap pieces anchors on piece[0] (edited in place by draft-stream) and
@@ -269,12 +350,25 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
   // text) thereafter. A non-parse failure is logged as a partial-delivery
   // warning and swallowed so the remaining tail pieces still get a chance to
   // land — never a silent drop, never an abort of pieces K..N (concern C1).
-  const upsertTail = async (ti: number, piece: { text: string; rich: boolean }): Promise<void> => {
+  //
+  // Returns TRUE when this piece's edit was SHED by the send gate (did not
+  // land): the caller must then report the whole flush as shed so
+  // draft-stream does not record the full body as delivered while a tail is
+  // stale (review F3). The piece's own tailLastText stays stale too, so the
+  // recovery flush re-attempts exactly the shed piece.
+  const upsertTail = async (
+    ti: number,
+    piece: { text: string; rich: boolean },
+  ): Promise<boolean> => {
     const existingId = tailIds[ti]
     if (existingId != null) {
-      if (tailLastText[ti] === piece.text) return // unchanged — skip the API call
+      if (tailLastText[ti] === piece.text) return false // unchanged — skip the API call
       try {
-        await retry(() => editPiece(existingId, piece, baseOpts), { threadId, chat_id: chatId })
+        const res = await retry(
+          () => editPiece(existingId, piece, baseOpts),
+          editGateOpts(existingId, piecePayload(piece)),
+        )
+        if (isSendGateShed(res)) return true // shed — stale; retried by the recovery flush
         tailLastText[ti] = piece.text
         onEdit?.(existingId, piece.text.length)
       } catch (err) {
@@ -282,10 +376,11 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
           warn?.(
             `stream-controller: tail-piece #${ti + 1} edit parse-entities rejected — retrying same id=${existingId} as plain text (${err instanceof Error ? err.message : String(err)})`,
           )
-          await retry(
+          const res = await retry(
             () => bot.api.editMessageText(chatId, existingId, piece.text, baseOpts),
-            { threadId, chat_id: chatId },
+            editGateOpts(existingId, piece.text),
           )
+          if (isSendGateShed(res)) return true // shed — stale; retried by the recovery flush
           tailLastText[ti] = piece.text
           onEdit?.(existingId, piece.text.length)
         } else {
@@ -296,7 +391,7 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
           )
         }
       }
-      return
+      return false
     }
     // First emission of this tail piece → a fresh follow-up message.
     try {
@@ -324,9 +419,12 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
         )
       }
     }
+    // First-emission SENDS are untagged (critical) — the gate never sheds
+    // them, so this path can only land or fail (handled above).
+    return false
   }
 
-  return createDraftStream(
+  const handle = createDraftStream(
     async (text) => {
       // Render → 1+ cap-respecting pieces. The FIRST piece's message_id anchors
       // the stream (later edits target it); any overflow pieces are parked as
@@ -378,14 +476,26 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
     async (id, text) => {
       const pieces = renderPieces(text)
       const head = pieces[0]
+      // Whether any piece of THIS flush was shed by the gate (did not land).
+      // Decided at the very end — AFTER the tail loop — so a benign anchor
+      // outcome (or even a shed anchor) never starves the tail pieces of
+      // their own upsert attempt (review F1: an anchor whose payload stopped
+      // changing resolves benignly every flush while only the tail grows).
+      let anchorShed = false
       // Edit the anchor message in place with the FIRST piece.
       try {
-        await retry(
-          () => editPiece(id, head, baseOpts),
-          { threadId, chat_id: chatId },
-        )
-        // C2: report the actual head-piece length, not the full body length.
-        onEdit?.(id, head.text.length)
+        const res = await retry(() => editPiece(id, head, baseOpts), editGateOpts(id, piecePayload(head)))
+        if (isSendGateShed(res)) {
+          // Shed by the gate (cosmetic under pressure / an open flood
+          // window) — did NOT land. Benign `undefined` resolutions (gate
+          // no-op drop, robustApiCall's swallowed "message is not modified")
+          // deliberately do NOT take this branch: the payload is already on
+          // screen and the flush proceeds as delivered.
+          anchorShed = true
+        } else {
+          // C2: report the actual head-piece length, not the full body length.
+          onEdit?.(id, head.text.length)
+        }
       } catch (err) {
         if (!literalText && head.rich && isParseEntitiesError(err)) {
           // Edit rejected because the markdown couldn't be parsed — DO NOT
@@ -400,11 +510,12 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
           // contract). For a single-piece stream (common case) this is the
           // whole body; a rare oversize split edits the head piece's body.
           const fallbackBody = pieces.length === 1 ? text : head.text
-          await retry(
+          const res = await retry(
             () => bot.api.editMessageText(chatId, id, fallbackBody, baseOpts),
-            { threadId, chat_id: chatId },
+            editGateOpts(id, fallbackBody),
           )
-          onEdit?.(id, head.text.length)
+          if (isSendGateShed(res)) anchorShed = true
+          else onEdit?.(id, head.text.length)
         } else {
           throw err
         }
@@ -414,10 +525,20 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
       // that only just came into existence) — we never re-send tails already
       // emitted on a prior flush. This is the fix for the duplicate-flood
       // blocker: the previous code re-sent pieces[1..n] as brand-new messages
-      // on each throttled edit tick.
+      // on each throttled edit tick. Runs BEFORE the shed decision below so a
+      // shed (or benign) anchor never starves the tails (review F1).
+      let anyTailShed = false
       for (let pi = 1; pi < pieces.length; pi++) {
-        await upsertTail(pi - 1, pieces[pi])
+        if (await upsertTail(pi - 1, pieces[pi])) anyTailShed = true
       }
+      // Review F3: ANY shed piece — anchor or tail — means this flush did not
+      // fully land. Throw the marker error so draft-stream does not record
+      // the body as delivered (its dedupe would freeze the shed piece
+      // forever) and instead preserves the snapshot for the finalize
+      // re-flush. Pieces that DID land are unaffected on that re-flush: the
+      // gate's no-op skip drops their identical payloads before the API, and
+      // landed tails short-circuit on tailLastText.
+      if (anchorShed || anyTailShed) throw makeDraftEditShedError(id)
     },
     {
       ...(throttleMs != null ? { throttleMs } : {}),
@@ -429,4 +550,6 @@ export function createStreamController(cfg: StreamControllerConfig): DraftStream
       chatId,
     },
   )
+  handleRef = handle
+  return handle
 }

package/telegram-plugin/stream-reply-handler.ts

@@ -516,10 +516,20 @@ export async function handleStreamReply(
     state.activeDraftStreams.set(sKey, stream)
   }
 
-  await stream.update(effectiveText)
+  if (!done) {
+    // Intermediate snapshot — an ordinary throttled draft update.
+    await stream.update(effectiveText)
+  }
 
   if (done) {
-    await stream.finalize()
+    // #3110: route the FINAL text through finalize(text) so the flush that
+    // renders the completed answer runs with the stream already final —
+    // stream-controller then classifies that edit `critical` for the send
+    // gate (never shed; fails fast with a structured FLOOD_WAIT_ACTIVE on a
+    // long flood window) while intermediate draft edits stay `cosmetic`
+    // (sheddable). The previous update()-then-finalize() pair flushed the
+    // final text inside update(), i.e. as an ordinary sheddable draft edit.
+    await stream.finalize(effectiveText)
     state.activeDraftStreams.delete(sKey)
     // #1713: stream_reply done=true is a NON-EVENT for the status
     // reaction. The reaction reflects current turn activity, not

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/bot-api.harness.ts

@@ -84,7 +84,11 @@ export function createMockBot(startMessageId = 500): MockBot {
   const api: MockBotApi = {
     sendMessage: vi.fn(async () => ({ message_id: state.nextMessageId++ })),
     sendRichMessage: vi.fn(async () => ({ message_id: state.nextMessageId++ })),
-    editMessageText: vi.fn(async () => undefined),
+    // Faithful to grammy: editMessageText resolves `Message | true`, NEVER
+    // undefined. An `undefined` from the production retry stack means the
+    // send gate shed/skipped the call (#3110) — stream-controller treats it
+    // as not-landed — so the mock default must not be undefined.
+    editMessageText: vi.fn(async () => true as const),
     deleteMessage: vi.fn(async () => true as const),
     setMessageReaction: vi.fn(async () => true as const),
     editMessageReplyMarkup: vi.fn(async () => undefined),
@@ -122,7 +126,8 @@ export function installBotResetHook(bot: MockBot): void {
     bot.api.sendRichMessage.mockImplementation(async () => ({
       message_id: bot.nextMessageId++,
     }))
-    bot.api.editMessageText.mockImplementation(async () => undefined)
+    // Faithful to grammy: `Message | true`, never undefined (see above).
+    bot.api.editMessageText.mockImplementation(async () => true as const)
     bot.api.deleteMessage.mockImplementation(async () => true as const)
     bot.api.setMessageReaction.mockImplementation(async () => true as const)
     bot.api.editMessageReplyMarkup.mockImplementation(async () => undefined)

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', () => {

package/telegram-plugin/tests/draft-stream.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
-import { createDraftStream } from '../draft-stream.js'
+import { createDraftStream, makeDraftEditShedError } from '../draft-stream.js'
 
 interface MockTelegram {
   send: (text: string) => Promise<number>
@@ -137,6 +137,115 @@ describe('createDraftStream', () => {
     expect(stream.isFinal()).toBe(true)
   })
 
+  it('finalize(finalText) flushes the supplied snapshot with the stream already final (#3110)', async () => {
+    const m = makeMock()
+    // Capture what isFinal() reads AT EDIT TIME — the transport layer
+    // (stream-controller) classifies the send-gate priority from exactly
+    // this signal, so the final snapshot MUST flush with final=true.
+    const finalAtEdit: boolean[] = []
+    const stream = createDraftStream(
+      m.send,
+      async (id, text) => {
+        finalAtEdit.push(stream.isFinal())
+        await m.edit(id, text)
+      },
+      { throttleMs: 1000 },
+    )
+
+    void stream.update('initial')
+    await microtaskFlush()
+    expect(m.sendCalls.length).toBe(1)
+
+    // A stale draft is pending; finalize(text) supersedes it (last-write-wins).
+    void stream.update('stale draft')
+    await microtaskFlush()
+    await stream.finalize('the completed answer')
+
+    expect(m.editCalls.length).toBe(1)
+    expect(m.editCalls[0].text).toBe('the completed answer')
+    expect(finalAtEdit).toEqual([true])
+    expect(stream.isFinal()).toBe(true)
+  })
+
+  it('a shed flush preserves the snapshot; argument-less finalize() re-delivers it (#3110 F2)', async () => {
+    const m = makeMock()
+    let shedNext = true
+    const stream = createDraftStream(
+      m.send,
+      async (id, text) => {
+        if (shedNext) {
+          shedNext = false
+          throw makeDraftEditShedError(id)
+        }
+        await m.edit(id, text)
+      },
+      { throttleMs: 1000 },
+    )
+
+    void stream.update('v1')
+    await microtaskFlush()
+    expect(m.sendCalls.length).toBe(1)
+
+    void stream.update('v2 — shed by the gate')
+    vi.advanceTimersByTime(1000)
+    await microtaskFlush()
+    // The edit was shed: nothing landed, and the snapshot must NOT be
+    // recorded as sent.
+    expect(m.editCalls.length).toBe(0)
+
+    // The gateway's cleanup paths finalize with NO argument — the shed
+    // snapshot must be re-flushed as the stream's final state, not lost.
+    await stream.finalize()
+    expect(m.editCalls.length).toBe(1)
+    expect(m.editCalls[0].text).toBe('v2 — shed by the gate')
+  })
+
+  it('a newer landed flush supersedes an earlier shed snapshot (no stale resurrect)', async () => {
+    const m = makeMock()
+    let shedNext = true
+    const stream = createDraftStream(
+      m.send,
+      async (id, text) => {
+        if (shedNext) {
+          shedNext = false
+          throw makeDraftEditShedError(id)
+        }
+        await m.edit(id, text)
+      },
+      { throttleMs: 1000 },
+    )
+
+    void stream.update('v1')
+    await microtaskFlush()
+    void stream.update('v2 — shed')
+    vi.advanceTimersByTime(1000)
+    await microtaskFlush()
+    expect(m.editCalls.length).toBe(0)
+
+    // A NEWER snapshot lands normally — the shed one is now stale.
+    void stream.update('v3 — landed')
+    vi.advanceTimersByTime(1000)
+    await microtaskFlush()
+    expect(m.editCalls.map((c) => c.text)).toEqual(['v3 — landed'])
+
+    // finalize() must NOT resurrect the superseded shed snapshot.
+    await stream.finalize()
+    expect(m.editCalls.map((c) => c.text)).toEqual(['v3 — landed'])
+  })
+
+  it('finalize(finalText) still dedupes against text that actually landed', async () => {
+    const m = makeMock()
+    const stream = createDraftStream(m.send, m.edit, { throttleMs: 1000 })
+
+    void stream.update('the answer')
+    await microtaskFlush()
+    expect(m.sendCalls.length).toBe(1)
+
+    // Same text again as the final snapshot → already on screen, no edit.
+    await stream.finalize('the answer')
+    expect(m.editCalls.length).toBe(0)
+  })
+
   it('updates after finalize are silently dropped', async () => {
     const m = makeMock()
     const stream = createDraftStream(m.send, m.edit, { throttleMs: 1000 })

package/telegram-plugin/tests/effort-command.test.ts

@@ -107,7 +107,7 @@ describe("effort-command: handler", () => {
     const { deps } = makeDeps({ getConfiguredEffort: () => "medium" });
     const r = await handleEffortCommand({ kind: "show" }, deps);
     expect(r.text).toContain("medium");
-    expect(r.text).toMatch(/persists across restarts and deploys/);
+    expect(r.text).toMatch(/lasts until the agent’s next restart/);
   });
 
   it("show falls back to low when effort is unreadable", async () => {
@@ -121,7 +121,7 @@ describe("effort-command: handler", () => {
     const r = await handleEffortCommand({ kind: "set", level: "high" }, deps);
     expect(calls).toEqual([{ agent: "carrie", level: "high" }]);
     expect(r.text).toContain("Set effort level to high");
-    expect(r.text).toMatch(/persists across restarts and deploys/);
+    expect(r.text).toMatch(/lasts until the agent’s next restart/);
   });
 
   it("set notes the re-read cost when a confirmation was needed", async () => {
@@ -249,9 +249,9 @@ describe("effort-command: /effort default (#3039)", () => {
     expect(marked?.text).toBe("✅ max");
   });
 
-  it("help text advertises /effort default and the sticky contract", async () => {
+  it("help text advertises /effort default and the session-only contract", async () => {
     const r = await handleEffortCommand({ kind: "help" }, makeDeps().deps);
     expect(r.text).toContain("/effort default");
-    expect(r.text).toContain("persists across restarts and deploys");
+    expect(r.text).toContain("lasts until the agent’s next restart");
   });
 });

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

@@ -122,6 +122,45 @@ describe('createFleetFallbackResumeGate — staleness guard', () => {
   })
 })
 
+describe('createFleetFallbackResumeGate — peek / arm seams (tier-downgrade LOW-3 + LOW-9a)', () => {
+  it('peek() evaluates the verdict WITHOUT arming the single-flight latch', () => {
+    const clk = fakeClock()
+    const gate = createFleetFallbackResumeGate({ nowFn: clk.now })
+    // Peeking 'resume' must not record an arm time — a following peek/decide is
+    // still 'resume'. This is what lets the gateway do a fallible carrier write
+    // between the peek and the arm without leaving a phantom armed latch (LOW-3).
+    expect(gate.peek(clk.now())).toBe('resume')
+    expect(gate.inspect().lastResumedAtMs).toBe(Number.NEGATIVE_INFINITY)
+    expect(gate.peek(clk.now())).toBe('resume')
+    // The real restart never fires (write threw) → nothing armed → a genuine
+    // later swap still resumes.
+    expect(gate.decide(clk.now())).toBe('resume')
+  })
+
+  it('arm() commits the single-flight window so a later peek reports skip-inflight (LOW-9a)', () => {
+    const clk = fakeClock()
+    const gate = createFleetFallbackResumeGate({ nowFn: clk.now, singleFlightMs: 60_000 })
+    // Turn 1: peek 'resume' → do the write → arm.
+    expect(gate.peek(clk.now())).toBe('resume')
+    gate.arm()
+    // Turn 2 (concurrent, same process, 1s later): a resume restart is already
+    // armed, so peek reports skip-inflight → the gateway suppresses the give-up.
+    clk.advance(1_000)
+    expect(gate.peek(clk.now())).toBe('skip-inflight')
+  })
+
+  it('peek(skip-inflight/skip-stale) never arms; only arm() records the window', () => {
+    const clk = fakeClock()
+    const gate = createFleetFallbackResumeGate({ nowFn: clk.now })
+    // A stale peek must not arm (mirrors decide()'s stale behaviour).
+    expect(gate.peek(clk.now() - (DEFAULT_RESUME_MAX_AGE_MS + 1))).toBe('skip-stale')
+    expect(gate.inspect().lastResumedAtMs).toBe(Number.NEGATIVE_INFINITY)
+    // decide() remains equivalent to peek+arm-on-resume.
+    expect(gate.decide(clk.now())).toBe('resume')
+    expect(gate.peek(clk.now())).toBe('skip-inflight')
+  })
+})
+
 describe('createFleetFallbackResumeGate — reset / inspect seams', () => {
   it('reset() clears the single-flight arm', () => {
     const clk = fakeClock()

package/telegram-plugin/tests/flood-windows-persistence.test.ts

@@ -14,7 +14,7 @@ import {
   FLOOD_STATE_MODE,
   FLOOD_WINDOWS_CORRUPT_SUPPRESS_MS,
 } from '../flood-circuit-breaker.js'
-import { createSendGate, type Clock } from '../send-gate.js'
+import { createSendGate, SEND_GATE_SHED, type Clock } from '../send-gate.js'
 
 /**
  * #3084 PR 2 — restart-proof SCOPED flood windows (part3-design §7). Verifies
@@ -103,9 +103,10 @@ describe('#3084 scoped flood-window persistence', () => {
       ),
     ).rejects.toBe(floodErr)
 
-    // The window is on disk.
+    // The window is on disk. #3111: a chat-bound 429 persists ONLY the chat
+    // scope — no coincident `global` window that would suppress unrelated chats.
     const persisted = readFloodWindows(winPath, 0)
-    expect(persisted.map((w) => w.scopeKey).sort()).toEqual(['chat:7', 'global'])
+    expect(persisted.map((w) => w.scopeKey).sort()).toEqual(['chat:7'])
 
     // Gate 2 (simulated restart): built BEFORE any outbound call from the
     // persisted windows. A cosmetic send on chat:7 must still shed.
@@ -119,7 +120,7 @@ describe('#3084 scoped flood-window persistence', () => {
       chat_id: '7',
       priorityClass: 'cosmetic',
     })
-    expect(res).toBeUndefined()
+    expect(res).toBe(SEND_GATE_SHED) // shed sentinel (#3110 F1)
     expect(gate2.stats().global.shed).toBe(1)
 
     // And a critical into the still-long window fails fast — restart did not