switchroom 0.19.18 → 0.19.19

package/telegram-plugin/gateway/store-file.ts

@@ -0,0 +1,244 @@
+/**
+ * Shared read side for the gateway's small JSON state stores
+ * (`pending-card-store.ts`, `scoped-grant-store.ts`,
+ * `missed-approvals-store.ts`, `always-allow-persist-queue.ts`).
+ *
+ * Problem: each of those stores read its backing file with a bare
+ * `try { JSON.parse(readFileSync(...)) } catch { return [] }`. Combined
+ * with a non-atomic `writeFileSync` straight over the destination (fixed
+ * separately — every writer now goes through `atomicWriteFileSync`), a
+ * crash between truncate and write left a TORN file. On the next boot the
+ * parse threw, the catch swallowed it, and the store came up EMPTY: every
+ * pending approval card and every live scoped grant silently forgotten,
+ * with nothing in the logs. The operator just saw dead buttons.
+ *
+ * Losing security state must be OBSERVABLE. So a parse failure here is
+ * never silent:
+ *   - the corrupt bytes are preserved by renaming them aside to
+ *     `<file>.corrupt-<epoch-ms>-<seq>-<rand>` (never deleted while they are the
+ *     newest few — they're the forensic record of what was lost, and the
+ *     only chance of manual recovery);
+ *   - a loud `telegram gateway: <store> CORRUPT …` line goes to stderr,
+ *     the same channel the surrounding stores already log write failures
+ *     on (the gateway's stderr is captured in the agent's runtime log);
+ *   - the caller gets a non-`ok` result and starts from an empty store —
+ *     the process still boots, it just no longer does so in silence.
+ *
+ * Three read outcomes, deliberately distinguished:
+ *   - `missing`     — the normal cold start. Silent, no quarantine.
+ *   - `corrupt`     — unparseable JSON (or a shape the store rejects, via
+ *                     `quarantineCorruptStoreFile`). Quarantine + loud log.
+ *   - `unreadable`  — any other fs error (EACCES, EIO, EISDIR, …). Loud log,
+ *                     but NO quarantine: renaming a file we merely failed to
+ *                     read would destroy good state over a transient fault.
+ *                     Instead the caller FAILS CLOSED on its next write —
+ *                     see `preserveUnreadableStoreFile` below.
+ *
+ * ── Known hazard: two writers ──────────────────────────────────────────
+ * Quarantine is a destructive-looking move (it renames the destination
+ * away), and it is NOT safe against a second process writing the same
+ * file: process A can parse-fail on a torn file, process B can then
+ * atomically rename GOOD state into place, and A's quarantine would move
+ * B's good file aside. Pre-fix a parse failure was inert, so this hazard is
+ * introduced here. It is accepted because the gateway is (near-)singleton
+ * per agent — see the `withLock` note in `always-allow-persist-queue.ts`
+ * for why "near", and note the window is the few microseconds between the
+ * failed parse and the rename. If a genuine multi-writer arrangement ever
+ * appears, quarantine must become an flock-guarded compare-and-rename.
+ */
+
+import { randomBytes } from 'node:crypto'
+import { readFileSync, readdirSync, renameSync, rmSync, statSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+
+/** Default sink — matches the stores' existing `process.stderr.write` use. */
+const defaultLog = (line: string): void => {
+  process.stderr.write(line)
+}
+
+/**
+ * How many `<file>.corrupt-*` forensic copies to keep per store file.
+ * They're tiny, but a store that corrupts on a loop must not fill the
+ * state dir — so the oldest are reaped past this cap. Newest wins.
+ */
+export const MAX_QUARANTINED_COPIES = 5
+
+/** Outcome of a store-file read. See the module docblock. */
+export type StoreReadResult =
+  | { status: 'ok'; value: unknown }
+  | { status: 'missing' }
+  | { status: 'corrupt' }
+  | { status: 'unreadable' }
+
+/**
+ * Monotonic within this process. Purely a name-uniqueness aid now — the
+ * reaper orders by mtime, NOT by name (see `reapOldQuarantines`), because a
+ * name-based order is only monotonic within one process: a restart resets
+ * this counter to 0, and a fresh copy written in the same epoch-ms as a
+ * prior process's burst would sort as the OLDEST and be reaped first.
+ */
+let quarantineSeq = 0
+
+/**
+ * `<file>.corrupt-<epoch-ms>-<seq>-<rand>`.
+ *
+ * All three tail components exist to make the name UNIQUE: two quarantines
+ * in the same millisecond, or from two processes, would otherwise collide
+ * and the second `renameSync` would silently clobber the first forensic copy
+ * — same reasoning as the tempfile naming in `src/util/atomic.ts`. The name
+ * is deliberately NOT the ordering key; mtime is.
+ */
+function quarantinePath(filePath: string): string {
+  const seq = String(quarantineSeq++).padStart(6, '0')
+  return `${filePath}.corrupt-${Date.now()}-${seq}-${randomBytes(4).toString('hex')}`
+}
+
+/**
+ * Reap all but the newest {@link MAX_QUARANTINED_COPIES} forensic copies.
+ *
+ * Ordered by the filesystem's own mtime (nanosecond resolution via the
+ * bigint stat) — unlike the embedded `<epoch-ms>-<seq>`, whose sequence
+ * restarts at 0 on every boot and would make a fresh copy sort as the oldest
+ * whenever a restart lands in the same millisecond as the previous process's
+ * burst. The name is used only as a stable tie-break.
+ *
+ * Where the guarantee ends: this is exact only on filesystems that record
+ * mtime at (sub-)nanosecond granularity — ext4, xfs, apfs, btrfs all do. On a
+ * coarse-granularity filesystem (older ext3, some network/FUSE mounts, where
+ * mtime rounds to a whole second) a burst of more than MAX_QUARANTINED_COPIES
+ * quarantines inside one second all tie on `mtimeNs`, the sort falls through
+ * to the name, and the restart-reset ordering above comes back: the prior
+ * process burns seq 000001-000005 in second T, a restart quarantines at
+ * 000000, all six tie, and the freshest copy is reaped first. That costs a
+ * forensic copy on a rare filesystem and never live state, so it is not
+ * defended against here — but do not read this reaper as unconditionally
+ * restart-safe.
+ */
+function reapOldQuarantines(filePath: string, log: (line: string) => void): void {
+  const dir = dirname(filePath)
+  const prefix = `${basename(filePath)}.corrupt-`
+  try {
+    const copies = readdirSync(dir)
+      .filter(f => f.startsWith(prefix))
+      .map(name => {
+        let mtimeNs = 0n
+        try {
+          mtimeNs = statSync(join(dir, name), { bigint: true }).mtimeNs
+        } catch {
+          // Vanished under us (a concurrent reap) — sorts oldest; the rmSync
+          // below is `force`, so a missing file is a no-op either way.
+        }
+        return { name, mtimeNs }
+      })
+      .sort((a, b) => (a.mtimeNs === b.mtimeNs ? a.name.localeCompare(b.name) : a.mtimeNs < b.mtimeNs ? -1 : 1))
+    for (const stale of copies.slice(0, Math.max(0, copies.length - MAX_QUARANTINED_COPIES))) {
+      rmSync(join(dir, stale.name), { force: true })
+    }
+  } catch (err) {
+    // Reaping is opportunistic — never let it mask the corruption itself.
+    log(`telegram gateway: quarantine reap failed dir=${dir}: ${(err as Error).message}\n`)
+  }
+}
+
+/**
+ * Move a corrupt/unusable store file aside so its bytes survive, and log
+ * loudly. Exported for stores whose corruption is a SHAPE failure (valid
+ * JSON, wrong structure) that only the store itself can detect.
+ */
+export function quarantineCorruptStoreFile(
+  filePath: string,
+  store: string,
+  reason: string,
+  log: (line: string) => void = defaultLog,
+): void {
+  const target = quarantinePath(filePath)
+  let preserved = target
+  try {
+    renameSync(filePath, target)
+  } catch (err) {
+    preserved = `NOT preserved (${(err as Error).message})`
+  }
+  log(
+    `telegram gateway: ${store} CORRUPT — ${reason}. ` +
+      `Persisted state was LOST and the store is starting EMPTY; ` +
+      `corrupt file ${preserved}\n`,
+  )
+  reapOldQuarantines(filePath, log)
+}
+
+/**
+ * FAIL-CLOSED guard for the `unreadable` read outcome.
+ *
+ * A read that failed for a non-ENOENT reason (a flaky mount returning EIO,
+ * a transient EACCES) leaves the store in memory EMPTY while the on-disk
+ * file may still hold perfectly good state. The next `save()` would then
+ * rename a fresh, near-empty file over it and destroy that state
+ * permanently — quietly, and for a fault that may have lasted one syscall.
+ *
+ * So the stores call this immediately BEFORE their first write following an
+ * unreadable read: the existing bytes are renamed aside (same
+ * `.corrupt-<ts>-<seq>-<rand>` forensic convention) so the overwrite can never be
+ * the thing that loses them. If the rename itself fails the write is
+ * ABORTED by throwing — better a loud failed write than a silent
+ * destruction of the only copy.
+ */
+export function preserveUnreadableStoreFile(
+  filePath: string,
+  store: string,
+  log: (line: string) => void = defaultLog,
+): void {
+  const target = quarantinePath(filePath)
+  try {
+    renameSync(filePath, target)
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+      // Nothing there to lose — the read failure wasn't about existing bytes.
+      return
+    }
+    log(
+      `telegram gateway: ${store} REFUSING to overwrite an unreadable file at ` +
+        `${filePath} — could not preserve it first: ${(err as Error).message}\n`,
+    )
+    throw err
+  }
+  log(
+    `telegram gateway: ${store} could not READ its file but is about to write it. ` +
+      `Preserved the previous (unreadable) bytes as ${target} rather than ` +
+      `overwriting them; the store continues from EMPTY\n`,
+  )
+  reapOldQuarantines(filePath, log)
+}
+
+/**
+ * Read + parse a store's backing JSON file. See {@link StoreReadResult} and
+ * the module docblock for what each outcome means and what it triggers.
+ */
+export function readStoreJsonSync(
+  filePath: string,
+  store: string,
+  log: (line: string) => void = defaultLog,
+): StoreReadResult {
+  let raw: string
+  try {
+    raw = readFileSync(filePath, 'utf-8')
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return { status: 'missing' }
+    log(
+      `telegram gateway: ${store} read FAILED path=${filePath}: ` +
+        `${(err as Error).message} — starting EMPTY for this read; the next write ` +
+        `will preserve the unreadable file rather than overwrite it\n`,
+    )
+    return { status: 'unreadable' }
+  }
+  try {
+    return { status: 'ok', value: JSON.parse(raw) }
+  } catch (err) {
+    quarantineCorruptStoreFile(
+      filePath,
+      store,
+      `unparseable JSON (${(err as Error).message}) — likely a torn write from a crash mid-persist`,
+      log,
+    )
+    return { status: 'corrupt' }
+  }
+}

package/telegram-plugin/hooks/tool-label-pretool.mjs

@@ -96,6 +96,85 @@ function urlHostPath(u) {
   }
 }
 
+/**
+ * ALLOWLIST-style summary of a Bash command, for when the model omitted the
+ * optional `description`.
+ *
+ * The failure this closes: `description` is optional, so a sub-agent that never
+ * writes one produced the constant label "Running a command" for EVERY Bash
+ * call. The worker feed's narrative dedup then dropped every repeat and the
+ * card froze on one line for the whole job — the user could not tell a running
+ * worker from a wedged one. The card must never depend on a model volunteering
+ * an optional field.
+ *
+ * SECURITY: a command line routinely carries tokens, passwords, URLs with
+ * credentials, and private paths, and this string is rendered into a Telegram
+ * message. So this is NOT a clip of the command — nothing is echoed unless it
+ * passes a strict allowlist:
+ *   - only the PROGRAM name (basename, no directory), and
+ *   - for a known multiplexer (git/docker/npm/…), at most one bare subcommand
+ *     of pure lowercase letters/hyphens.
+ * Anything with a slash, `=`, digit-mixed shape, quote, or any other character
+ * is refused and we fall back to the generic label. Arguments, flag VALUES,
+ * env assignments, redirections and heredocs are never considered at all.
+ *
+ * Returns '' when nothing safe can be derived (caller uses the generic label).
+ */
+export function summariseBashCommand(cmd) {
+  if (typeof cmd !== 'string') return ''
+  // First line only — a heredoc/multiline body must never be inspected.
+  const firstLine = cmd.split('\n', 1)[0]
+  if (!firstLine) return ''
+
+  // Split on shell separators and prefer the first segment that actually runs
+  // something (`cd /x && git status` should read as "git status", not "cd").
+  const NAV = new Set(['cd', 'pushd', 'popd', 'export', 'set', 'source', '.', 'unset'])
+  const PREFIXES = new Set(['sudo', 'env', 'nohup', 'time', 'exec', 'command', 'doas', 'runuser', 'nice', 'xargs'])
+  const segments = firstLine.split(/&&|\|\||[;|]/).map((s) => s.trim()).filter(Boolean)
+  if (segments.length === 0) return ''
+
+  const PROGRAM_RE = /^[A-Za-z][A-Za-z0-9._+-]{0,19}$/
+  const SUBCOMMAND_RE = /^[a-z][a-z-]{1,15}$/
+  const MULTIPLEXERS = new Set([
+    'git', 'docker', 'npm', 'npx', 'bun', 'yarn', 'pnpm', 'cargo', 'go', 'gh',
+    'kubectl', 'systemctl', 'apt', 'apt-get', 'brew', 'pip', 'pip3', 'poetry',
+    'uv', 'terraform', 'aws', 'gcloud', 'helm', 'switchroom', 'make', 'openssl',
+  ])
+
+  /** Program + optional subcommand for one segment, or null. */
+  function fromSegment(seg) {
+    let tokens = seg.split(/\s+/).filter(Boolean)
+    // Drop leading env assignments (FOO=bar) and wrapper prefixes.
+    while (tokens.length > 0 && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[0]) || PREFIXES.has(tokens[0]))) {
+      tokens = tokens.slice(1)
+    }
+    if (tokens.length === 0) return null
+    // Basename only: never surface a directory (paths leak layout, usernames).
+    const head = safeBasename(tokens[0])
+    if (!PROGRAM_RE.test(head)) return null
+    if (NAV.has(head)) return { program: head, nav: true }
+    if (!MULTIPLEXERS.has(head)) return { program: head, nav: false }
+    // ONLY the immediately-following token may be a subcommand. Scanning past
+    // flags would surface a flag VALUE (`docker --context prod-internal ps` →
+    // "prod-internal"), which is exactly the kind of private name this
+    // function exists to keep out of a chat message. `git -C /x status` losing
+    // its "status" is the correct trade.
+    const next = tokens[1]
+    return next != null && SUBCOMMAND_RE.test(next)
+      ? { program: `${head} ${next}`, nav: false }
+      : { program: head, nav: false }
+  }
+
+  let firstAny = null
+  for (const seg of segments) {
+    const r = fromSegment(seg)
+    if (r == null) continue
+    if (firstAny == null) firstAny = r
+    if (!r.nav) return r.program
+  }
+  return firstAny != null ? firstAny.program : ''
+}
+
 /**
  * Compute a label for a (toolName, input) pair. Returns null when the
  * tool should NOT be labeled (suppress / fall through to existing
@@ -111,8 +190,15 @@ export function computeLabel(toolName, input) {
   // never reaches the live draft. Uses the model-authored `description`
   // for Bash/Task, matching the gateway's describeToolUse rendering.
   switch (toolName) {
-    case 'Bash':
-      return clip(asText(i.description), 70).trim() || 'Running a command'
+    case 'Bash': {
+      const described = clip(asText(i.description), 70).trim()
+      if (described) return described
+      // No model-authored description — derive a sanitised one from the
+      // command itself rather than emitting the constant "Running a command"
+      // that freezes the step feed. See summariseBashCommand.
+      const derived = summariseBashCommand(asText(i.command))
+      return derived ? `Running ${derived}` : 'Running a command'
+    }
     case 'Task':
     case 'Agent': {
       const d = clip(asText(i.description), 60).trim()

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')
+    }
+  })
+})