switchroom 0.19.18 → 0.19.22

package/telegram-plugin/gateway/gateway.ts

@@ -294,6 +294,7 @@ import {
   retryWithThreadFallback,
   isFloodWaitActiveError,
 } from '../retry-api-call.js'
+import { installEditFloodFuse } from '../edit-flood-fuse.js'
 import { createSendGate, sendGateConfigFromEnv, isSendGateShed } from '../send-gate.js'
 import { createStatsLogger, createFloodWindowObserver } from '../send-gate-observability.js'
 import { installTgPostLogger, installRichMarkdownGuard, withTgPostTags } from '../shared/bot-runtime.js'
@@ -635,6 +636,8 @@ import { formatUpdateStatusLine } from './update-status-line.js'
 import type { HostdRequest, HostdResponse } from '../../src/host-control/protocol.js'
 import type { AgentAudit } from '../welcome-text.js'
 import { shouldSweepChatAtBoot } from './boot-sweep-filter.js'
+import { createBootSweepGate, runBootPinSweepSteps } from './boot-sweep-gate.js'
+import { createStatusPinApi, type PinCapableBot, type RobustApiSeam } from './status-pin-api.js'
 import {
   createDmPinSweeper,
   collectDmChatIdsFromStores,
@@ -1438,6 +1441,9 @@ async function rawEditMessageChecklist(args: {
 
 const chatLock = createChatLock()
 // P0b (#2996): wrapped in initGatewayBot() once `bot` is constructed at boot.
+// The `!` is an ASSERTION, not a guarantee — a module-eval-time reader gets
+// `undefined` and tsc will not warn (#3664). Anything touching the Bot API from
+// module scope must run behind `bootPinSweepGate` / assert readiness first.
 let lockedBot!: Bot<Context>
 let botUsername = ''
 
@@ -8660,21 +8666,14 @@ function persistBannerRow(row: PersistedStatusPin | null): void {
   )
 }
 
-// The Bot API surface the pin driver needs. `lockedBot` is defined later; wrap
-// lazily so this helper can be declared alongside the state it owns.
+// The Bot API surface the pin driver needs. `lockedBot` is assigned late (in
+// initGatewayBot) so it is read lazily; createStatusPinApi also asserts it
+// exists and converts a send-gate SHED into a throw — see status-pin-api.ts.
 function statusPinApi(): PinBotApi {
-  return {
-    pinChatMessage: (chat_id, message_id, opts) =>
-      robustApiCall(
-        () => lockedBot.api.pinChatMessage(chat_id, message_id, opts),
-        { chat_id: String(chat_id), verb: 'status-pin.pin' },
-      ),
-    unpinChatMessage: (chat_id, message_id) =>
-      robustApiCall(
-        () => lockedBot.api.unpinChatMessage(chat_id, message_id),
-        { chat_id: String(chat_id), verb: 'status-pin.unpin' },
-      ),
-  }
+  return createStatusPinApi(
+    () => lockedBot as unknown as PinCapableBot | undefined,
+    robustApiCall as RobustApiSeam,
+  )
 }
 
 /**
@@ -9291,42 +9290,46 @@ const dmPinSweeper: DmPinSweeper = createDmPinSweeper({
 })
 
 /**
- * Boot-time pin cleanup + DM stale-pin sweep, sequenced under the startup
- * mutex. Collects the DM chat IDs with a prior-session pin record BEFORE the
- * store reapers empty the stores, runs the three existing boot reapers, marks
- * the DM sweep eligible (this gateway now owns the shared state), then
- * unpin-alls each recorded DM chat. Fire-and-forget from the caller — never
- * blocks boot, never rejects unhandled.
+ * Boot-time pin cleanup + DM stale-pin sweep. Collects the DM chat IDs with a
+ * prior-session pin record BEFORE the store reapers empty the stores, runs the
+ * three boot reapers, marks the DM sweep eligible, then unpin-alls each
+ * recorded DM chat. Ordering and per-step isolation live in
+ * `runBootPinSweepSteps` (boot-sweep-gate.ts) — a throwing reaper must not
+ * strand `enableDmSweep`. Dispatched only via `bootPinSweepGate` below (mutex
+ * won AND `lockedBot` constructed); fire-and-forget — never blocks boot.
  */
-async function runBootPinCleanupAndDmSweep(): Promise<void> {
-  let dmChatIds: string[] = []
-  try {
-    dmChatIds = collectDmChatIdsFromStores({
-      statusPins:
-        statusPinPersistEnabled || bannerPinPersistEnabled || toolPinPersistEnabled
-          ? loadStatusPins(STATUS_PIN_STORE_PATH, statusPinStoreFs)
+function runBootPinCleanupAndDmSweep(): Promise<void> {
+  return runBootPinSweepSteps({
+    scanDmChatIds: () =>
+      collectDmChatIdsFromStores({
+        statusPins:
+          statusPinPersistEnabled || bannerPinPersistEnabled || toolPinPersistEnabled
+            ? loadStatusPins(STATUS_PIN_STORE_PATH, statusPinStoreFs)
+            : [],
+        activityCards: activityCardPersistEnabled
+          ? loadActivityCards(ACTIVITY_CARD_STORE_PATH, activityCardStoreFs)
           : [],
-      activityCards: activityCardPersistEnabled
-        ? loadActivityCards(ACTIVITY_CARD_STORE_PATH, activityCardStoreFs)
-        : [],
-      queuedCards: queuedCardPersistEnabled
-        ? loadQueuedCards(QUEUED_CARD_STORE_PATH, queuedCardStoreFs)
-        : [],
-    })
-  } catch (err) {
-    process.stderr.write(
-      `telegram gateway: dm-pin-sweep: store scan failed: ${(err as Error).message}\n`,
-    )
-  }
-  await statusPinBootCleanup()
-  await activityCardBootReaper()
-  await queuedCardBootReaper()
-  // This gateway now owns the shared per-agent pin state — enable the DM
-  // unpin-all path (both the boot sweep below and lazy first-inbound sweeps).
-  dmPinSweepEligible = true
-  for (const id of dmChatIds) await dmPinSweeper.sweep(id)
+        queuedCards: queuedCardPersistEnabled
+          ? loadQueuedCards(QUEUED_CARD_STORE_PATH, queuedCardStoreFs)
+          : [],
+      }),
+    statusPinCleanup: statusPinBootCleanup,
+    activityCardReaper: activityCardBootReaper,
+    queuedCardReaper: queuedCardBootReaper,
+    // This gateway owns the shared pin state — enable the DM unpin-all path
+    // (this sweep AND lazy first-inbound sweeps).
+    enableDmSweep: () => {
+      dmPinSweepEligible = true
+    },
+    sweepDm: (id) => dmPinSweeper.sweep(id),
+    log: (line) => process.stderr.write(line),
+  })
 }
 
+// #3664: needs BOTH the mutex (arm) and a constructed `lockedBot` (botReady,
+// end of initGatewayBot) before it may run — see boot-sweep-gate.ts.
+const bootPinSweepGate = createBootSweepGate({ run: runBootPinCleanupAndDmSweep, onError: (err) => process.stderr.write(`telegram gateway: boot pin cleanup / DM sweep failed: ${(err as Error).message}\n`) })
+
 // Activity feed. The gateway streams a live "what it's doing" tool-activity
 // feed for every turn. The PreToolUse sidecar emits a `tool_label` per tool
 // call (flush-independent, so it stays real-time on fast/clustered-tool
@@ -9486,14 +9489,11 @@ if (isGatewayMain) {  // #2996 P0c: gated in place; guarded await never runs on
       const carrierAgentDir = resolveAgentDirFromEnv()
       if (carrierAgentDir != null) consumeSessionModelCarrierOnHealthyBoot(carrierAgentDir)
     }
-    // We WON the startup mutex — this gateway is the sole live owner of the
-    // shared per-agent status-pin store, so it's now safe to clean up orphaned
-    // pins from a prior (dead) session. Gated here (not at import time) so a
-    // LOSING double-boot never unpins the live holder's legitimate pins.
-    // Fire-and-forget: cleanup is best-effort and must not block boot.
-    // #3026: sequenced so the DM stale-pin sweep runs after the reapers and
-    // only once this gateway owns the shared state.
-    void runBootPinCleanupAndDmSweep()
+    // We WON the startup mutex — the sole live owner of the shared per-agent
+    // pin store may clear a dead session's orphans (a LOSING double-boot must
+    // not, hence arming here, not at import). #3664: arming is HALF the
+    // precondition — the gate holds the sweep until `lockedBot` exists.
+    bootPinSweepGate.arm()
   } catch (err) {
     process.stderr.write(
       `telegram gateway: boot.lock_acquire_failed err=${(err as Error).message} agent=${SWITCHROOM_AGENT_NAME}\n`,
@@ -9516,8 +9516,8 @@ if (isGatewayMain) {  // #2996 P0c: gated in place; guarded await never runs on
         const carrierAgentDir = resolveAgentDirFromEnv()
         if (carrierAgentDir != null) consumeSessionModelCarrierOnHealthyBoot(carrierAgentDir)
       }
-      // #3026: same sequenced cleanup + DM stale-pin sweep as the mutex path.
-      void runBootPinCleanupAndDmSweep()
+      // #3026: same sequenced cleanup + DM sweep, same #3664 bot-ready gate.
+      bootPinSweepGate.arm()
     } catch (writeErr) {
       process.stderr.write(`telegram gateway: writePidFile failed: ${writeErr}\n`)
     }
@@ -22959,6 +22959,13 @@ async function initGatewayBot(): Promise<void> {
 
   bot = new Bot(TOKEN)
   installTgPostLogger(bot); installRichMarkdownGuard(bot) // #3252/#3463: universal fmt guard installed after logger (composes outermost); see installRichMarkdownGuard docblock
+  // #3620 flood fuse — installed LAST so it composes OUTERMOST: the one seam no
+  // outbound call can bypass (grammY has no route to the network that skips the
+  // transformer stack). Kill-switch SWITCHROOM_EDIT_FUSE=0; see edit-flood-fuse.ts.
+  installEditFloodFuse(bot, {
+    enabled: process.env.SWITCHROOM_EDIT_FUSE !== '0',
+    onTrip: (i) => process.stderr.write(`edit-flood-fuse ${i.action} method=${i.method} key=${i.key}\n`),
+  })
 
   // Diagnostic update tap (#3300): one compact line per received update, logged
   // BEFORE any specific handler runs, so a routing-layer drop is diagnosable
@@ -23081,6 +23088,9 @@ async function initGatewayBot(): Promise<void> {
 
   // Install the grammY registration surface (P0a) — once, before the runner.
   registerGatewayHandlers(bot, {})
+
+  // #3664: `lockedBot` exists now — release the boot pin sweep iff armed.
+  bootPinSweepGate.botReady()
 }
 
 // One-shot startup guard. The outer for-loop below re-enters its try block

package/telegram-plugin/gateway/inbound-interceptors.ts

@@ -169,6 +169,9 @@ export interface InboundInterceptorDeps {
     ReturnType<typeof createCallbackQueryHandlers>,
     | 'executeDeferredSecretSave'
     | 'performVaultAccessApproval'
+    // #3627: owns the per-passphrase-entry attempt counter + re-prompt /
+    // lockout decision after the broker refuses a mint as a mismatch.
+    | 'resolveAccessApprovalPassphraseMismatch'
     | 'parseGrantDuration'
     | 'grantWizardConfirm'
   >
@@ -750,10 +753,13 @@ export async function interceptVault(
         // unlocking. We captured the next message as the passphrase,
         // cache it, delete the chat copy, and resume the approve
         // flow for EVERY queued stage (#1051 — without the queue, a
-        // concurrent second tap orphaned the first stage). Wrong
+        // concurrent second tap orphaned the first stage). A wrong
         // passphrase surfaces via the broker's
-        // DENIED:passphrase-mismatch path and edits each card to the
-        // mint_grant-failed message (see performVaultAccessApproval).
+        // DENIED:passphrase-mismatch path; #3627 keeps those stages
+        // ALIVE and re-prompts with the attempts remaining (counted per
+        // passphrase ENTRY, since this one entry drains the whole batch)
+        // until MAX_VAULT_PASSPHRASE_ATTEMPTS, then falls back to the
+        // terminal card edit.
         const passphrase = p.text.trim()
         if (!passphrase) {
           await deps.switchroomReply(p.ctx, 'Passphrase cannot be empty. Ask the agent to re-issue the request card.', { html: true })
@@ -767,6 +773,11 @@ export async function interceptVault(
         // grows monotonically (item 1 mints grant for [keyA]; item 2
         // lists, finds [keyA], unions with keyB → mints [keyA, keyB]).
         // Parallel processing would race on the list-and-merge.
+        // #3627: stages the broker refused as a passphrase MISMATCH. They
+        // are still staged and their cards still say "waiting" — collected
+        // here so one re-prompt covers the whole batch.
+        const mismatched: typeof pendingVault.items = []
+        let mismatchMsg = ''
         for (const item of pendingVault.items) {
           const stagedAccess = deps.pendingVaultRequestAccesses.get(item.stageId)
           if (!stagedAccess) {
@@ -783,7 +794,19 @@ export async function interceptVault(
               .catch(() => {})
             continue
           }
-          await deps.callbackQueryHandlers().performVaultAccessApproval(p.ctx, stagedAccess, item.stageId, item.senderId, { kind: 'passphrase', passphrase })
+          const outcome = await deps.callbackQueryHandlers().performVaultAccessApproval(p.ctx, stagedAccess, item.stageId, item.senderId, { kind: 'passphrase', passphrase })
+          if (outcome?.kind === 'passphrase-mismatch') {
+            mismatched.push(item)
+            mismatchMsg = outcome.msg
+          }
+        }
+        if (mismatched.length > 0) {
+          await deps.callbackQueryHandlers().resolveAccessApprovalPassphraseMismatch(p.ctx, {
+            chat_id: p.chat_id,
+            failed: mismatched,
+            priorAttempts: pendingVault.attempts ?? 0,
+            brokerMsg: mismatchMsg,
+          })
         }
       } else if (pendingVault.kind === 'grant-wizard' && pendingVault.awaitingCustomDuration) {
         // Issue #227: custom duration text reply for grant wizard

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/narrative-lane.ts

@@ -49,6 +49,7 @@
 import { runSilentTurnHeartbeatTick } from '../feed-heartbeat-climb.js'
 import { NarrativeFlushController, PENDING_NARRATIVE_FLUSH_MS } from '../narrative-flush.js'
 import { richMessage } from '../rich-send.js'
+import { isSendGateShed } from '../send-gate.js'
 import { appendShownBlock } from '../shown-ledger.js'
 import {
   appendActivityLabel, clipNarrative, formatStepSuffix, renderActivityFeedWithNested,
@@ -446,10 +447,41 @@ export function createNarrativeLane(deps: NarrativeLaneDeps) {
             )
           } else {
             const id = turn.activityMessageId
-            await robustApiCall(
+            // #3620: the live activity card is THE highest-volume repeated
+            // editMessageText on one message id in the whole gateway, and until
+            // this fix it passed NO `messageId` / `editPayload` to the send
+            // gate. `sendGate.gate` only routes to its edit path when BOTH are
+            // present (send-gate.ts `gate()`), so every card edit fell through
+            // to the plain-send path: no per-message edit floor, no
+            // last-write-wins coalescing, no no-op payload skip, and — because
+            // an untagged non-edit send defaults to `critical`
+            // (UNTAGGED_SEND_CLASS) — never shed and never budget-capped. The
+            // card was therefore free to edit one message at the per-chat
+            // bucket rate (1/s = 60/min) for as long as a turn ran, which is
+            // what earned the 2026-07-25 62-minute flood ban.
+            //
+            // Tagging it COSMETIC + keying it engages all four protections,
+            // including the long-horizon per-message edit budget that is
+            // scoped to cosmetic edits.
+            const editRes = await robustApiCall(
               () => bot.api.editMessageText(chat, id, richMessage(html), {}),
-              { chat_id: chat, ...(thread != null ? { threadId: thread } : {}), verb: 'activity-summary.edit' },
+              {
+                chat_id: chat,
+                ...(thread != null ? { threadId: thread } : {}),
+                verb: 'activity-summary.edit',
+                priorityClass: 'cosmetic',
+                messageId: id,
+                editPayload: html,
+              },
             )
+            // Shed honesty: a shed edit did NOT land (the gate resolves the
+            // SEND_GATE_SHED sentinel, not `undefined`). Leaving
+            // `activityLastSentRender` behind keeps the newest render PENDING so
+            // the next drain (a fresh tool label, or the feed heartbeat)
+            // repaints it, and `break`ing stops the drain hot-looping against a
+            // closed gate. A no-op drop still resolves `undefined` — that
+            // payload IS on screen, so it advances normally below.
+            if (isSendGateShed(editRes)) break
           }
           turn.activityLastSentRender = target
         } catch (err) {
@@ -853,7 +885,21 @@ export function createNarrativeLane(deps: NarrativeLaneDeps) {
       try {
         await robustApiCall(
           () => bot.api.editMessageText(chat, id, richMessage(finalHtml), {}),
-          { chat_id: chat, ...(thread != null ? { threadId: thread } : {}), verb: 'activity-summary.finalize' },
+          {
+            chat_id: chat,
+            ...(thread != null ? { threadId: thread } : {}),
+            verb: 'activity-summary.finalize',
+            // Keyed for the same reason as the drain edit: this edits the SAME
+            // message id the drain has been repainting, so it must share that
+            // message's edit floor / coalescer / budget rather than slipping
+            // past the gate as an untagged `critical` send. `useful` (not
+            // `cosmetic`) because it paints the card's terminal state — it may
+            // be deferred, but it should not be shed at the first sign of
+            // pressure.
+            priorityClass: 'useful',
+            messageId: id,
+            editPayload: finalHtml,
+          },
         )
       } catch (err) {
         // Same transport-class discipline as the delete path: the card

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`)
       }
     },
   }