switchroom 0.18.6 → 0.18.8

package/telegram-plugin/tests/approval-card-restart-outcome.test.ts

@@ -0,0 +1,218 @@
+/**
+ * Outcome-based composition test for the approval/restart continuation
+ * contract in `reference/jobs/approve-what-my-agent-can-touch.md`:
+ *
+ *   - "An approval card survives a gateway restart. A tap on a still-valid
+ *      card after a restart works; a card that expired during the outage is
+ *      re-offered on the operator's return."
+ *   - "Cards time out (60-min default) and the timeout wakes the agent as a
+ *      timeout, not a denial ... An expired card is re-offered when the
+ *      operator returns."
+ *
+ * The sibling suites pin each module in isolation (pending-card-store.test.ts,
+ * pending-card-expiry.test.ts with mocked deps, approval-timeout-inbound-
+ * builders.test.ts) and pending-card-durability-wiring.test.ts pins the
+ * gateway wiring at the source-text level. This suite wires the REAL modules
+ * together — file-backed durable store + real missed-approvals store + real
+ * expiry sweep + real timeout builders — across a simulated gateway bounce
+ * (store re-instantiation from the same state dir), asserting the promised
+ * OUTCOMES rather than any one module's contract.
+ *
+ * SCOPE CAVEAT: the expiry predicate / remove / deliver / recordMiss closures
+ * below are TEST-SUPPLIED stand-ins for gateway.ts's inline closures (which
+ * close over module-level gateway state and can't be imported without a
+ * production refactor). This suite therefore proves the modules COMPOSE
+ * correctly; that gateway.ts actually wires them this way is pinned
+ * separately by pending-card-durability-wiring.test.ts's source greps. The
+ * user-visible acceptance twin is
+ * `uat/scenarios/vault-card-survives-gateway-restart-dm.test.ts`.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import {
+  createPendingCardStore,
+  type PersistedApprovalCard,
+  type PersistedVaultAccessCard,
+} from '../gateway/pending-card-store.js'
+import { createMissedApprovalsStore } from '../gateway/missed-approvals-store.js'
+import { expirePendingCard, sweepExpiredEntries } from '../gateway/pending-card-expiry.js'
+import { buildVaultAccessTimeoutInbound } from '../gateway/approval-timeout-inbound-builders.js'
+import type { InboundMessage } from '../gateway/ipc-protocol.js'
+
+// Test-local stand-in for the 60-min default the spec names. The production
+// TTL comes from approvalTtlMs() in gateway/permission-timeout.ts; this suite
+// does NOT assert that config plumbing — only how the modules behave around
+// whatever TTL the sweep predicate encodes.
+const TTL_MS = 60 * 60_000
+const NOW = 1_700_000_000_000
+
+function accessCard(overrides: Partial<PersistedVaultAccessCard> = {}): PersistedVaultAccessCard {
+  return {
+    family: 'vault_request_access',
+    stageId: 'stage-1',
+    agent: 'test-agent',
+    chatId: '12345',
+    cardMessageId: 777,
+    stagedAt: NOW - 60_000, // staged a minute ago — still valid
+    key: 'example/api-key',
+    scope: 'read',
+    ttlSeconds: 30 * 86_400,
+    ...overrides,
+  }
+}
+
+describe('approval/restart continuation — spec outcomes across a gateway bounce', () => {
+  let stateDir: string
+
+  beforeEach(() => {
+    stateDir = mkdtempSync(join(tmpdir(), 'approval-card-restart-outcome-'))
+  })
+  afterEach(() => {
+    rmSync(stateDir, { recursive: true, force: true })
+  })
+
+  it('a still-valid card record survives the bounce intact, and removing it clears the durable store', () => {
+    // Gateway process #1 stages the card.
+    const before = createPendingCardStore(stateDir)
+    const card = accessCard()
+    before.add(card)
+
+    // ── gateway restarts: all in-memory maps are gone ──
+    const after = createPendingCardStore(stateDir)
+    const restored = after.loadAll()
+    expect(restored).toHaveLength(1)
+    // Metadata roundtrips byte-identical — stagedAt included, so the expiry
+    // deadline the sweep computes from it is unchanged by the bounce.
+    expect(restored[0]).toEqual(card)
+
+    // Post-restart resolution path (what a tap handler does with the store):
+    // remove() drops the durable record so a later boot can't resurrect it.
+    // The tap handler's Telegram/grant side is NOT exercised here — that's
+    // the UAT twin's job.
+    after.remove(card.stageId)
+    expect(after.loadAll()).toHaveLength(0)
+  })
+
+  it('a card that expired during the outage wakes the agent ONCE as timeout-not-denial and records the re-offer', () => {
+    // Staged well past the TTL before the bounce.
+    const expired = accessCard({ stageId: 'stage-expired', stagedAt: NOW - TTL_MS - 60_000 })
+    createPendingCardStore(stateDir).add(expired)
+
+    // ── restart: restore into the in-memory map, then the reaper sweeps ──
+    const store = createPendingCardStore(stateDir)
+    const missed = createMissedApprovalsStore(stateDir)
+    const map = new Map<string, PersistedVaultAccessCard>(
+      store.loadAll().map(e => [e.stageId, e as PersistedVaultAccessCard]),
+    )
+    expect(map.size).toBe(1)
+
+    const delivered: InboundMessage[] = []
+    const sweep = () =>
+      sweepExpiredEntries(
+        map,
+        (v, now) => v.stagedAt < now - TTL_MS,
+        (stageId, v) => {
+          expirePendingCard({
+            remove: () => {
+              map.delete(stageId)
+              store.remove(stageId)
+            },
+            editCard: () => {},
+            buildInbound: () =>
+              buildVaultAccessTimeoutInbound({
+                agent: v.agent,
+                chatId: v.chatId,
+                stageId,
+                timeoutMinutes: Math.round(TTL_MS / 60_000),
+                nowMs: NOW,
+                key: v.key,
+                scope: v.scope,
+              }),
+            deliver: m => {
+              delivered.push(m)
+              return true
+            },
+            recordMiss: () =>
+              missed.add({
+                requestId: `approval-card:${stageId}`,
+                toolName: 'vault_request_access',
+                action: `vault access to ${v.key}`,
+                chatId: v.chatId,
+                timedOutAt: NOW,
+              }),
+            log: () => {},
+          })
+        },
+        NOW,
+        () => {},
+      )
+
+    sweep()
+
+    // Exactly one wake, and it is a TIMEOUT, never a denial.
+    expect(delivered).toHaveLength(1)
+    expect(delivered[0].text).toMatch(/TIMEOUT, not a denial/)
+    expect(delivered[0].text).toContain('example/api-key')
+    expect(delivered[0].meta?.source).toBe('vault_grant_timeout')
+
+    // The re-offer is durably recorded for the operator's return.
+    const pending = missed.listPending()
+    expect(pending).toHaveLength(1)
+    expect(pending[0].requestId).toBe('approval-card:stage-expired')
+
+    // Durable record is gone — a later boot can't resurrect the card.
+    expect(store.loadAll()).toHaveLength(0)
+
+    // A second boot's sweep restores from the (now empty) durable store and
+    // therefore fires nothing — the remove() step cleared BOTH the in-memory
+    // map and the store, so no later process can re-deliver the wake. (The
+    // intra-process single-shot ordering guarantee — remove() before any
+    // fallible side effect — is pinned behaviorally in
+    // pending-card-expiry.test.ts, not here.)
+    const rebootMap = new Map<string, PersistedVaultAccessCard>(
+      createPendingCardStore(stateDir)
+        .loadAll()
+        .map(e => [e.stageId, e as PersistedVaultAccessCard]),
+    )
+    expect(rebootMap.size).toBe(0)
+    let secondBootExpiries = 0
+    sweepExpiredEntries(
+      rebootMap,
+      (v, now) => v.stagedAt < now - TTL_MS,
+      () => {
+        secondBootExpiries += 1
+      },
+      NOW,
+      () => {},
+    )
+    expect(secondBootExpiries).toBe(0)
+    expect(delivered).toHaveLength(1)
+  })
+
+  it('the post-restart sweep never expires a still-valid card (no false timeout on bounce)', () => {
+    const valid = accessCard({ stageId: 'stage-valid', stagedAt: NOW - 60_000 })
+    createPendingCardStore(stateDir).add(valid)
+
+    const store = createPendingCardStore(stateDir)
+    const map = new Map<string, PersistedApprovalCard>(store.loadAll().map(e => [e.stageId, e]))
+
+    let expiredCount = 0
+    sweepExpiredEntries(
+      map,
+      (v, now) => v.stagedAt < now - TTL_MS,
+      () => {
+        expiredCount += 1
+      },
+      NOW,
+      () => {},
+    )
+
+    expect(expiredCount).toBe(0)
+    expect(map.size).toBe(1) // the card stays live and tappable
+    expect(store.loadAll()).toHaveLength(1)
+  })
+})

package/telegram-plugin/tests/approval-timeout-inbound-builders.test.ts

@@ -0,0 +1,94 @@
+/**
+ * Pin the synthetic-inbound shapes the gateway injects when an agent-initiated
+ * approval card TTL-expires unanswered (the "wake the parked agent on timeout"
+ * half of the durability fix). A regression that drops/changes `meta.source`
+ * silently breaks the wake-up: the bridge wouldn't recognize the source and the
+ * model wouldn't know its card timed out.
+ *
+ * The load-bearing wording invariant: each message says TIMEOUT, not a denial,
+ * matching the permission-card philosophy so the model degrades gracefully
+ * instead of spam-re-requesting into an absent operator.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  buildVaultAccessTimeoutInbound,
+  buildVaultSaveTimeoutInbound,
+  buildSecretRequestTimeoutInbound,
+  buildMentalModelProposeTimeoutInbound,
+} from '../gateway/approval-timeout-inbound-builders.js'
+
+const FIXED_NOW = 1_700_000_000_000
+const BASE = { agent: 'gymbro', chatId: '12345', stageId: 's1', timeoutMinutes: 60, nowMs: FIXED_NOW }
+
+describe('timeout inbound builders — envelope', () => {
+  const cases = [
+    buildVaultAccessTimeoutInbound({ ...BASE, key: 'fatsecret/creds', scope: 'read' }),
+    buildVaultSaveTimeoutInbound({ ...BASE, key: 'brevo/api-key' }),
+    buildSecretRequestTimeoutInbound({ ...BASE, key: 'openai/token' }),
+    buildMentalModelProposeTimeoutInbound({ ...BASE, name: 'training-plan-state' }),
+  ]
+
+  it('all share the canonical vault-broker envelope', () => {
+    for (const m of cases) {
+      expect(m.type).toBe('inbound')
+      expect(m.chatId).toBe('12345')
+      expect(m.user).toBe('vault-broker')
+      expect(m.userId).toBe(0)
+      expect(m.ts).toBe(FIXED_NOW)
+      expect(m.messageId).toBe(FIXED_NOW)
+      expect(m.meta?.agent).toBe('gymbro')
+      expect(m.meta?.stage_id).toBe('s1')
+    }
+  })
+
+  it('every message says TIMEOUT, not a denial (degrade-gracefully wording)', () => {
+    for (const m of cases) {
+      expect(m.text).toMatch(/TIMEOUT, not a denial/)
+      expect(m.text).toMatch(/60 min/)
+      expect(m.text).toMatch(/Do NOT (re-request|loop|re-propose)/i)
+    }
+  })
+})
+
+describe('timeout inbound builders — distinct sources', () => {
+  it('pins each meta.source string (load-bearing for the bridge)', () => {
+    expect(buildVaultAccessTimeoutInbound({ ...BASE, key: 'k', scope: 'read' }).meta?.source).toBe('vault_grant_timeout')
+    expect(buildVaultSaveTimeoutInbound({ ...BASE, key: 'k' }).meta?.source).toBe('vault_save_timeout')
+    expect(buildSecretRequestTimeoutInbound({ ...BASE, key: 'k' }).meta?.source).toBe('secret_request_timeout')
+    expect(buildMentalModelProposeTimeoutInbound({ ...BASE, name: 'n' }).meta?.source).toBe('mental_model_propose_timeout')
+  })
+
+  it('sources are all disjoint', () => {
+    const sources = [
+      buildVaultAccessTimeoutInbound({ ...BASE, key: 'k', scope: 'read' }).meta?.source,
+      buildVaultSaveTimeoutInbound({ ...BASE, key: 'k' }).meta?.source,
+      buildSecretRequestTimeoutInbound({ ...BASE, key: 'k' }).meta?.source,
+      buildMentalModelProposeTimeoutInbound({ ...BASE, name: 'n' }).meta?.source,
+    ]
+    expect(new Set(sources).size).toBe(4)
+  })
+})
+
+describe('timeout inbound builders — topic routing', () => {
+  const THREAD = 4242
+  it('threadId set → top-level threadId + meta.message_thread_id (stringified)', () => {
+    const m = buildVaultAccessTimeoutInbound({ ...BASE, threadId: THREAD, key: 'k', scope: 'write' })
+    expect(m.threadId).toBe(THREAD)
+    expect(m.meta?.message_thread_id).toBe(String(THREAD))
+    expect(m.meta?.scope).toBe('write')
+  })
+  it('threadId absent → both omitted (DM stays thread-less)', () => {
+    const m = buildVaultSaveTimeoutInbound({ ...BASE, key: 'k' })
+    expect(m.threadId).toBeUndefined()
+    expect(m.meta?.message_thread_id).toBeUndefined()
+  })
+  it('defaults nowMs to Date.now() when omitted', () => {
+    const before = Date.now()
+    const m = buildSecretRequestTimeoutInbound({ agent: 'a', chatId: '1', stageId: 's', timeoutMinutes: 30, key: 'k' })
+    const after = Date.now()
+    expect(m.ts).toBeGreaterThanOrEqual(before)
+    expect(m.ts).toBeLessThanOrEqual(after)
+    expect(m.messageId).toBe(m.ts)
+  })
+})

package/telegram-plugin/tests/boot-card-flood-suppress.test.ts

@@ -0,0 +1,111 @@
+/**
+ * #2923 — boot-card flood-wait suppression. When a Telegram per-bot flood ban
+ * is active, a restart's boot card is a NON-ESSENTIAL send straight into the
+ * open window that can reset/extend the ban. startBootCard must SKIP the send
+ * (and log) while the flood-wait is active, and post normally once it lifts.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { startBootCard } from '../gateway/boot-card.js'
+import type { BotApiForBootCard } from '../gateway/boot-card.js'
+import { computeFloodWait, writeFloodState, floodStatePath, makeFloodWaitRecorder } from '../flood-circuit-breaker.js'
+import { createRetryApiCall } from '../retry-api-call.js'
+import { errors } from './fake-bot-api.js'
+
+let dir: string
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'boot-card-flood-'))
+})
+afterEach(() => rmSync(dir, { recursive: true, force: true }))
+
+function makeBot() {
+  const sends: string[] = []
+  const bot: BotApiForBootCard = {
+    sendMessage: async (chatId, _text, _opts) => {
+      sends.push(chatId)
+      return { message_id: 1001 }
+    },
+    editMessageText: async () => ({}),
+  }
+  return { bot, sends }
+}
+
+function mkOpts(floodPath: string, nowMs: number, overrides: Record<string, unknown> = {}) {
+  return {
+    agentName: 'TestAgent',
+    agentSlug: 'test-agent',
+    version: 'v0.0.0-test',
+    agentDir: dir,
+    gatewayInfo: { pid: 1, startedAtMs: nowMs },
+    restartReason: 'graceful' as const,
+    agentLiveWindowMs: 0,
+    settleWindowMs: 1_000_000,
+    floodStatePath: floodPath,
+    nowMs: () => nowMs,
+    ...overrides,
+  } as unknown as Parameters<typeof startBootCard>[3]
+}
+
+it('SUPPRESSES the boot card while a flood-wait is active', async () => {
+  const p = floodStatePath(dir)
+  const now = 1_000_000
+  writeFloodState(p, computeFloodWait(null, 68 * 60, now)) // ~68 min ban
+  const logs: string[] = []
+  const { bot, sends } = makeBot()
+  const handle = await startBootCard('chat1', undefined, bot, mkOpts(p, now), undefined, (l) =>
+    logs.push(l),
+  )
+  expect(sends).toEqual([]) // nothing sent into the open ban window
+  expect(handle.messageId).toBe(-1)
+  expect(logs.join('')).toMatch(/SUPPRESSED/)
+})
+
+it('POSTS the boot card once the flood-wait has lifted', async () => {
+  const p = floodStatePath(dir)
+  const banStart = 1_000_000
+  writeFloodState(p, computeFloodWait(null, 60, banStart))
+  const afterBan = banStart + 60_000 + 1
+  const { bot, sends } = makeBot()
+  await startBootCard('chat1', undefined, bot, mkOpts(p, afterBan), undefined, () => {})
+  expect(sends).toEqual(['chat1'])
+})
+
+it('POSTS normally when no flood state file exists (back-compat)', async () => {
+  const p = floodStatePath(dir) // never written
+  const { bot, sends } = makeBot()
+  await startBootCard('chat1', undefined, bot, mkOpts(p, 1_000_000), undefined, () => {})
+  expect(sends).toEqual(['chat1'])
+})
+
+it('INTEGRATION: a 429 through the real retry path suppresses a later boot card', async () => {
+  // Wire the two halves exactly as gateway.ts does: the retry wrapper's
+  // onFloodWait recorder and the boot card BOTH point at the same file.
+  const p = floodStatePath(dir)
+  const now = 5_000_000
+  const retry = createRetryApiCall({
+    sleep: async () => {}, // don't actually wait out the flood
+    onFloodWait: makeFloodWaitRecorder(p, () => now),
+  })
+
+  // Drive a real GrammyError 429 through the wrapper (first call floods, then
+  // succeeds) — this is what records the window on disk.
+  let n = 0
+  await retry(async () => {
+    if (n++ === 0) throw errors.floodWait(4116) // ~68 min ban
+    return 'ok'
+  })
+
+  // Now a restart's boot card must be suppressed via the SAME file.
+  const { bot, sends } = makeBot()
+  const logs: string[] = []
+  const handle = await startBootCard('chat1', undefined, bot, mkOpts(p, now), undefined, (l) =>
+    logs.push(l),
+  )
+  expect(sends).toEqual([]) // not posted into the open ban window
+  expect(handle.messageId).toBe(-1)
+  expect(logs.join('')).toMatch(/SUPPRESSED/)
+})

package/telegram-plugin/tests/busy-ack-wiring.test.ts

@@ -0,0 +1,118 @@
+/**
+ * #2995 — mid-flight busy ack: gateway wiring guards.
+ *
+ * The gateway IIFE is too entangled to instantiate in-process, so these
+ * are source-level assertions (the established pattern —
+ * multitopic-routing-wiring.test.ts, buffer-gate-broadened.test.ts). They
+ * pin the load-bearing wiring: the buffered-inbound and steer call sites,
+ * the silent send, the shared queuedStatusMsgIds lifecycle (promote/reap
+ * cleanup for free), the per-turn dedupe reset, and the kill switch. The
+ * POLICY and the rendered text are behaviourally tested in
+ * busy-ack.test.ts; the live end-to-end shape in
+ * uat/scenarios/jtbd-midflight-busy-ack-dm.test.ts.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const gatewaySrc = readFileSync(
+  resolve(__dirname, '..', 'gateway', 'gateway.ts'),
+  'utf-8',
+)
+
+describe('#2995 mid-flight busy ack — gateway wiring', () => {
+  it('the buffer-until-idle branch calls maybePostBusyAck for the inbound own chat/topic', () => {
+    expect(gatewaySrc).toMatch(
+      /maybePostBusyAck\('buffer-until-idle', chat_id, messageThreadId \?\? undefined\)/,
+    )
+    // …AFTER the pendingInboundBuffer.push (the ack narrates a real queue).
+    const branch = gatewaySrc.split("deliveryGate.decision === 'buffer-until-idle'")[1] ?? ''
+    const pushIdx = branch.indexOf('pendingInboundBuffer.push(selfAgent, inboundMsg)')
+    const ackIdx = branch.indexOf("maybePostBusyAck('buffer-until-idle'")
+    expect(pushIdx).toBeGreaterThanOrEqual(0)
+    expect(ackIdx).toBeGreaterThan(pushIdx)
+  })
+
+  it('cross-topic queued status and the busy ack are mutually exclusive (no double-card race)', () => {
+    // Both helpers record into queuedStatusMsgIds only AFTER their
+    // sendMessage awaits resolve, so calling both in the same handler pass
+    // would race past each other's has(key) check and double-card the
+    // topic. The buffer branch must pick exactly one.
+    expect(gatewaySrc).toMatch(
+      /if \(crossTopicQueuedCard\) \{\s*postQueuedStatus\(chat_id, messageThreadId, inFlightThread\)\s*\} else \{/,
+    )
+  })
+
+  it('a mid-turn steer gets the steer-worded variant only AFTER successful bridge dispatch', () => {
+    // A "Steer noted" card for a send that missed (bridge offline) would
+    // be untrue — the ack lives inside the `if (delivered)` branch.
+    expect(gatewaySrc).toMatch(
+      /if \(delivered\) \{[\s\S]{0,700}if \(isSteering\) \{\s*maybePostBusyAck\('steer', chat_id, messageThreadId \?\? undefined\)/,
+    )
+  })
+
+  it('an under-threshold miss arms ONE deferred re-check pinned to the running turn', () => {
+    const fn = gatewaySrc.split('function maybePostBusyAck')[1]?.split('\nfunction ')[0] ?? ''
+    // Armed only for the young-step miss, for the remaining age gap.
+    expect(fn).toMatch(/stepAgeMs < BUSY_ACK_STEP_AGE_THRESHOLD_MS &&\s*!busyAckRecheckTimers\.has\(key\)/)
+    expect(fn).toMatch(/BUSY_ACK_STEP_AGE_THRESHOLD_MS - stepAgeMs \+ 250/)
+    // The re-fire is guarded on the SAME turn still running.
+    expect(fn).toMatch(/currentTurn\?\.turnId !== turnIdAtSchedule\) return/)
+    // A posted card cancels the pending re-check.
+    expect(fn).toMatch(/clearTimeout\(pendingRecheck\)/)
+  })
+
+  it('the decision is fed from live tool-flight + step-age readings (pure module owns policy)', () => {
+    const fn = gatewaySrc.split('function maybePostBusyAck')[1]?.split('\nfunction ')[0] ?? ''
+    expect(fn).toMatch(/shouldPostBusyAck\(\{ gateDecision, midToolCall, stepAgeMs, alreadyAcked \}\)/)
+    expect(fn).toMatch(/const midToolCall = toolFlightTracker\.isMidToolCall\(\)/)
+    expect(fn).toMatch(/silencePoke\.longestInFlightTool\(/)
+    expect(fn).toMatch(/const stepAgeMs = step\?\.durationMs \?\? null/)
+  })
+
+  it('dedupe: alreadyAcked couples the live card map AND the per-turn key set', () => {
+    const fn = gatewaySrc.split('function maybePostBusyAck')[1]?.split('\nfunction ')[0] ?? ''
+    expect(fn).toMatch(
+      /const alreadyAcked = queuedStatusMsgIds\.has\(key\) \|\| busyAckPostedKeys\.has\(key\)/,
+    )
+    expect(fn).toMatch(/busyAckPostedKeys\.add\(key\)/)
+  })
+
+  it('the card is sent SILENT (disable_notification: true) through the swallowing wrapper', () => {
+    const fn = gatewaySrc.split('function postBusyAck')[1]?.split('\nfunction ')[0] ?? ''
+    expect(fn).toMatch(/swallowingApiCall\(/)
+    expect(fn).toMatch(/disable_notification: true/)
+    // Thread-optional: a DM send must NOT pass message_thread_id.
+    expect(fn).toMatch(/\.\.\.\(threadId != null \? \{ message_thread_id: threadId \} : \{\}\)/)
+  })
+
+  it('the card shares queuedStatusMsgIds — promote/reap lifecycle cleans it up', () => {
+    const fn = gatewaySrc.split('function postBusyAck')[1]?.split('\nfunction ')[0] ?? ''
+    // Idempotent against the shared key (never stacks on the cross-topic card).
+    expect(fn).toMatch(/if \(queuedStatusMsgIds\.has\(key\)\) return/)
+    expect(fn).toMatch(/queuedStatusMsgIds\.set\(key, \{ chatId, threadId: threadId \?\? null, messageId \}\)/)
+    // Post-race orphan cleanup, same pattern as postQueuedStatus.
+    expect(fn).toMatch(/busy-ack\.post-race-cleanup/)
+  })
+
+  it('turn-end cleanup is PER-KEY: dedupe entry deleted and re-check timer cancelled for the ending turn only', () => {
+    const purge = gatewaySrc.split('function purgeReactionTracking')[1]?.split('\nfunction ')[0] ?? ''
+    // Per-key delete — a purge for topic A must not reset topic B's dedupe.
+    expect(purge).toMatch(/busyAckPostedKeys\.delete\(key\)/)
+    expect(purge).not.toMatch(/busyAckPostedKeys\.clear\(\)/)
+    expect(purge).toMatch(/busyAckRecheckTimers\.delete\(key\)/)
+    expect(purge).toMatch(/clearTimeout\(busyAckRecheck\)/)
+  })
+
+  it('DM cards are promoted too (promoteQueuedStatus no longer early-returns on a null thread)', () => {
+    const fn = gatewaySrc.split('function promoteQueuedStatus')[1]?.split('\nfunction ')[0] ?? ''
+    expect(fn).not.toMatch(/if \(thread == null\) return/)
+  })
+
+  it('kill switch defaults ON, independently disableable', () => {
+    expect(gatewaySrc).toMatch(/SWITCHROOM_MIDFLIGHT_BUSY_ACK !== '0'/)
+    const fn = gatewaySrc.split('function maybePostBusyAck')[1]?.split('\nfunction ')[0] ?? ''
+    expect(fn).toMatch(/if \(!MIDFLIGHT_BUSY_ACK_ENABLED\) return/)
+  })
+})

package/telegram-plugin/tests/busy-ack.test.ts

@@ -0,0 +1,121 @@
+/**
+ * #2995 — mid-flight busy ack: pure decision module.
+ *
+ * Pins the deterministic policy (`shouldPostBusyAck`) and the rendered
+ * card text (`formatBusyAckText`) — the model-free ack a buffered/steered
+ * mid-turn inbound gets while the running turn sits inside one long tool
+ * step. Behavioral assertions on the RENDERED text (wording contract:
+ * "Queued" for the buffered path per the steer-or-queue classification-
+ * visibility invariant; never "Queued" for a steer).
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  BUSY_ACK_STEP_AGE_THRESHOLD_MS,
+  shouldPostBusyAck,
+  formatBusyAckText,
+} from '../gateway/busy-ack.js'
+
+const base = {
+  gateDecision: 'buffer-until-idle' as const,
+  midToolCall: true,
+  stepAgeMs: BUSY_ACK_STEP_AGE_THRESHOLD_MS + 1,
+  alreadyAcked: false,
+}
+
+describe('shouldPostBusyAck', () => {
+  it('fires for a buffered inbound behind an old tool step', () => {
+    expect(shouldPostBusyAck(base)).toBe(true)
+  })
+
+  it('fires for a steer behind an old tool step', () => {
+    expect(shouldPostBusyAck({ ...base, gateDecision: 'steer' })).toBe(true)
+  })
+
+  it('never fires for a plain fresh-turn deliver', () => {
+    expect(shouldPostBusyAck({ ...base, gateDecision: 'deliver' })).toBe(false)
+  })
+
+  it('never fires when not mid-tool-call (turn thinking between tools)', () => {
+    expect(shouldPostBusyAck({ ...base, midToolCall: false })).toBe(false)
+  })
+
+  it('never fires below the step-age threshold (agent seconds from answering)', () => {
+    expect(
+      shouldPostBusyAck({ ...base, stepAgeMs: BUSY_ACK_STEP_AGE_THRESHOLD_MS - 1 }),
+    ).toBe(false)
+    // exactly at the threshold → fires (>= semantics)
+    expect(
+      shouldPostBusyAck({ ...base, stepAgeMs: BUSY_ACK_STEP_AGE_THRESHOLD_MS }),
+    ).toBe(true)
+  })
+
+  it('never fires with no tracked step age', () => {
+    expect(shouldPostBusyAck({ ...base, stepAgeMs: null })).toBe(false)
+  })
+
+  it('fires at most once per key — a second ping gets no second card', () => {
+    // The gateway feeds `alreadyAcked` from its per-turn key set + the live
+    // card map; the policy must refuse when either says "already acked".
+    expect(shouldPostBusyAck({ ...base, alreadyAcked: true })).toBe(false)
+  })
+
+  it('threshold constant sits between the fast-tool envelope and the ignored horizon', () => {
+    expect(BUSY_ACK_STEP_AGE_THRESHOLD_MS).toBeGreaterThanOrEqual(5_000)
+    expect(BUSY_ACK_STEP_AGE_THRESHOLD_MS).toBeLessThanOrEqual(30_000)
+  })
+})
+
+describe('formatBusyAckText — rendered card text', () => {
+  it('buffered path says "Queued", names the blocking activity, and promises the answer', () => {
+    const text = formatBusyAckText({
+      gateDecision: 'buffer-until-idle',
+      toolName: 'Bash',
+      toolLabel: 'gh pr checks --watch',
+    })
+    expect(text).toContain('Queued')
+    expect(text).toContain('`Bash: gh pr checks --watch`')
+    expect(text).toMatch(/I'll answer when this step finishes/)
+  })
+
+  it('carries no point-in-time elapsed figure (a static card must not decay)', () => {
+    // The card is posted once and never re-rendered while the blocking
+    // step runs — any "(Nm elapsed)" would silently go stale on screen.
+    const text = formatBusyAckText({
+      gateDecision: 'buffer-until-idle',
+      toolName: 'Bash',
+      toolLabel: 'sleep 90',
+    })
+    expect(text).not.toMatch(/elapsed|\b\d+[sm]\b/)
+  })
+
+  it('steer path never says "Queued" (classification-visibility invariant)', () => {
+    const text = formatBusyAckText({
+      gateDecision: 'steer',
+      toolName: 'Bash',
+      toolLabel: 'sleep 90',
+    })
+    expect(text).not.toContain('Queued')
+    expect(text).toContain('Steer noted')
+    expect(text).toContain('`Bash: sleep 90`')
+  })
+
+  it('degrades honestly when the tool label is unknown', () => {
+    const text = formatBusyAckText({
+      gateDecision: 'buffer-until-idle',
+      toolName: null,
+      toolLabel: null,
+    })
+    expect(text).toContain('Queued')
+    expect(text).toContain('a long-running step')
+  })
+
+  it('uses the bare tool name when no label was derived', () => {
+    const text = formatBusyAckText({
+      gateDecision: 'buffer-until-idle',
+      toolName: 'Bash',
+      toolLabel: null,
+    })
+    expect(text).toContain('`Bash`')
+  })
+})