switchroom 0.12.13 → 0.12.15

package/telegram-plugin/gateway/approval-callback.ts

@@ -22,14 +22,58 @@
  */
 
 import { type Context, InlineKeyboard } from "grammy";
-import { parseApprovalCallback, ttlMsFromToken } from "./approval-card.js";
 import {
-  approvalConsume,
-  approvalRecord,
-} from "../../src/vault/approvals/client.js";
+  parseApprovalCallback,
+  ttlMsFromToken,
+  type ApprovalChoice,
+} from "./approval-card.js";
+import { approvalConsumeRecord } from "../../src/vault/approvals/client.js";
 import type { ApprovalDecisionMode } from "../../src/vault/approvals/schema.js";
 import { scopeToOpenInDriveButton } from "../../src/drive/deep-links.js";
 
+/**
+ * Resolve a tapped approval choice to its decision tuple — PURE, no
+ * kernel I/O, so the `bad ttl token` branch (the only fallible path in
+ * the old inline switch) is unit-testable without mocking grammy.
+ *
+ * Extracted (PR-5) from `handleApprovalCallback` so PR-4's invariant —
+ * "compute + validate the decision BEFORE burning the single-use
+ * nonce" — is now structural, not a comment: the handler calls this
+ * first and only proceeds to `approvalConsume` on `ok: true`. A
+ * malformed ttl token returns `{ ok: false }` and the nonce is never
+ * touched (operator can re-tap a valid choice).
+ */
+export type ResolvedApprovalDecision =
+  | {
+      ok: true;
+      decision: ApprovalDecisionMode;
+      granted: boolean;
+      ttl_ms: number | null;
+      displayMode: string;
+    }
+  | { ok: false; error: string };
+
+export function resolveApprovalDecision(
+  choice: ApprovalChoice,
+): ResolvedApprovalDecision {
+  switch (choice.kind) {
+    case "deny":
+      return { ok: true, decision: "deny", granted: false, ttl_ms: null, displayMode: "denied" };
+    case "once":
+      // No expiry — recorded as a one-shot grant; the agent calls
+      // approval_lookup at most once, then proceeds. /approvals revoke
+      // can still target the row by id.
+      return { ok: true, decision: "allow_once", granted: true, ttl_ms: null, displayMode: "granted once" };
+    case "always":
+      return { ok: true, decision: "allow_always", granted: true, ttl_ms: null, displayMode: "granted always" };
+    case "ttl": {
+      const ms = ttlMsFromToken(choice.param);
+      if (ms === null) return { ok: false, error: "bad ttl token" };
+      return { ok: true, decision: "allow_ttl", granted: true, ttl_ms: ms, displayMode: `granted for ${choice.param}` };
+    }
+  }
+}
+
 /**
  * Build the post-tap keyboard for a granted decision. Today this is
  * just the `[ 📖 Open in Drive ]` button when the granted scope names
@@ -57,55 +101,21 @@ export async function handleApprovalCallback(
     return;
   }
 
-  const consumed = await approvalConsume(parsed.request_id);
-  if (consumed === null) {
-    await ctx.answerCallbackQuery({ text: "approval kernel unreachable" });
+  // Resolve + validate the decision BEFORE burning the single-use
+  // nonce (PR-4 invariant, now structural via the pure
+  // resolveApprovalDecision — see its doc). A malformed ttl token
+  // returns { ok: false } here and the nonce is never touched, so the
+  // operator can re-tap a valid choice; pre-fix this validation ran
+  // AFTER approvalConsume(), burning the nonce with no decision
+  // recorded → the agent's approval_lookup poll never saw a verdict
+  // and the turn wedged. There is now NO fallible step between the
+  // consume→record below.
+  const resolved = resolveApprovalDecision(parsed.choice);
+  if (!resolved.ok) {
+    await ctx.answerCallbackQuery({ text: resolved.error });
     return;
   }
-  if (!consumed.consumed) {
-    // Single-use enforcement: someone already tapped, or the nonce
-    // expired/unknown. Match the RFC §8.1 wording.
-    await ctx.answerCallbackQuery({ text: "this prompt expired" });
-    return;
-  }
-
-  // Compute decision + ttl from the choice variant.
-  let decision: ApprovalDecisionMode;
-  let granted: boolean;
-  let ttl_ms: number | null = null;
-  let displayMode: string;
-  switch (parsed.choice.kind) {
-    case "deny":
-      decision = "deny";
-      granted = false;
-      displayMode = "denied";
-      break;
-    case "once":
-      decision = "allow_once";
-      granted = true;
-      // No expiry — recorded as a one-shot grant; the agent calls
-      // approval_lookup at most once, then proceeds. /approvals revoke
-      // can still target the row by id.
-      displayMode = "granted once";
-      break;
-    case "always":
-      decision = "allow_always";
-      granted = true;
-      displayMode = "granted always";
-      break;
-    case "ttl": {
-      decision = "allow_ttl";
-      granted = true;
-      const ms = ttlMsFromToken(parsed.choice.param);
-      if (ms === null) {
-        await ctx.answerCallbackQuery({ text: "bad ttl token" });
-        return;
-      }
-      ttl_ms = ms;
-      displayMode = `granted for ${parsed.choice.param}`;
-      break;
-    }
-  }
+  const { decision, granted, ttl_ms, displayMode } = resolved;
 
   const granted_by_user_id = ctx.from?.id ?? 0;
   // Approver set at decision time = the chat that received the card. We
@@ -114,18 +124,37 @@ export async function handleApprovalCallback(
   // when each surface migrates and starts passing access.allowFrom.
   const approver_set = [String(granted_by_user_id)];
 
-  const decision_id = await approvalRecord({
+  // PR-6: atomic consume+record — ONE round-trip; the kernel burns the
+  // single-use nonce AND writes the decision in one SQLite transaction.
+  // If the record fails the burn rolls back, so `null` genuinely means
+  // "nothing happened, safe to retry" — there is no burned-nonce /
+  // no-decision wedge any more (the residual the shipped permission-TTL
+  // auto-deny used to backstop). resolveApprovalDecision already
+  // validated the ttl above, so no fallible step precedes this call.
+  const result = await approvalConsumeRecord({
     request_id: parsed.request_id,
     decision,
     approver_set,
     granted_by_user_id,
     ttl_ms,
   });
-
-  if (decision_id === null) {
+  if (result === null) {
+    await ctx.answerCallbackQuery({ text: "approval kernel unreachable" });
+    return;
+  }
+  if (!result.consumed) {
+    // Already tapped / expired / unknown — single-use is enforced
+    // kernel-side and NO decision was written. RFC §8.1 wording.
+    await ctx.answerCallbackQuery({ text: "this prompt expired" });
+    return;
+  }
+  if (!result.decision_id) {
+    // Defensive: consumed:true must carry a decision_id. Kept distinct
+    // from the unreachable message for operator triage.
     await ctx.answerCallbackQuery({ text: "kernel record failed" });
     return;
   }
+  const decision_id: string = result.decision_id;
 
   // Edit the original card to its post-tap state. Drop the original
   // action keyboard either way; on a successful grant for a Drive
@@ -138,8 +167,8 @@ export async function handleApprovalCallback(
       ? ` · /approvals revoke <code>${decision_id}</code>`
       : "");
 
-  const postTapKeyboard = granted && consumed.scope
-    ? buildGrantedKeyboard(consumed.scope)
+  const postTapKeyboard = granted && result.scope
+    ? buildGrantedKeyboard(result.scope)
     : undefined;
 
   try {

package/telegram-plugin/gateway/gateway.ts

@@ -245,10 +245,14 @@ import { shouldSweepChatAtBoot } from './boot-sweep-filter.js'
 import { createIpcServer, type IpcClient, type IpcServer } from './ipc-server.js'
 import { handleRequestDriveApproval } from './drive-write-approval.js'
 import { buildDiffPreviewCard } from './diff-preview-card.js'
-import { createPendingInboundBuffer } from './pending-inbound-buffer.js'
+import { createPendingInboundBuffer, redeliverBufferedInbound } from './pending-inbound-buffer.js'
+import { createPendingPermissionBuffer } from './pending-permission-decisions.js'
 import {
   buildVaultGrantApprovedInbound,
   buildVaultGrantDeniedInbound,
+  buildVaultSaveCompletedInbound,
+  buildVaultSaveFailedInbound,
+  buildVaultSaveDiscardedInbound,
 } from './vault-grant-inbound-builders.js'
 import { createPollHealthCheck, type PollHealthCheckHandle } from './poll-health.js'
 import type {
@@ -262,6 +266,7 @@ import type {
   PtyPartialForward,
   InboundMessage,
   InjectInboundMessage,
+  PermissionEvent,
 } from './ipc-protocol.js'
 import { DebounceBuffer, HourCap, buildReactionInboundMeta, buildReactionInboundText, evaluateTriggerCandidate, isGroupChat, resolveReactionsConfig, truncatePreview, type PendingReaction, type ReactionBatch, type ReactionsResolvedConfig } from './reaction-trigger.js'
 import { writePidFile, clearPidFile } from './pid-file.js'
@@ -2093,7 +2098,23 @@ const pendingStateReaper = setInterval(() => {
     if (now - v.startedAt > VAULT_INPUT_TTL_MS) pendingVaultOps.delete(k)
   }
   for (const [k, v] of pendingPermissions) {
-    if (now - v.startedAt > PERMISSION_TTL_MS) pendingPermissions.delete(k)
+    if (now - v.startedAt > PERMISSION_TTL_MS) {
+      // Don't just drop it: the claude turn is suspended INSIDE the MCP
+      // permission call waiting for a verdict. A silent delete left it
+      // wedged forever when the operator never tapped — permanent
+      // silence, the exact symptom this series fixes. Auto-deny so the
+      // call unblocks; claude then tells the user it couldn't get
+      // permission (or takes a fallback). Routed through
+      // dispatchPermissionVerdict so it's buffered+redelivered too if
+      // the bridge is also offline at sweep time.
+      dispatchPermissionVerdict({ type: 'permission', requestId: k, behavior: 'deny' })
+      process.stderr.write(
+        `telegram gateway: permission TTL expired — auto-deny request=${k} ` +
+        `tool=${v.tool_name} (no operator response in ` +
+        `${Math.round(PERMISSION_TTL_MS / 60000)}m)\n`,
+      )
+      pendingPermissions.delete(k)
+    }
   }
   for (const [k, v] of vaultPassphraseCache) {
     if (now > v.expiresAt) vaultPassphraseCache.delete(k)
@@ -2722,10 +2743,27 @@ silencePoke.startTimer({
     try {
       clearSilentEndState(fbKey)
     } catch { /* best-effort */ }
+    // Self-heal the inbound buffer. pendingInboundBuffer otherwise
+    // drains ONLY on bridge re-register (onClientRegistered). After a
+    // network storm that settles with the bridge STILL connected, user
+    // messages buffered during the flap sit forever — until a manual
+    // restart forces a re-register (the fleet-update thundering-herd
+    // incident, 2026-05-19: agents "not responding", logs show
+    // pending-inbound-buffer depth>0 with no drain). Flushing on
+    // wedge-clear makes the agent self-heal. selfAgent-keyed; a miss
+    // re-buffers so nothing is lost if the bridge is genuinely offline.
+    const fbSelfAgent = process.env.SWITCHROOM_AGENT_NAME ?? ''
+    const fbRedeliver = redeliverBufferedInbound(
+      pendingInboundBuffer,
+      fbSelfAgent,
+      (m) => ipcServer.sendToAgent(fbSelfAgent, m),
+    )
     process.stderr.write(
       `telegram gateway: silence-poke framework-fallback ended wedged turn ` +
       `chat=${fbChatId} thread=${ctx.threadId ?? '-'} silence_ms=${ctx.silenceMs} ` +
-      `currentTurn_nulled=${turnMatchesFallback}\n`,
+      `currentTurn_nulled=${turnMatchesFallback} ` +
+      `drained_buffered=${fbRedeliver.redelivered}/${fbRedeliver.drained}` +
+      `${fbRedeliver.rebuffered > 0 ? ` rebuffered=${fbRedeliver.rebuffered}` : ''}\n`,
     )
   },
 })
@@ -2738,6 +2776,36 @@ silencePoke.startTimer({
 // would mint the grant but silently drop the `vault_grant_approved`
 // inbound, leaving the agent stuck waiting for a manual poke.
 const pendingInboundBuffer = createPendingInboundBuffer()
+const pendingPermissionBuffer = createPendingPermissionBuffer()
+
+/**
+ * Deliver a permission verdict to this agent's bridge, buffering on a
+ * miss so it's redelivered when the bridge reconnects. Replaces the
+ * bare `ipcServer.broadcast({type:'permission',...})` at every verdict
+ * site (and the TTL-sweep auto-deny). broadcast was fire-and-forget:
+ * a verdict produced while the bridge was mid-reconnect was dropped
+ * and the claude turn stayed suspended INSIDE the MCP permission call
+ * forever — the user tapped Approve/Deny and nothing happened, no
+ * further output, permanent silence. sendToAgent is registered-keyed
+ * and returns a real delivered bool; on a miss we buffer and
+ * onClientRegistered re-sends so the reconnecting bridge relays the
+ * verdict to the still-suspended call. A late verdict for a dead
+ * request_id is harmless — the bridge relays it and Claude Code
+ * ignores an unknown request_id. (Function declaration so the
+ * pre-2747 TTL sweep can reference it; ipcServer/pendingPermissionBuffer
+ * are resolved at call-time, after module init.)
+ */
+function dispatchPermissionVerdict(ev: PermissionEvent): void {
+  const selfAgent = process.env.SWITCHROOM_AGENT_NAME ?? ''
+  const delivered = ipcServer.sendToAgent(selfAgent, ev)
+  if (!delivered) {
+    pendingPermissionBuffer.push(selfAgent, ev)
+    process.stderr.write(
+      `telegram gateway: permission verdict buffered (bridge offline) ` +
+      `request=${ev.requestId} behavior=${ev.behavior}\n`,
+    )
+  }
+}
 
 const ipcServer: IpcServer = createIpcServer({
   socketPath: SOCKET_PATH,
@@ -2765,6 +2833,22 @@ const ipcServer: IpcServer = createIpcServer({
           )
         }
       }
+      // PR-3: drain permission verdicts missed while the bridge was
+      // offline. A claude turn suspended inside the MCP permission call
+      // is unblocked the moment the reconnecting bridge relays the
+      // verdict; without this the verdict (incl. the TTL auto-deny) was
+      // lost and the turn stayed silent forever.
+      const pendingVerdicts = pendingPermissionBuffer.drain(client.agentName)
+      for (const ev of pendingVerdicts) {
+        try {
+          client.send(ev)
+        } catch (err) {
+          process.stderr.write(
+            `telegram gateway: pending-permission drain failed agent=${client.agentName} ` +
+            `request=${ev.requestId} behavior=${ev.behavior}: ${(err as Error).message}\n`,
+          )
+        }
+      }
     }
 
     // If the agent reconnected after a /restart (or any restart), post a boot
@@ -6251,7 +6335,7 @@ async function handleInbound(
     // Forward permission reply to connected bridge
     const behavior = permMatch[1]!.toLowerCase().startsWith('y') ? 'allow' : 'deny'
     const request_id = permMatch[2]!.toLowerCase()
-    ipcServer.broadcast({
+    dispatchPermissionVerdict({
       type: 'permission',
       requestId: request_id,
       behavior,
@@ -6981,17 +7065,28 @@ async function handleInbound(
     },
   }
 
-  // Try to send to a connected bridge. If no bridge connected, tell the user.
-  ipcServer.broadcast(inboundMsg)
-  const delivered = ipcServer.clientCount() > 0
-
+  // Deliver to THIS agent's registered bridge, buffering on miss.
+  // broadcast()/clientCount() were the wrong primitives: broadcast is
+  // not registered-keyed (writes to any alive socket incl. an
+  // unregistered pre-handshake one) and yields no delivered signal,
+  // and clientCount() counts unregistered sockets — so a bridge
+  // mid-reconnect made clientCount()>0, the message was broadcast into
+  // a non-registered socket, the "restarting" notice was suppressed,
+  // and the user's message was silently lost. The old "queued either
+  // way" comment was false: broadcast does not queue. sendToAgent is
+  // registered-keyed + returns a real delivered bool; on a miss we
+  // push to pendingInboundBuffer, which onClientRegistered drains on
+  // the next bridge register — so the notice below is now truthful.
+  const selfAgent = process.env.SWITCHROOM_AGENT_NAME ?? ''
+  const delivered = ipcServer.sendToAgent(selfAgent, inboundMsg)
   if (!delivered) {
+    pendingInboundBuffer.push(selfAgent, inboundMsg)
     const threadOpts = messageThreadId != null ? { message_thread_id: messageThreadId } : {}
     // #1075: thread-id-bearing — swallow via robustApiCall so a deleted
-    // topic doesn't crash the gateway. Fire-and-forget; the user-visible
-    // hint is non-critical (the inbound is queued either way).
+    // topic doesn't crash the gateway. Fire-and-forget; the inbound is
+    // genuinely buffered now, so the hint is accurate, not a guess.
     void swallowingApiCall(
-      () => bot.api.sendMessage(chat_id, '⏳ Agent is restarting, please wait…', { ...threadOpts }),
+      () => bot.api.sendMessage(chat_id, '⏳ Agent is restarting — your message is queued and will be processed when it reconnects.', { ...threadOpts }),
       {
         chat_id,
         verb: 'agent-restarting-notice',
@@ -8847,7 +8942,7 @@ async function handlePermissionSlash(ctx: Context, behavior: 'allow' | 'deny'):
     return
   }
   // Forward to connected bridges — same IPC the button handler uses.
-  ipcServer.broadcast({ type: 'permission', requestId: request_id, behavior })
+  dispatchPermissionVerdict({ type: 'permission', requestId: request_id, behavior })
   pendingPermissions.delete(request_id)
   process.stderr.write(
     `[telegram gateway] slash-${behavior} request_id=${request_id} tool=${details.tool_name} by=${senderId}\n`,
@@ -10039,6 +10134,21 @@ async function handleVaultRequestSaveCallback(ctx: Context, data: string): Promi
         )
         .catch(() => {})
     }
+    // Wake the agent that called vault_request_save — symmetric with
+    // the vra: approve/deny path (#1052/#1150/#1156). Without this the
+    // tool returned "waiting for operator", the turn ended, and a
+    // Discard left the agent silently idle forever.
+    const discardInbound = buildVaultSaveDiscardedInbound({
+      ctx: { agent: pending.agent, key: pending.key, chat_id: pending.chat_id },
+      stageId,
+      operatorId: senderId,
+    })
+    const dDelivered = ipcServer.sendToAgent(pending.agent, discardInbound)
+    process.stderr.write(
+      `telegram gateway: vault_save_discarded injection agent=${pending.agent} ` +
+      `key=${pending.key} stage=${stageId} delivered=${dDelivered}\n`,
+    )
+    if (!dDelivered) pendingInboundBuffer.push(pending.agent, discardInbound)
     return
   }
 
@@ -10143,6 +10253,22 @@ async function handleVaultRequestSaveCallback(ctx: Context, data: string): Promi
       // retry by re-invoking the same MCP tool, but the value will be
       // re-staged with a new ID. Drop the current stage.
       pendingVaultRequestSaves.delete(stageId)
+      // Wake the waiting agent with the failure (symmetric with the
+      // success/discard paths) so it doesn't assume vault:<key> exists.
+      const failReason =
+        (write.output || 'vault write error').split('\n')[0]!.slice(0, 200)
+      const failInbound = buildVaultSaveFailedInbound({
+        ctx: { agent: pending.agent, key: pending.key, chat_id: pending.chat_id },
+        stageId,
+        operatorId: senderId,
+        reason: failReason,
+      })
+      const fDelivered = ipcServer.sendToAgent(pending.agent, failInbound)
+      process.stderr.write(
+        `telegram gateway: vault_save_failed injection agent=${pending.agent} ` +
+        `key=${pending.key} stage=${stageId} delivered=${fDelivered}\n`,
+      )
+      if (!fDelivered) pendingInboundBuffer.push(pending.agent, failInbound)
       return
     }
 
@@ -10158,6 +10284,20 @@ async function handleVaultRequestSaveCallback(ctx: Context, data: string): Promi
         )
         .catch(() => {})
     }
+    // Wake the agent that called vault_request_save so it resumes the
+    // task that was blocked on this credential (symmetric with the
+    // vra: approve path; buffered if the bridge is mid-reconnect).
+    const okInbound = buildVaultSaveCompletedInbound({
+      ctx: { agent: pending.agent, key: pending.key, chat_id: pending.chat_id },
+      stageId,
+      operatorId: senderId,
+    })
+    const okDelivered = ipcServer.sendToAgent(pending.agent, okInbound)
+    process.stderr.write(
+      `telegram gateway: vault_save_completed injection agent=${pending.agent} ` +
+      `key=${pending.key} stage=${stageId} delivered=${okDelivered}\n`,
+    )
+    if (!okDelivered) pendingInboundBuffer.push(pending.agent, okInbound)
     return
   }
 
@@ -12084,16 +12224,25 @@ bot.on('callback_query:data', async ctx => {
     process.stderr.write(
       `telegram gateway: button_callback chatId=${cbChatId} user=${ctx.from.id} data=${JSON.stringify(agentCb.raw)} btnText=${JSON.stringify(buttonText ?? null)}\n`,
     )
-    ipcServer.broadcast(inboundMsg)
-    if (ipcServer.clientCount() === 0) {
-      // No bridge connected — the agent's gone. Tell the user so they
-      // don't think the button silently swallowed their tap.
+    // Registered-keyed delivery + buffer-on-miss (same fix as the
+    // normal-inbound path above): broadcast()/clientCount() lost the
+    // tap whenever the bridge was mid-reconnect (clientCount() counts
+    // unregistered sockets, so the notice was suppressed AND nothing
+    // was actually queued). sendToAgent → pendingInboundBuffer (drained
+    // by onClientRegistered) makes the "queued" promise real.
+    const selfAgentBtn = process.env.SWITCHROOM_AGENT_NAME ?? ''
+    const btnDelivered = ipcServer.sendToAgent(selfAgentBtn, inboundMsg)
+    if (!btnDelivered) {
+      pendingInboundBuffer.push(selfAgentBtn, inboundMsg)
+      // No registered bridge — the agent's mid-restart. Tell the user
+      // so they don't think the button silently swallowed their tap;
+      // the tap is genuinely buffered now and replays on reconnect.
       // #1075: thread-id-bearing — swallow on THREAD_NOT_FOUND.
       void swallowingApiCall(
         () =>
           bot.api.sendMessage(
             cbChatId,
-            '⏳ Agent is restarting — your button tap was queued but won\'t be processed until it comes back.',
+            '⏳ Agent is restarting — your button tap is queued and will be processed when it comes back.',
             cbThreadId != null ? { message_thread_id: cbThreadId } : {},
           ),
         {
@@ -12222,7 +12371,7 @@ bot.on('callback_query:data', async ctx => {
       // otherwise the rule may be unsafe to honour at scale and we
       // fall back to single-use allow.
       synthInbound: () => {
-        ipcServer.broadcast({
+        dispatchPermissionVerdict({
           type: 'permission',
           requestId: request_id,
           behavior: 'allow',
@@ -12260,7 +12409,7 @@ bot.on('callback_query:data', async ctx => {
     newText: baseText ? `${baseText}\n\n${label}` : label,
     parseMode: 'HTML',
     synthInbound: () => {
-      ipcServer.broadcast({
+      dispatchPermissionVerdict({
         type: 'permission',
         requestId: request_id,
         behavior: behavior as 'allow' | 'deny',

package/telegram-plugin/gateway/pending-inbound-buffer.ts

@@ -54,6 +54,45 @@ export interface PendingInboundBufferOptions {
   log?: (line: string) => void
 }
 
+/**
+ * Drain `agent`'s buffered inbound and re-deliver each via `send`. A
+ * `send` returning false (or throwing) means "not delivered" — the
+ * message is re-buffered so nothing is lost when the bridge is still
+ * offline. Returns counts for observability.
+ *
+ * This exists because `drain` is otherwise only called on bridge
+ * re-register (`onClientRegistered`). After a network storm that
+ * settles with the bridge STILL connected, messages buffered during
+ * the flap never drain — they sit until a manual restart forces a
+ * re-register. The silence-poke framework fallback calls this on
+ * wedge-clear so the agent self-heals (fleet-update thundering-herd
+ * incident, 2026-05-19).
+ */
+export function redeliverBufferedInbound(
+  buffer: PendingInboundBuffer,
+  agent: string,
+  send: (msg: InboundMessage) => boolean,
+): { drained: number; redelivered: number; rebuffered: number } {
+  const pending = buffer.drain(agent)
+  let redelivered = 0
+  let rebuffered = 0
+  for (const msg of pending) {
+    let delivered = false
+    try {
+      delivered = send(msg)
+    } catch {
+      delivered = false
+    }
+    if (delivered) {
+      redelivered++
+    } else {
+      buffer.push(agent, msg)
+      rebuffered++
+    }
+  }
+  return { drained: pending.length, redelivered, rebuffered }
+}
+
 export function createPendingInboundBuffer(
   opts: PendingInboundBufferOptions = {},
 ): PendingInboundBuffer {

package/telegram-plugin/gateway/pending-permission-decisions.ts

@@ -0,0 +1,112 @@
+/**
+ * Per-agent buffer for permission verdicts the gateway couldn't deliver
+ * because no live IPC client was registered for the agent at send-time.
+ *
+ * Background (PR-3 of the callback→model-continuation series): a
+ * tool/skill/MCP permission request suspends the claude turn *inside*
+ * the MCP permission call until the gateway relays the operator's
+ * Approve/Deny verdict back (`{type:'permission'}` → bridge
+ * `onPermission` → Claude Code). The verdict sites previously used
+ * `ipcServer.broadcast(...)`, which is fire-and-forget: if the bridge
+ * was mid-reconnect at the exact moment the operator tapped (every
+ * agent/gateway restart, claude session bounce), the verdict was
+ * dropped and the model stayed wedged forever — the user's tap did
+ * nothing and they were left silent.
+ *
+ * This is the permission-verdict analog of `pending-inbound-buffer.ts`:
+ * the verdict sites now `sendToAgent` (registered-keyed, real delivered
+ * bool) and on a miss `push()` here; `onClientRegistered` `drain()`s
+ * and re-sends so a reconnecting bridge relays the missed verdict to
+ * the still-suspended permission call.
+ *
+ * Contract mirrors pending-inbound-buffer:
+ *   - `push(agent, ev)` best-effort, synchronous, bounded.
+ *   - `drain(agent)` returns ALL pending verdicts in insertion order
+ *     and clears them; called from `onClientRegistered`.
+ *   - In-memory only; survives reconnect within one gateway lifetime,
+ *     not a gateway restart. A late-redelivered verdict for a
+ *     request_id claude no longer has is harmless — the bridge relays
+ *     it and Claude Code ignores an unknown request_id. The TTL-sweep
+ *     auto-deny is the independent backstop for "operator never tapped".
+ *
+ * Per-agent cap prevents a never-reconnecting bridge from leaking
+ * memory; on overflow the OLDEST verdict is dropped (freshest is most
+ * relevant) and logged.
+ */
+
+import type { PermissionEvent } from './ipc-protocol.js'
+
+/** Default cap per agent — a reasonable backlog of permission cards
+ *  stacked while the bridge is offline, no more. */
+export const DEFAULT_PENDING_PERMISSION_CAP = 32
+
+export interface PendingPermissionBuffer {
+  /** Append `ev` to `agent`'s queue. Returns true if accepted without
+   *  eviction, false if the cap forced dropping the oldest (the new
+   *  entry is STILL accepted). */
+  push: (agent: string, ev: PermissionEvent) => boolean
+  /** Pop and return all pending verdicts for `agent` (insertion order).
+   *  Empty array when none. Idempotent. */
+  drain: (agent: string) => PermissionEvent[]
+  /** Test-only: current depth for `agent`. */
+  depth: (agent: string) => number
+  /** Test-only: total depth across all agents. */
+  totalDepth: () => number
+}
+
+export interface PendingPermissionBufferOptions {
+  capPerAgent?: number
+  log?: (line: string) => void
+}
+
+export function createPendingPermissionBuffer(
+  opts: PendingPermissionBufferOptions = {},
+): PendingPermissionBuffer {
+  const cap = opts.capPerAgent ?? DEFAULT_PENDING_PERMISSION_CAP
+  const log = opts.log ?? ((line: string) => process.stderr.write(line))
+  const queues = new Map<string, PermissionEvent[]>()
+
+  return {
+    push(agent, ev) {
+      let q = queues.get(agent)
+      if (q == null) {
+        q = []
+        queues.set(agent, q)
+      }
+      let evicted = false
+      if (q.length >= cap) {
+        const dropped = q.shift()
+        evicted = true
+        log(
+          `pending-permission-buffer: agent=${agent} cap=${cap} reached — ` +
+          `dropped oldest verdict request=${dropped?.requestId ?? '-'} ` +
+          `behavior=${dropped?.behavior ?? '-'}\n`,
+        )
+      }
+      q.push(ev)
+      log(
+        `pending-permission-buffer: agent=${agent} buffered request=${ev.requestId} ` +
+        `behavior=${ev.behavior} depth_after=${q.length} evicted=${evicted}\n`,
+      )
+      return !evicted
+    },
+    drain(agent) {
+      const q = queues.get(agent)
+      if (q == null || q.length === 0) return []
+      queues.delete(agent)
+      log(
+        `pending-permission-buffer: drained agent=${agent} count=${q.length} ` +
+        `requests=[${q.map((e) => e.requestId).join(',')}]\n`,
+      )
+      return q
+    },
+    depth(agent) {
+      return queues.get(agent)?.length ?? 0
+    },
+    totalDepth() {
+      let n = 0
+      for (const q of queues.values()) n += q.length
+      return n
+    },
+  }
+}