switchroom 0.18.8 → 0.18.10

package/telegram-plugin/tests/pending-session-command.test.ts

@@ -0,0 +1,322 @@
+/**
+ * Contract pins for the mid-turn ack-queue-apply-confirm slots (#3017/#3018)
+ * that back `/model` + `/effort` when the agent is busy.
+ *
+ * The gateway wiring (busy-gate enqueue, idle-gate drain, reaper drain-cap,
+ * shutdown resolution) is exercised end-to-end by the UAT harness and pinned
+ * structurally in gateway-pending-command-wiring.test.ts; these lock the PURE
+ * contract the gateway relies on:
+ *
+ *   - one slot PER KIND (model, effort): same-kind last-write-wins (a rapid
+ *     re-issue queues only the latest and REPORTS the displaced one so it's
+ *     never silently lost); cross-kind requests COEXIST (#3018 finding 2)
+ *   - take(kind)/takeAll() are the atomic drain reads (empty the slots)
+ *   - size mirrors the `pendingRestarts.size` gate shape (0..2)
+ *   - the reaper's drainCapDecision DEFERS while a turn is in flight — the
+ *     60s cap must never force a mid-turn drain (#3018 finding 1)
+ *   - shutdownResolutionActions empties the slots and yields, per queued
+ *     command, the durable persist the gateway should perform so the choice
+ *     still applies across the bounce (#3039) — with a re-issue fallback only
+ *     for the unresolvable menu-tag case
+ *   - the ack / superseded / restart-superseded text names the target so the
+ *     operator always sees their choice was captured, replaced, or deferred —
+ *     never dropped.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  createPendingSessionCommandSlots,
+  drainCapDecision,
+  shutdownResolutionActions,
+  resolveForRestart,
+  drainTakenCommands,
+  type DrainIo,
+  ackText,
+  supersededText,
+  restartSupersededText,
+  type PendingSessionCommand,
+} from '../gateway/pending-session-command.js'
+
+const ident = (s: string) => s
+
+function cmd(overrides: Partial<PendingSessionCommand> = {}): PendingSessionCommand {
+  return {
+    kind: 'model',
+    origin: 'typed',
+    arg: 'fable',
+    targetLabel: 'fable',
+    chatId: '100',
+    threadId: undefined,
+    ackChatId: '100',
+    ackMessageId: 42,
+    requestedAt: 1_000,
+    ...overrides,
+  }
+}
+
+describe('pending-session-command slots', () => {
+  it('start empty (size 0, get null, take null, takeAll empty)', () => {
+    const slots = createPendingSessionCommandSlots()
+    expect(slots.size).toBe(0)
+    expect(slots.get('model')).toBeNull()
+    expect(slots.get('effort')).toBeNull()
+    expect(slots.take('model')).toBeNull()
+    expect(slots.takeAll()).toEqual([])
+    expect(slots.list()).toEqual([])
+  })
+
+  it('set on an empty slot displaces nothing and becomes gettable', () => {
+    const slots = createPendingSessionCommandSlots()
+    const a = cmd({ arg: 'opus', targetLabel: 'opus' })
+    expect(slots.set(a)).toBeNull()
+    expect(slots.size).toBe(1)
+    expect(slots.get('model')).toBe(a)
+  })
+
+  it('SAME-KIND last-write-wins: a second set returns the displaced command', () => {
+    const slots = createPendingSessionCommandSlots()
+    const first = cmd({ arg: 'fable', targetLabel: 'fable', ackMessageId: 1 })
+    const second = cmd({ arg: 'opus', targetLabel: 'opus', ackMessageId: 2 })
+    expect(slots.set(first)).toBeNull()
+    const displaced = slots.set(second)
+    expect(displaced).toBe(first) // caller edits THIS ack card to "superseded"
+    expect(slots.get('model')).toBe(second) // only the latest is queued
+    expect(slots.size).toBe(1)
+  })
+
+  it('CROSS-KIND commands coexist: /effort never displaces a queued /model (#3018 finding 2)', () => {
+    const slots = createPendingSessionCommandSlots()
+    const model = cmd({ kind: 'model', arg: 'fable', targetLabel: 'fable', ackMessageId: 1 })
+    const effort = cmd({ kind: 'effort', arg: 'high', targetLabel: 'high', ackMessageId: 2 })
+    expect(slots.set(model)).toBeNull()
+    expect(slots.set(effort)).toBeNull() // NOT a displacement
+    expect(slots.size).toBe(2)
+    expect(slots.get('model')).toBe(model)
+    expect(slots.get('effort')).toBe(effort)
+    // …and vice versa: a later model re-issue displaces only the model slot.
+    const model2 = cmd({ kind: 'model', arg: 'opus', targetLabel: 'opus', ackMessageId: 3 })
+    expect(slots.set(model2)).toBe(model)
+    expect(slots.get('effort')).toBe(effort)
+    expect(slots.size).toBe(2)
+  })
+
+  it('take(kind) atomically empties only that slot (the per-kind drain read)', () => {
+    const slots = createPendingSessionCommandSlots()
+    const model = cmd({ kind: 'model' })
+    const effort = cmd({ kind: 'effort', arg: 'high', targetLabel: 'high' })
+    slots.set(model)
+    slots.set(effort)
+    expect(slots.take('model')).toBe(model)
+    expect(slots.size).toBe(1)
+    expect(slots.get('model')).toBeNull()
+    expect(slots.get('effort')).toBe(effort)
+    expect(slots.take('model')).toBeNull() // second drain is a no-op
+  })
+
+  it('takeAll() empties everything in enqueue order; a same-kind re-enqueue moves to the back', () => {
+    const slots = createPendingSessionCommandSlots()
+    const model1 = cmd({ kind: 'model', targetLabel: 'fable', ackMessageId: 1 })
+    const effort = cmd({ kind: 'effort', arg: 'high', targetLabel: 'high', ackMessageId: 2 })
+    const model2 = cmd({ kind: 'model', targetLabel: 'opus', ackMessageId: 3 })
+    slots.set(model1)
+    slots.set(effort)
+    slots.set(model2) // displaces model1 AND moves the model slot behind effort
+    const all = slots.takeAll()
+    expect(all).toEqual([effort, model2])
+    expect(slots.size).toBe(0)
+    expect(slots.takeAll()).toEqual([])
+  })
+
+  it('clear() drops every queued command without returning them', () => {
+    const slots = createPendingSessionCommandSlots()
+    slots.set(cmd({ kind: 'model' }))
+    slots.set(cmd({ kind: 'effort', arg: 'high', targetLabel: 'high' }))
+    slots.clear()
+    expect(slots.size).toBe(0)
+    expect(slots.get('model')).toBeNull()
+    expect(slots.get('effort')).toBeNull()
+  })
+})
+
+describe('drainCapDecision (#3018 finding 1: the cap must never force mid-turn)', () => {
+  const CAP = 60_000
+
+  it('waits when nothing is queued', () => {
+    expect(drainCapDecision([], 1_000_000, CAP, false)).toBe('wait')
+    expect(drainCapDecision([], 1_000_000, CAP, true)).toBe('wait')
+  })
+
+  it('waits while the queued command is younger than the cap', () => {
+    const q = [cmd({ requestedAt: 100_000 })]
+    expect(drainCapDecision(q, 100_000 + CAP, CAP, false)).toBe('wait')
+  })
+
+  it('forces once overdue AND the session is idle (missed idle gate)', () => {
+    const q = [cmd({ requestedAt: 100_000 })]
+    expect(drainCapDecision(q, 100_000 + CAP + 1, CAP, false)).toBe('force')
+  })
+
+  it('DEFERS (keeps waiting) when overdue but a turn is in flight — a forced mid-turn drain would destroy the queued command', () => {
+    const q = [cmd({ requestedAt: 100_000 })]
+    expect(drainCapDecision(q, 100_000 + CAP + 1, CAP, true)).toBe('defer-turn-in-flight')
+    // …even hours overdue: the idle gate at turn end is the drain point.
+    expect(drainCapDecision(q, 100_000 + 100 * CAP, CAP, true)).toBe('defer-turn-in-flight')
+  })
+
+  it('any one overdue command trips the cap (mixed ages)', () => {
+    const q = [
+      cmd({ kind: 'model', requestedAt: 100_000 }),
+      cmd({ kind: 'effort', requestedAt: 100_000 + CAP }),
+    ]
+    expect(drainCapDecision(q, 100_000 + CAP + 1, CAP, false)).toBe('force')
+  })
+})
+
+describe('shutdownResolutionActions (#3018 finding 3 + #3039: SIGTERM persists the queued choice)', () => {
+  it('empties the slots and yields a persist action per queued command', () => {
+    const slots = createPendingSessionCommandSlots()
+    slots.set(cmd({ kind: 'model', targetLabel: 'fable', arg: 'fable', ackChatId: '100', ackMessageId: 7 }))
+    slots.set(cmd({ kind: 'effort', targetLabel: 'high', arg: 'high', ackChatId: '100', ackMessageId: 9 }))
+    const actions = shutdownResolutionActions(slots, ident)
+    expect(actions).toHaveLength(2)
+    expect(slots.size).toBe(0) // the queue is RESOLVED, not left behind
+    const model = actions.find(a => a.cmd.ackMessageId === 7)!
+    expect(model.persist).toBe('model')
+    expect(model.arg).toBe('fable')
+    expect(model.persistedText).toContain('`fable`')
+    expect(model.persistedText).toContain('saved')
+    // The fallback (persist failed) still names the choice + how to recover.
+    expect(model.reissueText).toContain('re-issue')
+    const effort = actions.find(a => a.cmd.ackMessageId === 9)!
+    expect(effort.persist).toBe('effort')
+    expect(effort.arg).toBe('high')
+  })
+
+  it('typed /model default → clear-model; typed /effort default → clear-effort', () => {
+    expect(resolveForRestart(cmd({ kind: 'model', arg: 'default', targetLabel: 'default' }), ident).persist).toBe('clear-model')
+    expect(resolveForRestart(cmd({ kind: 'effort', arg: 'default', targetLabel: 'default' }), ident).persist).toBe('clear-effort')
+  })
+
+  it('menu model selection (mdl:s:<tag>) is not offline-resolvable → persist null, re-issue fallback', () => {
+    const a = resolveForRestart(cmd({ kind: 'model', origin: 'menu', arg: 'mdl:s:abcd1234', targetLabel: 'the selected model' }), ident)
+    expect(a.persist).toBeNull()
+    expect(a.reissueText).toContain('re-issue')
+  })
+
+  it('menu effort tap (eff:s:<level>) IS resolvable → persist effort with the level', () => {
+    const a = resolveForRestart(cmd({ kind: 'effort', origin: 'menu', arg: 'eff:s:xhigh', targetLabel: 'xhigh' }), ident)
+    expect(a.persist).toBe('effort')
+    expect(a.arg).toBe('xhigh')
+  })
+
+  it('returns no actions when nothing is queued', () => {
+    expect(shutdownResolutionActions(createPendingSessionCommandSlots(), ident)).toEqual([])
+  })
+})
+
+describe('ackText', () => {
+  it('names the model target with a mid-turn framing', () => {
+    const t = ackText('model', 'fable', ident)
+    expect(t).toContain('mid-turn')
+    expect(t).toContain('`fable`')
+    expect(t).toContain('switch to')
+  })
+
+  it('uses the effort verb for effort commands', () => {
+    const t = ackText('effort', 'high', ident)
+    expect(t).toContain('set effort to')
+    expect(t).toContain('`high`')
+  })
+
+  it('routes the label through escapeHtml', () => {
+    const seen: string[] = []
+    ackText('model', 'sr-glm-5', (s) => { seen.push(s); return s })
+    expect(seen).toContain('sr-glm-5')
+  })
+})
+
+describe('supersededText', () => {
+  it('names BOTH the replaced and the new target', () => {
+    const displaced = cmd({ kind: 'model', targetLabel: 'fable' })
+    const next = cmd({ kind: 'model', targetLabel: 'opus' })
+    const t = supersededText(displaced, next, ident)
+    expect(t).toContain('`opus`')
+    expect(t).toContain('`fable`')
+    expect(t).toContain('replaced')
+  })
+})
+
+describe('restartSupersededText', () => {
+  it('tells the operator to re-issue after the restart', () => {
+    const t = restartSupersededText(cmd({ kind: 'effort', targetLabel: 'max' }), ident)
+    expect(t).toContain('restarting')
+    expect(t).toContain('/effort max')
+    expect(t).toContain('`max`')
+  })
+})
+
+
+// ─── #3042 blocker 1: drain loss-safety across a two-command batch ───────────
+
+describe('drainTakenCommands (#3042 blocker 1: an early stop must not drop the rest of the batch)', () => {
+  function makeIo(overrides: Partial<DrainIo> = {}) {
+    const events: string[] = []
+    const io: DrainIo = {
+      restartPending: () => false,
+      turnInFlight: () => false,
+      apply: async c => { events.push(`apply:${c.kind}`); return `✅ ${c.kind} done` },
+      isBusyRefusal: t => t.includes('BUSY'),
+      resolveForRestartText: c => `persisted:${c.kind}`,
+      editCard: async (c, text) => { events.push(`edit:${c.kind}:${text}`) },
+      reEnqueue: c => { events.push(`requeue:${c.kind}`) },
+      failureText: (c, err) => `fail:${c.kind}:${(err as Error).message}`,
+      ...overrides,
+    }
+    return { io, events }
+  }
+  const batch = () => [cmd({ kind: 'model' }), cmd({ kind: 'effort', arg: 'high', targetLabel: 'high' })]
+
+  it('happy path applies and confirms both commands in order', async () => {
+    const { io, events } = makeIo()
+    await drainTakenCommands(batch(), io)
+    expect(events).toEqual(['apply:model', 'edit:model:✅ model done', 'apply:effort', 'edit:effort:✅ effort done'])
+  })
+
+  it('turn races in before the FIRST command → BOTH are re-enqueued, none applied or confirmed', async () => {
+    const { io, events } = makeIo({ turnInFlight: () => true })
+    await drainTakenCommands(batch(), io)
+    expect(events).toEqual(['requeue:model', 'requeue:effort'])
+  })
+
+  it('turn races in before the SECOND command → first applied, second re-enqueued (not lost)', async () => {
+    let calls = 0
+    const { io, events } = makeIo({ turnInFlight: () => ++calls > 1 })
+    await drainTakenCommands(batch(), io)
+    expect(events).toEqual(['apply:model', 'edit:model:✅ model done', 'requeue:effort'])
+  })
+
+  it('handler busy-refusal on the FIRST command → the refusal never reaches the ack card and BOTH are re-enqueued', async () => {
+    const { io, events } = makeIo({
+      apply: async c => (c.kind === 'model' ? 'BUSY — mid-turn' : '✅ effort done'),
+    })
+    await drainTakenCommands(batch(), io)
+    expect(events).toEqual(['requeue:model', 'requeue:effort'])
+  })
+
+  it('apply throwing on the first command does NOT stop the second (failure is per-command)', async () => {
+    const { io, events } = makeIo({
+      apply: async c => {
+        if (c.kind === 'model') throw new Error('boom')
+        return '✅ effort done'
+      },
+    })
+    await drainTakenCommands(batch(), io)
+    expect(events).toEqual(['edit:model:fail:model:boom', 'edit:effort:✅ effort done'])
+  })
+
+  it('restart pending → every command is resolved via the carriers, none applied live', async () => {
+    const { io, events } = makeIo({ restartPending: () => true })
+    await drainTakenCommands(batch(), io)
+    expect(events).toEqual(['edit:model:persisted:model', 'edit:effort:persisted:effort'])
+  })
+})

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/permission-timeout.test.ts

@@ -19,6 +19,8 @@ import {
   HOSTD_PERMISSION_TTL_MS,
   ttlForTool,
   buildTimedOutCardEdits,
+  buildCancelledCardEdits,
+  CANCELLED_FOOTER,
   isStaleTap,
   STALE_TAP_NOTICE,
   TIMED_OUT_FOOTER,
@@ -178,6 +180,30 @@ describe('buildTimedOutCardEdits (Bug 2 fix #1 — strip stale keyboard)', () =>
   })
 })
 
+describe('buildCancelledCardEdits (#3020 — halt cancels pending cards)', () => {
+  it('marks every recorded card for keyboard-strip and appends the cancelled footer', () => {
+    const cards = [
+      { chatId: '111', messageId: 5 },
+      { chatId: '222', messageId: 9 },
+    ]
+    const edits = buildCancelledCardEdits('🔐 **Overlord** wants to roll the fleet', cards)
+    expect(edits).toHaveLength(2)
+    for (const [i, edit] of edits.entries()) {
+      // Same contract as the timeout path: a live Approve after the halt
+      // would dispatch a verdict into an idle session.
+      expect(edit.stripKeyboard).toBe(true)
+      expect(edit.chatId).toBe(cards[i]!.chatId)
+      expect(edit.messageId).toBe(cards[i]!.messageId)
+      expect(edit.text).toContain('roll the fleet')
+      expect(edit.text.endsWith(CANCELLED_FOOTER)).toBe(true)
+    }
+  })
+
+  it('returns no edits when there were no recorded cards', () => {
+    expect(buildCancelledCardEdits('body', [])).toEqual([])
+  })
+})
+
 describe('isStaleTap (Bug 2 fix #3 — do not dispatch a verdict for a dead id)', () => {
   it('is stale when no pending entry exists for the tapped request_id', () => {
     // hasPending=false ⇒ the reaper already auto-denied + deleted it.

package/telegram-plugin/tests/permission-verdict-resume-guard.test.ts

@@ -79,6 +79,18 @@ const isSilentNoCardVerdict = (idx: number): boolean =>
 const isCardFoldedResume = (idx: number): boolean =>
   LINES.slice(idx, idx + POST_WINDOW + 1).some((l) => /card-folded-resume/.test(l))
 
+// A HALTED-TURN verdict (#3020 `executeHaltNow` → `cancelPendingPermissionsForHalt`)
+// denies the pending call because the operator is KILLING the turn (/stop,
+// bare "stop", empty `!`). There is nothing to resume — the turn is about to
+// be C-c'd and its busy state torn down — so neither the glyph flip nor the
+// "got it, continuing" message applies. The card is still visibly terminal:
+// the halt path edits it to "⏹ Cancelled" with the keyboard stripped, and the
+// /stop reply acks the operator. Such callsites carry the
+// `halted-turn-verdict` sentinel within the 5 lines above the dispatch and
+// are exempt from BOTH pairings.
+const isHaltedTurnVerdict = (idx: number): boolean =>
+  LINES.slice(Math.max(0, idx - 5), idx + 1).some((l) => /halted-turn-verdict/.test(l))
+
 // How far below the dispatch the resume call is allowed to live. The
 // widest real gap today is ~9 lines (the slash-command path); 15 gives
 // refactor headroom without letting an unrelated resume "cover" a
@@ -99,6 +111,8 @@ describe('permission verdict → resume reaction wiring', () => {
     const unpaired: number[] = []
     for (const idx of dispatchCallsites) {
       if (isSilentNoCardVerdict(idx)) continue
+      // Exempt: the halt path kills the turn — nothing resumes (#3020).
+      if (isHaltedTurnVerdict(idx)) continue
       const window = LINES.slice(idx, idx + RESUME_WINDOW + 1).join('\n')
       if (!/\bresumeReactionAfterVerdict\s*\(\s*\)/.test(window)) {
         // 1-based line number for a human-readable failure.
@@ -125,6 +139,8 @@ describe('permission verdict → resume reaction wiring', () => {
     const unpaired: number[] = []
     for (const idx of dispatchCallsites) {
       if (isSilentNoCardVerdict(idx)) continue
+      // Exempt: the halt path kills the turn — nothing resumes (#3020).
+      if (isHaltedTurnVerdict(idx)) continue
       // Exempt: card-ux fix 3 folds the resume line into the card edit
       // instead of a separate message (still visibly resumes the operator).
       if (isCardFoldedResume(idx)) continue