switchroom 0.19.19 → 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/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/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),
+      ),
+  }
+}