switchroom 0.18.7 → 0.18.9

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

@@ -0,0 +1,222 @@
+import { describe, it, expect } from 'vitest'
+import {
+  repairEscapedWhitespace,
+  normalizeParagraphBreaks,
+  normalizePunctuation,
+  stripExcessBold,
+  addParagraphSpacers,
+  splitMarkdownChunks,
+  hardSliceToCap,
+  RICH_MESSAGE_MAX_CHARS,
+} from '../format.js'
+import { scrubVoice } from '../text-voice-scrub.js'
+import { redact } from '../secret-detect/redact.js'
+import { OutboundDedupCache } from '../recent-outbound-dedup.js'
+import {
+  normalizeOutboundBody,
+  computeEffectiveText,
+  computeReplyChunks,
+  resplitOversizeChunk,
+  chunkText,
+} from '../gateway/outbound-send-path.js'
+
+/**
+ * Golden-transcript harness for the outbound send-path extraction (#2996,
+ * plan §3B).
+ *
+ * `executeReply` is not exported (same constraint the sibling
+ * gateway-outbound-redact.test.ts documents), so the golden reference is a
+ * VERBATIM inline copy of the pre-extraction pipeline transforms (below).
+ * Every fixture is run through BOTH the inline reference and the extracted
+ * `outbound-send-path.ts` module; the test asserts byte-identical output.
+ * If the extraction ever drifts from the inline pipeline, these diverge.
+ *
+ * The reference below is copied line-for-line from the executeReply entry
+ * (normalize → redact → punctuation/bold → voice scrub), the effective-text
+ * spacing decision, the chunk decision, and the oversize re-split. The
+ * `redact` injected here is the same `redact()` the gateway's
+ * `redactOutboundText` wraps.
+ */
+
+// ── Verbatim inline reference (the code as it lived in gateway.ts) ──────────
+
+function referenceNormalize(rawText: string): { text: string; voiceReplaced: number } {
+  let text = normalizeParagraphBreaks(repairEscapedWhitespace(rawText))
+  // redactOutboundText(text, 'reply') → redact(text) (the stderr log is a
+  // side effect the pure module leaves to the injected redactor).
+  text = redact(text)
+  text = stripExcessBold(normalizePunctuation(text))
+  let voiceReplaced = 0
+  const scrub = scrubVoice(text)
+  if (scrub.replaced > 0) {
+    text = scrub.scrubbed
+    voiceReplaced = scrub.replaced
+  }
+  return { text, voiceReplaced }
+}
+
+function referenceEffectiveText(text: string, literalText: boolean): string {
+  return literalText ? text : addParagraphSpacers(text)
+}
+
+function referenceChunks(
+  effectiveText: string,
+  literalText: boolean,
+  limit: number,
+  chunkMode: 'length' | 'newline',
+): string[] {
+  return literalText
+    ? chunkText(effectiveText, limit, chunkMode)
+    : splitMarkdownChunks(effectiveText, limit)
+}
+
+function referenceResplit(chunk: string): string[] {
+  const subPieces = splitMarkdownChunks(chunk, RICH_MESSAGE_MAX_CHARS)
+  return subPieces.length > 1 ? subPieces : hardSliceToCap(chunk, RICH_MESSAGE_MAX_CHARS)
+}
+
+const injectedRedact = (text: string, _site: string): string => redact(text)
+
+// ── Representative outbound fixtures ────────────────────────────────────────
+
+const FIXTURES: Record<string, string> = {
+  plain: 'Hello there, this is a normal reply.',
+  multiParagraph: 'First paragraph here.\n\nSecond paragraph here.\n\nThird one.',
+  codeFence:
+    'Here is code:\n\n```ts\nconst x = 1 // a comment — with an em-dash\nconst y = 2\n```\n\nDone.',
+  emDashes: 'This — that — and the other thing. En–dash here too.',
+  excessBold: '**bold one** and **bold two** and **bold three** and **bold four**.',
+  // Assembled at runtime so the source holds no contiguous token literal
+  // (scripts/check-no-pii-secrets.mjs rejects contiguous sk-ant-… literals).
+  secretApiKey: `Your key is ${'sk-ant-' + 'api03-' + 'ABCD'.repeat(12)} and more text.`,
+  jsonEscaped: 'Line one\\nLine two\\n\\nParagraph two with a \\t tab.',
+  bullets: '- item one\n- item two\n- item three with a — dash',
+  oversize: 'x'.repeat(RICH_MESSAGE_MAX_CHARS + 5000),
+  multiChunkProse: Array.from({ length: 60 }, (_, i) => `Paragraph number ${i} with some filler text to grow length.`).join('\n\n'),
+}
+
+describe('outbound-send-path — normalizeOutboundBody parity with inline pipeline', () => {
+  for (const [name, raw] of Object.entries(FIXTURES)) {
+    it(`normalize byte-identical: ${name}`, () => {
+      const ref = referenceNormalize(raw)
+      const got = normalizeOutboundBody(raw, 'reply', injectedRedact)
+      expect(got.text).toBe(ref.text)
+      expect(got.voiceReplaced).toBe(ref.voiceReplaced)
+    })
+  }
+
+  it('secret fixture is actually redacted (mask fired)', () => {
+    const got = normalizeOutboundBody(FIXTURES.secretApiKey, 'reply', injectedRedact)
+    expect(got.text).not.toContain('sk-ant-' + 'api03-' + 'ABCD'.repeat(12))
+  })
+
+  it('em/en dashes are removed by the normalize pipeline', () => {
+    const got = normalizeOutboundBody(FIXTURES.emDashes, 'reply', injectedRedact)
+    // normalizePunctuation + scrubVoice between them strip em/en dashes from
+    // prose; the exact stage that fires is an implementation detail, but no
+    // raw em-dash survives the pipeline.
+    expect(got.text).not.toContain('—')
+  })
+})
+
+describe('outbound-send-path — effective text + chunk parity', () => {
+  for (const [name, raw] of Object.entries(FIXTURES)) {
+    for (const literalText of [true, false]) {
+      it(`effectiveText + chunks byte-identical: ${name} literal=${literalText}`, () => {
+        const { text } = normalizeOutboundBody(raw, 'reply', injectedRedact)
+        const refEff = referenceEffectiveText(text, literalText)
+        const gotEff = computeEffectiveText(text, literalText)
+        expect(gotEff).toBe(refEff)
+
+        const limit = RICH_MESSAGE_MAX_CHARS
+        const chunkMode: 'length' | 'newline' = 'length'
+        const refChunks = referenceChunks(refEff, literalText, limit, chunkMode)
+        const gotChunks = computeReplyChunks({ effectiveText: gotEff, literalText, limit, chunkMode })
+        expect(gotChunks).toEqual(refChunks)
+      })
+    }
+  }
+
+  it('literal newline-mode chunking parity on a large body', () => {
+    const body = FIXTURES.multiChunkProse
+    const limit = 400
+    expect(computeReplyChunks({ effectiveText: body, literalText: true, limit, chunkMode: 'newline' }))
+      .toEqual(chunkText(body, limit, 'newline'))
+  })
+
+  it('oversize chunk re-split parity + every piece under the wire cap', () => {
+    const oversize = FIXTURES.oversize
+    const ref = referenceResplit(oversize)
+    const got = resplitOversizeChunk(oversize)
+    expect(got).toEqual(ref)
+    for (const piece of got) expect(piece.length).toBeLessThanOrEqual(RICH_MESSAGE_MAX_CHARS)
+  })
+})
+
+describe('outbound-send-path — chunkText golden snapshots', () => {
+  it('length mode hard-cuts at the limit', () => {
+    expect(chunkText('abcdefghij', 4, 'length')).toEqual(['abcd', 'efgh', 'ij'])
+  })
+  it('newline mode prefers a paragraph break past halfway', () => {
+    expect(chunkText('aaaa\n\nbbbbbbbb', 8, 'newline')).toEqual(['aaaa\n', 'bbbbbbbb'])
+  })
+  it('short text is returned whole', () => {
+    expect(chunkText('short', 100, 'length')).toEqual(['short'])
+  })
+})
+
+// ── Cross-surface dedup suppression (the load-bearing singleton contract) ────
+//
+// The plan calls out that `outboundDedup` MUST be the SAME injected instance
+// across executeReply / answer-stream / turn-flush — a hoist-once bug (the
+// gateway landmine comment) broke all three. The dedup KEY on every surface is
+// the post-`normalizeOutboundBody` text, so a stream-path record must suppress
+// a reply-path check for the same normalized content on the same singleton.
+
+describe('outbound-send-path — cross-surface dedup suppression', () => {
+  it('stream-path record suppresses reply-path check on the shared singleton', () => {
+    const dedup = new OutboundDedupCache()
+    const chatId = '12345'
+    const threadId = undefined
+    const turnKey = 'turn-abc'
+    const t0 = 1_000_000
+
+    // Both surfaces normalize the same raw model text identically.
+    const rawFromModel = 'The answer is 42 — computed carefully across the whole set of inputs.'
+    const streamText = normalizeOutboundBody(rawFromModel, 'stream_reply', injectedRedact).text
+    const replyText = normalizeOutboundBody(rawFromModel, 'reply', injectedRedact).text
+    expect(replyText).toBe(streamText) // same key on every surface
+
+    // Miss before anything recorded.
+    expect(dedup.check(chatId, threadId, replyText, t0, turnKey)).toBeNull()
+
+    // Answer-stream records first (same singleton, same turnKey).
+    dedup.record(chatId, threadId, streamText, t0, turnKey)
+
+    // Reply path now sees the within-turn duplicate and is suppressed.
+    const hit = dedup.check(chatId, threadId, replyText, t0 + 500, turnKey)
+    expect(hit).not.toBeNull()
+    expect(hit!.matched).toBe(true)
+  })
+
+  it('a DISTINCT normalized reply is NOT suppressed (no false dedup)', () => {
+    const dedup = new OutboundDedupCache()
+    const chatId = '12345'
+    const turnKey = 'turn-abc'
+    const t0 = 2_000_000
+    const a = normalizeOutboundBody('First distinct answer with enough length to record.', 'stream_reply', injectedRedact).text
+    const b = normalizeOutboundBody('Second completely different answer, also long enough.', 'reply', injectedRedact).text
+    dedup.record(chatId, undefined, a, t0, turnKey)
+    expect(dedup.check(chatId, undefined, b, t0 + 500, turnKey)).toBeNull()
+  })
+
+  it('cross-turn identical content is NOT suppressed (distinct turnKeys)', () => {
+    const dedup = new OutboundDedupCache()
+    const chatId = '12345'
+    const t0 = 3_000_000
+    const text = normalizeOutboundBody('Same content typed twice across two turns, long enough to record.', 'reply', injectedRedact).text
+    dedup.record(chatId, undefined, text, t0, 'turn-1')
+    // A later, separate turn with the same content still delivers.
+    expect(dedup.check(chatId, undefined, text, t0 + 500, 'turn-2')).toBeNull()
+  })
+})

package/telegram-plugin/tests/pending-card-durability-wiring.test.ts

@@ -20,6 +20,16 @@ import { dirname, resolve } from 'node:path'
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const read = (p: string) => readFileSync(resolve(__dirname, '..', p), 'utf8')
 const GATEWAY = read('gateway/gateway.ts')
+// #2996 Phase 3: the in-memory approval-card Maps + their TTL sweeps moved
+// behind approval-card-stores.ts. The gateway now delegates each family sweep
+// to `<store>.sweep(now)`; the per-entry sweepExpiredEntries guard lives in the
+// store module.
+const CARD_STORES = read('gateway/approval-card-stores.ts')
+// #2996 Phase 5: the callback-query handler families (vault access/save,
+// mental-model, deferred-secret, grant wizard, operator-event, auth dashboard)
+// moved verbatim behind callback-query-handlers.ts; handler-body pins read
+// that module while staging/boot/sweep wiring stays pinned on gateway.ts.
+const CB_HANDLERS = read('gateway/callback-query-handlers.ts')
 
 function slice(src: string, header: string, span = 3000): string {
   const start = src.indexOf(header)
@@ -90,7 +100,7 @@ describe('boot restore (Defect A)', () => {
   })
 
   it('a Save tap on a restored (valueless) card degrades gracefully instead of writing empty', () => {
-    const fn = slice(GATEWAY, 'async function handleVaultRequestSaveCallback', 9000)
+    const fn = slice(CB_HANDLERS, 'async function handleVaultRequestSaveCallback', 9000)
     expect(fn).toMatch(/pending\.restoredWithoutValue \|\| pending\.value\.length === 0/)
     expect(fn).toMatch(/lost to a gateway restart/)
     expect(fn).toMatch(/buildVaultSaveFailedInbound/)
@@ -102,15 +112,15 @@ describe('boot restore (Defect A)', () => {
 describe('resolution clears the durable store (Defect A)', () => {
   it('vault access approve/deny remove from the store', () => {
     // deny path
-    const deny = slice(GATEWAY, 'async function handleVaultRequestAccessCallback', 4000)
+    const deny = slice(CB_HANDLERS, 'async function handleVaultRequestAccessCallback', 4000)
     expect(deny).toMatch(/pendingCardStore\.remove\(stageId\)/)
     // approve path (performVaultAccessApproval) removes on every terminal branch
-    const approve = slice(GATEWAY, 'async function performVaultAccessApproval', 9000)
+    const approve = slice(CB_HANDLERS, 'async function performVaultAccessApproval', 9000)
     expect(approve).toMatch(/pendingCardStore\.remove\(stageId\)/)
   })
 
   it('vault save resolution paths remove from the store', () => {
-    const fn = slice(GATEWAY, 'async function handleVaultRequestSaveCallback', 12000)
+    const fn = slice(CB_HANDLERS, 'async function handleVaultRequestSaveCallback', 12000)
     // discard / write-fail / success / passphrase-missing all clear the store.
     const count = (fn.match(/pendingCardStore\.remove\(stageId\)/g) ?? []).length
     expect(count).toBeGreaterThanOrEqual(3)
@@ -124,7 +134,7 @@ describe('resolution clears the durable store (Defect A)', () => {
   })
 
   it('mental model resolve removes from the store', () => {
-    const fn = slice(GATEWAY, 'async function handleMentalModelProposeCallback', 4000)
+    const fn = slice(CB_HANDLERS, 'async function handleMentalModelProposeCallback', 4000)
     expect(fn).toMatch(/pendingCardStore\.remove\(stageId\)/)
   })
 })
@@ -141,10 +151,13 @@ describe('TTL expiry wakes the parked agent (Defect B)', () => {
   })
 
   it('sweepExpiredApprovalCards runs all four family sweeps', () => {
+    // #2996 Phase 3: three families now delegate to their store's `.sweep(now)`;
+    // request_secret still routes via sweepSecretRequests (which also sweeps the
+    // transient armedSecretCaptures) and that in turn calls the store sweep.
     const fn = slice(GATEWAY, 'function sweepExpiredApprovalCards', 600)
-    expect(fn).toMatch(/sweepPendingVaultRequestAccesses\(now\)/)
-    expect(fn).toMatch(/sweepPendingVaultRequestSaves\(now\)/)
-    expect(fn).toMatch(/sweepPendingMentalModelProposes\(now\)/)
+    expect(fn).toMatch(/pendingVaultRequestAccesses\.sweep\(now\)/)
+    expect(fn).toMatch(/pendingVaultRequestSaves\.sweep\(now\)/)
+    expect(fn).toMatch(/pendingMentalModelProposes\.sweep\(now\)/)
     expect(fn).toMatch(/sweepSecretRequests\(now\)/)
   })
 
@@ -173,14 +186,20 @@ describe('TTL expiry wakes the parked agent (Defect B)', () => {
   })
 
   it('each family sweep is per-entry guarded via sweepExpiredEntries', () => {
-    for (const fnName of [
-      'function sweepPendingVaultRequestAccesses',
-      'function sweepPendingVaultRequestSaves',
-      'function sweepPendingMentalModelProposes',
-      'function sweepSecretRequests',
+    // #2996 Phase 3: the per-entry guard moved into the store module's `.sweep`,
+    // which is a thin pass-through to the same pure sweepExpiredEntries core.
+    // The three vault/mental families delegate to that store method; the
+    // request_secret family's sweepSecretRequests delegates to it too.
+    expect(CARD_STORES).toMatch(/sweep:\s*\(now\)\s*=>\s*\n?\s*sweepExpiredEntries\(/)
+    const secretSweep = slice(GATEWAY, 'function sweepSecretRequests', 500)
+    expect(secretSweep).toMatch(/pendingSecretRequests\.sweep\(now\)/)
+    for (const store of [
+      'const pendingVaultRequestAccesses = createSweepableCardStore',
+      'const pendingVaultRequestSaves = createSweepableCardStore',
+      'const pendingMentalModelProposes = createSweepableCardStore',
+      'const pendingSecretRequests = createSweepableCardStore',
     ]) {
-      const fn = slice(GATEWAY, fnName, 500)
-      expect(fn, fnName).toMatch(/sweepExpiredEntries\(/)
+      expect(GATEWAY, store).toContain(store)
     }
   })
 

package/telegram-plugin/tests/pending-state-stores.test.ts

@@ -0,0 +1,235 @@
+/**
+ * Contract + race/ordering pins for the long-tail pending-state stores
+ * (gateway/pending-state-stores.ts), extracted in #2996 Phase 3 step 2.
+ *
+ * Written BEFORE the long-tail Maps moved behind the store module. They lock:
+ *
+ *   1. Each family's EXACT `isExpired` comparison direction survives verbatim —
+ *      TTL directions differ across families (`now - staged_at > TTL`,
+ *      `now - startedAt > TTL`, `now - createdAt > TTL`, `now - armed_at > TTL`,
+ *      and the absolute `now > expiresAt`), and a store must delete exactly the
+ *      entries the old open-coded loop deleted, not one tick early or late.
+ *   2. `sweep` is delete-during-iteration safe (JS Map iterators tolerate
+ *      deleting the current key — the raw reaper loops relied on this).
+ *   3. The gateway-visible EAGER-SWEEP-AT-ADD pattern (the sweep called right
+ *      after a `.set` at a staging site, e.g. `sweepSecretRequests()` after the
+ *      `pendingSecretRequests.set` in executeRequestSecret) is single-shot: an
+ *      add followed by an eager sweep expires only entries already past TTL and
+ *      leaves the just-added fresh entry intact.
+ *   4. Map-surface parity for every operation the call sites use, including the
+ *      LRU eviction pattern `agentButtonMeta` uses (`keys().next().value`) and
+ *      the live `size` getter.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  createSweepableStore,
+  createPlainStore,
+} from '../gateway/pending-state-stores.js'
+
+// TTL constants mirror the gateway family values so the direction pins are
+// meaningful (values themselves are not the contract — the direction is).
+const VAULT_INPUT_TTL_MS = 5 * 60 * 1000
+const VAULT_PASSPHRASE_TTL_MS = 30 * 60 * 1000
+const DEFERRED_SECRET_TTL_MS = 5 * 60 * 1000
+const ARMED_SECRET_CAPTURE_TTL_MS = 10 * 60_000
+const ALWAYS_ALLOW_CORRELATION_TTL_MS = 30_000
+const MENTAL_MODEL_CORRELATION_TTL_MS = 720_000
+const REAUTH_INTERCEPT_TTL_MS = 10 * 60_000
+
+describe('pending-state-stores: per-family isExpired direction (byte-identical)', () => {
+  it('pendingVaultOps — now - startedAt > VAULT_INPUT_TTL_MS', () => {
+    const store = createSweepableStore<{ startedAt: number }>(
+      (v, now) => now - v.startedAt > VAULT_INPUT_TTL_MS,
+    )
+    const now = 10_000_000
+    store.set('fresh', { startedAt: now - VAULT_INPUT_TTL_MS }) // exactly TTL old: NOT expired (> is strict)
+    store.set('stale', { startedAt: now - VAULT_INPUT_TTL_MS - 1 })
+    store.sweep(now)
+    expect(store.has('fresh')).toBe(true)
+    expect(store.has('stale')).toBe(false)
+  })
+
+  it('vaultPassphraseCache — absolute now > expiresAt', () => {
+    const store = createSweepableStore<{ expiresAt: number }>(
+      (v, now) => now > v.expiresAt,
+    )
+    const now = 10_000_000
+    store.set('atExpiry', { expiresAt: now }) // now > now is false → NOT expired
+    store.set('past', { expiresAt: now - 1 })
+    store.sweep(now)
+    expect(store.has('atExpiry')).toBe(true)
+    expect(store.has('past')).toBe(false)
+    void VAULT_PASSPHRASE_TTL_MS
+  })
+
+  it('deferredSecrets — now - staged_at > DEFERRED_SECRET_TTL_MS', () => {
+    const store = createSweepableStore<{ staged_at: number }>(
+      (v, now) => now - v.staged_at > DEFERRED_SECRET_TTL_MS,
+    )
+    const now = 10_000_000
+    store.set('fresh', { staged_at: now - DEFERRED_SECRET_TTL_MS })
+    store.set('stale', { staged_at: now - DEFERRED_SECRET_TTL_MS - 1 })
+    store.sweep(now)
+    expect(store.has('fresh')).toBe(true)
+    expect(store.has('stale')).toBe(false)
+  })
+
+  it('armedSecretCaptures — now - armed_at > ARMED_SECRET_CAPTURE_TTL_MS', () => {
+    const store = createSweepableStore<{ armed_at: number }>(
+      (v, now) => now - v.armed_at > ARMED_SECRET_CAPTURE_TTL_MS,
+    )
+    const now = 10_000_000
+    store.set('fresh', { armed_at: now - ARMED_SECRET_CAPTURE_TTL_MS })
+    store.set('stale', { armed_at: now - ARMED_SECRET_CAPTURE_TTL_MS - 1 })
+    store.sweep(now)
+    expect(store.has('fresh')).toBe(true)
+    expect(store.has('stale')).toBe(false)
+  })
+
+  it('pendingAlwaysAllowCorrelations — 30s now - createdAt > TTL', () => {
+    const store = createSweepableStore<{ createdAt: number }>(
+      (v, now) => now - v.createdAt > ALWAYS_ALLOW_CORRELATION_TTL_MS,
+    )
+    const now = 10_000_000
+    store.set('fresh', { createdAt: now - ALWAYS_ALLOW_CORRELATION_TTL_MS })
+    store.set('stale', { createdAt: now - ALWAYS_ALLOW_CORRELATION_TTL_MS - 1 })
+    store.sweep(now)
+    expect(store.has('fresh')).toBe(true)
+    expect(store.has('stale')).toBe(false)
+  })
+
+  it('pendingMentalModelCorrelations — 720s now - createdAt > TTL (outlives the 30s window)', () => {
+    const store = createSweepableStore<{ createdAt: number }>(
+      (v, now) => now - v.createdAt > MENTAL_MODEL_CORRELATION_TTL_MS,
+    )
+    const now = 10_000_000
+    // A slow-but-valid tap 10 min in must NOT be swept (the whole point of the
+    // dedicated 720s TTL vs the 30s always-allow window).
+    store.set('slowTap', { createdAt: now - 10 * 60_000 })
+    store.set('stale', { createdAt: now - MENTAL_MODEL_CORRELATION_TTL_MS - 1 })
+    store.sweep(now)
+    expect(store.has('slowTap')).toBe(true)
+    expect(store.has('stale')).toBe(false)
+  })
+
+  it('pendingReauthFlows — now - startedAt > REAUTH_INTERCEPT_TTL_MS', () => {
+    const store = createSweepableStore<{ startedAt: number }>(
+      (v, now) => now - v.startedAt > REAUTH_INTERCEPT_TTL_MS,
+    )
+    const now = 10_000_000
+    store.set('fresh', { startedAt: now - REAUTH_INTERCEPT_TTL_MS })
+    store.set('stale', { startedAt: now - REAUTH_INTERCEPT_TTL_MS - 1 })
+    store.sweep(now)
+    expect(store.has('fresh')).toBe(true)
+    expect(store.has('stale')).toBe(false)
+  })
+})
+
+describe('pending-state-stores: sweep safety', () => {
+  it('deletes every past-TTL entry across a multi-entry map (delete-during-iteration safe)', () => {
+    const store = createSweepableStore<{ staged_at: number }>(
+      (v, now) => now - v.staged_at > 1000,
+    )
+    for (let i = 0; i < 10; i++) store.set(`e${i}`, { staged_at: i % 2 === 0 ? 0 : 9_999_999 })
+    store.sweep(1_000_000) // even entries stale, odd entries fresh
+    for (let i = 0; i < 10; i++) {
+      expect(store.has(`e${i}`)).toBe(i % 2 === 1)
+    }
+  })
+
+  it('is single-shot across two sweep ticks', () => {
+    const store = createSweepableStore<{ staged_at: number }>(
+      (v, now) => now - v.staged_at > 1000,
+    )
+    store.set('one', { staged_at: 0 })
+    store.sweep(1_000_000)
+    expect(store.size).toBe(0)
+    expect(() => store.sweep(1_000_000)).not.toThrow() // second tick — nothing left
+    expect(store.size).toBe(0)
+  })
+})
+
+describe('pending-state-stores: eager-sweep-at-add pattern (gateway-visible)', () => {
+  // Mirrors executeRequestSecret: dedupe-drop prior stage for the same target,
+  // .set the new one, then eagerly sweep. The just-added fresh entry survives;
+  // a stale sibling is reaped in the same eager pass.
+  it('add + eager sweep expires only stale siblings, keeps the fresh add', () => {
+    const TTL = 30 * 60_000
+    const store = createSweepableStore<{ chat_id: string; key: string; staged_at: number }>(
+      (v, now) => now - v.staged_at > TTL,
+    )
+    const now = 100_000_000
+    store.set('old', { chat_id: 'c', key: 'k1', staged_at: now - TTL - 1 }) // stale
+    // Dedupe pass (same target) would delete a live dup; here targets differ.
+    const fresh = { chat_id: 'c', key: 'k2', staged_at: now }
+    store.set('new', fresh)
+    store.sweep(now) // eager sweep at the add site
+    expect(store.has('new')).toBe(true) // fresh add never self-expires
+    expect(store.get('new')).toBe(fresh)
+    expect(store.has('old')).toBe(false) // stale sibling reaped in the eager pass
+  })
+
+  it('dedupe-then-add-then-sweep leaves exactly the new entry', () => {
+    const TTL = 30 * 60_000
+    const store = createSweepableStore<{ chat_id: string; key: string; staged_at: number }>(
+      (v, now) => now - v.staged_at > TTL,
+    )
+    const now = 100_000_000
+    store.set('dup', { chat_id: 'c', key: 'k', staged_at: now - 1000 })
+    // dedupe: drop prior stage for the same (chat, key)
+    for (const [sid, p] of store) {
+      if (p.chat_id === 'c' && p.key === 'k') store.delete(sid)
+    }
+    store.set('fresh', { chat_id: 'c', key: 'k', staged_at: now })
+    store.sweep(now)
+    expect([...store.keys()]).toEqual(['fresh'])
+  })
+})
+
+describe('pending-state-stores: plain store (no sweep)', () => {
+  it('has no sweep method and preserves Map surface', () => {
+    const store = createPlainStore<{ n: number }>()
+    expect((store as { sweep?: unknown }).sweep).toBeUndefined()
+    store.set('a', { n: 1 })
+    store.set('b', { n: 2 })
+    expect(store.size).toBe(2)
+    expect(store.get('a')?.n).toBe(1)
+    expect(store.has('b')).toBe(true)
+    expect(store.delete('a')).toBe(true)
+    expect(store.has('a')).toBe(false)
+  })
+
+  it('agentButtonMeta LRU eviction — keys().next().value is the oldest insertion', () => {
+    const AGENT_BUTTON_META_MAX = 3
+    const store = createPlainStore<Map<string, { ack: string }>>()
+    const remember = (key: string) => {
+      store.set(key, new Map([['cb', { ack: key }]]))
+      while (store.size > AGENT_BUTTON_META_MAX) {
+        const oldest = store.keys().next().value
+        if (oldest === undefined) break
+        store.delete(oldest)
+      }
+    }
+    remember('m1')
+    remember('m2')
+    remember('m3')
+    remember('m4') // evicts m1 (oldest insertion)
+    expect(store.has('m1')).toBe(false)
+    expect([...store.keys()]).toEqual(['m2', 'm3', 'm4'])
+    expect(store.get('m4')?.get('cb')?.ack).toBe('m4')
+  })
+
+  it('pendingAskUser surface — values()/entries()/get/delete used by call sites', () => {
+    const store = createPlainStore<{ chatId: string; messageId: number | null }>()
+    store.set('ask1', { chatId: 'c1', messageId: 10 })
+    store.set('ask2', { chatId: 'c2', messageId: null })
+    expect([...store.values()].map((v) => v.chatId).sort()).toEqual(['c1', 'c2'])
+    const collected: string[] = []
+    for (const [askId] of store.entries()) collected.push(askId)
+    expect(collected.sort()).toEqual(['ask1', 'ask2'])
+    expect(store.get('ask1')?.messageId).toBe(10)
+    store.delete('ask1')
+    expect(store.size).toBe(1)
+  })
+})

package/telegram-plugin/tests/pty-partial-handler.test.ts

@@ -9,6 +9,7 @@ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
 import {
   createPtyPartialHandler,
   handlePtyPartialPure,
+  looksLikeRawApiError,
   type PtyHandlerState,
   type PtyHandlerDeps,
 } from '../pty-partial-handler.js'
@@ -65,6 +66,35 @@ describe('handlePtyPartialPure', () => {
     expect(bot.api.sendMessage).not.toHaveBeenCalled()
   })
 
+  it('suppresses a raw API-error TUI line so it never leaks to chat (#2922 Bug 3)', async () => {
+    const state = makeState({ currentSessionChatId: '1' })
+    const deps = makeDeps(bot)
+    // The exact shape Claude Code's TUI renders on a transient 429.
+    const raw =
+      "API Error: Server is temporarily limiting requests (not your usage limit) · " +
+      "b'{\"type\":\"error\",\"error\":{\"type\":\"rate_limit_error\"}}'"
+    const action = handlePtyPartialPure(raw, state, deps)
+    expect(action).toBe('error-suppressed')
+    await microtaskFlush()
+    // Nothing sent — the operator-event pipeline owns the user-facing card.
+    expect(bot.api.sendMessage).not.toHaveBeenCalled()
+    expect(state.activeDraftStreams.size).toBe(0)
+    // Not recorded as a preview, so it can't poison later dedup either.
+    expect(state.lastPtyPreviewByChat.size).toBe(0)
+  })
+
+  it('does NOT suppress ordinary assistant text that merely mentions errors', async () => {
+    const state = makeState({ currentSessionChatId: '1' })
+    const action = handlePtyPartialPure(
+      "Here's how to handle an error in your retry loop:",
+      state,
+      makeDeps(bot),
+    )
+    expect(action).toBe('update-new')
+    await microtaskFlush()
+    expect(bot.api.sendMessage).toHaveBeenCalledTimes(1)
+  })
+
   it('dedups when same text arrives twice in a row', async () => {
     const state = makeState({ currentSessionChatId: '1' })
     const deps = makeDeps(bot)
@@ -324,3 +354,29 @@ describe('createPtyPartialHandler — session + buffer replay', () => {
     expect(state.activeDraftStreams.size).toBe(0)
   })
 })
+
+describe('looksLikeRawApiError (#2922 Bug 3)', () => {
+  it('flags the CLI "API Error: … · b\'{…}\'" line', () => {
+    expect(
+      looksLikeRawApiError(
+        "API Error: Server is temporarily limiting requests · b'{\"type\":\"error\"}'",
+      ),
+    ).toBe(true)
+  })
+
+  it('flags a bare rate_limit_error JSON body', () => {
+    expect(
+      looksLikeRawApiError('{"type":"error","error":{"type":"rate_limit_error"}}'),
+    ).toBe(true)
+  })
+
+  it('flags overloaded_error and is_error markers', () => {
+    expect(looksLikeRawApiError('{"type":"overloaded_error"}')).toBe(true)
+    expect(looksLikeRawApiError('{"is_error":true,"content":"boom"}')).toBe(true)
+  })
+
+  it('does not flag ordinary prose mentioning "error"', () => {
+    expect(looksLikeRawApiError('I hit an error handling that request')).toBe(false)
+    expect(looksLikeRawApiError('')).toBe(false)
+  })
+})