switchroom 0.18.11 → 0.18.13

package/telegram-plugin/tests/flood-windows-persistence.test.ts

@@ -0,0 +1,224 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync, existsSync, statSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  readFloodWindows,
+  writeFloodWindow,
+  makeFloodWindowRecorder,
+  loadInitialFloodWindows,
+  floodWindowsPath,
+  floodStatePath,
+  writeFloodState,
+  computeFloodWait,
+  FLOOD_STATE_MODE,
+  FLOOD_WINDOWS_CORRUPT_SUPPRESS_MS,
+} from '../flood-circuit-breaker.js'
+import { createSendGate, type Clock } from '../send-gate.js'
+
+/**
+ * #3084 PR 2 — restart-proof SCOPED flood windows (part3-design §7). Verifies
+ * the write-through/round-trip contract on real temp files (isolated per the
+ * repo's vault/shared-state test discipline) and that a gate reconstructed from
+ * disk is STILL blocked — the whole point of §7 (a boot mid-ban must not resend
+ * into the open window).
+ */
+describe('#3084 scoped flood-window persistence', () => {
+  let dir: string
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'flood-win-'))
+  })
+  afterEach(() => rmSync(dir, { recursive: true, force: true }))
+
+  it('round-trips a scoped window and prunes expired entries', () => {
+    const path = floodWindowsPath(dir)
+    const now = 1_000_000
+    writeFloodWindow(path, { scopeKey: 'chat:5', untilTs: now + 60_000, retryAfterSrc: '429', observedAt: now }, now)
+    writeFloodWindow(path, { scopeKey: 'global', untilTs: now + 10_000, retryAfterSrc: '429', observedAt: now }, now)
+
+    // Before either expires: both present.
+    const live = readFloodWindows(path, now + 5_000)
+    expect(live.map((w) => w.scopeKey).sort()).toEqual(['chat:5', 'global'])
+
+    // After the global one expires: only chat:5 survives (prune-on-read).
+    const later = readFloodWindows(path, now + 20_000)
+    expect(later.map((w) => w.scopeKey)).toEqual(['chat:5'])
+  })
+
+  it('EXTENDS never shortens a window on a later, shorter re-record (boot-never-shortens)', () => {
+    const path = floodWindowsPath(dir)
+    const now = 1_000_000
+    // A long ban is recorded.
+    writeFloodWindow(path, { scopeKey: 'global', untilTs: now + 600_000, retryAfterSrc: '429', observedAt: now }, now)
+    // A later, SHORTER 429 (or a restart re-observing a smaller retry_after)
+    // must not pull the expiry earlier.
+    writeFloodWindow(
+      path,
+      { scopeKey: 'global', untilTs: now + 1_000 + 5_000, retryAfterSrc: '429', observedAt: now + 1_000 },
+      now + 1_000,
+    )
+    const w = readFloodWindows(path, now + 2_000).find((x) => x.scopeKey === 'global')
+    expect(w?.untilTs).toBe(now + 600_000)
+  })
+
+  it('loadInitialFloodWindows combines the global flood-wait.json window with scoped windows', () => {
+    const now = 1_000_000
+    const statePath = floodStatePath(dir)
+    const winPath = floodWindowsPath(dir)
+    writeFloodState(statePath, computeFloodWait(null, 300, now)) // global, +300s
+    writeFloodWindow(winPath, { scopeKey: 'chat:9', untilTs: now + 120_000, retryAfterSrc: '429', observedAt: now }, now)
+
+    const initial = loadInitialFloodWindows(statePath, winPath, now)
+    const scopes = initial.map((w) => w.scopeKey).sort()
+    expect(scopes).toEqual(['chat:9', 'global'])
+    expect(initial.find((w) => w.scopeKey === 'global')?.untilTs).toBe(now + 300_000)
+  })
+
+  it('gate opens a window on a 429 → persists → a NEW gate built from disk is still blocked', async () => {
+    const winPath = floodWindowsPath(dir)
+    const statePath = floodStatePath(dir)
+    const recorder = makeFloodWindowRecorder(winPath, () => 0)
+
+    // Gate 1: a critical send hits a 429 (FLOOD_WAIT_ACTIVE) which opens +
+    // persists scope windows via onWindowOpen.
+    const clock1: Clock = { now: () => 0, sleep: () => Promise.resolve() }
+    const gate1 = createSendGate({
+      enabled: true,
+      clock: clock1,
+      onWindowOpen: (scopeKey, untilTs) => recorder(scopeKey, untilTs),
+    })
+    const floodErr = Object.assign(new Error('FLOOD_WAIT_ACTIVE'), {
+      retryAfterSec: 600,
+      untilTs: 600_000,
+      error_code: 429 as const,
+      parameters: { retry_after: 600 },
+      original: null,
+    })
+    await expect(
+      gate1.gate(
+        async () => {
+          throw floodErr
+        },
+        { chat_id: '7', priorityClass: 'critical' },
+      ),
+    ).rejects.toBe(floodErr)
+
+    // The window is on disk.
+    const persisted = readFloodWindows(winPath, 0)
+    expect(persisted.map((w) => w.scopeKey).sort()).toEqual(['chat:7', 'global'])
+
+    // Gate 2 (simulated restart): built BEFORE any outbound call from the
+    // persisted windows. A cosmetic send on chat:7 must still shed.
+    const clock2: Clock = { now: () => 0, sleep: () => Promise.resolve() }
+    const gate2 = createSendGate({
+      enabled: true,
+      clock: clock2,
+      initialWindows: loadInitialFloodWindows(statePath, winPath, 0),
+    })
+    const res = await gate2.gate(async () => 'should-not-run', {
+      chat_id: '7',
+      priorityClass: 'cosmetic',
+    })
+    expect(res).toBeUndefined()
+    expect(gate2.stats().global.shed).toBe(1)
+
+    // And a critical into the still-long window fails fast — restart did not
+    // reset the ban.
+    await expect(
+      gate2.gate(async () => 'nope', { chat_id: '7', priorityClass: 'critical' }),
+    ).rejects.toThrow('FLOOD_WAIT_ACTIVE')
+  })
+
+  it('H2: writes flood-windows.json world-READABLE (0o644), not 0o600', () => {
+    // A 0o600 marker is unreadable to a gateway running under a DIFFERENT uid
+    // (root vs agent uid share the state dir), which silently defeats the
+    // restart-proof windows — a restart under the other uid boots blind and
+    // resends into the ban. Must match `flood-wait.json` (FLOOD_STATE_MODE).
+    const path = floodWindowsPath(dir)
+    const now = 2_000_000
+    writeFloodWindow(path, { scopeKey: 'global', untilTs: now + 60_000, retryAfterSrc: '429', observedAt: now }, now)
+    expect(statSync(path).mode & 0o777).toBe(FLOOD_STATE_MODE)
+    expect(FLOOD_STATE_MODE).toBe(0o644)
+  })
+
+  it('M1: a CORRUPT flood-windows.json fails SAFE (conservative global window), not open', () => {
+    const path = floodWindowsPath(dir)
+    const now = 3_000_000
+    writeFileSync(path, '{ this is not valid json ][', 'utf-8')
+    const logs: string[] = []
+    const windows = readFloodWindows(path, now, (l) => logs.push(l))
+    // NOT [] (fail-open) — a bounded conservative global window instead.
+    expect(windows).toHaveLength(1)
+    expect(windows[0]!.scopeKey).toBe('global')
+    expect(windows[0]!.untilTs).toBe(now + FLOOD_WINDOWS_CORRUPT_SUPPRESS_MS)
+    // Logged loudly.
+    expect(logs.join('')).toMatch(/failing SAFE/)
+  })
+
+  it('M1: a non-array flood-windows.json fails SAFE', () => {
+    const path = floodWindowsPath(dir)
+    const now = 3_500_000
+    writeFileSync(path, '{"scopeKey":"global"}', 'utf-8') // object, not array
+    const windows = readFloodWindows(path, now, () => {})
+    expect(windows).toEqual([
+      {
+        scopeKey: 'global',
+        untilTs: now + FLOOD_WINDOWS_CORRUPT_SUPPRESS_MS,
+        retryAfterSrc: expect.stringContaining('failsafe'),
+        observedAt: now,
+      },
+    ])
+  })
+
+  it('M1: an UNREADABLE flood-windows.json (read error, not ENOENT) fails SAFE', () => {
+    // Root bypasses file-mode EACCES, so simulate a non-ENOENT read failure
+    // deterministically by making the windows path a DIRECTORY — readFileSync
+    // throws EISDIR, the same "file exists but I can't read it" class as EACCES.
+    const path = floodWindowsPath(dir)
+    const now = 4_000_000
+    mkdirSync(path)
+    const logs: string[] = []
+    const windows = readFloodWindows(path, now, (l) => logs.push(l))
+    expect(windows).toHaveLength(1)
+    expect(windows[0]!.scopeKey).toBe('global')
+    expect(windows[0]!.untilTs).toBe(now + FLOOD_WINDOWS_CORRUPT_SUPPRESS_MS)
+    expect(logs.join('')).toMatch(/unreadable/)
+  })
+
+  it('M1: a genuinely ABSENT file is still "no windows" (ENOENT ≠ corrupt)', () => {
+    const path = floodWindowsPath(dir) // never written
+    expect(readFloodWindows(path, 5_000_000, () => {})).toEqual([])
+  })
+
+  it('M3: flag-OFF gate opens NO window and writes NO flood-windows.json', () => {
+    // The gateway wires onFloodWait → openFloodWindow('global', …)
+    // unconditionally; with the flag OFF that must be a pure no-op — no in-memory
+    // suppression, no fs side effect (a poison-perms file created before the
+    // feature is ever enabled).
+    const path = floodWindowsPath(dir)
+    const recorder = makeFloodWindowRecorder(path, () => 0)
+    const clock: Clock = { now: () => 0, sleep: () => Promise.resolve() }
+    const gate = createSendGate({
+      enabled: false,
+      clock,
+      onWindowOpen: (scopeKey, untilTs) => recorder(scopeKey, untilTs),
+    })
+    gate.openFloodWindow('global', 600_000)
+    expect(existsSync(path)).toBe(false)
+  })
+
+  it('a boot loading initial windows never shortens an on-disk window', async () => {
+    const clock: Clock = { now: () => 0, sleep: () => Promise.resolve() }
+    // Boot with a long window applied at construction.
+    const gate = createSendGate({
+      enabled: true,
+      clock,
+      initialWindows: [{ scopeKey: 'global', untilTs: 600_000 }],
+    })
+    // Re-opening the SAME scope with a shorter untilTs must not shorten it.
+    gate.openFloodWindow('global', 10_000)
+    // A critical still fails fast against the ORIGINAL long window.
+    const e = await gate.gate(async () => 'x', { priorityClass: 'critical' }).catch((err) => err)
+    expect((e as { untilTs: number }).untilTs).toBe(600_000)
+  })
+})

package/telegram-plugin/tests/gateway-boot-marker-clear.test.ts

@@ -43,7 +43,7 @@ describe('gateway boot — clear stale turn-active marker', () => {
     // window to ~5KB so we don't pick up the unrelated
     // `removeTurnActiveMarker` call in the onTurnComplete handler
     // way down at the bottom of the file.
-    const setupWindow = GATEWAY_SRC.slice(setupBlockStart, setupBlockStart + 9000)
+    const setupWindow = GATEWAY_SRC.slice(setupBlockStart, setupBlockStart + 12000)
     const clearMatches = setupWindow.match(/removeTurnActiveMarker\s*\(\s*STATE_DIR\s*\)/g) ?? []
     expect(clearMatches.length).toBe(1)
   })
@@ -53,7 +53,7 @@ describe('gateway boot — clear stale turn-active marker', () => {
     // must not prevent the gateway from coming up. Pin the try-wrapping
     // to make sure a future refactor doesn't drop it.
     const setupBlockStart = GATEWAY_SRC.indexOf('if (!didOneTimeSetup)')
-    const setupWindow = GATEWAY_SRC.slice(setupBlockStart, setupBlockStart + 9000)
+    const setupWindow = GATEWAY_SRC.slice(setupBlockStart, setupBlockStart + 12000)
     expect(setupWindow).toMatch(/try\s*\{\s*removeTurnActiveMarker\(STATE_DIR\)\s*\}\s*catch/)
   })
 
@@ -62,7 +62,7 @@ describe('gateway boot — clear stale turn-active marker', () => {
     // Clearing the marker first means the watchdog sees a clean slate
     // immediately, even if pin sweep takes 30s+ to finish.
     const setupBlockStart = GATEWAY_SRC.indexOf('if (!didOneTimeSetup)')
-    const setupWindow = GATEWAY_SRC.slice(setupBlockStart, setupBlockStart + 9000)
+    const setupWindow = GATEWAY_SRC.slice(setupBlockStart, setupBlockStart + 12000)
     const clearIdx = setupWindow.indexOf('removeTurnActiveMarker(STATE_DIR)')
     const pinSweepIdx = setupWindow.indexOf('Boot-time pin sweep')
     expect(clearIdx).toBeGreaterThan(0)

package/telegram-plugin/tests/gateway-disconnect-flush.test.ts

@@ -36,6 +36,7 @@ function makeDeps(agentName: string | null) {
   const finalizeB = vi.fn(async () => {})
   const clearActiveReactions = vi.fn()
   const disposeProgressDriver = vi.fn()
+  const stopTurnTypingLoops = vi.fn()
   const log = vi.fn()
 
   const activeStatusReactions = new Map<string, FakeCtrl>([
@@ -72,7 +73,7 @@ function makeDeps(agentName: string | null) {
   // carry or clear it.
 
   return {
-    spies: { setDoneA, setDoneB, finalizeA, finalizeB, clearActiveReactions, disposeProgressDriver, log },
+    spies: { setDoneA, setDoneB, finalizeA, finalizeB, clearActiveReactions, disposeProgressDriver, stopTurnTypingLoops, log },
     deps: {
       agentName,
       activeStatusReactions,
@@ -83,6 +84,7 @@ function makeDeps(agentName: string | null) {
       activeDraftStreams,
       clearActiveReactions,
       disposeProgressDriver,
+      stopTurnTypingLoops,
       log,
     },
   }
@@ -121,6 +123,16 @@ describe('flushOnAgentDisconnect — anonymous clients (the regression scenario)
     expect(spies.setDoneA).toHaveBeenCalledTimes(0)
     expect(spies.setDoneB).toHaveBeenCalledTimes(0)
   })
+
+  it('#2650: does NOT sweep the turn-typing loops for anonymous disconnects', () => {
+    // An anonymous one-shot IPC client (recall.py, etc.) never owned a
+    // turn-typing loop. The sweep MUST be gated by the agentName-null
+    // early-return so a constant stream of anonymous disconnects can't
+    // kill a live agent's typing indicator.
+    const { spies, deps } = makeDeps(null)
+    flushOnAgentDisconnect(deps)
+    expect(spies.stopTurnTypingLoops).not.toHaveBeenCalled()
+  })
 })
 
 describe('flushOnAgentDisconnect — registered agent disconnects (existing behavior preserved)', () => {
@@ -144,6 +156,15 @@ describe('flushOnAgentDisconnect — registered agent disconnects (existing beha
     expect(spies.clearActiveReactions).toHaveBeenCalledTimes(1)
   })
 
+  it('#2650: sweeps the turn-typing loops on a real agent disconnect', () => {
+    // The bridge died mid-turn — the canonical turn-end that would stop the
+    // per-(chat,thread) `typing…` interval will never arrive, so the flush
+    // must sweep every live loop or a stale "typing…" shows until next turn.
+    const { spies, deps } = makeDeps('clerk')
+    flushOnAgentDisconnect(deps)
+    expect(spies.stopTurnTypingLoops).toHaveBeenCalledTimes(1)
+  })
+
   it('finalizes only non-final draft streams and clears the maps', () => {
     const { spies, deps } = makeDeps('clerk')
     flushOnAgentDisconnect(deps)
@@ -172,6 +193,7 @@ describe('flushOnAgentDisconnect — dangling-turn sweep (2026-05-23 wedge fix)'
     const onDanglingTurnsSwept = vi.fn()
     const clearActiveReactions = vi.fn()
     const disposeProgressDriver = vi.fn()
+    const stopTurnTypingLoops = vi.fn()
     const log = vi.fn()
     const deps = {
       agentName: 'clerk',
@@ -185,6 +207,7 @@ describe('flushOnAgentDisconnect — dangling-turn sweep (2026-05-23 wedge fix)'
       activeDraftStreams: new Map<string, FakeStream>(),
       clearActiveReactions,
       disposeProgressDriver,
+      stopTurnTypingLoops,
       onDanglingTurnsSwept,
       log,
     }
@@ -243,6 +266,7 @@ describe('flushOnAgentDisconnect — dangling-turn sweep (2026-05-23 wedge fix)'
       activeDraftStreams: new Map<string, FakeStream>(),
       clearActiveReactions: vi.fn(),
       disposeProgressDriver: vi.fn(),
+      stopTurnTypingLoops: vi.fn(),
       onDanglingTurnsSwept,
       log: vi.fn(),
     }
@@ -278,6 +302,7 @@ describe('flushOnAgentDisconnect — dangling-turn sweep (2026-05-23 wedge fix)'
       activeDraftStreams: new Map<string, FakeStream>(),
       clearActiveReactions: vi.fn(),
       disposeProgressDriver: vi.fn(),
+      stopTurnTypingLoops: vi.fn(),
       onDanglingTurnsSwept,
       log,
     }
@@ -310,6 +335,7 @@ describe('flushOnAgentDisconnect — dangling-turn sweep (2026-05-23 wedge fix)'
       activeDraftStreams: new Map<string, FakeStream>(),
       clearActiveReactions: vi.fn(),
       disposeProgressDriver: vi.fn(),
+      stopTurnTypingLoops: vi.fn(),
     }
     // Singular form.
     flushOnAgentDisconnect({
@@ -348,6 +374,7 @@ describe('flushOnAgentDisconnect — dangling-turn sweep (2026-05-23 wedge fix)'
       activeDraftStreams: new Map<string, FakeStream>(),
       clearActiveReactions: vi.fn(),
       disposeProgressDriver: vi.fn(),
+      stopTurnTypingLoops: vi.fn(),
       log,
     })
     expect(log.mock.calls.some((c: unknown[]) =>
@@ -368,6 +395,7 @@ describe('flushOnAgentDisconnect — dangling-turn sweep (2026-05-23 wedge fix)'
       activeDraftStreams: new Map<string, FakeStream>(),
       clearActiveReactions: vi.fn(),
       disposeProgressDriver: vi.fn(),
+      stopTurnTypingLoops: vi.fn(),
       // onDanglingTurnsSwept intentionally omitted.
       log: vi.fn(),
     }

package/telegram-plugin/tests/gateway-loopback-paste-redact.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+
+/**
+ * Structural integration test for the loopback-paste fail-safe redaction in
+ * the gateway's inbound handler (security audit #3084, F2/F3).
+ *
+ * Why structural: gateway/gateway.ts does not export its inbound handler, so a
+ * pure-functional invocation would require end-to-end harnessing of
+ * Bot/Grammy/Context. The decision predicate (shouldConsumeLoopbackPaste, incl.
+ * the malformed-paste fail-safe) is exhaustively unit-tested in
+ * `auth-loopback-relay.test.ts`, and the redaction primitive
+ * (redactAuthCodeMessage) in `auth-code-redact.test.ts`. What's left to assert
+ * here is that the gateway actually WIRES a fail-safe so a code-bearing paste
+ * that is malformed, or arrives just after the intercept TTL, or has no active
+ * flow, is redacted + dropped rather than forwarded to the agent.
+ *
+ * The invariants:
+ *   1. The stale (TTL-expired) loopback branch does NOT let the paste fall
+ *      through to the agent — it flows into the fail-safe below.
+ *   2. A fail-safe `if (shouldConsumeLoopbackPaste(text))` block exists that
+ *      redacts (redactAuthCodeMessage) and returns, sitting AFTER the
+ *      pending-flow branch but BEFORE the generic auth-code / agent-forward
+ *      handlers.
+ */
+describe('gateway loopback-paste fail-safe redaction — structural wiring', () => {
+  const src = readFileSync(
+    new URL('../gateway/gateway.ts', import.meta.url),
+    'utf8',
+  )
+
+  it('imports the consume predicate + redaction helper', () => {
+    expect(src).toMatch(/shouldConsumeLoopbackPaste/)
+    expect(src).toMatch(/redactAuthCodeMessage/)
+  })
+
+  it('has a fail-safe redact-and-return block guarded by shouldConsumeLoopbackPaste', () => {
+    // Isolate the fail-safe block: `if (shouldConsumeLoopbackPaste(text)) { ... }`
+    // that is NOT part of the `pendingLoop && ...` pending-flow branch.
+    const failSafe = src.match(
+      /if \(shouldConsumeLoopbackPaste\(text\)\) \{[\s\S]{0,600}?\n {2}\}/g,
+    )
+    expect(failSafe).not.toBeNull()
+    // The standalone fail-safe (the one NOT preceded by `pendingLoop &&`).
+    const standalone = (failSafe ?? []).find(
+      (b) => !b.startsWith('if (pendingLoop'),
+    )
+    expect(standalone).toBeDefined()
+    expect(standalone!).toMatch(/redactAuthCodeMessage/)
+    expect(standalone!).toMatch(/return/)
+  })
+
+  it('the stale loopback branch falls through to the fail-safe (does not forward)', () => {
+    // The stale-path comment must reference the fail-safe, and the fail-safe
+    // block must appear AFTER the pending-loop branch and BEFORE the generic
+    // auth-code intercept (`pendingReauthFlows`).
+    const failSafeIdx = src.indexOf(
+      'Fail-safe redaction (security audit #3084, F2/F3)',
+    )
+    const pendingLoopIdx = src.indexOf('const pendingLoop = pendingLoopbackFlows.get')
+    const reauthIdx = src.indexOf('const pendingReauth = pendingReauthFlows.get')
+    expect(failSafeIdx).toBeGreaterThan(-1)
+    expect(failSafeIdx).toBeGreaterThan(pendingLoopIdx)
+    expect(reauthIdx).toBeGreaterThan(failSafeIdx)
+  })
+})

package/telegram-plugin/tests/gateway-outbound-redact.test.ts

@@ -77,6 +77,63 @@ describe('gateway outbound secret-scrub — structural wiring', () => {
     expect(truncIdx).toBeGreaterThan(redactIdx) // mask BEFORE the slice
   })
 
+  it('ask_user: redacts question + option labels at entry, BEFORE the send', () => {
+    // F1 — ask_user sent the question + button labels unredacted. The scrub
+    // must run at the top of executeAskUser (via redactAskUserFields), before
+    // the keyboard is built and the question is sent to Telegram.
+    const start = src.indexOf('async function executeAskUser(')
+    const redactIdx = src.indexOf('redactAskUserFields(args.question, args.options', start)
+    const keyboardIdx = src.indexOf('const keyboard = new InlineKeyboard()', start)
+    const sendIdx = src.indexOf('sendRichMessage(args.chatId, richMessage(args.question)', start)
+    expect(start).toBeGreaterThan(0)
+    expect(redactIdx).toBeGreaterThan(start)
+    expect(keyboardIdx).toBeGreaterThan(redactIdx) // mask BEFORE labels become buttons
+    expect(sendIdx).toBeGreaterThan(redactIdx) // mask BEFORE the question is sent
+  })
+
+  it('send_checklist: redacts title + task text BEFORE rawSendChecklist', () => {
+    // F2 — checklist title + task strings were sent unredacted.
+    const start = src.indexOf('async function executeSendChecklist(')
+    const redactIdx = src.indexOf('redactChecklistFields(', start)
+    const sendIdx = src.indexOf('rawSendChecklist({', start)
+    expect(start).toBeGreaterThan(0)
+    expect(redactIdx).toBeGreaterThan(start)
+    expect(sendIdx).toBeGreaterThan(redactIdx) // mask BEFORE the send
+  })
+
+  it('update_checklist: redacts title + task text BEFORE rawEditMessageChecklist', () => {
+    // F2 sibling — update_checklist shares the identical leak class.
+    const start = src.indexOf('async function executeUpdateChecklist(')
+    const redactIdx = src.indexOf('redactChecklistFields(', start)
+    const editIdx = src.indexOf('rawEditMessageChecklist({', start)
+    expect(start).toBeGreaterThan(0)
+    expect(redactIdx).toBeGreaterThan(start)
+    expect(editIdx).toBeGreaterThan(redactIdx) // mask BEFORE the edit
+  })
+
+  it('pty draft-preview: redacts at the gateway boundary BEFORE the stream', () => {
+    // F3 — the PTY-tail partial (assistant reply text extracted from the TUI)
+    // forwards straight to the draft-preview stream. Mask at the top of
+    // handlePtyPartial, before it hands off to handlePtyPartialPure.
+    const start = src.indexOf('function handlePtyPartial(text: string): void {')
+    const redactIdx = src.indexOf(`redactOutboundText(text, 'pty_preview')`, start)
+    const pureIdx = src.indexOf('handlePtyPartialPure(text, state', start)
+    expect(start).toBeGreaterThan(0)
+    expect(redactIdx).toBeGreaterThan(start)
+    expect(pureIdx).toBeGreaterThan(redactIdx) // mask BEFORE the stream push
+  })
+
+  it('pty activity: redacts at the gateway boundary BEFORE the stream', () => {
+    // F3 — the (currently-unwired) PTY-activity lane is masked too so the fix
+    // is durable if it is ever re-armed.
+    const start = src.indexOf('function handlePtyActivity(text: string): void {')
+    const redactIdx = src.indexOf(`redactOutboundText(text, 'pty_activity')`, start)
+    const streamIdx = src.indexOf('handleStreamReply(', start)
+    expect(start).toBeGreaterThan(0)
+    expect(redactIdx).toBeGreaterThan(start)
+    expect(streamIdx).toBeGreaterThan(redactIdx) // mask BEFORE the stream
+  })
+
   it('does not log the secret value when a mask fires', () => {
     const idx = src.indexOf('function redactOutboundText(')
     const body = src.slice(idx, idx + 400)

package/telegram-plugin/tests/gw-trace-gate.test.ts

@@ -0,0 +1,105 @@
+/**
+ * Pin the gateway trace verbosity gate (#3025): zero-signal per-poll
+ * heartbeats are suppressed by default and the full firehose is restored
+ * only when SWITCHROOM_GW_TRACE is truthy. Error lines and real
+ * (non-poll / non-idle-tick) activity ALWAYS emit regardless of the flag.
+ *
+ * DUAL-RUNNER NOTE (vitest + bun): this file runs under BOTH runners, and
+ * bun's vitest shim does not honor `vi.resetModules()` — a re-import
+ * returns the originally-cached module, so flag variants CANNOT be tested
+ * via env + fresh import. Instead the gate exposes pure paths: the env
+ * parse is `computeGwTraceVerbose(flag)` and both should-emit functions
+ * take an explicit `verbose` argument (defaulting to the module-init
+ * read). Tests pass verbosity explicitly.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  computeGwTraceVerbose,
+  shouldEmitTgPost,
+  shouldEmitShadowTrace,
+} from '../shared/gw-trace-gate.js'
+
+describe('computeGwTraceVerbose — env flag parsing', () => {
+  it('is OFF when unset', () => {
+    expect(computeGwTraceVerbose(undefined)).toBe(false)
+  })
+
+  it('opts IN on the truthy set, case-insensitively (1/true/yes/on)', () => {
+    for (const v of ['1', 'true', 'TRUE', 'True', 'yes', 'Yes', 'YES', 'on', 'ON', 'On', ' 1', 'true ']) {
+      expect(computeGwTraceVerbose(v)).toBe(true)
+    }
+  })
+
+  it('stays OFF for falsey / unrecognized values', () => {
+    for (const v of ['', '0', 'false', 'FALSE', 'off', 'No', 'x', 'enabled']) {
+      expect(computeGwTraceVerbose(v)).toBe(false)
+    }
+  })
+})
+
+describe('shouldEmitTgPost — default (verbose=false): suppress poll heartbeats', () => {
+  it('suppresses status=ok for getUpdates and getMe', () => {
+    expect(shouldEmitTgPost('getUpdates', 'ok', false)).toBe(false)
+    expect(shouldEmitTgPost('getMe', 'ok', false)).toBe(false)
+  })
+
+  it('ALWAYS emits error lines, even for the poll methods', () => {
+    expect(shouldEmitTgPost('getUpdates', 'err', false)).toBe(true)
+    expect(shouldEmitTgPost('getMe', 'err', false)).toBe(true)
+  })
+
+  it('keeps status=ok for real outbound methods', () => {
+    for (const m of ['sendMessage', 'editMessageText', 'sendChatAction', 'answerCallbackQuery']) {
+      expect(shouldEmitTgPost(m, 'ok', false)).toBe(true)
+    }
+  })
+})
+
+describe('shouldEmitShadowTrace — default (verbose=false): suppress idle no-op ticks', () => {
+  it('suppresses a tick with no effects in an idle global state', () => {
+    expect(shouldEmitShadowTrace('tick', 0, 'bridge_alive_idle', false)).toBe(false)
+    expect(shouldEmitShadowTrace('tick', 0, 'bridge_dead', false)).toBe(false)
+  })
+
+  it('emits a tick that produced effects (e.g. a TTL turn expiry)', () => {
+    expect(shouldEmitShadowTrace('tick', 1, 'bridge_alive_idle', false)).toBe(true)
+  })
+
+  it('emits a tick while a turn is in flight', () => {
+    expect(shouldEmitShadowTrace('tick', 0, 'bridge_alive_in_turn', false)).toBe(true)
+  })
+
+  it('ALWAYS emits non-tick events (real inbound/turn/bridge activity)', () => {
+    for (const ev of ['inbound', 'turnStart', 'turnEnd', 'bridgeUp', 'bridgeDown', 'permVerdict']) {
+      expect(shouldEmitShadowTrace(ev, 0, 'bridge_alive_idle', false)).toBe(true)
+    }
+  })
+})
+
+describe('verbose=true — full firehose restored', () => {
+  it('emits every line, including the two suppressed-by-default families', () => {
+    expect(shouldEmitTgPost('getUpdates', 'ok', true)).toBe(true)
+    expect(shouldEmitTgPost('getMe', 'ok', true)).toBe(true)
+    expect(shouldEmitShadowTrace('tick', 0, 'bridge_alive_idle', true)).toBe(true)
+    expect(shouldEmitShadowTrace('tick', 0, 'bridge_dead', true)).toBe(true)
+  })
+})
+
+describe('default verbose argument wiring', () => {
+  it('the defaulted call form works and matches the module-init env read', () => {
+    // Env-agnostic assertion: the defaulted form must agree with the
+    // explicit form using the parsed CURRENT env — proving the default
+    // parameter is wired to the module-init flag, whatever its value in
+    // the test process.
+    const envVerbose = computeGwTraceVerbose(process.env.SWITCHROOM_GW_TRACE)
+    expect(shouldEmitTgPost('getUpdates', 'ok')).toBe(
+      shouldEmitTgPost('getUpdates', 'ok', envVerbose),
+    )
+    expect(shouldEmitShadowTrace('tick', 0, 'bridge_alive_idle')).toBe(
+      shouldEmitShadowTrace('tick', 0, 'bridge_alive_idle', envVerbose),
+    )
+    // Regardless of the flag, an error line always emits via the default form.
+    expect(shouldEmitTgPost('getUpdates', 'err')).toBe(true)
+  })
+})