switchroom 0.19.30 → 0.19.32

package/telegram-plugin/registry/turns-schema.ts

@@ -240,7 +240,27 @@ const PHASE4_MIGRATIONS = [
 
 function applySchema(db: SqliteDatabase): void {
   db.exec('PRAGMA journal_mode = WAL')
-  db.exec('PRAGMA synchronous = NORMAL')
+  // FULL, not NORMAL. This registry is the crash-recovery ledger: the turn row
+  // is what tells the boot-time resume protocol that a turn was in flight when
+  // the process died. Under WAL, `synchronous = NORMAL` deliberately does NOT
+  // fsync the WAL on commit — it syncs only at checkpoint — so a container kill
+  // is survived but a HOST POWER CUT can lose the last commits, including the
+  // whole turn row. The interrupted turn then becomes invisible to resume:
+  // silently unrecoverable, which is exactly the case this ledger exists for.
+  //
+  // Cost is bounded and measured, not assumed: on this fleet's ext4/NVMe volume
+  // a FULL commit costs ~0.87ms mean (p99 1.7ms) vs ~0.011ms at NORMAL, i.e. a
+  // ~1150 commits/s ceiling. Steady state is ~330 commits/day, and the hot path
+  // is `bumpSubagentActivity` (subagents-schema.ts) at ~1Hz per running worker
+  // — ~4 commits/s during fan-out, a ~0.35% duty cycle.
+  //
+  // `synchronous` is per-connection and NOT persisted in the DB file (unlike
+  // `journal_mode`), so it binds only connections that set it. The PreToolUse
+  // subagent tracker (`hooks/subagent-tracker-pretool.mjs`) opens this same
+  // registry.db without the pragma and has therefore been running at SQLite's
+  // default FULL on the tool-call hot path since it shipped; the gateway's
+  // NORMAL was the outlier.
+  db.exec('PRAGMA synchronous = FULL')
   // Concurrency: multiple writers contend on this registry (the PreToolUse
   // subagent-tracker hook, the gateway's subagent-watcher backfill, the turns
   // writer) — especially when several sub-agents dispatch at once. Without a

package/telegram-plugin/retry-api-call.ts

@@ -92,13 +92,49 @@ export interface RetryCallOpts {
   priorityClass?: 'critical' | 'useful' | 'cosmetic'
 }
 
+/**
+ * The three benign Telegram 400s this policy swallows (contract table above).
+ */
+export type BenignTelegram400Kind = 'not_modified' | 'message_not_found' | 'delete_not_found'
+
+/**
+ * Single source of truth for "is this Telegram 400 a benign no-op?".
+ *
+ * Benign here means exactly what the retry policy already treats as a
+ * non-event: the edit was a no-op because the content is identical, or the
+ * target message vanished before the edit/delete landed. Both are
+ * high-volume on a healthy agent (every coalesced card repaint can produce
+ * one) and neither means anything is wrong — so any surface that reports
+ * Telegram failures needs to tell them apart from a real rejection WITHOUT
+ * maintaining a second copy of the description list (#3927). The retry
+ * policy's own swallow branches call this, so there is one list.
+ *
+ * Returns the benign kind, or `null` for everything else — including 429,
+ * 403, and any 400 not on this deliberately narrow list. A new benign
+ * description belongs here, not in a caller.
+ */
+export function classifyBenignTelegram400(
+  errorCode: number | undefined,
+  description: string | undefined,
+): BenignTelegram400Kind | null {
+  if (errorCode !== 400) return null
+  const desc = (description ?? '').toLowerCase()
+  // "message is not modified" / "message was not modified" — Telegram's
+  // no-op-on-equal-text.
+  if (desc.includes('not modified')) return 'not_modified'
+  // "message to edit/delete not found" — the target vanished.
+  if (desc.includes('message to edit not found')) return 'message_not_found'
+  if (desc.includes('message to delete not found')) return 'delete_not_found'
+  return null
+}
+
 export interface RetryObserver {
   /** Fires just before sleeping for a retry. */
   onRetry?(info: { attempt: number; reason: 'flood_wait' | 'network'; delayMs: number }): void
   /** Fires when max retries is reached and the wrapper gives up. */
   onGiveUp?(info: { attempts: number; error: unknown }): void
   /** Fires for each benign error we swallowed (not-modified, not-found). */
-  onBenign?(info: { kind: 'not_modified' | 'message_not_found' | 'delete_not_found' }): void
+  onBenign?(info: { kind: BenignTelegram400Kind }): void
 }
 
 export interface RetryApiCallConfig {
@@ -399,26 +435,15 @@ export function createRetryApiCall(
           continue
         }
 
-        // Swallow "message is not modified" — Telegram's no-op-on-equal-text.
-        if (
-          isGrammyErr &&
-          (err as GrammyError).error_code === 400 &&
-          desc.includes('not modified')
-        ) {
-          observer?.onBenign?.({ kind: 'not_modified' })
-          return undefined as unknown as T
-        }
-
-        // Swallow "message to edit/delete not found" — target vanished.
-        if (
-          isGrammyErr &&
-          (err as GrammyError).error_code === 400 &&
-          (desc.includes('message to edit not found') ||
-            desc.includes('message to delete not found'))
-        ) {
-          observer?.onBenign?.({
-            kind: desc.includes('edit') ? 'message_not_found' : 'delete_not_found',
-          })
+        // Swallow the benign 400s — "message is not modified" (Telegram's
+        // no-op-on-equal-text) and "message to edit/delete not found" (the
+        // target vanished). Classification lives in `classifyBenignTelegram400`
+        // so the tg-post logger reports the same family identically (#3927).
+        const benignKind = isGrammyErr
+          ? classifyBenignTelegram400((err as GrammyError).error_code, desc)
+          : null
+        if (benignKind !== null) {
+          observer?.onBenign?.({ kind: benignKind })
           return undefined as unknown as T
         }
 

package/telegram-plugin/session-tail.ts

@@ -93,6 +93,13 @@ export function findActiveSessionFile(projectsDir: string): string | null {
 export type SessionEvent =
   | { kind: 'enqueue'; chatId: string | null; messageId: string | null; threadId: string | null; rawContent: string; isSync?: boolean }
   | { kind: 'dequeue' }
+  // #3927 — `queue-operation` op `remove`: the queued item was folded into the
+  // ALREADY-RUNNING turn as a `queued_command` attachment rather than drained
+  // into a new turn. It is the OTHER terminal of an `enqueue` (the CLI writes
+  // exactly one of `dequeue` / `remove` per enqueue), and unlike `dequeue` it
+  // REPLAYS the enqueue's `content` byte-for-byte — which is what lets the
+  // gateway discard the right parked turn-start by identity.
+  | { kind: 'queue_remove'; rawContent: string }
   | { kind: 'thinking' }
   // Live model in use for the MAIN session, extracted from `message.model` on
   // each `type:"assistant"` transcript line (the exact model that served that
@@ -566,6 +573,12 @@ export function projectTranscriptLine(line: string): SessionEvent[] {
     if (op === 'dequeue') {
       return [{ kind: 'dequeue' }]
     }
+    // #3927 — the enqueue's OTHER terminal. Previously dropped, which left the
+    // gateway unable to tell "queued message folded into the running turn"
+    // (`remove`) from "queue drained into a new turn" (`dequeue`).
+    if (op === 'remove') {
+      return [{ kind: 'queue_remove', rawContent: (obj.content as string | undefined) ?? '' }]
+    }
     return []
   }
 

package/telegram-plugin/shared/bot-runtime.ts

@@ -28,10 +28,10 @@ import { execFileSync, spawnSync } from 'child_process'
 import { createHash } from 'crypto'
 import { AsyncLocalStorage } from 'async_hooks'
 import { clearStaleTelegramPollingState } from '../startup-reset.js'
-import { createRetryApiCall } from '../retry-api-call.js'
+import { createRetryApiCall, classifyBenignTelegram400 } from '../retry-api-call.js'
 import { makeFloodWaitRecorder, makeFloodWaitProbe } from '../flood-circuit-breaker.js'
 import { RICH_MESSAGE_MAX_CHARS } from '../format.js'
-import { shouldEmitTgPost } from './gw-trace-gate.js'
+import { shouldEmitTgPost, type TgPostStatus } from './gw-trace-gate.js'
 import { guardAccidentalFormatting } from '../rich-send.js'
 
 // ─── tg-post tag plumbing ─────────────────────────────────────────────────
@@ -80,6 +80,17 @@ function formatTgPostTags(tags: TgPostTags | undefined): string {
 
 // ─── tg-post observability transformer ────────────────────────────────────
 
+/**
+ * Sanitise a Telegram error description for single-line log output —
+ * collapse whitespace, strip newlines, cap at 80 chars, `-` when absent.
+ * PII-safe: Telegram error descriptions are server-generated and don't
+ * echo the request body.
+ */
+function shortDesc(raw: string | undefined): string {
+  if (!raw) return '-'
+  return raw.replace(/\s+/g, ' ').slice(0, 80).replace(/[\r\n]/g, ' ') || '-'
+}
+
 /**
  * Installs an API transformer on the bot that emits one stderr line per
  * outbound Telegram Bot API POST. This is the single catchment point for
@@ -91,7 +102,30 @@ function formatTgPostTags(tags: TgPostTags | undefined): string {
  *
  * Log shape (one line per POST, on both success and failure):
  *
- *   tg-post method=<m> chat=<id> thread=<id|-> parse_mode=<HTML|MarkdownV2|none> bytes=<n> hash=<sha1-12> status=<ok|err> err=<class-or--> code=<http-or--> desc=<short|-->
+ *   tg-post method=<m> chat=<id> thread=<id|-> parse_mode=<HTML|MarkdownV2|none> bytes=<n> hash=<sha1-12> status=<ok|benign|err> err=<class-or--> code=<http-or--> desc=<short|-->
+ *
+ * TRUTHFULNESS (#3927): grammY resolves the transformer chain with the raw
+ * `ApiResponse`, and only converts `{ok:false}` into a thrown `GrammyError`
+ * AFTER the chain returns — verified in the pinned grammy 1.44.0,
+ * `out/core/client.js:95-100`:
+ *
+ *     const data = await this.call(method, payload, signal)   // chain
+ *     if (data.ok) return data.result
+ *     else throw toGrammyError(data, method, payload)          // OUTSIDE
+ *
+ * So EVERY Telegram-level rejection (429 flood-wait, 400, 403) arrives here
+ * as a RESOLVED response, and the `catch` below only ever sees transport
+ * (`HttpError`) failures. Before this was fixed the logger reported every
+ * one of them as `status=ok err=- code=- desc=-` — a rate-limited
+ * `unpinAllChatMessages` logged as SUCCESS 3ms before the retry policy
+ * logged `429 rate limited, waiting 3s`. We therefore inspect the resolved
+ * body and report `status=err err=telegram_<code>` from it.
+ *
+ * The narrow set of benign 400s the retry policy already swallows
+ * ("message is not modified", "message to edit/delete not found" —
+ * classified by the shared `classifyBenignTelegram400`) gets `status=benign`
+ * instead, so promoting real rejections out of `status=ok` doesn't bury
+ * `grep status=err` under high-volume card-repaint no-ops.
  *
  * Body content is never logged — only its length and a 12-char sha1 prefix
  * so we can recognise repeated identical sends without leaking PII. The
@@ -115,16 +149,34 @@ export function installTgPostLogger(bot: Bot): void {
       ? createHash('sha1').update(text).digest('hex').slice(0, 12)
       : '-'
     const tagSuffix = formatTgPostTags(_getTgPostTags())
-    try {
-      const res = await prev(method, payload, signal)
+    const emit = (status: TgPostStatus, errClass: string, code: string, desc: string) => {
       // #3025: suppress zero-signal per-poll heartbeats (getUpdates/getMe
       // status=ok, one line per ~30s long-poll tick) unless the operator
       // set SWITCHROOM_GW_TRACE. Errors and all other methods still log.
-      if (shouldEmitTgPost(method, 'ok')) {
-        process.stderr.write(
-          `tg-post method=${method} chat=${chat} thread=${thread} parse_mode=${parseMode} bytes=${bytes} hash=${hash} status=ok err=- code=- desc=-${tagSuffix}\n`,
+      if (!shouldEmitTgPost(method, status)) return
+      process.stderr.write(
+        `tg-post method=${method} chat=${chat} thread=${thread} parse_mode=${parseMode} bytes=${bytes} hash=${hash} status=${status} err=${errClass} code=${code} desc=${desc}${tagSuffix}\n`,
+      )
+    }
+    try {
+      const res = await prev(method, payload, signal)
+      // A RESOLVED response can still be a Telegram-level rejection — grammy
+      // converts `{ok:false}` to a thrown GrammyError only after this chain
+      // returns (see the docblock). Same defensive shape as the edit fuse's
+      // `runObserved` (edit-flood-fuse.ts).
+      const r = res as unknown as { ok?: boolean; error_code?: number; description?: string }
+      if (r != null && typeof r === 'object' && r.ok === false) {
+        const code = r.error_code
+        const benign = classifyBenignTelegram400(code, r.description)
+        emit(
+          benign !== null ? 'benign' : 'err',
+          `telegram_${code ?? 'unknown'}`,
+          code != null ? String(code) : '-',
+          shortDesc(r.description),
         )
+        return res
       }
+      emit('ok', '-', '-', '-')
       return res
     } catch (err) {
       const errClass = err instanceof GrammyError
@@ -134,15 +186,7 @@ export function installTgPostLogger(bot: Bot): void {
       const rawDesc = err instanceof GrammyError
         ? (err as GrammyError).description
         : (err instanceof Error ? err.message : '')
-      // Sanitise the description for single-line log output — collapse
-      // whitespace, strip newlines, cap at 80 chars. PII-safe: Telegram
-      // error descriptions are server-generated and don't echo body.
-      const desc = rawDesc
-        ? rawDesc.replace(/\s+/g, ' ').slice(0, 80).replace(/[\r\n]/g, ' ') || '-'
-        : '-'
-      process.stderr.write(
-        `tg-post method=${method} chat=${chat} thread=${thread} parse_mode=${parseMode} bytes=${bytes} hash=${hash} status=err err=${errClass} code=${code} desc=${desc}${tagSuffix}\n`,
-      )
+      emit('err', errClass, code, shortDesc(rawDesc))
       throw err
     }
   })

package/telegram-plugin/shared/gw-trace-gate.ts

@@ -57,6 +57,20 @@ export const gwTraceVerbose: boolean = computeGwTraceVerbose(
  */
 const ZERO_SIGNAL_POLL_METHODS = new Set(['getUpdates', 'getMe'])
 
+/**
+ * The status tiers a `tg-post` line can carry.
+ *
+ * `benign` (#3927) is a REJECTED call that is nonetheless a non-event —
+ * the narrow set of 400s the retry policy already swallows ("message is
+ * not modified", "message to edit/delete not found"), classified by
+ * `classifyBenignTelegram400`. It exists so that promoting resolved
+ * `ok:false` responses out of `status=ok` doesn't drown the newly-truthful
+ * `status=err` signal in high-volume card-repaint no-ops: `grep status=err`
+ * stays a list of real failures, and the benign lines are still there,
+ * honestly labelled, for anyone who wants them.
+ */
+export type TgPostStatus = 'ok' | 'benign' | 'err'
+
 /**
  * Decide whether a `tg-post` line should be written.
  *
@@ -66,11 +80,13 @@ const ZERO_SIGNAL_POLL_METHODS = new Set(['getUpdates', 'getMe'])
  * Always emitted:
  *   - any `status=err` (real failures — the whole point of the log),
  *   - every other method's `ok` line (sendMessage/editMessageText/... are
- *     genuine outbound observability, #656/#657).
+ *     genuine outbound observability, #656/#657),
+ *   - `status=benign` on any non-poll method — same volume as the
+ *     `status=ok` line it replaces, just no longer mislabelled as success.
  */
 export function shouldEmitTgPost(
   method: string,
-  status: 'ok' | 'err',
+  status: TgPostStatus,
   verbose: boolean = gwTraceVerbose,
 ): boolean {
   if (verbose) return true

package/telegram-plugin/tests/activity-card-wiring.test.ts

@@ -119,17 +119,17 @@ describe('activity-card durability wiring', () => {
 
   it('the boot reaper runs ONLY after the startup mutex is won (never at import time)', () => {
     // #3026: the reaper is now invoked via the mutex-gated orchestrator
-    // runBootPinCleanupAndDmSweep() (which runs it alongside
-    // statusPinBootCleanup + queuedCardBootReaper, then runs the DM
-    // stale-pin sweep). Invariant unchanged: reachable only post-lock.
+    // runBootPinCleanupAndStalePinSweep() (which runs it alongside
+    // statusPinBootCleanup + queuedCardBootReaper, then runs the stale-pin
+    // stack sweep). Invariant unchanged: reachable only post-lock.
     // (1) The orchestrator runs the reaper. Since the #3664 S2 salvage the
     // steps are INJECTED into runBootPinSweepSteps (each individually
-    // absorbed, so a throwing reaper cannot strand the DM sweep behind it)
+    // absorbed, so a throwing reaper cannot strand the sweep behind it)
     // instead of being awaited inline — so the marker is the step binding.
     const orchestrator = between(
       gatewaySrc,
-      'function runBootPinCleanupAndDmSweep()',
-      'dmPinSweepEligible = true',
+      'function runBootPinCleanupAndStalePinSweep()',
+      'stalePinSweepEligible = true',
     )
     expect(orchestrator).toMatch(/activityCardReaper: activityCardBootReaper,/)
     // (2) Both orchestrator invocation sites (mutex-won + mutex-fallback)
@@ -146,7 +146,7 @@ describe('activity-card durability wiring', () => {
     // statusPinBootCleanup documents.
     const beforeMain = gatewaySrc.split('await acquireStartupLock({')[0] ?? ''
     expect(beforeMain).not.toMatch(/^\s*void activityCardBootReaper\(\)/m)
-    expect(beforeMain).not.toMatch(/^\s*void runBootPinCleanupAndDmSweep\(\)/m)
+    expect(beforeMain).not.toMatch(/^\s*void runBootPinCleanupAndStalePinSweep\(\)/m)
     expect(beforeMain).not.toMatch(/^\s*bootPinSweepGate\.(arm|botReady)\(\)/m)
   })
 

package/telegram-plugin/tests/activity-drain-fuse-drop-not-failure.test.ts

@@ -0,0 +1,324 @@
+/**
+ * The edit-flood fuse's DELIBERATE drops must not be reported as failures.
+ *
+ * ── The defect ────────────────────────────────────────────────────────────
+ * `edit-flood-fuse.ts` is installed as a grammY **transformer**
+ * (`bot.api.config.use`, `installEditFloodFuse`). A transformer's return
+ * contract is the raw `ApiResponse` ENVELOPE, and grammY's `Api.callApi`
+ * unwraps it:
+ *
+ * ```js
+ * const data = await this.call(method, payload, signal)
+ * if (data.ok) return data.result
+ * else throw toGrammyError(data, method, payload)
+ * ```
+ * (grammy `out/core/client.js`)
+ *
+ * The fuse resolved a dropped call with the bare `true` — the *result*, with no
+ * envelope. `(true).ok` is `undefined`, so EVERY intentional fuse drop took the
+ * `else` branch and was raised as
+ * `GrammyError: Call to 'editMessageText' failed! (undefined: undefined)`.
+ *
+ * Downstream, `narrative-lane.ts`'s activity-summary drain caught that, found
+ * nothing in its `isTransport` allowlist matching, incremented
+ * `turn.activityDrainFailures` and wrote a `activity-summary drain failed:` line
+ * to stderr. `activityDrainFailures` is what flags a turn DEGRADED at turn-end,
+ * so a healthy turn whose progress card was correctly rate-limited was reported
+ * as broken — observed reaching `failures=8` on a single turn.
+ *
+ * ── Why the fix is the envelope, not an `isTransport` entry ───────────────
+ * Classifying the string in `isTransport` would paper over a real contract
+ * violation that ALSO corrupts every other caller of a fused API method (each
+ * one sees a synthetic transport error for a benign no-op). Restoring the
+ * envelope is the durable fix; `isTransport` then needs no new entry at all,
+ * because nothing is thrown.
+ *
+ * ── R1 on the per-MESSAGE tier ───────────────────────────────────────────
+ * The second describe covers the other half: a card must never freeze mid-step
+ * because a frame was shed. `awaitRoom`'s `dropGuard` (R1: "only drop while
+ * something NEWER for this message is still in flight to repaint it") was wired
+ * into the two per-chat tiers but NOT the per-message tier, which passed
+ * `dropGuard: undefined` — read as "drop unconditionally at the deadline". A
+ * lone terminal `finalize`, which by definition has nothing newer coming, was
+ * therefore droppable there regardless of its priority class, freezing the card
+ * on "→ in-progress".
+ */
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { tmpdir } from 'node:os'
+import { GrammyError } from 'grammy'
+
+import { createEditFloodFuse, type EditFloodFuseConfig } from '../edit-flood-fuse.js'
+import { withOutboundClass, type OutboundClass } from '../outbound-class.js'
+import { createNarrativeLane } from '../gateway/narrative-lane.js'
+import type { CurrentTurn, NarrativeLaneDeps } from '../gateway/gateway.js'
+
+const CHAT = '1001'
+
+/**
+ * grammY's `Api.callApi`, verbatim in behaviour: run the transformer chain,
+ * unwrap `ok:true`, throw `GrammyError` otherwise. This is the seam the defect
+ * lived in, so the harness must model it rather than assume the fuse's return
+ * value reaches the caller untouched (which is what the pre-existing fuse tests
+ * assumed — they hand `next` a bare `true` and never unwrap, which is exactly
+ * why the bug survived them).
+ */
+function makeFusedApi(config: EditFloodFuseConfig) {
+  const fuse = createEditFloodFuse(config)
+  const landed: Array<{ method: string; message_id?: number; text: string | null }> = []
+  let nextId = 3000
+
+  const callApi = async (method: string, payload: Record<string, unknown>, run: () => unknown) => {
+    const data = (await fuse.apply(method, payload, async () => ({ ok: true, result: run() }))) as {
+      ok?: boolean
+      result?: unknown
+    }
+    if (data.ok === true) return data.result
+    throw new GrammyError(`Call to '${method}' failed!`, data as never, method, payload as never)
+  }
+
+  const api = {
+    sendRichMessage: (c: string, b: { markdown: string }) => {
+      const id = ++nextId
+      return callApi('sendRichMessage', { chat_id: c }, () => {
+        landed.push({ method: 'sendRichMessage', message_id: id, text: b.markdown })
+        return { message_id: id }
+      }) as Promise<{ message_id: number }>
+    },
+    editMessageText: (c: string, m: number, b: { markdown: string }) =>
+      callApi('editMessageText', { chat_id: c, message_id: m }, () => {
+        landed.push({ method: 'editMessageText', message_id: m, text: b.markdown })
+        return true
+      }),
+    deleteMessage: (c: string, m: number) =>
+      callApi('deleteMessage', { chat_id: c, message_id: m }, () => {
+        landed.push({ method: 'deleteMessage', message_id: m, text: null })
+        return true
+      }),
+  }
+  return { api, landed, fuse }
+}
+
+/**
+ * The real `createNarrativeLane`, wired to a bot whose API traverses the real
+ * fuse. `robustApiCall` stands in for the production chain
+ * `robustApiCall → sendGate.gate → withOutboundClass → fn`: the only part of it
+ * the fuse can observe is the published outbound class, so the stub publishes it
+ * for real via `withOutboundClass` and calls straight through.
+ */
+function makeFusedLane(config: EditFloodFuseConfig) {
+  const { api, landed, fuse } = makeFusedApi(config)
+  const submitted: Array<{ verb?: string; priorityClass?: OutboundClass }> = []
+  const noop = () => {}
+  const fakeEA = {
+    mayDrain: () => true,
+    openOrEditCard: (_p: string, fn: () => void) => fn(),
+    finalizeCard: (fn: () => void) => fn(),
+    markSubstantiveFinalDelivered: (fn: () => void) => fn(),
+  }
+  const deps = {
+    ACTIVITY_CARD_STORE_PATH: `${tmpdir()}/lane-fuse-drop-activity-cards.json`,
+    CLEAR_STATUS_ON_COMPLETION: false,
+    FEED_HEARTBEAT_ENABLED: false,
+    FEED_HEARTBEAT_MIN_STALE_MS: 6000,
+    FEED_LIVENESS_OPEN_ENABLED: false,
+    FEED_LIVENESS_OPEN_MS: 5000,
+    PIN_STATUS_WHILE_WORKING: false,
+    POST_ANSWER_LIVENESS_STALE_MS: 90000,
+    STATIC: false,
+    activeDraftStreams: new Map(),
+    activityCardPersistEnabled: false,
+    activityCardStoreFs: {
+      readFileSync: () => '',
+      writeFileSync: noop,
+      mkdirSync: noop,
+      renameSync: noop,
+      unlinkSync: noop,
+    },
+    bot: { api },
+    cardDrainGate: (_t: unknown, _ea: unknown, run: () => void) => run(),
+    currentTurnMap: { get: () => null, byKey: new Map() },
+    earlyLivenessOpenTimers: new Map(),
+    emissionAuthorityFor: () => fakeEA,
+    feedOpenGateDeps: () => ({
+      hasOutboundDeliveredSince: () => false,
+      historyEnabled: false,
+      finalAnswerMinChars: 200,
+    }),
+    getCurrentTurn: () => null,
+    reconcileStatusPin: noop,
+    robustApiCall: (fn: () => Promise<unknown>, opts?: { verb?: string; priorityClass?: OutboundClass }) => {
+      submitted.push({ verb: opts?.verb, priorityClass: opts?.priorityClass })
+      return withOutboundClass(opts?.priorityClass ?? 'critical', fn)
+    },
+    statusKey: (c: string, t?: number | null) => `${c}:${t ?? 'main'}`,
+  } as unknown as NarrativeLaneDeps
+  const lane = createNarrativeLane(deps)
+  return { lane, landed, fuse, submitted }
+}
+
+function makeLaneTurn(lane: ReturnType<typeof createNarrativeLane>): CurrentTurn {
+  const turn = {
+    turnId: 'turn-fuse-drop-1',
+    sessionChatId: CHAT,
+    sessionThreadId: undefined,
+    sourceMessageId: null,
+    registryKey: null,
+    startedAt: Date.now() - 3000,
+    currentModel: null,
+    totalTokens: 0,
+    labeledToolCount: 0,
+    mirrorLines: [] as string[],
+    foregroundSubAgents: new Map<string, string[]>(),
+    activityPendingRender: null as string | null,
+    activityLastSentRender: null as string | null,
+    activityMessageId: null as number | null,
+    activityInFlight: null as Promise<void> | null,
+    activityEverOpened: false,
+    activityDrainFailures: 0,
+    finalAnswerEverDelivered: false,
+    finalAnswerDelivered: false,
+    replyCalled: false,
+    capturedText: [] as string[],
+    lastReplyText: '',
+    answerStream: null,
+    liveness: { recentlyStreaming: () => false, onStreamEvent: () => {}, note: () => {} },
+  } as unknown as CurrentTurn
+  ;(turn as { narrativeGate?: unknown }).narrativeGate = lane.makeNarrativeGate(turn)
+  return turn
+}
+
+const settle = () => new Promise((r) => setTimeout(r, 20))
+
+/**
+ * A fuse tuned so a cosmetic repaint is genuinely DROPPED:
+ *   - one cosmetic edit per message per window, so frame 2+ is over budget;
+ *   - a short defer deadline so the wait ends inside the test;
+ *   - `lateReleaseMaxPerWindow: 0`, i.e. the bounded R1 overshoot budget is
+ *     already spent, which is the state in which a lone cosmetic frame is
+ *     dropped rather than late-released. Without this the fix in the second
+ *     describe would late-release the frame and no drop would occur at all.
+ */
+const DROPPING_FUSE: EditFloodFuseConfig = {
+  perMessageMaxPerWindow: 1,
+  cosmeticPerMessageMaxPerWindow: 1,
+  perMessageWindowMs: 60_000,
+  maxDeferMs: 20,
+  lateReleaseMaxPerWindow: 0,
+}
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('edit-flood fuse — a deliberate drop is not a failure', () => {
+  it('a dropped cosmetic edit RESOLVES through grammY instead of throwing "(undefined: undefined)"', async () => {
+    const { api, fuse } = makeFusedApi(DROPPING_FUSE)
+    const results: unknown[] = []
+    const errors: string[] = []
+    for (let i = 0; i < 3; i++) {
+      await withOutboundClass('cosmetic', () => api.editMessageText(CHAT, 42, { markdown: `frame ${i}` }))
+        .then((r) => results.push(r))
+        .catch((e: unknown) => errors.push((e as Error).message))
+    }
+    // Pre-fix: two of the three surface as
+    // `Call to 'editMessageText' failed! (undefined: undefined)`.
+    expect(errors).toEqual([])
+    // The drop is real — this asserts the fuse actually shed, so the test cannot
+    // pass by simply never exercising the drop path.
+    expect(fuse.stats().dropped).toBeGreaterThan(0)
+    // grammY unwraps `{ok:true, result:true}` to the `true` an edit resolves to.
+    expect(results).toEqual([true, true, true])
+  })
+
+  it('the activity-summary drain records ZERO failures and logs no "drain failed" line', async () => {
+    const stderr = vi.spyOn(process.stderr, 'write').mockImplementation(() => true)
+    const { lane, fuse } = makeFusedLane(DROPPING_FUSE)
+    const turn = makeLaneTurn(lane)
+
+    // Open the card, then repaint it past the cosmetic ceiling so the fuse drops.
+    lane.showNarrativeStep(turn, 'Step one of the work')
+    await turn.activityInFlight
+    for (let i = 2; i <= 6; i++) {
+      lane.showNarrativeStep(turn, `Step ${i} of the work`)
+      await turn.activityInFlight
+      await settle()
+    }
+
+    expect(fuse.stats().dropped + fuse.stats().superseded).toBeGreaterThan(0)
+    // The counter that flags the turn DEGRADED at turn-end. Pre-fix this reached
+    // the number of dropped repaints (observed: 8 on a real turn).
+    expect(turn.activityDrainFailures).toBe(0)
+    const lines = stderr.mock.calls.map((c) => String(c[0]))
+    expect(lines.filter((l) => l.includes('drain failed'))).toEqual([])
+  })
+})
+
+describe('edit-flood fuse — a terminal card render is never shed', () => {
+  it('the lane submits the finalize above `cosmetic`, at a class the fuse will not shed', async () => {
+    // REGRESSION PIN. `useful` and `critical` are the only classes above
+    // `cosmetic` (`outbound-class.ts` / `retry-api-call.ts` `priorityClass`);
+    // the finalize takes `useful` — it may be DEFERRED, but the fuse's
+    // cosmetic-only per-message/per-chat ceilings and the R1 drop path do not
+    // apply to it. Live repaints staying `cosmetic` is correct and unchanged.
+    const { lane, submitted } = makeFusedLane({ enabled: false })
+    const turn = makeLaneTurn(lane)
+    lane.showNarrativeStep(turn, 'Doing the work now')
+    await turn.activityInFlight
+    lane.clearActivitySummary(turn)
+    await settle()
+
+    const drain = submitted.filter((s) => s.verb === 'activity-summary.edit')
+    const finalize = submitted.filter((s) => s.verb === 'activity-summary.finalize')
+    expect(finalize.length).toBeGreaterThanOrEqual(1)
+    for (const f of finalize) expect(f.priorityClass).toBe('useful')
+    // The live repaints are deliberately still sheddable.
+    for (const d of drain) expect(d.priorityClass).toBe('cosmetic')
+  })
+
+  it('the fuse LATE-RELEASES a lone terminal frame at the deadline instead of freezing the card', async () => {
+    // R1 on the per-MESSAGE tier. One `useful` edit fills the per-message
+    // window; the terminal frame that follows is over budget, is the ONLY frame
+    // in flight for its message (nothing newer will ever repaint it), and must
+    // therefore be released late rather than dropped.
+    const { api, landed, fuse } = makeFusedApi({
+      perMessageMaxPerWindow: 1,
+      perMessageWindowMs: 60_000,
+      maxDeferMs: 20,
+    })
+    await withOutboundClass('useful', () => api.editMessageText(CHAT, 77, { markdown: 'live frame' }))
+    // Nothing else is in flight for message 77 — this is the card's last frame.
+    const res = await withOutboundClass('useful', () =>
+      api.editMessageText(CHAT, 77, { markdown: 'TERMINAL ✅ done' }),
+    )
+
+    // Pre-fix this frame was dropped at the deadline (`dropGuard: undefined` on
+    // the per-message tier), so it never reached the API and the card stayed on
+    // "live frame" forever — and, via the envelope defect, the caller saw a
+    // synthetic transport error on top.
+    expect(landed.map((l) => l.text)).toEqual(['live frame', 'TERMINAL ✅ done'])
+    expect(res).toBe(true)
+    expect(fuse.stats().dropped).toBe(0)
+  })
+
+  it('a superseded frame is still dropped — R1 does not disable last-write-wins', async () => {
+    // The guard is a DEADLINE guard only. A genuinely newer frame for the same
+    // message must still kill the older waiter, or the fix would turn the
+    // per-message tier into an unbounded queue.
+    const { api, landed, fuse } = makeFusedApi({
+      perMessageMaxPerWindow: 1,
+      perMessageWindowMs: 60_000,
+      maxDeferMs: 5_000,
+    })
+    await withOutboundClass('cosmetic', () => api.editMessageText(CHAT, 88, { markdown: 'v1' }))
+    const stale = withOutboundClass('cosmetic', () => api.editMessageText(CHAT, 88, { markdown: 'v2' }))
+    await settle()
+    const newest = withOutboundClass('cosmetic', () => api.editMessageText(CHAT, 88, { markdown: 'v3' }))
+    // Both settle without throwing; the stale one simply never painted.
+    await expect(stale).resolves.toBe(true)
+    await settle()
+    expect(fuse.stats().superseded).toBeGreaterThan(0)
+    expect(landed.map((l) => l.text)).toEqual(['v1'])
+    // Release the still-waiting newest frame so the test does not leak a timer.
+    void newest.catch(() => {})
+  })
+})