switchroom 0.19.18 → 0.19.19

package/telegram-plugin/dist/server.js

@@ -24767,6 +24767,19 @@ var init_bridge = __esm(async () => {
         required: ["chat_id", "text"]
       }
     },
+    {
+      name: "progress_update",
+      description: 'Post a short interim progress line to Telegram mid-task ("still working through X"). Sends a NEW plain message to the chat \u2014 it is not an edit and not a card row, so use it sparingly and only when the user genuinely benefits from knowing where a long task stands. The gateway enforces its own limits: text is truncated at 300 chars, at most one update per 20s per chat+thread, and at most 5 per turn; over-limit calls return {ok:false, reason:"too_soon"|"turn_limit"} instead of sending. Prefer edit_message when you already own a message to update, and always deliver the actual answer with reply.',
+      inputSchema: {
+        type: "object",
+        properties: {
+          chat_id: { type: "string", description: "Chat to post the progress line in \u2014 pass chat_id from the inbound message." },
+          text: { type: "string", description: "The progress line. One short sentence; truncated at 300 chars by the gateway." },
+          message_thread_id: { type: "string", description: "Forum topic thread ID. Auto-applied from the last inbound message in the same chat if not specified." }
+        },
+        required: ["chat_id", "text"]
+      }
+    },
     {
       name: "react",
       description: "Add an emoji reaction to a Telegram message. Telegram only accepts a fixed whitelist (\uD83D\uDC4D \uD83D\uDC4E \u2764 \uD83D\uDD25 \uD83D\uDC40 \uD83C\uDF89 etc) \u2014 non-whitelisted emoji will be rejected.",

package/telegram-plugin/gateway/always-allow-persist-queue.ts

@@ -32,11 +32,18 @@
  * {@link MAX_QUEUE_SIZE} below, and the tests that pin them.
  *
  * File format mirrors `missed-approvals-store.ts`: a single bounded JSON
- * array, written synchronously, mode 0o600.
+ * array, written synchronously and ATOMICALLY (tmp + fsync + rename),
+ * mode 0o600 — a crash mid-persist leaves the previous queue intact
+ * instead of a torn file. NOTE: atomic REPLACEMENT only —
+ * whole-old-or-whole-new, not power-loss durability; the missing
+ * parent-directory fsync is tracked in #3603.
  *
  * Failure semantics (hardened post-#2973 adversarial review): a failed
- * READ degrades to an empty list — a corrupt/missing queue file is not
- * fatal, it just means "nothing queued yet". A failed WRITE is a
+ * READ degrades to an empty list so the gateway still boots — but a
+ * CORRUPT file is no longer silent: the bytes are quarantined to
+ * `<file>.corrupt-<ts>` and a loud line goes to the log (see
+ * `store-file.ts`), because "queue silently came up empty" is exactly
+ * how queued retries disappeared unnoticed. A failed WRITE is a
  * different story: silently swallowing it would mean `enqueue()` tells
  * its caller "queued for retry" when nothing was actually persisted to
  * disk, and a concurrent `recordAttempt()`/`remove()` would silently
@@ -51,8 +58,14 @@
  * success.
  */
 
-import { readFileSync, writeFileSync, unlinkSync } from 'node:fs'
+import { writeFileSync, unlinkSync } from 'node:fs'
 import { join } from 'node:path'
+import { atomicWriteFileSync } from '../../src/util/atomic.js'
+import {
+  preserveUnreadableStoreFile,
+  quarantineCorruptStoreFile,
+  readStoreJsonSync,
+} from './store-file.js'
 
 /** Hard cap on retry attempts per entry — never retry indefinitely. */
 export const MAX_ATTEMPTS = 5
@@ -161,13 +174,33 @@ export function computeBackoffMs(attempts: number, retryAfterMs?: number): numbe
   return exp
 }
 
+/**
+ * The real writer: `atomicWriteFileSync` (tmp + fsync + rename) behind a
+ * `writeFileSync`-shaped signature, so the injectable seam below keeps its
+ * existing type and the fault-injection tests are unaffected. Only `mode`
+ * from the options bag is meaningful here; the store always passes 0o600.
+ */
+export const atomicWriteSeam = ((path, data, opts) => {
+  const mode = typeof opts === 'object' && opts !== null && typeof opts.mode === 'number' ? opts.mode : 0o600
+  atomicWriteFileSync(path as string, data as string, mode)
+}) as typeof writeFileSync
+
 export function createAlwaysAllowPersistQueue(
   stateDir: string,
   /** Injectable for tests to force a write failure (disk full / permissions /
    * read-only fs) without real filesystem faults — we run as root in CI/
    * containers, so chmod-based permission tricks don't reliably fail, and
-   * bun's test runner doesn't support mocking node:fs built-ins. */
-  writeFileSyncFn: typeof writeFileSync = writeFileSync,
+   * bun's test runner doesn't support mocking node:fs built-ins.
+   *
+   * CAUTION: a test that injects a seam replaces the ATOMIC writer. Such a
+   * test proves failure PROPAGATION, never atomicity — the injected function
+   * is whatever the test supplies (typically a plain `writeFileSync`, which
+   * is exactly the non-atomic writer this store moved off). Tests that mean
+   * to exercise the real write path must either leave this defaulted or wrap
+   * the exported {@link atomicWriteSeam}. */
+  writeFileSyncFn: typeof writeFileSync = atomicWriteSeam,
+  /** Log sink — defaults to stderr (the gateway's runtime log). */
+  log: (line: string) => void = l => process.stderr.write(l),
 ): AlwaysAllowPersistQueue {
   const filePath = join(stateDir, 'always-allow-persist-queue.json')
 
@@ -183,6 +216,26 @@ export function createAlwaysAllowPersistQueue(
   // single promise chain, so at most one is ever in flight at a time,
   // regardless of how many callers invoke enqueue/recordAttempt/remove
   // "concurrently".
+  //
+  // SCOPE (verified, not assumed): this is an IN-PROCESS promise chain, not
+  // an OS file lock. It serializes callers inside ONE gateway process only.
+  // Two gateway processes sharing a STATE_DIR WOULD still lose updates to
+  // each other, and that is not impossible — only rare. `startup-mutex.ts`
+  // makes concurrent gateways UNLIKELY, not unreachable: its bootMismatch
+  // path steals the lock with NO liveness check when the holder's bootId
+  // differs from the current one (exactly the restart-overlap case on a
+  // shared STATE_DIR — see the `boot.lock_stale_recovered_boot_mismatch`
+  // revert referenced at gateway.ts), `readCurrentBootId()` returns null
+  // off-Linux which disables the gate entirely, the lock is taken once at
+  // boot and never revalidated, and `isGatewayMain` lets harnesses bypass
+  // it. So: rare, not guaranteed.
+  //
+  // Cross-process mutual exclusion is deliberately OUT OF SCOPE for this
+  // change (which is about torn writes, not lost updates), and every write
+  // here is now atomic so an overlap can lose an update but can never
+  // corrupt the file. A real `flock` (cf. src/vault/flock-concurrent.test.ts)
+  // is the durable fix — tracked as follow-up. Do not read the startup mutex
+  // as a hard singleton invariant.
   let lock: Promise<unknown> = Promise.resolve()
   function withLock<T>(fn: () => T): Promise<T> {
     const result = lock.then(fn, fn) // run fn even if the previous link rejected
@@ -192,14 +245,39 @@ export function createAlwaysAllowPersistQueue(
     return result
   }
 
+  /** Set when the last read failed for a non-ENOENT reason — the next write
+   * must preserve the file it could not read instead of clobbering it. */
+  let unreadable = false
+
   function read(): FileShape {
-    try {
-      const raw = readFileSync(filePath, 'utf-8')
-      const parsed = JSON.parse(raw) as Partial<FileShape>
-      return { entries: Array.isArray(parsed?.entries) ? parsed.entries : [] }
-    } catch {
+    const result = readStoreJsonSync(filePath, 'always-allow-persist-queue', log)
+    unreadable = result.status === 'unreadable'
+    if (result.status !== 'ok') return { entries: [] }
+    const parsed = result.value as Partial<FileShape>
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+      quarantineCorruptStoreFile(
+        filePath,
+        'always-allow-persist-queue',
+        'parsed to a non-object — not a persist-queue file',
+        log,
+      )
       return { entries: [] }
     }
+    // A PRESENT-but-non-array `entries` is corruption, not "empty queue".
+    // Coercing it to [] would resurrect the silent-loss bug: a half-written
+    // `{"entries": {}}` parses fine, so quarantine would never fire and the
+    // queued retries would vanish unnoticed. An ABSENT `entries` is the
+    // legitimate cold-start/partial-shape case and stays silent.
+    if (parsed.entries !== undefined && !Array.isArray(parsed.entries)) {
+      quarantineCorruptStoreFile(
+        filePath,
+        'always-allow-persist-queue',
+        '`entries` is present but not an array — truncated or malformed write',
+        log,
+      )
+      return { entries: [] }
+    }
+    return { entries: parsed.entries ?? [] }
   }
 
   /** Unlike `read()`, a write failure is NOT swallowed — it propagates so
@@ -207,6 +285,14 @@ export function createAlwaysAllowPersistQueue(
    * not actually land on disk (disk full, permissions, etc.) instead of
    * silently proceeding as if it had. */
   function write(f: FileShape): void {
+    // Fail closed: never let an overwrite be what destroys a queue we merely
+    // failed to READ (flaky mount, transient EACCES) — this throws if the
+    // previous bytes can't be preserved, and that throw is exactly the
+    // propagate-don't-swallow contract above.
+    if (unreadable) {
+      preserveUnreadableStoreFile(filePath, 'always-allow-persist-queue', log)
+      unreadable = false
+    }
     writeFileSyncFn(filePath, JSON.stringify(f), { encoding: 'utf-8', mode: 0o600 })
   }
 

package/telegram-plugin/gateway/missed-approvals-store.ts

@@ -19,13 +19,24 @@
  * record and edits the card closed.
  *
  * File format: a single JSON object `{ pending, delivered }`, written
- * synchronously to avoid interleaving on concurrent auto-denies, mode 0o600.
- * Mirrors the `permission-card-store.ts` pattern. Both lists are hard-capped
- * so the file stays tiny under a runaway loop.
+ * synchronously to avoid interleaving on concurrent auto-denies, mode 0o600,
+ * ATOMICALLY (tmp + fsync + rename) so a crash mid-persist can't leave a torn
+ * file. Mirrors the `permission-card-store.ts` pattern. Both lists are
+ * hard-capped so the file stays tiny under a runaway loop. A corrupt file is
+ * quarantined and logged loudly rather than silently read as "nothing was
+ * missed" — see store-file.ts. NOTE: atomic REPLACEMENT only —
+ * whole-old-or-whole-new, not power-loss durability; the missing
+ * parent-directory fsync is tracked in #3603.
  */
 
-import { readFileSync, writeFileSync, unlinkSync } from 'node:fs'
+import { unlinkSync } from 'node:fs'
 import { join } from 'node:path'
+import { atomicWriteFileSync } from '../../src/util/atomic.js'
+import {
+  preserveUnreadableStoreFile,
+  quarantineCorruptStoreFile,
+  readStoreJsonSync,
+} from './store-file.js'
 
 export interface MissedApproval {
   /** The permission request_id that timed out (dedup key). */
@@ -80,29 +91,67 @@ export interface MissedApprovalsStore {
 export const MAX_PENDING = 50
 export const MAX_DELIVERED = 20
 
-export function createMissedApprovalsStore(stateDir: string): MissedApprovalsStore {
+export function createMissedApprovalsStore(
+  stateDir: string,
+  /** Log sink — defaults to stderr (the gateway's runtime log). */
+  log: (line: string) => void = l => process.stderr.write(l),
+): MissedApprovalsStore {
   const filePath = join(stateDir, 'missed-approvals.json')
 
+  const EMPTY = (): FileShape => ({ pending: [], delivered: [] })
+
+  /** Set when the last read failed for a non-ENOENT reason — the next write
+   * must preserve the file it could not read instead of clobbering it. */
+  let unreadable = false
+
   function read(): FileShape {
-    try {
-      const raw = readFileSync(filePath, 'utf-8')
-      const parsed = JSON.parse(raw) as Partial<FileShape>
-      return {
-        pending: Array.isArray(parsed?.pending) ? parsed.pending : [],
-        delivered: Array.isArray(parsed?.delivered) ? parsed.delivered : [],
+    const result = readStoreJsonSync(filePath, 'missed-approvals-store', log)
+    unreadable = result.status === 'unreadable'
+    if (result.status !== 'ok') return EMPTY()
+    const parsed = result.value as Partial<FileShape>
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+      quarantineCorruptStoreFile(
+        filePath,
+        'missed-approvals-store',
+        'parsed to a non-object — not a missed-approvals file',
+        log,
+      )
+      return EMPTY()
+    }
+    // A PRESENT-but-non-array list is corruption, not "empty". Coercing it to
+    // [] would resurrect the exact bug this store was hardened against: a
+    // half-written `{"pending": null}` parses fine, so quarantine would never
+    // fire and the digest would silently come up empty. An ABSENT list is the
+    // legitimate cold-start/partial-shape case and stays silent.
+    for (const field of ['pending', 'delivered'] as const) {
+      if (parsed[field] !== undefined && !Array.isArray(parsed[field])) {
+        quarantineCorruptStoreFile(
+          filePath,
+          'missed-approvals-store',
+          `\`${field}\` is present but not an array — truncated or malformed write`,
+          log,
+        )
+        return EMPTY()
       }
-    } catch {
-      return { pending: [], delivered: [] }
+    }
+    return {
+      pending: parsed.pending ?? [],
+      delivered: parsed.delivered ?? [],
     }
   }
 
   function write(f: FileShape): void {
     try {
-      writeFileSync(filePath, JSON.stringify(f), { encoding: 'utf-8', mode: 0o600 })
+      // Fail closed: never let an overwrite be what destroys state we merely
+      // failed to READ (flaky mount, transient EACCES).
+      if (unreadable) {
+        preserveUnreadableStoreFile(filePath, 'missed-approvals-store', log)
+        unreadable = false
+      }
+      // tmp + fsync + rename — never truncate the destination in place.
+      atomicWriteFileSync(filePath, JSON.stringify(f), 0o600)
     } catch (err) {
-      process.stderr.write(
-        `telegram gateway: missed-approvals-store write failed: ${(err as Error).message}\n`,
-      )
+      log(`telegram gateway: missed-approvals-store write failed: ${(err as Error).message}\n`)
     }
   }
 

package/telegram-plugin/gateway/pending-card-store.ts

@@ -32,11 +32,24 @@
  *
  * File format: JSON array of PersistedApprovalCard objects. Written
  * synchronously (mode 0o600) to avoid interleaving on concurrent card posts;
- * production rate is a handful of cards, so the file stays tiny.
+ * production rate is a handful of cards, so the file stays tiny. The write
+ * goes through `atomicWriteFileSync` (tmp + fsync + rename) so a crash
+ * mid-persist can never leave a torn file behind — the destination holds
+ * either the whole previous array or the whole new one. A file that IS
+ * corrupt (from a pre-fix write, or anything else) is quarantined and logged
+ * loudly rather than silently read as "no pending cards" — see
+ * `store-file.ts`. NOTE: atomic REPLACEMENT only — whole-old-or-whole-new, not
+ * power-loss durability; the missing parent-directory fsync is tracked in #3603.
  */
 
-import { readFileSync, writeFileSync, unlinkSync, chmodSync } from 'node:fs'
+import { unlinkSync } from 'node:fs'
 import { join } from 'node:path'
+import { atomicWriteFileSync } from '../../src/util/atomic.js'
+import {
+  preserveUnreadableStoreFile,
+  quarantineCorruptStoreFile,
+  readStoreJsonSync,
+} from './store-file.js'
 
 /** The four agent-initiated approval-card families we persist. */
 export type ApprovalCardFamily =
@@ -111,30 +124,47 @@ export interface PendingCardStore {
   clear(): void
 }
 
-export function createPendingCardStore(stateDir: string): PendingCardStore {
+export function createPendingCardStore(
+  stateDir: string,
+  /** Log sink — defaults to stderr (the gateway's runtime log). */
+  log: (line: string) => void = l => process.stderr.write(l),
+): PendingCardStore {
   const filePath = join(stateDir, 'pending-approval-cards.json')
 
+  /** Set when the last read failed for a non-ENOENT reason — the next write
+   * must preserve the file it could not read instead of clobbering it. */
+  let unreadable = false
+
   function read(): PersistedApprovalCard[] {
-    try {
-      const raw = readFileSync(filePath, 'utf-8')
-      const parsed = JSON.parse(raw)
-      return Array.isArray(parsed) ? (parsed as PersistedApprovalCard[]) : []
-    } catch {
+    const result = readStoreJsonSync(filePath, 'pending-card-store', log)
+    unreadable = result.status === 'unreadable'
+    if (result.status !== 'ok') return []
+    if (!Array.isArray(result.value)) {
+      quarantineCorruptStoreFile(
+        filePath,
+        'pending-card-store',
+        'parsed to a non-array — not a pending-card file',
+        log,
+      )
       return []
     }
+    return result.value as PersistedApprovalCard[]
   }
 
   function write(entries: PersistedApprovalCard[]): void {
     try {
-      writeFileSync(filePath, JSON.stringify(entries), { encoding: 'utf-8', mode: 0o600 })
-      // `mode` only applies when writeFileSync CREATES the file; an existing
-      // file keeps its prior perms. Re-assert 0600 on every write so the file
-      // can never stay laxer than intended.
-      chmodSync(filePath, 0o600)
+      // Fail closed: never let an overwrite be what destroys state we merely
+      // failed to READ (flaky mount, transient EACCES) — throws if it can't.
+      if (unreadable) {
+        preserveUnreadableStoreFile(filePath, 'pending-card-store', log)
+        unreadable = false
+      }
+      // tmp + fsync + rename, mode pinned to 0600 on the tempfile fd (so an
+      // existing file can't keep laxer perms, and a crash mid-write leaves
+      // the previous good file untouched).
+      atomicWriteFileSync(filePath, JSON.stringify(entries), 0o600)
     } catch (err) {
-      process.stderr.write(
-        `telegram gateway: pending-card-store write failed: ${(err as Error).message}\n`,
-      )
+      log(`telegram gateway: pending-card-store write failed: ${(err as Error).message}\n`)
     }
   }
 

package/telegram-plugin/gateway/scoped-grant-store.ts

@@ -8,7 +8,11 @@
  * immediately. It reads as "my approval didn't stick."
  *
  * Fix: mirror the store to a tiny JSON file in STATE_DIR (same shape as
- * permission-card-store.ts — synchronous writes, mode 0o600, one small file).
+ * permission-card-store.ts — synchronous ATOMIC writes (tmp + fsync + rename),
+ * mode 0o600, one small file; a corrupt file is quarantined and logged loudly
+ * rather than silently read as "no grants" — see store-file.ts). NOTE: atomic
+ * REPLACEMENT only — whole-old-or-whole-new, not power-loss durability; the
+ * missing parent-directory fsync is tracked in #3603.
  * Write-through on every grant and on sweep-expiry removal; reload at boot,
  * dropping entries already past their ABSOLUTE expiry.
  *
@@ -23,8 +27,13 @@
  * and never write (any pre-existing file is ignored).
  */
 
-import { readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { atomicWriteFileSync } from '../../src/util/atomic.js'
+import {
+  preserveUnreadableStoreFile,
+  quarantineCorruptStoreFile,
+  readStoreJsonSync,
+} from './store-file.js'
 import {
   serializeScopedGrants,
   deserializeScopedGrants,
@@ -50,18 +59,31 @@ export function scopedGrantPersistEnabled(
 export function createScopedGrantStore(
   stateDir: string,
   env: Record<string, string | undefined> = process.env,
+  /** Log sink — defaults to stderr (the gateway's runtime log). */
+  log: (line: string) => void = l => process.stderr.write(l),
 ): ScopedGrantPersistence {
   const filePath = join(stateDir, 'scoped-grants.json')
   const enabled = scopedGrantPersistEnabled(env)
 
+  /** Set when the last read failed for a non-ENOENT reason — the next write
+   * must preserve the file it could not read instead of clobbering it. */
+  let unreadable = false
+
   function read(): unknown[] {
-    try {
-      const raw = readFileSync(filePath, 'utf-8')
-      const parsed = JSON.parse(raw)
-      return Array.isArray(parsed) ? parsed : []
-    } catch {
+    const result = readStoreJsonSync(filePath, 'scoped-grant-store', log)
+    unreadable = result.status === 'unreadable'
+    if (result.status !== 'ok') return []
+    const parsed = result.value
+    if (!Array.isArray(parsed)) {
+      quarantineCorruptStoreFile(
+        filePath,
+        'scoped-grant-store',
+        'parsed to a non-array — not a scoped-grants file',
+        log,
+      )
       return []
     }
+    return parsed
   }
 
   return {
@@ -75,14 +97,17 @@ export function createScopedGrantStore(
     save(store) {
       if (!enabled) return
       try {
-        writeFileSync(filePath, JSON.stringify(serializeScopedGrants(store)), {
-          encoding: 'utf-8',
-          mode: 0o600,
-        })
+        // Fail closed: never let an overwrite be what destroys grants we
+        // merely failed to READ (flaky mount, transient EACCES).
+        if (unreadable) {
+          preserveUnreadableStoreFile(filePath, 'scoped-grant-store', log)
+          unreadable = false
+        }
+        // tmp + fsync + rename — a crash mid-persist leaves the previous
+        // grant set intact rather than a torn file that reads as "no grants".
+        atomicWriteFileSync(filePath, JSON.stringify(serializeScopedGrants(store)), 0o600)
       } catch (err) {
-        process.stderr.write(
-          `telegram gateway: scoped-grant-store write failed: ${(err as Error).message}\n`,
-        )
+        log(`telegram gateway: scoped-grant-store write failed: ${(err as Error).message}\n`)
       }
     },
   }