switchroom 0.19.19 → 0.19.23

package/telegram-plugin/gateway/captured-answer-resume.ts

@@ -14,8 +14,8 @@
  *
  * ── The fix (design-of-record §2.2) ─────────────────────────────────────────
  * Make the re-present a *byte-identical captured-answer resume* of ONLY the
- * not-yet-`landed-confirmed` tail — never a regeneration — so a chunk that
- * already reached the chat is provably never re-posted:
+ * not-yet-LANDED tail — never a regeneration — so a chunk that already reached
+ * the chat is provably never re-posted:
  *
  *   1. On a partial (`!delivered`) turn-flush, persist a {@link
  *      CapturedDeliverySnapshot} (the split chunks + each landed chunk's ids and
@@ -25,9 +25,9 @@
  *   2. The obligation sweep's `represent` branch becomes source-aware: when the
  *      obligation carries a captured-delivery snapshot it drives THIS resume
  *      (re-run `runBackstopDelivery` for the SAME `turnId` and the SAME captured
- *      chunks, resuming at the first non-`landed-confirmed` index) instead of
- *      pushing a fresh-generation inbound. No snapshot ⇒ the genuine "model wrote
- *      nothing / never fired a backstop" case falls through to fresh generation
+ *      chunks, resuming at the first UNSENT index) instead of pushing a
+ *      fresh-generation inbound. No snapshot ⇒ the genuine "model wrote nothing
+ *      / never fired a backstop" case falls through to fresh generation
  *      unchanged.
  *   3. The in-memory ledger is rehydrated from the snapshot AND reconciled against
  *      the durable outbound-text oracle (`hasOutboundWithText`), so a chunk that
@@ -39,9 +39,29 @@
  * chunks (not a regenerated answer). #3278's per-chunk state machine
  * (`unsent → pending → landed-unconfirmed → {landed-confirmed | unsent}`) binds
  * here too: the resume re-PROBES `landed-unconfirmed` chunks (never re-sends
- * them) and re-SENDS only `unsent` ones, so a confirmed chunk is never duplicated
+ * them) and re-SENDS only `unsent` ones, so a landed chunk is never duplicated
  * by either the in-fire retry OR the cross-represent resume.
  *
+ * ── The CLOSE condition is LANDED, not confirmed (#3702) ────────────────────
+ * `runBackstopDelivery`'s verdict is evidence-based: every chunk landed a
+ * message id and at least one is a fresh non-card id. An inconclusive read-back
+ * does not lower it (only a POSITIVE `absent`, which demotes the chunk back to
+ * `unsent`, does). So a resume over a snapshot whose chunks ALL landed but were
+ * never corroborated closes the obligation having sent NOTHING — the re-probe
+ * ran, resolved nothing, and the landed-id evidence stood.
+ *
+ * That is deliberate, not an oversight. The alternative — keep the obligation
+ * OPEN because nothing corroborated the ids — has no corrective action
+ * available: the resume never re-sends a LANDED chunk, so every subsequent
+ * represent would re-run the same shed probe, send zero messages, and burn
+ * represent budget until the cap escalates a false "the agent never answered
+ * you" nudge to the operator. Representing cannot deliver anything the first
+ * delivery did not; the only thing it can produce is noise. When the durable
+ * outbound-text oracle CAN corroborate (history enabled + the row present) it
+ * confirms the chunk at hydration and the same close happens by the older
+ * `hasOutboundWithText` route — this path is the same decision when that oracle
+ * is unavailable.
+ *
  * This module is PURE state + orchestration over injected effects — no Telegram,
  * no SQLite, no gateway module state — so the resume decision is unit-testable
  * (see tests/captured-answer-resume.test.ts). The gateway owns the real
@@ -55,10 +75,10 @@ import type { CapturedDeliverySnapshot, Obligation } from './obligation-ledger.j
 /**
  * Build the durable {@link CapturedDeliverySnapshot} from the live per-chunk
  * ledger after a partial `runBackstopDelivery`. Captures every LANDED chunk's
- * message ids + confirmed flag so the resume can (a) never re-send a confirmed
- * chunk and (b) re-PROBE a landed-unconfirmed chunk instead of blindly re-sending
- * it. Chunks that never landed (send threw) are simply absent → the resume treats
- * them as `unsent` and re-sends them. Pure.
+ * message ids + confirmed flag so the resume can (a) never re-send a chunk that
+ * already landed and (b) re-PROBE a landed-unconfirmed chunk instead of blindly
+ * re-sending it. Chunks that never landed (send threw) are simply absent → the
+ * resume treats them as `unsent` and re-sends them. Pure.
  */
 export function buildCapturedDeliverySnapshot(
   ledger: BackstopDeliveryLedger,
@@ -165,9 +185,13 @@ export interface CapturedResumeDispatcher {
  * The obligation-sweep's captured-answer resume driver. Owns the in-flight guard
  * + the deliver→close/leave-open orchestration so the gateway sweep stays a
  * two-line dispatch. On each dispatch it consumes one represent-budget unit
- * (bounding the ladder → escalate), re-delivers only the non-confirmed tail, and:
+ * (bounding the ladder → escalate), re-delivers only the UNSENT tail (a landed
+ * chunk is re-probed, never re-sent), and:
  *   - fully delivered ⇒ record the supersede tail, close the obligation, GC the
- *     ledger (the represent ladder stops);
+ *     ledger (the represent ladder stops). Since #3702 "delivered" means every
+ *     chunk LANDED — so a snapshot that is already fully landed closes here
+ *     having sent nothing (see the module header for why that is the right
+ *     call, and why leaving it OPEN would only manufacture a false escalation);
  *   - still partial / error ⇒ leave the obligation OPEN so the next eligible
  *     sweep (after the per-represent grace) retries, until the represent cap
  *     escalates it to the operator nudge — no infinite loop.
@@ -176,7 +200,7 @@ export function createCapturedResumeDispatcher(ports: CapturedResumePorts): Capt
   const stderr = ports.stderr ?? (() => {})
   const inFlight = new Set<string>()
 
-  /** Re-deliver the non-confirmed tail of `o`'s captured answer, byte-identical,
+  /** Re-deliver the UNSENT tail of `o`'s captured answer, byte-identical,
    *  by rehydrating the per-chunk ledger from the snapshot reconciled against the
    *  durable text oracle. Never regenerates. */
   function deliver(o: Obligation, snapshot: CapturedDeliverySnapshot): Promise<{ delivered: boolean; sentIds: number[] }> {
@@ -221,16 +245,21 @@ export function createCapturedResumeDispatcher(ports: CapturedResumePorts): Capt
       if (delivered) {
         ports.obligationLedger.close(o.originTurnId)
         ports.backstopDeliveryLedger.clear(o.originTurnId)
+        // `sentIds` is `ledger.sentIds()` — every LANDED id, which since #3702
+        // routinely includes ids no read-back corroborated. Say "landed", not
+        // "confirmed": claiming confirmation for an uncorroborated id is exactly
+        // the overstatement this PR removed from the delivery verdict.
         stderr(
           `telegram gateway: captured-answer resume delivered — origin=${o.originTurnId} ` +
-            `${sentIds.length} chunk(s) confirmed; obligation closed\n`,
+            `${sentIds.length} message id(s) landed; obligation closed\n`,
         )
       } else {
-        // Tail still not confirmed — leave the obligation OPEN for the next paced
-        // sweep / escalation (bounded by the represent cap).
+        // Not fully landed (a chunk never got an id, or a positive `absent`
+        // demoted one) — leave the obligation OPEN for the next paced sweep /
+        // escalation (bounded by the represent cap).
         stderr(
           `telegram gateway: captured-answer resume partial — origin=${o.originTurnId} ` +
-            `tail still not confirmed; left OPEN for retry\n`,
+            `tail still not landed; left OPEN for retry\n`,
         )
       }
     } catch (err) {

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,
@@ -715,7 +718,7 @@ import {
 import { CurrentTurnMap } from './current-turn-map.js'
 import { resolveAnswerThreadId } from './answer-thread-resolve.js'
 import { decideObligationTurnEnd } from './obligation-turn-end.js'
-import { maybeRotate } from './turns-jsonl-rotate.js'
+import { maybeRotate, resolveAgentStateDir, resolveTurnsJsonlPath } from './turns-jsonl-rotate.js'
 import {
   buildTurnRecord,
   finalizeBackstopSendGated,
@@ -1029,7 +1032,7 @@ const blockedApprovalStore = createBlockedApprovalStore(
   // Fallback: the agent's OWN state dir, which the scaffold chowns to the agent
   // uid, so a write there always succeeds. Guarantees the record can never be
   // silently lost when the shared dir isn't writable by this agent's uid.
-  process.env.SWITCHROOM_AGENT_STATE_DIR ?? '/state/agent',
+  resolveAgentStateDir(),
 )
 
 /**
@@ -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 = ''
 
@@ -2450,9 +2456,9 @@ async function deliverAnswer(args: {
    *  the send alive if the user deleted their message. Null for synthesized
    *  turns (cron/handback) — those send bare, as before. */
   replyToMessageId: number | null
-  /** #3282 captured-answer RESUME (see captured-answer-resume.ts): re-deliver the SAME byte-identical chunks + pre-hydrate the ledger (non-confirmed tail only). */
+  /** #3282 captured-answer RESUME (see captured-answer-resume.ts): re-deliver the SAME byte-identical chunks + pre-hydrate the ledger (unsent tail only; a landed chunk is re-probed, never re-sent). */
   resume?: { snapshot: CapturedDeliverySnapshot; hydrate: (ledger: BackstopDeliveryLedger, turnId: string) => void }
-}): Promise<{ sentIds: number[]; chunkCount: number; delivered: boolean; exhausted: boolean }> {
+}): Promise<{ sentIds: number[]; chunkCount: number; delivered: boolean; exhausted: boolean; landedUnconfirmed: number }> {
   const { chatId, turnId } = args
   // Spacers into `\n\n` gaps then split (as executeReply); a resume re-delivers the EXACT captured chunks (byte-stable, no re-split).
   const chunks = args.resume
@@ -2588,6 +2594,7 @@ async function deliverAnswer(args: {
     chunkCount: result.chunkCount,
     delivered: result.delivered,
     exhausted: result.exhausted,
+    landedUnconfirmed: result.landedUnconfirmedIds.length, // #3702 — the caller stamps this on the turn record
   }
 }
 
@@ -3421,6 +3428,7 @@ export type CurrentTurn = {
   // turn-end paths (reply-tool tail, silent-marker, genuine no-reply), where
   // the legacy `finalAnswerDelivered` reading still applies unchanged.
   deliveryOutcome?: DeliveryOutcome
+  landedUnconfirmed?: number // #3702 — landed ids no read-back corroborated; emitted as `landed_unconfirmed` (rationale: turn-record-status.ts)
   // Feed-reopen-after-ack refinement — whether the reply that set
   // `finalAnswerDelivered` was a *substantive* final answer (stream
   // `done`, or ≥200 chars) as opposed to a short pinging interim ACK.
@@ -5006,7 +5014,7 @@ function snapshotContextOccupancy(): void {
     } catch {
       cap = null; // config unreadable → show occupancy without a ratio
     }
-    const stateDir = process.env.SWITCHROOM_AGENT_STATE_DIR ?? "/state/agent";
+    const stateDir = resolveAgentStateDir();
     writeContextOccupancySnapshot(
       stateDir,
       buildContextOccupancy(occupancy, cap, Date.now()),
@@ -5027,12 +5035,12 @@ function emitTurnRecord(turn: CurrentTurn, endedAt: number): void {
             toolCallCount: turn.toolCallCount ?? 0,
             turnId: turn.turnId,
             finalAnswerDelivered: turn.finalAnswerDelivered,
-            deliveryOutcome: turn.deliveryOutcome,
+            deliveryOutcome: turn.deliveryOutcome, landedUnconfirmed: turn.landedUnconfirmed,
           },
           endedAt,
         ),
       ) + '\n'
-    const turnsPath = '/state/agent/turns.jsonl'
+    const turnsPath = resolveTurnsJsonlPath() // honours SWITCHROOM_AGENT_STATE_DIR
     // Size-cap rotation: keep at most one rotated generation so the file can't
     // grow unbounded on a long-lived agent. Best-effort (never throws).
     maybeRotate(turnsPath, {
@@ -8660,21 +8668,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 +9292,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 +9491,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 +9518,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 +22961,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 +23090,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/outbound-send-path.ts

@@ -611,7 +611,14 @@ export function createBackstopReadBack(
     }
     try {
       const r = await w.gate(() => w.editMessageText(messageId, body, editApiOpts), gateOpts)
-      return w.isShed(r) ? 'ambiguous' : 'exists'
+      // A shed resolves the SEND_GATE_SHED sentinel; a gate no-op drop (the
+      // identical payload is already the last one sent for this message id) or
+      // an expired queue entry resolves `undefined`. In BOTH cases the edit
+      // never reached Telegram, so there is no evidence of existence —
+      // `ambiguous`, never a fabricated `exists`. Only a real API result
+      // (grammy resolves `true` or the edited Message) proves presence.
+      if (w.isShed(r) || r === undefined) return 'ambiguous'
+      return 'exists'
     } catch (err) {
       return classifyReadBackError(err)
     }