switchroom 0.19.18 → 0.19.22

package/telegram-plugin/gateway/status-pin-api.ts

@@ -0,0 +1,145 @@
+/**
+ * status-pin-api.ts — the Bot API surface the status-pin driver calls, bound to
+ * the gateway's retry policy + send gate (#3664).
+ *
+ * Extracted out of `gateway.ts` (which is under a line ratchet,
+ * `scripts/check-gateway-line-ratchet.mjs`) so the two invariants below can be
+ * enforced in code and proven in isolation, instead of resting on defaults that
+ * live in other modules.
+ *
+ * INVARIANT 1 — the bot must exist (`assertBotReady`).
+ * `lockedBot` in gateway.ts is declared `let lockedBot!: Bot<Context>`. The
+ * definite-assignment `!` is an ASSERTION, not a guarantee: it told `tsc` to
+ * stop checking, which is exactly why the boot orphan sweep dereferencing an
+ * unset `lockedBot` at module-eval time compiled clean and shipped. Every unpin
+ * it issued failed with the opaque
+ * `undefined is not an object (evaluating 'lockedBot.api')`, which read like a
+ * Telegram fault for a month. The ordering FIX is the two-condition gate in
+ * `boot-sweep-gate.ts`; this is the BACKSTOP, so any future pre-ready caller
+ * gets a named, greppable `STATUS_PIN_BOT_NOT_READY` instead.
+ *
+ * INVARIANT 2 — a shed send must not look like a landed one (`assertLanded`).
+ * See the docblock on `assertLanded`.
+ */
+
+import type { PinBotApi } from '../status-pin-driver.js'
+import { SEND_GATE_SHED } from '../send-gate.js'
+
+/** Thrown when the pin API is used before `lockedBot` has been assigned. */
+export class BotNotReadyError extends Error {
+  constructor(what: string) {
+    super(
+      `STATUS_PIN_BOT_NOT_READY: ${what} used before initGatewayBot() assigned ` +
+        `lockedBot — the boot sweep must run behind the boot-sweep gate`,
+    )
+    this.name = 'BotNotReadyError'
+  }
+}
+
+/** Narrow `bot` to non-null or throw {@link BotNotReadyError}. */
+export function assertBotReady<T>(bot: T | undefined | null, what: string): T {
+  if (bot == null) throw new BotNotReadyError(what)
+  return bot
+}
+
+/** Thrown when the outbound send gate SHED a pin/unpin — it never reached Telegram. */
+export class SendGateShedError extends Error {
+  constructor(verb: string) {
+    super(`STATUS_PIN_SEND_SHED: ${verb} was shed by the send gate and never reached Telegram`)
+    this.name = 'SendGateShedError'
+  }
+}
+
+/**
+ * Convert a send-gate SHED into a throw.
+ *
+ * The pin state machine reads "the call did not throw" as "the pin/unpin
+ * LANDED": `reconcilePin` claims the message on a resolved pin, and treats a
+ * resolved unpin as confirmed — dropping the in-memory claim AND (via the null
+ * branch of `reconcileAndPersistStatusPin`) the durable `status-pins.json` row.
+ * A send that was DROPPED but resolved success-shaped therefore reopens #3664
+ * Defect B through a second door: the still-pinned message loses its last
+ * record and no reaper or boot sweep can ever find it again.
+ *
+ * `robustApiCall` does not throw on a shed — it RESOLVES the gate's
+ * `SEND_GATE_SHED` sentinel (send-gate.ts). Today a status-pin call
+ * cannot be shed, because it is an untagged SEND and untagged sends admit as
+ * `UNTAGGED_SEND_CLASS`, which is `'critical'` and is never shed.
+ * But that is a DEFAULT IN ANOTHER MODULE: tagging `status-pin.unpin` with a
+ * `priorityClass`, or changing that default, would silently reopen the defect
+ * with no test failing. This turns the default into an enforced invariant.
+ *
+ * Sentinel ONLY. A plain `undefined` is deliberately NOT a failure: the gate
+ * also resolves `undefined` for a benign no-op drop (identical payload already
+ * on screen) and the retry policy resolves `undefined` for swallowed benign
+ * 400s. Conflating those with a shed is the exact ambiguity `SEND_GATE_SHED`
+ * was introduced to remove (see its docblock in send-gate.ts).
+ *
+ * Known residual: a `useful`-classed send whose queue TTL EXPIRES also resolves
+ * `undefined` (`send-gate.ts`, `outcome.result === 'expired'`) and so is not
+ * caught here. That is unreachable for status pins — they are untagged, hence
+ * `critical`, which is never TTL-dropped — and closing it would mean treating
+ * every benign `undefined` as a failure, which is strictly worse. If a status
+ * pin is ever deliberately tagged `useful`, this needs a distinguishable
+ * expiry sentinel too.
+ */
+export function assertLanded(result: unknown, verb: string): unknown {
+  if (result === SEND_GATE_SHED) throw new SendGateShedError(verb)
+  return result
+}
+
+/** Minimal shape of the wrapped gateway bot this module needs. */
+export interface PinCapableBot {
+  api: {
+    pinChatMessage: (
+      chatId: string | number,
+      messageId: number,
+      opts?: Record<string, unknown>,
+    ) => Promise<unknown>
+    unpinChatMessage: (chatId: string | number, messageId: number) => Promise<unknown>
+  }
+}
+
+/**
+ * The gateway's `robustApiCall` seam (retry policy + send gate), erased to the
+ * shape this module needs so `gateway.ts` can pass it with a single cast.
+ */
+export type RobustApiSeam = (
+  fn: () => Promise<unknown>,
+  opts: Record<string, unknown>,
+) => Promise<unknown>
+
+/**
+ * Build the pin API.
+ *
+ * `getBot` is read LAZILY on every call — `lockedBot` is assigned late, inside
+ * `initGatewayBot()` — and asserted non-null (INVARIANT 1). `robust` is the
+ * gateway's `robustApiCall`, so pins/unpins ride the send gate and retry policy
+ * exactly as before this extraction, with the shed sentinel converted to a
+ * throw on the way out (INVARIANT 2).
+ */
+export function createStatusPinApi(
+  getBot: () => PinCapableBot | undefined,
+  robust: RobustApiSeam,
+): PinBotApi {
+  const call = (verb: string, fn: (bot: PinCapableBot) => Promise<unknown>, chatId: string) =>
+    robust(() => fn(assertBotReady(getBot(), verb)), { chat_id: chatId, verb }).then((r) =>
+      assertLanded(r, verb),
+    )
+  return {
+    pinChatMessage: (chat_id, message_id, opts) =>
+      call(
+        'status-pin.pin',
+        // allow-raw-bot-api: `call` runs this inside the injected `robust` seam (robustApiCall).
+        (bot) => bot.api.pinChatMessage(chat_id, message_id, opts),
+        String(chat_id),
+      ),
+    unpinChatMessage: (chat_id, message_id) =>
+      call(
+        'status-pin.unpin',
+        // allow-raw-bot-api: as above — wrapped by the injected `robust` seam.
+        (bot) => bot.api.unpinChatMessage(chat_id, message_id),
+        String(chat_id),
+      ),
+  }
+}

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