switchroom 0.18.26 → 0.18.27

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

@@ -17,6 +17,7 @@ import { describe, it, expect, beforeAll } from "vitest";
 import {
   parseModelCommand,
   planModelCommand,
+  resolveStaleAwareBusy,
   isModelCommandBusy,
   modelCommandReceiptLine,
   handleModelCommand,
@@ -1622,6 +1623,117 @@ describe("#3177 typed /model never silently swallowed mid-turn", () => {
     });
   });
 
+  describe("resolveStaleAwareBusy — phantom 'active turn' fix (#3262)", () => {
+    const HARD_TTL = 10 * 60_000;
+
+    it("APPLIES a set when the turn atom is DANGLING (older than the hard TTL)", () => {
+      // A currentTurn atom whose turn_end never fired: non-null but its
+      // liveness marker is far older than the ceiling. Discounted to idle,
+      // and flagged for the gateway to clear.
+      const r = resolveStaleAwareBusy({
+        currentTurnActive: true,
+        turnAgeMs: HARD_TTL + 1,
+        machineInTurn: false,
+        oldestPendingApprovalAgeMs: null,
+        hardTtlMs: HARD_TTL,
+      });
+      expect(r.currentTurnActive).toBe(false);
+      expect(r.turnInFlight).toBe(false);
+      expect(r.clearStaleTurn).toBe(true);
+      // Routing sees "idle" → applies, not queues.
+      const d = planModelCommand(
+        { kind: "set", model: "opus" },
+        { currentTurnActive: r.currentTurnActive, turnInFlight: r.turnInFlight, menuEnabled: true },
+      );
+      expect(d).toEqual({ kind: "apply", parsed: { kind: "set", model: "opus" } });
+    });
+
+    it("QUEUES a set when the turn is FRESH (marker within the TTL) — no regression", () => {
+      const r = resolveStaleAwareBusy({
+        currentTurnActive: true,
+        turnAgeMs: 5_000,
+        machineInTurn: false,
+        oldestPendingApprovalAgeMs: null,
+        hardTtlMs: HARD_TTL,
+      });
+      expect(r.currentTurnActive).toBe(true);
+      expect(r.clearStaleTurn).toBe(false);
+      const d = planModelCommand(
+        { kind: "set", model: "opus" },
+        { currentTurnActive: r.currentTurnActive, turnInFlight: r.turnInFlight, menuEnabled: true },
+      );
+      expect(d).toEqual({ kind: "queue", target: "opus" });
+    });
+
+    it("APPLIES when only a WEDGED approval (older than the TTL) holds the gate on an idle session", () => {
+      const r = resolveStaleAwareBusy({
+        currentTurnActive: false,
+        turnAgeMs: null,
+        machineInTurn: false,
+        oldestPendingApprovalAgeMs: HARD_TTL + 1,
+        hardTtlMs: HARD_TTL,
+      });
+      expect(r.turnInFlight).toBe(false);
+      expect(r.currentTurnActive).toBe(false);
+      const d = planModelCommand(
+        { kind: "set", model: "opus" },
+        { currentTurnActive: r.currentTurnActive, turnInFlight: r.turnInFlight, menuEnabled: true },
+      );
+      expect(d).toEqual({ kind: "apply", parsed: { kind: "set", model: "opus" } });
+    });
+
+    it("QUEUES when a RECENT pending approval holds the gate — a real block is preserved", () => {
+      const r = resolveStaleAwareBusy({
+        currentTurnActive: false,
+        turnAgeMs: null,
+        machineInTurn: false,
+        oldestPendingApprovalAgeMs: 3_000,
+        hardTtlMs: HARD_TTL,
+      });
+      expect(r.turnInFlight).toBe(true);
+      const d = planModelCommand(
+        { kind: "set", model: "opus" },
+        { currentTurnActive: r.currentTurnActive, turnInFlight: r.turnInFlight, menuEnabled: true },
+      );
+      expect(d).toEqual({ kind: "queue", target: "opus" });
+    });
+
+    it("QUEUES when the machine is genuinely in-turn regardless of atom age", () => {
+      const r = resolveStaleAwareBusy({
+        currentTurnActive: false,
+        turnAgeMs: null,
+        machineInTurn: true,
+        oldestPendingApprovalAgeMs: null,
+        hardTtlMs: HARD_TTL,
+      });
+      expect(r.turnInFlight).toBe(true);
+      expect(r.clearStaleTurn).toBe(false);
+    });
+
+    it("does NOT clear or discount when there is no turn atom", () => {
+      const r = resolveStaleAwareBusy({
+        currentTurnActive: false,
+        turnAgeMs: null,
+        machineInTurn: false,
+        oldestPendingApprovalAgeMs: null,
+        hardTtlMs: HARD_TTL,
+      });
+      expect(r).toEqual({ currentTurnActive: false, turnInFlight: false, clearStaleTurn: false });
+    });
+
+    it("keeps a non-null atom busy when its age is exactly at the ceiling (strict >)", () => {
+      const r = resolveStaleAwareBusy({
+        currentTurnActive: true,
+        turnAgeMs: HARD_TTL,
+        machineInTurn: false,
+        oldestPendingApprovalAgeMs: null,
+        hardTtlMs: HARD_TTL,
+      });
+      expect(r.currentTurnActive).toBe(true);
+      expect(r.clearStaleTurn).toBe(false);
+    });
+  });
+
   describe("modelCommandReceiptLine — the durable, greppable entry trace", () => {
     it("stamps agent, kind, arg, and busy for a typed set", () => {
       const line = modelCommandReceiptLine("finn", { kind: "set", model: "opus" }, true);

package/telegram-plugin/tests/multitopic-routing-wiring.test.ts

@@ -20,6 +20,13 @@ const bridgeSrc = readFileSync(
   resolve(__dirname, '..', 'bridge', 'bridge.ts'),
   'utf-8',
 )
+// #3268 — deriveTurnId was extracted from the gateway monolith into its own
+// importable module so the enqueue seam and the handback round-trip test share
+// ONE function. The body-shape assertion below now reads it from there.
+const deriveTurnIdSrc = readFileSync(
+  resolve(__dirname, '..', 'gateway', 'derive-turn-id.ts'),
+  'utf-8',
+)
 
 describe('component 3 — turn-origin reply routing', () => {
   it('CurrentTurn carries a turnId, and the enqueue handler initialises it', () => {
@@ -35,10 +42,15 @@ describe('component 3 — turn-origin reply routing', () => {
 
   it('deriveTurnId is stable across inbound-build and enqueue (message-id based)', () => {
     // The id must be derivable identically at both sites — keyed on
-    // chat/thread/messageId, NOT the not-yet-known startedAt.
-    const fn = gatewaySrc.split('function deriveTurnId')[1]?.split('\nfunction ')[0] ?? ''
+    // chat/thread/messageId, NOT the not-yet-known startedAt. Lives in the
+    // extracted derive-turn-id.ts module (#3268); the gateway imports it under
+    // the same name (asserted below), so every enqueue callsite is unchanged.
+    const fn = deriveTurnIdSrc.split('export function deriveTurnId')[1]?.split('\nexport function ')[0] ?? ''
     expect(fn).toMatch(/chatKey\(chatId, threadId \?\? null\)/)
     expect(fn).toMatch(/messageId/)
+    // The gateway must import the shared function, not redefine it — so the
+    // enqueue seam and the round-trip test provably use the same identity.
+    expect(gatewaySrc).toMatch(/import \{ deriveTurnId \} from '\.\/derive-turn-id\.js'/)
   })
 
   it('executeReply resolves the answer thread via the origin turn, not the live currentTurn', () => {

package/telegram-plugin/tests/outbound-send-chunks.test.ts

@@ -302,3 +302,60 @@ describe('sendReplyChunks — preview edit-in-place', () => {
     expect(calls.filter((c) => c.kind === 'sendRich')).toHaveLength(0)
   })
 })
+
+// Reply-flicker fix: the flushed-turn supersede edits the flushed message A in
+// place instead of delete+resend, by re-pointing `previewMessageId` at A's id.
+// These drive that exact execution lane through the fake bot to assert the
+// user-visible OUTCOME (one message survives, no flicker) rather than the path.
+describe('sendReplyChunks — flushed-turn supersede edit-in-place', () => {
+  it('a single-message text reply superseding a flushed message EDITS A in place — no delete', async () => {
+    // Gateway sets previewMessageId to the flushed message id when
+    // decideSupersedeCorrection returns edit-in-place (single chunk, no files/preview).
+    const { deps, calls, deleted } = makeFake()
+    const flushedId = 700
+    const state = baseState({ chunks: ['the real answer'], previewMessageId: flushedId })
+    const res = await sendReplyChunks(deps, state)
+    // A is edited in place with the canonical reply body — NOT deleted.
+    expect(calls).toHaveLength(1)
+    expect(calls[0].kind).toBe('editPreview')
+    expect(calls[0].messageId).toBe(flushedId)
+    expect(calls[0].body).toEqual({ rich: 'the real answer' })
+    expect(deleted).toEqual([])
+    expect(calls.some((c) => c.kind === 'sendRich')).toBe(false)
+    // Exactly ONE message survives, and it is the (edited) flushed message.
+    expect(state.sentIds).toEqual([flushedId])
+    expect(res.previewMessageId).toBeNull()
+  })
+
+  it('anti-duplicate: an edit-in-place supersede never leaves BOTH the flush and a fresh reply visible', async () => {
+    const { deps, calls, deleted } = makeFake()
+    const state = baseState({ chunks: ['answer'], previewMessageId: 710 })
+    await sendReplyChunks(deps, state)
+    // No fresh send happened alongside the edit, and nothing was deleted — the
+    // single surviving message is the flushed one, now carrying the reply.
+    const fresh = calls.filter((c) => c.kind === 'sendRich' || c.kind === 'sendLiteral')
+    expect(fresh).toHaveLength(0)
+    expect(deleted).toEqual([])
+    expect(state.sentIds).toEqual([710])
+  })
+
+  it('edit returns a 400 → falls back to delete+resend, exactly one clean message survives', async () => {
+    // Message too old / uneditable / gone: editPreview throws, the lane deletes
+    // A and sends the canonical reply fresh — never both, never neither.
+    const { deps, calls, deleted } = makeFake({
+      failNext: { editPreview: [grammy400("message can't be edited", 'editMessageText')] },
+    })
+    const flushedId = 720
+    const state = baseState({ chunks: ['the real answer'], previewMessageId: flushedId })
+    const res = await sendReplyChunks(deps, state)
+    // Fallback: stale flush deleted, canonical reply sent fresh.
+    expect(deleted).toEqual([flushedId])
+    const fresh = calls.filter((c) => c.kind === 'sendRich')
+    expect(fresh).toHaveLength(1)
+    expect(fresh[0].body).toEqual({ rich: 'the real answer' })
+    // Exactly one surviving message (the fresh send), and it is NOT the flushed id.
+    expect(state.sentIds).toHaveLength(1)
+    expect(state.sentIds[0]).not.toBe(flushedId)
+    expect(res.previewMessageId).toBeNull()
+  })
+})

package/telegram-plugin/tests/permission-no-repeat-wiring.test.ts

@@ -90,20 +90,27 @@ describe('inbound gate holds while approval card is outstanding (#2841)', () =>
   // even after releaseTurnBufferGate has cleared claudeBusyKeys/machine on the
   // first interim reply. Without this, a new inbound delivered in that window
   // displaces the approval context and orphans the pending MCP call.
-  it('turnInFlightForGate includes pendingPermissions.size > 0 on the legacy path', () => {
-    // span 2600: the function gained a ~1100-char note (#3084 follow-up) documenting
-    // the one case with no timeout valve — a HELD approval.
-    const fn = slice(GATEWAY, 'function turnInFlightForGate()', 2600)
-    // Both paths (legacy claudeBusyKeys + machine-authoritative) must include the check.
-    expect(fn).toMatch(/claudeBusyKeys\.size\s*>\s*0\s*\|\|\s*hasPendingApproval/)
+  it('turnInFlightForGate STILL composes the pending-approval hold (#2841 contract)', () => {
+    // #3262 factored the machine-in-turn leg into turnInFlightMachineOnly(), but
+    // the shared inbound gate must remain UNCONDITIONALLY busy while an approval
+    // card is outstanding. That contract now lives in the composition here.
+    // span 2800: the function carries a ~1100-char #2841/#3084 note before the
+    // composition line.
+    const fn = slice(GATEWAY, 'function turnInFlightForGate()', 2800)
+    expect(fn).toMatch(/return\s+turnInFlightMachineOnly\(\)\s*\|\|\s*hasPendingApproval/)
+    expect(fn).toMatch(/hasPendingApproval\s*=\s*pendingPermissions\.size\s*>\s*0/)
   })
 
-  it('turnInFlightForGate includes pendingPermissions.size > 0 on the machine path', () => {
-    const fn = slice(GATEWAY, 'function turnInFlightForGate()', 2700)
-    // probeGateParity(...) || hasPendingApproval — the inner arg contains its own
-    // parens (isMachineInTurn()), so match the two tokens independently.
+  it('turnInFlightMachineOnly carries BOTH busy paths (legacy claudeBusyKeys + machine)', () => {
+    // #3262: the machine-in-turn signal moved here (read by the /model & /effort
+    // resolver without the approval hold). Both the legacy claudeBusyKeys path
+    // and the machine-authoritative probeGateParity path must be present — a
+    // dropped branch would silently change the busy read.
+    const fn = slice(GATEWAY, 'function turnInFlightMachineOnly()', 1400)
+    expect(fn).toMatch(/claudeBusyKeys\.size\s*>\s*0/)
     expect(fn).toContain('probeGateParity(')
-    expect(fn).toMatch(/probeGateParity[\s\S]+?\|\|\s*hasPendingApproval/)
+    // NOT gated by the approval hold — that stays in turnInFlightForGate.
+    expect(fn).not.toContain('hasPendingApproval')
   })
 
   it('hasPendingApproval reads pendingPermissions.size', () => {

package/telegram-plugin/tests/reply-owner-resolve.test.ts

@@ -277,3 +277,93 @@ describe('F2 — recency-bound the destructive latest-ended supersede tier', ()
     ).toBe('turn-T')
   })
 })
+
+/**
+ * Reply-flicker edit-in-place fix (PR #3266) — the deferred-correction
+ * resurrection window (adversarial-review L1).
+ *
+ * The fix defers the flushed-message correction (delete-resend vs edit-in-place)
+ * from the supersede site to the send site so a single-message reply can EDIT
+ * the flushed message A in place instead of delete+resend. But `take()` consumes
+ * the supersede record at the supersede site, and TWO arg-validation `throw`s
+ * (file too-large, invalid inline_keyboard) sit BETWEEN consumption and the
+ * correction. A late reply that supersedes a flush AND carries an oversized file
+ * / invalid keyboard throws before the correction runs: message A is neither
+ * deleted nor edited, the model retries `reply`, and — the record already
+ * consumed — the retry takes the no-record branch. Without a latch the retry
+ * would ship a fresh B alongside the stale narration A (both visible).
+ *
+ * The fix latches `ownerTurn.answerDelivered = true` at record consumption, so
+ * the retry (resolving the SAME ended owner turn) is caught by
+ * `decideAnswerLatchSuppression` and suppressed — exactly one message survives.
+ */
+describe('reply-flicker edit-in-place — mid-path throw + retry never resurrects the duplicate (L1)', () => {
+  const CHAT = '636363'
+
+  /** Minimal model of the ended owner turn atom the gateway mutates + reads. */
+  interface OwnerTurn { turnId: string; answerDelivered: boolean }
+
+  /**
+   * Drive the two gateway `reply` calls the incident produces, threading the
+   * SAME registry + owner-turn atom. `setLatchOnSupersede` toggles the fix on
+   * (true = PR behaviour) vs off (false = pre-fix red-on-main contrast).
+   * Returns which messages are visible after the sequence.
+   */
+  function runSupersedeThenThrowRetry(setLatchOnSupersede: boolean): {
+    visible: string[]
+    firstSuperseded: boolean
+    retrySuppressed: boolean
+  } {
+    const reg = new FlushedTurnSupersedeRegistry()
+    const now = 2_000_000
+    const owner: OwnerTurn = { turnId: 'turn-A', answerDelivered: false }
+    // The flush posted message A for turn-A and recorded it.
+    reg.record(CHAT, undefined, { turnId: owner.turnId, messageIds: [8001], text: 'narration\n\nthe answer' }, now)
+    const visible = ['A(flush-narration)']
+
+    // --- Call 1: the model's real `reply` lands and SUPERSEDES the flush. ---
+    const d1 = reg.take(CHAT, undefined, { liveTurnId: owner.turnId, now: now + 10 })
+    const firstSuperseded = d1.supersede
+    if (d1.supersede && setLatchOnSupersede) {
+      // The fix: latch at consumption, BEFORE the arg-validation throw.
+      owner.answerDelivered = true
+    }
+    // Arg-validation throw fires here (oversized file / invalid keyboard):
+    // the correction never runs → A is neither deleted nor edited, B not sent.
+    // (Modelled by simply NOT applying the correction and NOT pushing B.)
+
+    // --- Call 2: the model retries `reply` after seeing the MCP error. ---
+    // The record was consumed by Call 1's take() → no-record now.
+    const d2 = reg.take(CHAT, undefined, { liveTurnId: owner.turnId, now: now + 20 })
+    let retrySuppressed = false
+    if (!d2.supersede) {
+      // else/no-record branch: the retry is a late substantive reply.
+      retrySuppressed = decideAnswerLatchSuppression({
+        superseded: false,
+        replySubstantive: true,
+        isLateReply: true,
+        ownerAnswerDelivered: owner.answerDelivered,
+      })
+    }
+    if (!retrySuppressed) visible.push('B(retry-reply)')
+    return { visible, firstSuperseded, retrySuppressed }
+  }
+
+  it('WITH the fix: the retry is latch-suppressed → exactly ONE surviving message (never A+B)', () => {
+    const r = runSupersedeThenThrowRetry(true)
+    expect(r.firstSuperseded).toBe(true)
+    expect(r.retrySuppressed).toBe(true)
+    expect(r.visible).toHaveLength(1)
+    // The single surviving message is the flushed A (the correction throw left it
+    // in place); the retry B was suppressed — no stale-narration + reply duplicate.
+    expect(r.visible).toEqual(['A(flush-narration)'])
+  })
+
+  it('WITHOUT the fix (contrast): the retry is NOT suppressed → BOTH A and B ship (the resurrected duplicate)', () => {
+    const r = runSupersedeThenThrowRetry(false)
+    expect(r.firstSuperseded).toBe(true)
+    expect(r.retrySuppressed).toBe(false)
+    // The exact regression: stale narration A AND the retry reply B are both visible.
+    expect(r.visible).toEqual(['A(flush-narration)', 'B(retry-reply)'])
+  })
+})

package/telegram-plugin/tests/subagent-handback-inbound-builder.test.ts

@@ -37,6 +37,11 @@ describe('buildSubagentHandbackInbound', () => {
     // The wake-up contract: bridge renders <channel source="subagent_handback">.
     expect(inbound.meta.source).toBe('subagent_handback')
     expect(inbound.meta.outcome).toBe('completed')
+    // #3268 — the fabricated ts rounds-trips through meta.message_id (the only
+    // channel-rendered id) so enqueue's deriveTurnId matches the pre-turn seam's
+    // adopt id. Must equal the top-level messageId as a string.
+    expect(inbound.meta.message_id).toBe(String(FIXED_NOW))
+    expect(inbound.meta.message_id).toBe(String(inbound.messageId))
     // Text carries the task, the result, and the beat-4 steer.
     expect(inbound.text).toContain('Refactor the auth module')
     expect(inbound.text).toContain('4 tests added, all green')

package/telegram-plugin/tests/turn-active-marker.test.ts

@@ -15,6 +15,9 @@ import {
   removeTurnActiveMarker,
   sweepStaleTurnActiveMarker,
   readTurnActiveMarkerAgeMs,
+  effectiveTurnAgeMs,
+  TURN_ACTIVE_HARD_TTL_MS,
+  TURN_ACTIVE_IDLE_SWEEP_MS,
 } from '../gateway/turn-active-marker.js'
 
 describe('turn-active-marker (#412)', () => {
@@ -28,6 +31,32 @@ describe('turn-active-marker (#412)', () => {
     rmSync(tmp, { recursive: true, force: true })
   })
 
+  it('exports the sweep TTL bounds as shared constants (#3262 single source of truth)', () => {
+    // The /model & /effort phantom-turn cross-check reuses these SAME bounds —
+    // guarding against a drift where the atom ceiling and the marker ceiling
+    // diverge into two different magic numbers.
+    expect(TURN_ACTIVE_HARD_TTL_MS).toBe(10 * 60_000)
+    expect(TURN_ACTIVE_IDLE_SWEEP_MS).toBe(60_000)
+    expect(TURN_ACTIVE_HARD_TTL_MS).toBeGreaterThan(TURN_ACTIVE_IDLE_SWEEP_MS)
+  })
+
+  it('effectiveTurnAgeMs prefers the marker age when present (#3262)', () => {
+    // Marker present (touched on tool_use) → its age wins over the fixed
+    // turn.startedAt, so a legitimately LONG turn that keeps touching the
+    // marker reads fresh and is never mis-swept as a phantom.
+    const now = 1_000_000
+    expect(effectiveTurnAgeMs(5_000, now - 9_999_999, now)).toBe(5_000)
+  })
+
+  it('effectiveTurnAgeMs falls back to now - startedAt when the marker is absent (#3262)', () => {
+    // Marker already swept (null age) → fall back to the turn-start timestamp,
+    // so a dangling atom whose marker was reaped still reports a large age and
+    // is recognised as stale by the /model & /effort cross-check.
+    const now = 1_000_000
+    const startedAt = now - 42_000
+    expect(effectiveTurnAgeMs(null, startedAt, now)).toBe(42_000)
+  })
+
   it('writeTurnActiveMarker creates a JSON file with the expected payload', () => {
     writeTurnActiveMarker(tmp, {
       turnKey: 'chat:1:1700000000000',

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

@@ -659,6 +659,10 @@ describe('createWorkerActivityFeed — heartbeat', () => {
       bot,
       now: () => clock,
       minEditIntervalMs: 2500,
+      // Suffix-mechanics test: pin the elapsed-refresh cadence to the edit floor
+      // so this exercises the classic 6s heartbeat suffix, not the coarse
+      // flood-pacing cadence (covered by its own tests below).
+      elapsedRefreshMs: 2500,
       heartbeatTickMs: 6000,
       // No real timer: drive ticks manually.
       setInterval: () => 1,
@@ -862,6 +866,10 @@ describe('createWorkerActivityFeed — heartbeat', () => {
       firstPaintMinMs: 8000,
       heartbeatTickMs: 6000,
       minEditIntervalMs: 2500,
+      // Heartbeat-liveness test: pin the elapsed-refresh cadence to the edit
+      // floor so a later heartbeat repaints the climbing clock under the classic
+      // 6s cadence (coarse flood-pacing is covered by its own tests below).
+      elapsedRefreshMs: 2500,
       setInterval: () => 1,
       clearInterval: () => {},
     })
@@ -1551,3 +1559,116 @@ describe('worker-feed send-gate shed contract', () => {
     expect(feed.has('w1')).toBe(false)
   })
 })
+
+// ─── elapsed-only edit pacing (flood-ban defense, Part 1) ────────────────────
+
+describe('createWorkerActivityFeed — elapsed-only edit pacing', () => {
+  const drain = () => new Promise((r) => setTimeout(r, 0))
+
+  function mkFeed(bot: FakeBot, nowRef: { t: number }) {
+    return createWorkerActivityFeed({
+      bot,
+      now: () => nowRef.t,
+      minEditIntervalMs: 2500,
+      elapsedRefreshMs: 15_000,
+      firstPaintMinMs: 8000,
+      heartbeatTickMs: 6000,
+      setInterval: () => 1,
+      clearInterval: () => {},
+    })
+  }
+
+  it('suppresses clock-only churn: elapsed advancing within elapsedRefreshMs emits NO edit', async () => {
+    const bot = makeFakeBot()
+    const ref = { t: 10_000 }
+    const feed = mkFeed(bot, ref)
+
+    // First paint.
+    ref.t = 20_000
+    await feed.update('w1', 'chat', view({ elapsedMs: 9000, latestSummary: 'scanning', toolCount: 3 }))
+    expect(bot.sent).toHaveLength(1)
+
+    // A stream of ticks where ONLY the elapsed clock advances (same step, same
+    // toolCount). Every one is past the 2.5s edit floor but under the 15s
+    // elapsed-refresh cadence measured from the last edit (paint @20_000) — so
+    // the send-gate-evading clock-only edit that earns a flood ban never fires.
+    for (const t of [23_000, 26_000, 30_000, 34_000]) {
+      ref.t = t
+      await feed.update('w1', 'chat', view({ elapsedMs: t - 11_000, latestSummary: 'scanning', toolCount: 3 }))
+    }
+    await drain()
+    expect(bot.edits).toHaveLength(0)
+  })
+
+  it('renders a substantive step change PROMPTLY (before the elapsed-refresh cadence)', async () => {
+    const bot = makeFakeBot()
+    const ref = { t: 10_000 }
+    const feed = mkFeed(bot, ref)
+
+    ref.t = 20_000
+    await feed.update('w1', 'chat', view({ elapsedMs: 9000, latestSummary: 'scanning', toolCount: 3 }))
+    expect(bot.sent).toHaveLength(1)
+
+    // 6s later: still under the 15s elapsed-refresh cadence, but the STEP and
+    // toolCount changed — a real update. It renders immediately (only the 2.5s
+    // floor applies), not held for the coarse clock cadence.
+    ref.t = 26_000
+    await feed.update('w1', 'chat', view({ elapsedMs: 15_000, latestSummary: 'writing report', toolCount: 4 }))
+    await drain()
+    expect(bot.edits.length).toBeGreaterThanOrEqual(1)
+    expect(bot.edits[bot.edits.length - 1].text).toContain('writing report')
+  })
+
+  it('forces the terminal edit through and renders the honest final elapsed', async () => {
+    const bot = makeFakeBot()
+    const ref = { t: 10_000 }
+    const feed = mkFeed(bot, ref)
+
+    ref.t = 20_000
+    await feed.update('w1', 'chat', view({ elapsedMs: 9000, latestSummary: 'scanning', toolCount: 3 }))
+    expect(bot.sent).toHaveLength(1)
+
+    // Completion within the elapsed-refresh window still finalizes immediately
+    // (terminal edits bypass the pacing) and shows the correct final elapsed.
+    ref.t = 28_000
+    await feed.finish('w1', view({ state: 'done', toolCount: 6, elapsedMs: 31_000, latestSummary: 'all done' }))
+    await drain()
+    expect(bot.edits.length).toBeGreaterThanOrEqual(1)
+    const last = bot.edits[bot.edits.length - 1].text
+    expect(last).toContain('done · 6 tools')
+    expect(last).toContain('31s')
+  })
+
+  it('does not over-suppress a substantive change that would field-boundary-collide under naive concatenation', async () => {
+    const bot = makeFakeBot()
+    const ref = { t: 10_000 }
+    const feed = mkFeed(bot, ref)
+
+    // Paint: toolCount 1, totalTokens 23. Under a delimiter-less substance key
+    // the fields `1` and `23` concatenate to `123`.
+    ref.t = 20_000
+    await feed.update(
+      'w1',
+      'chat',
+      view({ elapsedMs: 9000, latestSummary: 'scanning', toolCount: 1, totalTokens: 23 }),
+    )
+    expect(bot.sent).toHaveLength(1)
+
+    // A REAL substantive change (toolCount 1→12, totalTokens 23→3) that collides
+    // to the SAME `123` under naive concatenation. It lands within the 15s
+    // elapsed-refresh window (past the 2.5s floor), so ONLY a substance-key
+    // difference can drive the edit. A colliding key would wrongly treat this as
+    // elapsed-only churn and suppress it; the NUL/RS-delimited key keeps them
+    // distinct, so the edit fires promptly.
+    ref.t = 22_500
+    await feed.update(
+      'w1',
+      'chat',
+      view({ elapsedMs: 11_500, latestSummary: 'scanning', toolCount: 12, totalTokens: 3 }),
+    )
+    await drain()
+    expect(bot.edits.length).toBeGreaterThanOrEqual(1)
+    // The rendered card reflects the new tool count, proving the change landed.
+    expect(bot.edits[bot.edits.length - 1].text).toContain('12 tools')
+  })
+})