switchroom 0.20.3 → 0.20.4

package/telegram-plugin/gateway/stream-render.ts

@@ -64,6 +64,7 @@ import { backstopAlreadyDelivered } from '../outbox.js'
 import { journalExternalDelivery } from './outbox-sweep.js'
 import { NarrativeFlushController } from '../narrative-flush.js'
 import { recordTurnEnd, recordTurnStart } from '../registry/turns-schema.js'
+import { stampSubagentDispatchTurn } from '../registry/subagents-schema.js'
 import { retryWithThreadFallback } from '../retry-api-call.js'
 import { richMessage } from '../rich-send.js'
 import { emitRuntimeMetric } from '../runtime-metrics.js'
@@ -604,6 +605,10 @@ function beginTurn(deps: StreamRenderDeps, ev: TurnStartEnvelope): void {
       replyCalled: false,
       finalAnswerDelivered: false,
       finalAnswerSubstantive: false,
+      // Post-substantive feed-reopen counter — reset each turn.
+      postSubstantiveToolLabelCount: 0,
+      // Post-substantive lever-1 lift latch — reset each turn.
+      postAnswerMainActivity: false,
       // Sticky latch — reset ONLY here (turn start), never by reopen.
       finalAnswerEverDelivered: false,
       // 2026-07 double-reply-on-DM fix (Part 2) — answer-delivered race
@@ -879,6 +884,7 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
     CONTEXT_EXHAUSTION_COOLDOWN_MS,
     DELIVERY_CONFIRM_ENABLED,
     FEED_REOPEN_AFTER_ACK_ENABLED,
+    FEED_REOPEN_AFTER_SUBSTANTIVE_ENABLED,
     HANDBACK_PRETURN_ENABLED,
     HISTORY_ENABLED,
     LIVENESS_TERMINAL_HONESTY,
@@ -1250,6 +1256,35 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
       // failure mode #116 originally tracked) emit no more tool_use
       // events, so the marker mtime stops advancing → watchdog acts.
       touchTurnActiveMarker(STATE_DIR)
+      // Dispatch-time parent_turn_key stamp from the GATEWAY's live turn
+      // context (Telegram msg 6897 misroute, 2026-08-04). The pretool hook's
+      // #2085 stamp reads the turn-active marker FILE, and the watcher's
+      // backfill needs a turns row whose window contains the dispatch — both
+      // can miss at once (marker swept, hook write lost to SQLITE_BUSY, a
+      // turn whose surface registration failed). The gateway observing this
+      // Agent/Task tool_use inside a live turn KNOWS the turn key directly:
+      // stamp it marker-free. COALESCE inside the helper — a hook-stamped
+      // value is never overwritten, so normal in-turn dispatch is unchanged.
+      if (
+        (ev.toolName === 'Agent' || ev.toolName === 'Task') &&
+        ev.toolUseId != null && ev.toolUseId.length > 0 &&
+        turn.registryKey != null && turnsDb != null
+      ) {
+        try {
+          stampSubagentDispatchTurn(turnsDb, {
+            toolUseId: ev.toolUseId,
+            parentTurnKey: turn.registryKey,
+            agentType: typeof ev.input?.subagent_type === 'string' ? ev.input.subagent_type : null,
+            description: typeof ev.input?.description === 'string' ? ev.input.description : null,
+            background: ev.input?.run_in_background === true,
+            now: Date.now(),
+          })
+        } catch (err) {
+          process.stderr.write(
+            `telegram gateway: dispatch-time parent_turn_key stamp failed toolUseId=${ev.toolUseId}: ${(err as Error).message}\n`,
+          )
+        }
+      }
       // #549 fix: a tool_use immediately following text events makes
       // those texts "preamble" — the progress card already captured
       // them as a narrative for this tool. Drop the pending answer-
@@ -1377,25 +1412,45 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
       // liveness is the bounded no-reply timer's job) and lets the silent-end
       // re-prompt fire if the turn ends on only an ack.
       // Kill switch SWITCHROOM_FEED_REOPEN_AFTER_ACK=0 → legacy `return`.
+      //
+      // POST-SUBSTANTIVE reopen: a turn that delivered a real answer and then
+      // kept doing tool work reopens the feed once >= SUBSTANTIVE_REOPEN_MIN_
+      // LABELS post-answer labels arrive — WITHOUT clearing finalAnswerDelivered
+      // (that would trip the turn-end re-prompt → duplicate answer). Instead the
+      // decision returns liftLeverOne, and the drain below opens the fresh card
+      // below the reply via `postAnswerMainActivity` (the foreground sibling of
+      // the sub-agent post-answer liveness exemption). Kill switch
+      // SWITCHROOM_FEED_REOPEN_AFTER_SUBSTANTIVE=0 → post-substantive labels stay
+      // dropped (legacy).
       if (turn.finalAnswerDelivered) {
-        // decideFeedReopen returns dropLabel (legacy return) or the reset
-        // deltas: finalAnswerDelivered→false (the turn has NOT delivered its
-        // final answer while still doing tool work), activityMessageId→null
-        // (a FRESH feed message opens below the ack), activityLastSentRender
-        // →null (so the drain loop's `pending !== lastSent` guard never
-        // mistakes the fresh render for the ack's finalized one and skips it).
+        // Count post-substantive-answer labels so the reopen fires only once the
+        // turn is plainly still working (>=2), not on a stray housekeeping tool.
+        if (turn.finalAnswerSubstantive) turn.postSubstantiveToolLabelCount++
+        // decideFeedReopen returns dropLabel (legacy return), or — on the ACK
+        // path — the reset deltas (finalAnswerDelivered→false, a FRESH feed
+        // message, last-sent cleared), or — on the SUBSTANTIVE path — no reset
+        // but liftLeverOne=true (keep finalAnswerDelivered true, open the card
+        // below the reply).
         const reopen = decideFeedReopen({
           finalAnswerDelivered: turn.finalAnswerDelivered,
-          // ACK-ONLY: reopen only when the prior final was a short ack, not a
-          // substantive answer — otherwise post-answer housekeeping would
-          // reset finalAnswerDelivered and trip the silent-end re-prompt.
           finalAnswerSubstantive: turn.finalAnswerSubstantive,
           enabled: FEED_REOPEN_AFTER_ACK_ENABLED,
+          reopenAfterSubstantiveEnabled: FEED_REOPEN_AFTER_SUBSTANTIVE_ENABLED,
+          postSubstantiveToolLabelCount: turn.postSubstantiveToolLabelCount,
         })
         if (reopen.dropLabel) return
-        turn.finalAnswerDelivered = reopen.reset!.finalAnswerDelivered
-        turn.activityMessageId = reopen.reset!.activityMessageId
-        turn.activityLastSentRender = reopen.reset!.activityLastSentRender
+        // ACK reopen carries a reset; the substantive reopen deliberately does
+        // not (finalAnswerDelivered stays true, activityMessageId is already
+        // null from the answer's clearActivitySummary).
+        if (reopen.reset != null) {
+          turn.finalAnswerDelivered = reopen.reset.finalAnswerDelivered
+          turn.activityMessageId = reopen.reset.activityMessageId
+          turn.activityLastSentRender = reopen.reset.activityLastSentRender
+        }
+        // Post-substantive reopen: latch the lever-1 lift so the drain (which
+        // reads this off `turn`) opens the fresh card below the delivered reply.
+        // Sticky for the rest of the turn — the model stays "still working".
+        if (reopen.liftLeverOne) turn.postAnswerMainActivity = true
       }
       const rendered = appendActivityLabel(turn.mirrorLines, ev.label)
       if (rendered != null) {

package/telegram-plugin/gateway/subagent-handback-inbound-builder.ts

@@ -115,6 +115,19 @@ export function buildSubagentHandbackInbound(opts: {
     meta: {
       source: 'subagent_handback',
       outcome: opts.ctx.outcome,
+      // Carry the originating chat as a model-visible channel attribute
+      // (mirrors the real-inbound + resume_interrupted shapes — see
+      // inbound-router.ts:buildInboundEnvelope and resume-inbound-builder.ts).
+      // LOAD-BEARING for turn registration: the gateway's enqueue handler
+      // (`beginTurn`, stream-render.ts) gates the ENTIRE turn-atom mint on
+      // `ev.chatId`, which is parsed from the channel XML's `chat_id`
+      // attribute — rendered ONLY from meta. Without it a handback turn gets
+      // NO `turns` row and NO `turn-active.json` marker, so a worker
+      // dispatched from inside that turn cannot be stamped with a
+      // `parent_turn_key` at dispatch (#2085) nor attributed by the
+      // started_at window backfill — its card + handback then misroute to
+      // the owner DM (Telegram msg 6897 incident, 2026-08-04).
+      chat_id: opts.ctx.chatId,
       // #3268 — round-trip the fabricated `ts` through `meta.message_id` so it
       // survives to enqueue. `ev.messageId` at enqueue is parsed from the
       // channel envelope's `message_id` attribute, which is rendered ONLY from

package/telegram-plugin/gateway/subagent-origin-surface.ts

@@ -0,0 +1,181 @@
+/**
+ * Sub-agent surface-chat resolution — the DB-backed seam behind the
+ * gateway's `resolveSubagentOriginChat` / `resolveWorkerFeedChat` and the
+ * handback/progress destination inputs.
+ *
+ * Extracted (Telegram msg 6897 misroute, 2026-08-04) so the FULL resolution
+ * precedence — including the new most-recent-turn floor — is unit-testable
+ * against a real registry DB (gateway.ts is not importable in tests; the
+ * repo's `decideWorkerFeedDestination` pattern).
+ *
+ * Precedence (resolveWorkerSurfaceChat):
+ *   1. `origin`       — the dispatch-attributed turn: jsonl_agent_id →
+ *      subagents.parent_turn_key (walking the nested-parent chain) →
+ *      turns.chat_id/thread_id. The correct answer whenever the row was
+ *      stamped (pretool-hook marker stamp #2085, gateway dispatch stamp, or
+ *      the watcher's started_at window backfill).
+ *   2. `fleet`        — the configured fleet chat (permanently '' today).
+ *   3. `recent-turn`  — NEW safe-degradation floor: the chat+topic of the
+ *      most recent turn AT OR BEFORE the worker's dispatch time. A
+ *      gap-dispatched worker (no turns row open at its started_at, stamp
+ *      missed) lands NEAR the work — in the topic the operator drove last
+ *      before dispatching — instead of the owner DM with the thread
+ *      stripped. Bounded by the dispatch time so a turn the operator drives
+ *      LATER in an unrelated (possibly shared) chat can never capture the
+ *      worker's surface; with no pre-dispatch turn (or no subagents row to
+ *      date the dispatch from) the floor declines and resolution falls to
+ *      the owner DM.
+ *   4. `owner-dm`     — the durable last resort ("wrong chat" beats
+ *      "no card").
+ */
+
+import {
+  getTurnByKey,
+  findMostRecentTurn,
+  type Turn,
+} from '../registry/turns-schema.js'
+import {
+  resolveSubagentOriginTurnKey,
+  getSubagentByJsonlId,
+} from '../registry/subagents-schema.js'
+
+/** Structural sqlite shape — byte-matches the registry modules' own
+ *  bun:sqlite structural type, so handles flow both ways without casts. */
+type SqliteDatabase = {
+  exec(sql: string): void
+  prepare(sql: string): {
+    run(...params: unknown[]): unknown
+    all(...params: unknown[]): unknown[]
+    get(...params: unknown[]): unknown
+  }
+  transaction(fn: (...args: unknown[]) => unknown): (...args: unknown[]) => unknown
+  close(): void
+}
+
+export interface SubagentSurfaceChat {
+  chatId: string
+  threadId?: number
+}
+
+export type SubagentSurfaceVia = 'origin' | 'fleet' | 'recent-turn' | 'owner-dm' | 'none'
+
+/** Map a turns row to a routable {chatId, threadId}. Null when the row has
+ *  no usable chat. thread_id is stored as TEXT — parse defensively. */
+function turnToSurfaceChat(turn: Pick<Turn, 'chat_id' | 'thread_id'> | null): SubagentSurfaceChat | null {
+  if (turn == null || turn.chat_id.length === 0) return null
+  const threadNum =
+    turn.thread_id != null && turn.thread_id.length > 0 ? Number(turn.thread_id) : NaN
+  return {
+    chatId: turn.chat_id,
+    ...(Number.isFinite(threadNum) ? { threadId: threadNum } : {}),
+  }
+}
+
+/**
+ * The dispatch-attributed origin chat for a worker (jsonl stem →
+ * parent_turn_key chain → turns row). Null on any miss; never throws.
+ * The DB-parameterized body of the gateway's `resolveSubagentOriginChat`.
+ */
+export function resolveSubagentOriginChatDb(
+  db: SqliteDatabase,
+  jsonlAgentId: string,
+): SubagentSurfaceChat | null {
+  try {
+    const originKey = resolveSubagentOriginTurnKey(db, jsonlAgentId)
+    if (originKey == null) return null
+    return turnToSurfaceChat(getTurnByKey(db, originKey))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The recent-turn routing floor: chat+topic of the newest turns row
+ * (running or ended) started AT OR BEFORE the worker's own dispatch time
+ * (`subagents.started_at`, looked up by jsonl stem). The bound is
+ * load-bearing (see `findMostRecentTurn`): a turn newer than the dispatch
+ * can never be the dispatching context, so flooring to it would leak the
+ * worker's surface into whatever unrelated chat the operator drove LAST.
+ * Null when the worker has no subagents row (no dispatch time to bound by —
+ * declining beats guessing), no pre-dispatch turn exists, or the row is
+ * unusable; never throws.
+ */
+export function resolveRecentTurnFallbackChat(
+  db: SqliteDatabase,
+  jsonlAgentId: string,
+): SubagentSurfaceChat | null {
+  try {
+    const worker = getSubagentByJsonlId(db, jsonlAgentId)
+    if (worker == null) return null
+    return turnToSurfaceChat(findMostRecentTurn(db, worker.started_at))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Once-per-agent recent-turn-floor audit line (msg-6897 hardening). The floor
+ * firing is deliberate safe degradation, but it must never be silent — an
+ * operator diagnosing a mis-landed worker surface needs the routing decision
+ * on stderr, exactly like the gateway's owner-DM fallback log. Bounded FIFO
+ * set (a late duplicate line is harmless; the cap bounds a long gateway
+ * lifetime); a gateway restart clears it. `log` injectable for tests.
+ */
+const RECENT_TURN_FLOOR_LOG_CAP = 256
+const recentTurnFloorLogged = new Set<string>()
+export function noteWorkerRecentTurnFloor(
+  agentId: string,
+  dest: SubagentSurfaceChat,
+  log: (line: string) => void = (line) => process.stderr.write(line),
+): void {
+  if (recentTurnFloorLogged.has(agentId)) return
+  recentTurnFloorLogged.add(agentId)
+  if (recentTurnFloorLogged.size > RECENT_TURN_FLOOR_LOG_CAP) {
+    const oldest = recentTurnFloorLogged.values().next().value
+    if (oldest != null) recentTurnFloorLogged.delete(oldest)
+  }
+  log(
+    `telegram gateway: worker origin unresolved agent=${agentId} — flooring to pre-dispatch recent turn chat=${dest.chatId}${dest.threadId != null ? ` thread=${dest.threadId}` : ''}\n`,
+  )
+}
+
+/**
+ * The full ladder resolved into the SHAPE the handback/progress deciders
+ * take (`decideSubagentHandback` / `decideSubagentProgress`): the resolved
+ * surface chat in their `fleetChatId` slot ('' on owner-dm/none so each
+ * decider's own `ownerChatId` floor stays the last resort) and the resolved
+ * topic in `originThreadId` (omitted when none). Audits the recent-turn
+ * floor when it fires. One helper so the gateway call sites are a spread,
+ * not a third and fourth hand-rolled copy of the precedence.
+ */
+export function resolveWorkerSurfaceForDecider(
+  db: SqliteDatabase | null,
+  jsonlAgentId: string,
+  opts: { fleetChatId: string; ownerDm: string },
+): { fleetChatId: string; originThreadId?: number } {
+  const dest = resolveWorkerSurfaceChat(db, jsonlAgentId, opts)
+  if (dest.via === 'recent-turn') noteWorkerRecentTurnFloor(jsonlAgentId, dest)
+  return {
+    fleetChatId: dest.via === 'owner-dm' || dest.via === 'none' ? '' : dest.chatId,
+    ...(dest.threadId != null ? { originThreadId: dest.threadId } : {}),
+  }
+}
+
+/**
+ * Full surface-chat precedence for a worker's card/handback/progress
+ * destination. `db` may be null (turn registry disabled) — resolution then
+ * degrades to fleet → owner DM exactly as before the recent-turn floor.
+ */
+export function resolveWorkerSurfaceChat(
+  db: SqliteDatabase | null,
+  jsonlAgentId: string,
+  opts: { fleetChatId: string; ownerDm: string },
+): { chatId: string; threadId?: number; via: SubagentSurfaceVia } {
+  const origin = db != null ? resolveSubagentOriginChatDb(db, jsonlAgentId) : null
+  if (origin != null && origin.chatId.length > 0) return { ...origin, via: 'origin' }
+  if (opts.fleetChatId.length > 0) return { chatId: opts.fleetChatId, via: 'fleet' }
+  const recent = db != null ? resolveRecentTurnFallbackChat(db, jsonlAgentId) : null
+  if (recent != null) return { ...recent, via: 'recent-turn' }
+  if (opts.ownerDm.length > 0) return { chatId: opts.ownerDm, via: 'owner-dm' }
+  return { chatId: '', via: 'none' }
+}

package/telegram-plugin/gateway/subagent-progress-inbound-builder.ts

@@ -137,6 +137,13 @@ export function buildSubagentProgressInbound(opts: {
     text,
     meta: {
       source: 'subagent_progress',
+      // Originating chat as a model-visible channel attribute — same
+      // load-bearing turn-registration role as the handback builder's
+      // meta.chat_id (see subagent-handback-inbound-builder.ts): without it
+      // the progress turn mints no turn atom (no `turns` row, no
+      // `turn-active.json`), so a worker dispatched from inside it can never
+      // be attributed to this chat/topic and its surfaces fall to the DM.
+      chat_id: opts.ctx.chatId,
       ...(opts.ctx.threadId != null ? { message_thread_id: String(opts.ctx.threadId) } : {}),
       subagent_jsonl_id: opts.ctx.subagentJsonlId,
       bucket_idx: String(opts.ctx.bucketIdx),

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

@@ -784,6 +784,67 @@ export function recordNestedSubagentDispatch(
   `).run(args.parentJsonlAgentId, args.parentJsonlAgentId, args.toolUseId)
 }
 
+export interface StampSubagentDispatchTurnArgs {
+  /** tool_use id of the Agent/Task dispatch — the subagents PK the pretool
+   *  hook inserts (or will insert) the row under. */
+  toolUseId: string
+  /** The live turn's registry key (`turns.turn_key`) at dispatch time. */
+  parentTurnKey: string
+  agentType?: string | null
+  description?: string | null
+  /** `run_in_background` from the dispatch's tool_input. */
+  background: boolean
+  now: number
+}
+
+/**
+ * Stamp `parent_turn_key` on a depth-1 sub-agent row at DISPATCH time, from
+ * the gateway's own live turn context (the `tool_use` session event for an
+ * Agent/Task dispatch observed while a turn atom is open).
+ *
+ * Why this exists (Telegram msg 6897 misroute, 2026-08-04): the pretool
+ * hook's dispatch-time stamp (#2085) sources the turn key from the
+ * `turn-active.json` marker file, and the watcher's backfill
+ * (subagent-watcher.ts) sources it from a `turns` row whose
+ * [started_at, ended_at] window contains the dispatch. Both sources can be
+ * missing at once — a synthesized turn that never registered its surface, a
+ * swept/corrupted marker, a hook write lost to SQLITE_BUSY — leaving
+ * `parent_turn_key` NULL and the worker's card + handback falling back to
+ * the owner DM with the thread stripped. The gateway, however, KNOWS the
+ * live turn key when it observes the dispatch: this helper writes it
+ * directly, marker-free and window-free.
+ *
+ * Behaviour (idempotent, mirrors recordNestedSubagentDispatch):
+ *   - INSERT OR IGNORE a row keyed on the dispatch tool_use_id (harmless
+ *     no-op when the pretool hook's row already landed — the common case).
+ *   - UPDATE `parent_turn_key` only when NULL (COALESCE), so a value the
+ *     hook already stamped from the live marker is never overwritten.
+ */
+export function stampSubagentDispatchTurn(
+  db: SqliteDatabase,
+  args: StampSubagentDispatchTurnArgs,
+): void {
+  db.prepare(`
+    INSERT OR IGNORE INTO subagents
+      (id, parent_session_id, parent_turn_key, agent_type, description,
+       background, started_at, last_activity_at, status)
+    VALUES (?, NULL, ?, ?, ?, ?, ?, ?, 'running')
+  `).run(
+    args.toolUseId,
+    args.parentTurnKey,
+    args.agentType ?? null,
+    args.description ?? null,
+    args.background ? 1 : 0,
+    args.now,
+    args.now,
+  )
+  db.prepare(`
+    UPDATE subagents
+    SET parent_turn_key = COALESCE(parent_turn_key, ?)
+    WHERE id = ?
+  `).run(args.parentTurnKey, args.toolUseId)
+}
+
 /**
  * Resolve the ORIGIN turn key for a worker, walking the nested-parent chain.
  *

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

@@ -673,6 +673,32 @@ export function findRecentTurnsForChat(
   return rows.map(mapRow)
 }
 
+/**
+ * Return the most recent turn across ALL chats (any state — running or
+ * ended) whose `started_at` is at or before `beforeOrAtMs`, or null when no
+ * such turn exists. The last-resort routing floor for an unattributable
+ * sub-agent's surfaces (worker card / handback): when origin resolution
+ * misses (parent_turn_key never stamped), the last turn BEFORE the worker's
+ * dispatch is where the operator dispatched it from — a strictly better
+ * landing spot than the owner DM with the thread stripped.
+ *
+ * The bound is load-bearing, not an optimisation: an UNBOUNDED "newest turn"
+ * floor routes a worker's private result to wherever the operator chatted
+ * LAST — possibly an unrelated, shared group entered after the dispatch. A
+ * turn newer than the dispatch can never be the dispatching context, so it
+ * is never a valid floor; callers with no pre-dispatch turn fall through to
+ * the owner-DM last resort instead.
+ */
+export function findMostRecentTurn(db: SqliteDatabase, beforeOrAtMs: number): Turn | null {
+  const row = db.prepare(`
+    SELECT * FROM turns
+    WHERE started_at <= ?
+    ORDER BY started_at DESC
+    LIMIT 1
+  `).get(beforeOrAtMs) as RawTurnRow | undefined
+  return row ? mapRow(row) : null
+}
+
 /**
  * Return the most recent N turns across all chats for an agent, ordered by
  * started_at DESC. Intended for the REST API endpoint

package/telegram-plugin/tests/edit-flood-fuse-cosmetic-fairness.test.ts

@@ -0,0 +1,229 @@
+/**
+ * Per-`message_id` cosmetic fair-share (#4300).
+ *
+ * The bug: `cosmeticPerChatMaxPerWindow` (6/60s) is ONE bucket shared across
+ * every cosmetic surface in a chat — the primary activity card, a worker /
+ * sub-agent card, and answer-stream draft edits. Under intra-cosmetic
+ * contention (two live cards) — and especially once a 429 tightens that bucket
+ * — the surface the user is actually watching (the primary activity card) could
+ * be starved well past 60s between frames while the OTHER surface kept
+ * repainting. The fix carves a small AIMD-immune per-message floor OUT OF the
+ * same pool (no new wire rate, so 429 risk is unchanged) so no cosmetic surface
+ * can starve another, and a watched card keeps a minimum cadence under flood.
+ *
+ * These tests assert OUTCOMES (frames that actually reached the API within a
+ * window), not code paths, and pin the behaviour against the kill-switch so a
+ * revert of the core change fails at least one of them.
+ */
+import { describe, it, expect } from 'vitest'
+import { createEditFloodFuse, EDIT_FLOOD_FUSE_DEFAULTS } from '../edit-flood-fuse.js'
+import type { Clock } from '../send-gate.js'
+
+const CHAT = '5005'
+const PRIMARY = 1 // the activity card the user watches
+const WORKER = 2 // a second live cosmetic surface (sub-agent card / draft)
+
+const D = EDIT_FLOOD_FUSE_DEFAULTS
+
+class FakeClock implements Clock {
+  private cur = 0
+  private seq = 0
+  private timers: { at: number; id: number; resolve: () => void }[] = []
+
+  now(): number { return this.cur }
+
+  sleep(ms: number): Promise<void> {
+    return new Promise<void>((resolve) => {
+      this.timers.push({ at: this.cur + ms, id: this.seq++, resolve })
+    })
+  }
+
+  async advance(ms: number): Promise<void> {
+    const target = this.cur + ms
+    for (;;) {
+      await flush()
+      const due = this.timers.filter((t) => t.at <= target).sort((a, b) => a.at - b.at || a.id - b.id)
+      if (due.length === 0) break
+      const t = due[0]!
+      this.timers = this.timers.filter((x) => x !== t)
+      this.cur = t.at
+      t.resolve()
+      await flush()
+    }
+    this.cur = target
+    await flush()
+  }
+}
+
+function flush(): Promise<void> {
+  return new Promise((r) => setImmediate(r))
+}
+
+const flood = () => Object.assign(
+  new Error('Too Many Requests: retry after 3'),
+  { error_code: 429, parameters: { retry_after: 3 } },
+)
+
+/**
+ * Drive `n` observed 429s so the ceilings tighten by `n` AIMD levels. The
+ * probes go to a SEPARATE chat: tightening is global, but a probe still charges
+ * the target chat's shared total window, and we don't want those synthetic
+ * sends to eat into CHAT's tightened cosmetic-total budget under test.
+ */
+async function tighten(fuse: ReturnType<typeof createEditFloodFuse>, n: number): Promise<void> {
+  for (let i = 0; i < n; i++) {
+    await fuse.apply('sendMessage', { chat_id: '9009', text: 'probe' }, async () => { throw flood() })
+      .then(() => { /* unreachable */ }, () => { /* the 429 is re-thrown; swallow */ })
+  }
+}
+
+/**
+ * Run a contention scenario: WORKER repaints densely (every `workerEveryMs`)
+ * and PRIMARY repaints at a heartbeat cadence (every `primaryEveryMs`), both
+ * for `spanMs`. Returns how many frames of each landed strictly inside the
+ * first `perChatWindowMs` window.
+ */
+async function contend(
+  fuse: ReturnType<typeof createEditFloodFuse>, clock: FakeClock,
+  opts: { spanMs: number; workerEveryMs: number; primaryEveryMs: number },
+): Promise<{ primary: number; worker: number }> {
+  const landed: { primary: number; worker: number } = { primary: 0, worker: 0 }
+  const inflight: Promise<unknown>[] = []
+  let nextWorker = 0
+  let nextPrimary = 3_000 // let the worker grab the pool first, as in the real stall
+  const step = 500
+  for (let t = 0; t <= opts.spanMs; t += step) {
+    if (t >= nextWorker) {
+      inflight.push(fuse.apply(
+        'editMessageText', { chat_id: CHAT, message_id: WORKER, text: `w${t}` },
+        async () => { if (clock.now() < D.perChatWindowMs) landed.worker++; return true },
+      ))
+      nextWorker += opts.workerEveryMs
+    }
+    if (t >= nextPrimary) {
+      inflight.push(fuse.apply(
+        'editMessageText', { chat_id: CHAT, message_id: PRIMARY, text: `p${t}` },
+        async () => { if (clock.now() < D.perChatWindowMs) landed.primary++; return true },
+      ))
+      nextPrimary += opts.primaryEveryMs
+    }
+    await clock.advance(step)
+  }
+  // Drain every still-deferred frame so no promise is left dangling.
+  await clock.advance(D.maxDeferMs + 1_000)
+  await Promise.all(inflight)
+  return landed
+}
+
+describe('#4300 cosmetic fair-share — a watched card is not starved by a second surface', () => {
+  it('(a) under flood tightening the primary card keeps its per-message floor while a worker card repaints', async () => {
+    // One 429 → AIMD level 1: the shared cosmetic pool ceiling(6) shrinks to 3,
+    // which two live cosmetic surfaces would otherwise fight over.
+    const clockOn = new FakeClock()
+    const fuseOn = createEditFloodFuse({ clock: clockOn })
+    await tighten(fuseOn, 1)
+    expect(fuseOn.stats().tightenLevel).toBeGreaterThanOrEqual(1)
+    const on = await contend(fuseOn, clockOn, { spanMs: 58_000, workerEveryMs: 1_000, primaryEveryMs: 6_000 })
+
+    // The invariant: the watched card still repaints at least its guaranteed
+    // floor (cosmeticFloorPerWindow = 2/60s = 1 edit/30s), AIMD-immune, even
+    // though the worker is hammering the same pool.
+    expect(on.primary).toBeGreaterThanOrEqual(D.cosmeticFloorPerWindow)
+  })
+
+  it('(d) mutation guard — with fair-share OFF the SAME scenario starves the primary below the floor', async () => {
+    // Kill-switch OFF is the pre-fix single shared bucket. Reverting the core
+    // change is behaviourally identical to this, so if the fix did nothing the
+    // (a) assertion above would already hold here — it must NOT.
+    const clockOff = new FakeClock()
+    const fuseOff = createEditFloodFuse({ clock: clockOff, cosmeticFairShareEnabled: false })
+    await tighten(fuseOff, 1)
+    const off = await contend(fuseOff, clockOff, { spanMs: 58_000, workerEveryMs: 1_000, primaryEveryMs: 6_000 })
+
+    // No per-message floor: the dense worker wins the shared pool and the
+    // watched card is starved below the floor the fix guarantees.
+    expect(off.primary).toBeLessThan(D.cosmeticFloorPerWindow)
+    expect(fuseOff.stats().cosmeticFairShareEnabled).toBe(false)
+  })
+
+  it('(b) a heavily-tightened pool still lets a lone watched card repaint ≥ 1 edit / 30s (AIMD floor)', async () => {
+    const clock = new FakeClock()
+    const fuse = createEditFloodFuse({ clock })
+    // Two 429s → level 2: ceiling(6) → 1, so WITHOUT the floor the whole chat's
+    // cosmetic budget would be a single frame per 60s.
+    await tighten(fuse, 2)
+    expect(fuse.stats().tightenLevel).toBeGreaterThanOrEqual(2)
+
+    const landed: number[] = []
+    const inflight: Promise<unknown>[] = []
+    // A watched card's heartbeat: an edit every 5s across a 60s window.
+    for (let i = 0; i < 12; i++) {
+      inflight.push(fuse.apply(
+        'editMessageText', { chat_id: CHAT, message_id: PRIMARY, text: `hb${i}` },
+        async () => { if (clock.now() < D.perChatWindowMs) landed.push(i); return true },
+      ))
+      await clock.advance(5_000)
+    }
+    await clock.advance(1_000)
+    const inWindow = landed.length
+    await clock.advance(D.maxDeferMs + 1_000)
+    await Promise.all(inflight)
+
+    // ≥ 1 edit / 30s = ≥ cosmeticFloorPerWindow (2) per 60s window, guaranteed
+    // no matter how many 429s tighten the pool.
+    expect(inWindow).toBeGreaterThanOrEqual(D.cosmeticFloorPerWindow)
+  })
+
+  it('(c) fair-share OFF is the old single shared bucket — two surfaces share exactly cosmeticPerChatMax, byte-for-byte', async () => {
+    // No tightening: the pre-fix behaviour is that ALL cosmetic surfaces in a
+    // chat draw from one `cosmeticPerChatMaxPerWindow` bucket with no
+    // per-message reservation. Two saturating surfaces therefore land, in
+    // aggregate, exactly the pool — never more (the fix does not raise the wire
+    // rate) and, with the flag off, with no floor keeping either one alive.
+    const clock = new FakeClock()
+    const fuse = createEditFloodFuse({ clock, cosmeticFairShareEnabled: false })
+    let a = 0
+    let b = 0
+    const inflight: Promise<unknown>[] = []
+    for (let t = 0; t < 58_000; t += 500) {
+      inflight.push(fuse.apply('editMessageText', { chat_id: CHAT, message_id: PRIMARY, text: `a${t}` },
+        async () => { if (clock.now() < D.perChatWindowMs) a++; return true }))
+      inflight.push(fuse.apply('editMessageText', { chat_id: CHAT, message_id: WORKER, text: `b${t}` },
+        async () => { if (clock.now() < D.perChatWindowMs) b++; return true }))
+      await clock.advance(500)
+    }
+    await clock.advance(D.maxDeferMs + 1_000)
+    await Promise.all(inflight)
+
+    // The single shared bucket: aggregate cosmetic frames == the pool, and the
+    // fair-share machinery is provably not in play.
+    expect(a + b).toBeLessThanOrEqual(D.cosmeticPerChatMaxPerWindow)
+    expect(a + b).toBeGreaterThan(0)
+    expect(fuse.stats().cosmeticFairShareEnabled).toBe(false)
+  })
+
+  it('raises a visible `throttled` signal when a cosmetic edit is deferred past throttleNoticeMs', async () => {
+    const clock = new FakeClock()
+    const actions: string[] = []
+    // Saturate the per-chat cosmetic pool with a DIFFERENT card so the target
+    // edit has to wait; a long defer window lets it cross the notice threshold.
+    const fuse = createEditFloodFuse({
+      clock,
+      cosmeticPerChatMaxPerWindow: 1, cosmeticFloorPerWindow: 0,
+      perChatWindowMs: 600_000, maxDeferMs: 120_000, throttleNoticeMs: 45_000,
+      onTrip: (i) => { actions.push(i.action) },
+    })
+    // Burn the pool.
+    await fuse.apply('editMessageText', { chat_id: CHAT, message_id: WORKER, text: 'hog' },
+      async () => true)
+    // The watched card's frame cannot get in; it sits deferred.
+    const stuck = fuse.apply('editMessageText', { chat_id: CHAT, message_id: PRIMARY, text: 'watched' },
+      async () => true)
+    await clock.advance(46_000)
+    expect(fuse.stats().throttled).toBeGreaterThan(0)
+    expect(actions).toContain('throttled')
+    // Drain.
+    await clock.advance(120_000)
+    await stuck
+  })
+})