switchroom 0.19.18 → 0.19.22

package/telegram-plugin/tests/boot-pin-sweep-wiring.test.ts

@@ -0,0 +1,101 @@
+/**
+ * Boot pin sweep WIRING fence (#3664 Defect A).
+ *
+ * The behaviour lives in `boot-sweep-gate.test.ts`; this file pins the gateway
+ * WIRING, because the regression was a wiring regression: `caa4d7568` (#3310)
+ * moved the `lockedBot` assignment into `initGatewayBot()` and left the sweep's
+ * kick-off at module-eval time. `tsc` stayed green (the `!` definite-assignment
+ * assertion on `lockedBot` suppresses the error) and no test noticed, so every
+ * boot-cleanup unpin threw `undefined is not an object` for a month.
+ *
+ * These are STRUCTURAL assertions (the gateway module can't be instantiated
+ * in-process — same pattern as silence-liveness-wiring.test.ts) that fail if a
+ * future refactor re-introduces a module-eval-time dispatch of the sweep.
+ */
+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('boot pin sweep wiring (#3664)', () => {
+  it('never dispatches runBootPinCleanupAndDmSweep() directly — only through the gate', () => {
+    // The original bug shape, verbatim: a fire-and-forget call at module-eval
+    // time. Any direct invocation (voided or awaited) bypasses the bot-ready
+    // half of the precondition.
+    const directCalls =
+      gatewaySrc.match(/(?<!function\s)(?<![.\w])runBootPinCleanupAndDmSweep\s*\(/g) ?? []
+    expect(directCalls).toEqual([])
+  })
+
+  it('passes the sweep to the gate as a reference, and arms it at both mutex sites', () => {
+    expect(gatewaySrc).toContain('createBootSweepGate({ run: runBootPinCleanupAndDmSweep')
+    // Both startup-lock outcomes (mutex acquired, and the non-atomic
+    // writePidFile fallback) arm — neither may dispatch on its own.
+    const armSites = gatewaySrc.match(/bootPinSweepGate\.arm\(\)/g) ?? []
+    expect(armSites.length).toBe(2)
+  })
+
+  it('signals botReady() only from initGatewayBot, AFTER lockedBot is assigned', () => {
+    const readySites = gatewaySrc.match(/bootPinSweepGate\.botReady\(\)/g) ?? []
+    expect(readySites.length).toBe(1)
+
+    const initStart = gatewaySrc.indexOf('async function initGatewayBot()')
+    const assignIdx = gatewaySrc.indexOf('lockedBot = chatLock.wrapBot(')
+    const readyIdx = gatewaySrc.indexOf('bootPinSweepGate.botReady()')
+    expect(initStart).toBeGreaterThan(-1)
+    expect(assignIdx).toBeGreaterThan(initStart)
+    expect(readyIdx).toBeGreaterThan(assignIdx)
+  })
+
+  it('runs the sweep steps through runBootPinSweepSteps, not a bare await chain', () => {
+    // Salvage S2. The BEHAVIOUR (a throwing step must not strand the steps
+    // behind it, and must never strand the DM-eligibility flip) is proven in
+    // boot-sweep-gate.test.ts. This fence is what makes that proof apply to the
+    // gateway: the reapers must reach the runner as injected steps, and nothing
+    // may reintroduce the bare sequential chain that skipped the isolation.
+    expect(gatewaySrc).toContain('return runBootPinSweepSteps({')
+    const stepFns = ['statusPinBootCleanup', 'activityCardBootReaper', 'queuedCardBootReaper']
+    for (const stepFn of stepFns) {
+      // Passed BY REFERENCE as a step, never invoked inline in the sweep.
+      expect(gatewaySrc).toContain(`: ${stepFn},`)
+      const inlineAwaits = gatewaySrc.match(new RegExp(`await\\s+${stepFn}\\s*\\(`, 'g')) ?? []
+      expect(inlineAwaits).toEqual([])
+    }
+    // The DM-eligibility flip is what a throw used to strand, so it must live
+    // INSIDE the enableDmSweep step callback — not as a statement sequenced
+    // after the reapers, where one rejection skips it for the whole session.
+    const lines = gatewaySrc.split('\n')
+    const flipIdxs = lines
+      .map((l, i) => ({ l, i }))
+      .filter(({ l }) => /^\s*dmPinSweepEligible = true\s*$/.test(l))
+      .map(({ i }) => i)
+    expect(flipIdxs.length).toBe(1)
+    expect(lines[flipIdxs[0] - 1]).toContain('enableDmSweep: () => {')
+  })
+
+  it('routes the pin API through the asserting seam, never a raw lockedBot.api pin', () => {
+    // Salvage S1/S3: `statusPinApi()` must build on `createStatusPinApi`, which
+    // asserts the bot exists and converts a send-gate SHED into a throw. A
+    // hand-rolled `robustApiCall(() => lockedBot.api.pinChatMessage(...))`
+    // anywhere in the gateway would bypass both invariants.
+    expect(gatewaySrc).toContain('return createStatusPinApi(')
+    // Every `status-pin.*` verb is now issued from status-pin-api.ts. A raw
+    // `robustApiCall(() => lockedBot.api.unpinChatMessage(…), { verb:
+    // 'status-pin.unpin' })` reappearing here would be a driver call that
+    // skips assertBotReady + assertLanded.
+    const statusPinVerbs = gatewaySrc.match(/verb:\s*['"`]status-pin\.(?:un)?pin['"`]/g) ?? []
+    expect(statusPinVerbs).toEqual([])
+  })
+
+  it('arms only from inside the startup-mutex block, never at bare module scope', () => {
+    // Every arm() site must be indented (i.e. nested inside the
+    // `if (isGatewayMain) { … }` startup-lock block), never a top-level
+    // statement that would run unconditionally on import.
+    for (const line of gatewaySrc.split('\n')) {
+      if (line.includes('bootPinSweepGate.arm()')) {
+        expect(line.startsWith(' ')).toBe(true)
+      }
+    }
+  })
+})

package/telegram-plugin/tests/boot-sweep-gate.test.ts

@@ -0,0 +1,293 @@
+/**
+ * boot-sweep-gate — the deterministic ordering fence for #3664 Defect A.
+ *
+ * The regression these assertions exist to catch: the boot orphan sweep was
+ * dispatched the moment the gateway won the startup mutex, which happens at
+ * module-eval time — thousands of lines before `initGatewayBot()` assigns
+ * `lockedBot`. Every boot-cleanup unpin therefore threw
+ * `undefined is not an object (evaluating 'lockedBot.api')` before reaching
+ * Telegram (14/14 fleet-wide failures since #3310, zero clean successes).
+ *
+ * The behavioural assertion is "arming ALONE must not dispatch the sweep" —
+ * a test that would have failed on the original bug shape.
+ */
+import { describe, it, expect } from 'vitest'
+import {
+  createBootSweepGate,
+  runBootPinSweepSteps,
+  type BootPinSweepSteps,
+} from '../gateway/boot-sweep-gate.js'
+
+/** A fake sweep that records whether it ran and what the bot handle looked
+ *  like at that moment — the thing the original bug got wrong. */
+function fakeSweep() {
+  const observed: (string | undefined)[] = []
+  let bot: string | undefined
+  return {
+    run: async () => {
+      observed.push(bot)
+    },
+    setBot: (b: string) => {
+      bot = b
+    },
+    get observed() {
+      return observed
+    },
+  }
+}
+
+describe('createBootSweepGate (#3664 Defect A)', () => {
+  it('does NOT dispatch on arm() alone — the bot handle does not exist yet', async () => {
+    const sweep = fakeSweep()
+    const gate = createBootSweepGate({ run: sweep.run })
+
+    gate.arm()
+    await Promise.resolve()
+
+    expect(gate.hasRun()).toBe(false)
+    expect(sweep.observed).toEqual([])
+  })
+
+  it('does NOT dispatch on botReady() alone — this boot may not own the pin state', async () => {
+    const sweep = fakeSweep()
+    const gate = createBootSweepGate({ run: sweep.run })
+
+    gate.botReady()
+    await Promise.resolve()
+
+    expect(gate.hasRun()).toBe(false)
+    expect(sweep.observed).toEqual([])
+  })
+
+  it('dispatches once BOTH signals arrive, and the bot handle is live when it does', async () => {
+    const sweep = fakeSweep()
+    const gate = createBootSweepGate({ run: sweep.run })
+
+    gate.arm() // startup mutex won (module-eval time)
+    await Promise.resolve()
+    expect(sweep.observed).toEqual([])
+
+    sweep.setBot('lockedBot') // initGatewayBot() assigns lockedBot …
+    gate.botReady() // … and signals the gate
+    await Promise.resolve()
+
+    // The sweep ran, and it saw a live bot handle — never `undefined`.
+    expect(sweep.observed).toEqual(['lockedBot'])
+    expect(gate.hasRun()).toBe(true)
+  })
+
+  it('is order-independent: botReady() before arm() still dispatches exactly once', async () => {
+    const sweep = fakeSweep()
+    const gate = createBootSweepGate({ run: sweep.run })
+
+    sweep.setBot('lockedBot')
+    gate.botReady()
+    await Promise.resolve()
+    expect(sweep.observed).toEqual([])
+
+    gate.arm()
+    await Promise.resolve()
+    expect(sweep.observed).toEqual(['lockedBot'])
+  })
+
+  it('dispatches at most once however many times the signals repeat', async () => {
+    const sweep = fakeSweep()
+    const gate = createBootSweepGate({ run: sweep.run })
+
+    sweep.setBot('lockedBot')
+    gate.arm()
+    gate.botReady()
+    gate.arm() // e.g. the mutex path AND the mutex-fallback path
+    gate.botReady()
+    await Promise.resolve()
+
+    expect(sweep.observed).toEqual(['lockedBot'])
+  })
+
+  it('routes a rejecting sweep to onError instead of leaking an unhandled rejection', async () => {
+    const rejections: unknown[] = []
+    const onUnhandled = (err: unknown) => rejections.push(err)
+    process.on('unhandledRejection', onUnhandled)
+    try {
+      const errs: unknown[] = []
+      const gate = createBootSweepGate({
+        run: async () => {
+          throw new Error('boom')
+        },
+        onError: (err) => errs.push(err),
+      })
+
+      gate.arm()
+      gate.botReady()
+      await new Promise((r) => setTimeout(r, 10))
+
+      expect((errs[0] as Error).message).toBe('boom')
+      expect(rejections).toEqual([])
+    } finally {
+      process.off('unhandledRejection', onUnhandled)
+    }
+  })
+})
+
+/**
+ * Per-step isolation (#3664 salvage S2).
+ *
+ * The steps used to be a bare sequential `await` chain in gateway.ts. A throw
+ * from either card reaper skipped `dmPinSweepEligible = true`, which authorises
+ * the DM unpin-all path for the WHOLE SESSION — so one throwing reaper silently
+ * disabled DM stale-pin cleanup, including every later lazy first-inbound
+ * sweep. That became newly reachable the moment #3664 made the sweep actually
+ * run for the first time.
+ *
+ * The outcome asserted is "was the DM path enabled and were the DM chats
+ * swept", not "was a wrapper called".
+ */
+describe('runBootPinSweepSteps (#3664 salvage S2)', () => {
+  function deps(over: Partial<BootPinSweepSteps> = {}) {
+    const order: string[] = []
+    const logs: string[] = []
+    const base: BootPinSweepSteps = {
+      scanDmChatIds: () => {
+        order.push('scan')
+        return ['12345']
+      },
+      statusPinCleanup: async () => {
+        order.push('status-pins')
+      },
+      activityCardReaper: async () => {
+        order.push('activity-cards')
+      },
+      queuedCardReaper: async () => {
+        order.push('queued-cards')
+      },
+      enableDmSweep: () => order.push('enable-dm'),
+      sweepDm: async (id) => {
+        order.push(`dm:${id}`)
+      },
+      log: (l) => logs.push(l),
+    }
+    return { order, logs, deps: { ...base, ...over } }
+  }
+
+  it('runs the store scan first, then the reapers, then enables + runs the DM sweep', async () => {
+    const d = deps()
+    await runBootPinSweepSteps(d.deps)
+    expect(d.order).toEqual([
+      'scan',
+      'status-pins',
+      'activity-cards',
+      'queued-cards',
+      'enable-dm',
+      'dm:12345',
+    ])
+  })
+
+  it('a throwing reaper does not strand the steps behind it', async () => {
+    const d = deps({
+      activityCardReaper: async () => {
+        throw new Error('boom')
+      },
+    })
+    await runBootPinSweepSteps(d.deps)
+    // The DM path is still enabled and the recorded DM chat is still swept.
+    expect(d.order).toEqual(['scan', 'status-pins', 'queued-cards', 'enable-dm', 'dm:12345'])
+    expect(d.logs.join('')).toContain("step 'activity-card-reaper' failed: boom")
+  })
+
+  it('enables the DM sweep even when EVERY earlier step throws', async () => {
+    const boom = async () => {
+      throw new Error('boom')
+    }
+    const d = deps({
+      statusPinCleanup: boom,
+      activityCardReaper: boom,
+      queuedCardReaper: boom,
+    })
+    await runBootPinSweepSteps(d.deps)
+    expect(d.order).toEqual(['scan', 'enable-dm', 'dm:12345'])
+  })
+
+  it('a failing store scan still lets the reapers and the DM enable run', async () => {
+    const d = deps({
+      scanDmChatIds: () => {
+        throw new Error('ENOENT')
+      },
+    })
+    await runBootPinSweepSteps(d.deps)
+    // No DM ids to sweep, but nothing behind the scan is stranded.
+    expect(d.order).toEqual(['status-pins', 'activity-cards', 'queued-cards', 'enable-dm'])
+    expect(d.logs.join('')).toContain("step 'dm-chat-scan' failed: ENOENT")
+  })
+
+  it('one failing DM chat does not block the next one', async () => {
+    const swept: string[] = []
+    const d = deps({
+      scanDmChatIds: () => ['1', '2'],
+      sweepDm: async (id) => {
+        if (id === '1') throw new Error('kicked')
+        swept.push(id)
+      },
+    })
+    await runBootPinSweepSteps(d.deps)
+    expect(swept).toEqual(['2'])
+  })
+
+  it('logs a non-Error throw honestly instead of "undefined"', async () => {
+    const d = deps({
+      queuedCardReaper: async () => {
+        // A non-Error throw: `(err as Error).message` would log "undefined".
+        throw 'not an Error'
+      },
+    })
+    await runBootPinSweepSteps(d.deps)
+    expect(d.logs.join('')).toContain("step 'queued-card-reaper' failed: not an Error")
+    expect(d.logs.join('')).not.toContain('failed: undefined')
+  })
+
+  it('survives a log sink that itself throws', async () => {
+    // stderr can be gone on a dying process; the one function whose job is
+    // "a step must not take the sweep down" must not take the sweep down.
+    const order: string[] = []
+    await expect(
+      runBootPinSweepSteps({
+        scanDmChatIds: () => [],
+        statusPinCleanup: async () => {
+          throw new Error('boom')
+        },
+        activityCardReaper: async () => {
+          order.push('activity-cards')
+        },
+        queuedCardReaper: async () => {
+          order.push('queued-cards')
+        },
+        enableDmSweep: () => order.push('enable-dm'),
+        sweepDm: async () => {},
+        log: () => {
+          throw new Error('EPIPE')
+        },
+      }),
+    ).resolves.toBeUndefined()
+    expect(order).toEqual(['activity-cards', 'queued-cards', 'enable-dm'])
+  })
+
+  it('never rejects — the caller fire-and-forgets it', async () => {
+    const boom = async () => {
+      throw new Error('boom')
+    }
+    await expect(
+      runBootPinSweepSteps({
+        scanDmChatIds: () => {
+          throw new Error('boom')
+        },
+        statusPinCleanup: boom,
+        activityCardReaper: boom,
+        queuedCardReaper: boom,
+        enableDmSweep: () => {
+          throw new Error('boom')
+        },
+        sweepDm: boom,
+        log: () => {},
+      }),
+    ).resolves.toBeUndefined()
+  })
+})

package/telegram-plugin/tests/bridge-tool-parity.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { buildEffectiveToolSchemas } from '../bridge/tool-filter.js'
+
+/**
+ * Half-wiring guard: every tool the gateway is willing to EXECUTE must be
+ * ADVERTISED by the bridge's MCP surface.
+ *
+ * The failure this pins (observed live 2026-07-25): `progress_update` was in
+ * the gateway's `ALLOWED_TOOLS` allowlist and had a full `executeProgressUpdate`
+ * implementation, but it was never carried over into `bridge/bridge.ts`'s
+ * `TOOL_SCHEMAS` when the legacy `server.ts` monolith was deleted (5496f792,
+ * Wave 3 F4). The monolith had registered it (7206817a); the bridge never did.
+ * Result: the tool was documented in every sub-agent's system prompt, executable
+ * by the gateway, and completely unreachable — a sub-agent calling it got
+ * "No such tool available". Nothing failed loudly; the capability just silently
+ * did not exist for ~14 months.
+ *
+ * Why structural (source text, not imports): `gateway.ts` has heavy import-time
+ * side effects (socket bind, bot construction) and `bridge.ts` exits the process
+ * at import when no gateway socket is present, so neither can be imported into a
+ * unit test. Both lists are plain string literals in source, so parsing them is
+ * exact and cheap. If either declaration is refactored out of the shape these
+ * regexes expect, the test FAILS (it never silently degrades to a no-op) —
+ * update the parser, don't delete the assertion.
+ */
+
+const PLUGIN_DIR = join(import.meta.dirname, '..')
+
+function readSource(rel: string): string {
+  return readFileSync(join(PLUGIN_DIR, rel), 'utf8')
+}
+
+/** Tool names in the gateway's IPC execution allowlist (`ALLOWED_TOOLS`). */
+function gatewayAllowedTools(): string[] {
+  const src = readSource('gateway/gateway.ts')
+  const m = src.match(/const ALLOWED_TOOLS = new Set\(\[([\s\S]*?)\]\)/)
+  if (m == null) throw new Error('could not locate ALLOWED_TOOLS in gateway/gateway.ts')
+  return [...m[1].matchAll(/'([a-z0-9_]+)'/g)].map((x) => x[1])
+}
+
+/** Tool names advertised by the bridge's MCP `tools/list` (`TOOL_SCHEMAS`). */
+function bridgeToolSchemaNames(): string[] {
+  const src = readSource('bridge/bridge.ts')
+  const m = src.match(/const TOOL_SCHEMAS = \[([\s\S]*?)\n\]\n/)
+  if (m == null) throw new Error('could not locate TOOL_SCHEMAS in bridge/bridge.ts')
+  return [...m[1].matchAll(/^ {4}name: '([a-z0-9_]+)',$/gm)].map((x) => x[1])
+}
+
+/**
+ * Tools deliberately executable-but-unadvertised. EMPTY on purpose.
+ *
+ * Adding a name here is a decision to make a capability unreachable by the
+ * model — it needs a comment naming the reason, not just an entry. The whole
+ * point of this file is that the omission is explicit and reviewed rather than
+ * an accident of a refactor.
+ */
+const INTENTIONALLY_UNADVERTISED: ReadonlySet<string> = new Set([])
+
+describe('bridge MCP tool surface ↔ gateway ALLOWED_TOOLS parity', () => {
+  it('parses both declarations (guards against a silently no-op test)', () => {
+    expect(gatewayAllowedTools().length).toBeGreaterThan(15)
+    expect(bridgeToolSchemaNames().length).toBeGreaterThan(15)
+  })
+
+  it('advertises every gateway-executable tool', () => {
+    const advertised = new Set(bridgeToolSchemaNames())
+    const missing = gatewayAllowedTools().filter(
+      (t) => !advertised.has(t) && !INTENTIONALLY_UNADVERTISED.has(t),
+    )
+    expect(missing).toEqual([])
+  })
+
+  it('advertises no tool the gateway would refuse to execute', () => {
+    const allowed = new Set(gatewayAllowedTools())
+    const orphans = bridgeToolSchemaNames().filter((t) => !allowed.has(t))
+    expect(orphans).toEqual([])
+  })
+
+  it('registers progress_update — the tool this guard was written for', () => {
+    expect(bridgeToolSchemaNames()).toContain('progress_update')
+    expect(gatewayAllowedTools()).toContain('progress_update')
+  })
+
+  it('keeps progress_update reachable through the tool-surface filter', () => {
+    // The Linear gate (tool-filter.ts) must not strip it, with or without a
+    // Linear connection: an unregistered-in-effect tool is the same outage.
+    const schemas = bridgeToolSchemaNames().map((name) => ({ name }))
+    for (const linearEnabled of [false, true]) {
+      const names = buildEffectiveToolSchemas(schemas, { linearEnabled }).map((t) => t.name)
+      expect(names).toContain('progress_update')
+    }
+  })
+})