switchroom 0.12.12 → 0.12.14

package/telegram-plugin/gateway/gateway.ts

@@ -246,9 +246,13 @@ 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 { 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)
@@ -2738,6 +2759,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 +2816,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 +6318,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 +7048,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 +8925,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 +10117,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 +10236,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 +10267,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 +12207,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 +12354,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 +12392,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-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
+    },
+  }
+}

package/telegram-plugin/gateway/vault-grant-inbound-builders.ts

@@ -123,3 +123,120 @@ export function buildVaultGrantDeniedInbound(opts: {
     },
   }
 }
+
+/** Subset of PendingVaultRequestSave the save-outcome builders need.
+ *  The `vault_request_save` flow has no scope/ttl (it stores a value,
+ *  it doesn't mint a scoped grant). */
+export interface VaultSaveInboundContext {
+  agent: string
+  key: string
+  /** Telegram chat the save card lived in — keeps the synthesized
+   *  resume-turn associated with the originating conversation. */
+  chat_id: string
+}
+
+/**
+ * Synthetic inbound for a successful operator Save tap on a
+ * `vault_request_save` card. Symmetric with
+ * `buildVaultGrantApprovedInbound`: the `vault_request_save` tool
+ * returns "waiting for operator" and the agent ends its turn, so
+ * without this inbound the secret is stored but the agent is never
+ * told and never resumes (the exact silence bug this fixes — the
+ * `vrs:` handler had no wake-up despite a comment claiming one).
+ */
+export function buildVaultSaveCompletedInbound(opts: {
+  ctx: VaultSaveInboundContext
+  stageId: string
+  operatorId: string
+  nowMs?: number
+}): InboundMessage {
+  const ts = opts.nowMs ?? Date.now()
+  return {
+    type: 'inbound',
+    chatId: opts.ctx.chat_id,
+    messageId: ts,
+    user: 'vault-broker',
+    userId: 0,
+    ts,
+    text:
+      `✅ Operator saved your secret as \`vault:${opts.ctx.key}\`. ` +
+      `Please resume the task that was waiting on it — reference the ` +
+      `value via the usual \`vault:${opts.ctx.key}\` path.`,
+    meta: {
+      source: 'vault_save_completed',
+      agent: opts.ctx.agent,
+      key: opts.ctx.key,
+      stage_id: opts.stageId,
+      operator_id: opts.operatorId,
+    },
+  }
+}
+
+/**
+ * Synthetic inbound for a Save tap whose vault write FAILED. Steers
+ * the model away from assuming the secret exists.
+ */
+export function buildVaultSaveFailedInbound(opts: {
+  ctx: VaultSaveInboundContext
+  stageId: string
+  operatorId: string
+  reason: string
+  nowMs?: number
+}): InboundMessage {
+  const ts = opts.nowMs ?? Date.now()
+  return {
+    type: 'inbound',
+    chatId: opts.ctx.chat_id,
+    messageId: ts,
+    user: 'vault-broker',
+    userId: 0,
+    ts,
+    text:
+      `⚠️ The operator tapped Save but the vault write for ` +
+      `\`vault:${opts.ctx.key}\` FAILED (${opts.reason}). The secret was ` +
+      `NOT stored — do NOT assume \`vault:${opts.ctx.key}\` resolves. ` +
+      `Either retry the save (the operator may need to fix the underlying ` +
+      `issue first) or pick a fallback for the original task.`,
+    meta: {
+      source: 'vault_save_failed',
+      agent: opts.ctx.agent,
+      key: opts.ctx.key,
+      stage_id: opts.stageId,
+      operator_id: opts.operatorId,
+    },
+  }
+}
+
+/**
+ * Synthetic inbound for an operator Discard tap. The secret was never
+ * written; steer the model to a fallback rather than silent idle.
+ */
+export function buildVaultSaveDiscardedInbound(opts: {
+  ctx: VaultSaveInboundContext
+  stageId: string
+  operatorId: string
+  nowMs?: number
+}): InboundMessage {
+  const ts = opts.nowMs ?? Date.now()
+  return {
+    type: 'inbound',
+    chatId: opts.ctx.chat_id,
+    messageId: ts,
+    user: 'vault-broker',
+    userId: 0,
+    ts,
+    text:
+      `🚫 Operator discarded your \`vault_request_save\` for ` +
+      `\`${opts.ctx.key}\` — the secret was NOT stored and ` +
+      `\`vault:${opts.ctx.key}\` will not resolve. Pick a fallback for ` +
+      `the original task (ask the user, try another approach, or skip ` +
+      `the feature). Do NOT re-request the save without asking the user.`,
+    meta: {
+      source: 'vault_save_discarded',
+      agent: opts.ctx.agent,
+      key: opts.ctx.key,
+      stage_id: opts.stageId,
+      operator_id: opts.operatorId,
+    },
+  }
+}

package/telegram-plugin/tests/pending-permission-decisions.test.ts

@@ -0,0 +1,73 @@
+/**
+ * Pin the per-agent permission-verdict buffer (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
+ * operator's Approve/Deny verdict is relayed back. The verdict sites
+ * previously `broadcast(...)` fire-and-forget, so a verdict produced
+ * while the bridge was mid-reconnect was dropped and the model stayed
+ * wedged forever (user tapped, nothing happened, silence). This buffer
+ * — the permission analog of pending-inbound-buffer — holds the missed
+ * verdict and is drained on the next bridge register.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  createPendingPermissionBuffer,
+  DEFAULT_PENDING_PERMISSION_CAP,
+} from '../gateway/pending-permission-decisions.js'
+import type { PermissionEvent } from '../gateway/ipc-protocol.js'
+
+function verdict(
+  requestId: string,
+  behavior: 'allow' | 'deny' = 'allow',
+  rule?: string,
+): PermissionEvent {
+  return { type: 'permission', requestId, behavior, ...(rule ? { rule } : {}) }
+}
+
+describe('pending-permission-decisions', () => {
+  it('push + drain — FIFO order per agent, idempotent drain', () => {
+    const buf = createPendingPermissionBuffer({ log: () => {} })
+    buf.push('a', verdict('r1', 'allow'))
+    buf.push('a', verdict('r2', 'deny'))
+    buf.push('b', verdict('r3', 'allow'))
+    const a = buf.drain('a')
+    expect(a.map((e) => e.requestId)).toEqual(['r1', 'r2'])
+    expect(a[1]!.behavior).toBe('deny')
+    expect(buf.drain('a')).toEqual([]) // idempotent
+    expect(buf.drain('b').map((e) => e.requestId)).toEqual(['r3'])
+    expect(buf.totalDepth()).toBe(0)
+  })
+
+  it('preserves the always-allow rule field through buffering', () => {
+    const buf = createPendingPermissionBuffer({ log: () => {} })
+    buf.push('a', verdict('r1', 'allow', 'Bash(ls:*)'))
+    const [ev] = buf.drain('a')
+    expect(ev!.rule).toBe('Bash(ls:*)')
+    expect(ev!.behavior).toBe('allow')
+  })
+
+  it('per-agent cap drops the OLDEST verdict and reports eviction', () => {
+    const buf = createPendingPermissionBuffer({ capPerAgent: 3, log: () => {} })
+    expect(buf.push('a', verdict('r1'))).toBe(true)
+    expect(buf.push('a', verdict('r2'))).toBe(true)
+    expect(buf.push('a', verdict('r3'))).toBe(true)
+    expect(buf.push('a', verdict('r4'))).toBe(false) // evicted oldest
+    const drained = buf.drain('a')
+    expect(drained.map((e) => e.requestId)).toEqual(['r2', 'r3', 'r4'])
+  })
+
+  it('depth/totalDepth track buffered verdicts', () => {
+    const buf = createPendingPermissionBuffer({ log: () => {} })
+    expect(buf.depth('a')).toBe(0)
+    buf.push('a', verdict('r1'))
+    buf.push('a', verdict('r2'))
+    buf.push('b', verdict('r3'))
+    expect(buf.depth('a')).toBe(2)
+    expect(buf.totalDepth()).toBe(3)
+  })
+
+  it('exports a sane default cap', () => {
+    expect(DEFAULT_PENDING_PERMISSION_CAP).toBeGreaterThanOrEqual(8)
+  })
+})

package/telegram-plugin/tests/vault-save-inbound-builders.test.ts

@@ -0,0 +1,96 @@
+/**
+ * Pin the InboundMessage shapes the gateway synthesizes when the
+ * operator taps Save / Discard (or the write fails) on a
+ * `vault_request_save` card. Before this, `handleVaultRequestSaveCallback`
+ * edited the card on every terminal outcome but NEVER woke the agent
+ * (no sendToAgent / no pendingInboundBuffer push) — so the secret was
+ * stored/discarded but the agent that called `vault_request_save`
+ * stayed silently idle. These builders + the gateway wiring close that
+ * gap symmetrically with the vra: approve/deny path (#1052/#1150/#1156).
+ *
+ * The wire shape is load-bearing; a dropped `meta.source` / field would
+ * silently regress the wake-up. Cheap regression guard.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  buildVaultSaveCompletedInbound,
+  buildVaultSaveFailedInbound,
+  buildVaultSaveDiscardedInbound,
+  type VaultSaveInboundContext,
+} from '../gateway/vault-grant-inbound-builders.js'
+
+const FIXED_NOW = 1_700_000_000_000
+
+const CTX: VaultSaveInboundContext = {
+  agent: 'gymbro',
+  key: 'garmin/credentials',
+  chat_id: '12345',
+}
+
+describe('buildVaultSaveCompletedInbound', () => {
+  it('emits the canonical vault-broker envelope', () => {
+    const msg = buildVaultSaveCompletedInbound({
+      ctx: CTX,
+      stageId: 'stage-001',
+      operatorId: '999',
+      nowMs: FIXED_NOW,
+    })
+    expect(msg.type).toBe('inbound')
+    expect(msg.chatId).toBe('12345')
+    expect(msg.user).toBe('vault-broker')
+    expect(msg.userId).toBe(0)
+    expect(msg.ts).toBe(FIXED_NOW)
+    expect(msg.messageId).toBe(FIXED_NOW)
+  })
+
+  it('carries the load-bearing meta + an actionable resume instruction', () => {
+    const msg = buildVaultSaveCompletedInbound({
+      ctx: CTX,
+      stageId: 'stage-001',
+      operatorId: '999',
+      nowMs: FIXED_NOW,
+    })
+    expect(msg.meta).toEqual({
+      source: 'vault_save_completed',
+      agent: 'gymbro',
+      key: 'garmin/credentials',
+      stage_id: 'stage-001',
+      operator_id: '999',
+    })
+    expect(msg.text).toContain('vault:garmin/credentials')
+    expect(msg.text.toLowerCase()).toContain('resume')
+  })
+})
+
+describe('buildVaultSaveFailedInbound', () => {
+  it('flags NOT stored, carries the reason + failed source', () => {
+    const msg = buildVaultSaveFailedInbound({
+      ctx: CTX,
+      stageId: 'stage-002',
+      operatorId: '999',
+      reason: 'VAULT-BROKER-DENIED: no operator attestation',
+      nowMs: FIXED_NOW,
+    })
+    expect(msg.meta?.source).toBe('vault_save_failed')
+    expect(msg.meta?.key).toBe('garmin/credentials')
+    expect(msg.text).toContain('FAILED')
+    expect(msg.text).toContain('VAULT-BROKER-DENIED')
+    expect(msg.text).toContain('NOT stored')
+  })
+})
+
+describe('buildVaultSaveDiscardedInbound', () => {
+  it('flags NOT stored + steers to a fallback, discarded source', () => {
+    const msg = buildVaultSaveDiscardedInbound({
+      ctx: CTX,
+      stageId: 'stage-003',
+      operatorId: '999',
+      nowMs: FIXED_NOW,
+    })
+    expect(msg.meta?.source).toBe('vault_save_discarded')
+    expect(msg.meta?.agent).toBe('gymbro')
+    expect(msg.text).toContain('discarded')
+    expect(msg.text).toContain('NOT stored')
+  })
+})