switchroom 0.7.13 → 0.7.15

package/telegram-plugin/gateway/gateway.ts

@@ -258,6 +258,7 @@ import { runPipeline } from '../secret-detect/pipeline.js'
 import { StagingMap } from '../secret-detect/staging.js'
 import { maskToken } from '../secret-detect/mask.js'
 import { defaultVaultWrite, defaultVaultList } from '../secret-detect/vault-write.js'
+import { parseVaultCliError, renderVaultCliError } from '../secret-detect/vault-error.js'
 import { detectSecrets } from '../secret-detect/index.js'
 import { classifyAdminGate } from '../admin-commands/index.js'
 import {
@@ -1390,6 +1391,9 @@ type PendingVaultOp =
     }
   // Issue #228: waiting for confirmation before revoking a grant.
   | { kind: 'revoke_confirm'; grantId: string; agent: string; keys: string[]; startedAt: number }
+  // Issue #969 P1a: user tapped "Rename" on a vault_request_save card;
+  // the next message becomes the new key name for the staged save.
+  | { kind: 'rename-vault-save'; stageId: string; startedAt: number }
 const VAULT_INPUT_TTL_MS = 5 * 60 * 1000
 const pendingVaultOps = new Map<string, PendingVaultOp>()
 
@@ -1426,6 +1430,40 @@ interface DeferredSecret {
 }
 const deferredSecrets = new Map<string, DeferredSecret>()
 
+/**
+ * Agent-initiated save staging (issue #969 P1a). When an agent calls the
+ * `vault_request_save` MCP tool, we stage the value here, render an
+ * approval card to the user, and write to vault only on tap. The value
+ * is held in gateway memory ONLY — never echoed back to the agent and
+ * never logged.
+ */
+interface PendingVaultRequestSave {
+  /** Agent that requested the save (process.env.SWITCHROOM_AGENT_NAME). */
+  agent: string
+  /** Chat to edit when the user taps. */
+  chat_id: string
+  /** Card message id (filled in after we send the card). */
+  card_message_id?: number
+  /** Currently-suggested slug; may be renamed by the user. */
+  key: string
+  /** Storage shape — 'string' (default) or 'binary'. */
+  kind: 'string' | 'binary'
+  /** The secret value, held in memory until the user approves/discards. */
+  value: string
+  /** Optional rationale shown on the card. */
+  why?: string
+  /** Unix-ms timestamp; entries are reaped after VAULT_REQUEST_SAVE_TTL_MS. */
+  staged_at: number
+}
+const pendingVaultRequestSaves = new Map<string, PendingVaultRequestSave>()
+const VAULT_REQUEST_SAVE_TTL_MS = 10 * 60 * 1000
+function sweepPendingVaultRequestSaves(): void {
+  const cutoff = Date.now() - VAULT_REQUEST_SAVE_TTL_MS
+  for (const [k, v] of pendingVaultRequestSaves) {
+    if (v.staged_at < cutoff) pendingVaultRequestSaves.delete(k)
+  }
+}
+
 /**
  * Mint an approval-kernel decision row for a deferred-secret card
  * (MIGRATION.md §1). Best-effort: if the kernel/broker is unreachable, we
@@ -2373,6 +2411,7 @@ const ALLOWED_TOOLS = new Set([
   'send_checklist', 'update_checklist',
   'ask_user',
   'send_sticker', 'send_gif',
+  'vault_request_save',
 ])
 
 async function executeToolCall(tool: string, args: Record<string, unknown>): Promise<unknown> {
@@ -2412,6 +2451,8 @@ async function executeToolCall(tool: string, args: Record<string, unknown>): Pro
       return executeSendSticker(args)
     case 'send_gif':
       return executeSendGif(args)
+    case 'vault_request_save':
+      return executeVaultRequestSave(args)
     default:
       throw new Error(`unknown tool: ${tool}`)
   }
@@ -3387,6 +3428,105 @@ async function publishToTelegraph(
   return page.value.url
 }
 
+/**
+ * Build the inline keyboard for the agent-initiated vault-save approval card.
+ * Issue #969 P1a. Callback prefix `vrs:` (vault-request-save).
+ *
+ * Buttons must fit Telegram's 64-byte callback_data limit. Stage IDs are
+ * 8 hex chars (32 bits of entropy), so each callback comfortably fits.
+ */
+function buildVaultRequestSaveKeyboard(stageId: string): { inline_keyboard: Array<Array<{ text: string; callback_data: string }>> } {
+  return {
+    inline_keyboard: [
+      [
+        { text: '✅ Save once', callback_data: `vrs:save:${stageId}` },
+        { text: '🚫 Discard', callback_data: `vrs:discard:${stageId}` },
+      ],
+      [
+        { text: '✏️ Rename', callback_data: `vrs:rename:${stageId}` },
+      ],
+    ],
+  }
+}
+
+function renderVaultRequestSaveCard(req: PendingVaultRequestSave, agentSlug: string): string {
+  const lines: string[] = []
+  lines.push(`🔐 <b>${escapeHtmlForTg(agentSlug)}</b> wants to save a secret`)
+  lines.push(`key: <code>${escapeHtmlForTg(req.key)}</code>`)
+  if (req.why && req.why.length > 0) {
+    lines.push(`why: <i>${escapeHtmlForTg(req.why)}</i>`)
+  }
+  lines.push('')
+  lines.push(`<i>Tap Save to write to the host vault, Rename to change the key name, or Discard to drop it. The value is held in this chat's gateway memory until you decide.</i>`)
+  return lines.join('\n')
+}
+
+/**
+ * `vault_request_save` tool — agent surfaces an approval card asking
+ * the user to confirm saving a secret. The value is staged here and
+ * written to vault only on user tap. See #969 P1a.
+ */
+async function executeVaultRequestSave(args: Record<string, unknown>): Promise<{ content: Array<{ type: string; text: string }> }> {
+  const chat_id = args.chat_id as string
+  if (!chat_id) throw new Error('vault_request_save: chat_id is required')
+  const key = args.key as string
+  if (!key || typeof key !== 'string') throw new Error('vault_request_save: key is required')
+  const value = args.value as string
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error('vault_request_save: value is required and must be a non-empty string')
+  }
+  const why = typeof args.why === 'string' ? args.why : undefined
+  const kindRaw = typeof args.kind === 'string' ? args.kind : 'string'
+  if (kindRaw !== 'string' && kindRaw !== 'binary') {
+    throw new Error('vault_request_save: kind must be "string" or "binary"')
+  }
+  assertAllowedChat(chat_id)
+
+  // Validate slug shape — vault keys must match a tight charset so the
+  // host CLI hints render cleanly and reference resolution stays
+  // predictable. Same shape as `validateVaultKey` in the broker, kept
+  // local here to avoid pulling in the broker import.
+  if (!/^[A-Za-z0-9_.-]{1,200}$/.test(key)) {
+    throw new Error('vault_request_save: key must match [A-Za-z0-9_.-]{1,200}')
+  }
+
+  const agentSlug = process.env.SWITCHROOM_AGENT_NAME || 'agent'
+
+  // Stage the request server-side. The value never leaves gateway memory
+  // until the user approves.
+  const stageId = randomBytes(4).toString('hex')
+  const pending: PendingVaultRequestSave = {
+    agent: agentSlug,
+    chat_id,
+    key,
+    kind: kindRaw,
+    value,
+    why,
+    staged_at: Date.now(),
+  }
+  pendingVaultRequestSaves.set(stageId, pending)
+  sweepPendingVaultRequestSaves()
+
+  // Send the approval card.
+  const text = renderVaultRequestSaveCard(pending, agentSlug)
+  const threadId = args.message_thread_id != null ? Number(args.message_thread_id) : undefined
+  const sent = await lockedBot.api.sendMessage(chat_id, text, {
+    parse_mode: 'HTML',
+    reply_markup: buildVaultRequestSaveKeyboard(stageId),
+    ...(threadId != null && Number.isFinite(threadId) ? { message_thread_id: threadId } : {}),
+  })
+  pending.card_message_id = sent.message_id
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: `vault_request_save: card sent (stage_id=${stageId}, key=${key}). The user must tap a button before the secret is persisted; do not assume success until you see the user's next message confirming the outcome.`,
+      },
+    ],
+  }
+}
+
 async function executeReact(args: Record<string, unknown>): Promise<unknown> {
   if (!args.chat_id) throw new Error('react: chat_id is required')
   if (!args.message_id) throw new Error('react: message_id is required')
@@ -4835,6 +4975,35 @@ async function handleInbound(
         if (codeBlockMatch) value = codeBlockMatch[1]!
         if (msgId != null) await deleteSensitiveMessage(chat_id, msgId, 'vault secret value')
         await executeVaultOp(ctx, chat_id, 'set', pendingVault.key, pendingVault.passphrase, value.trim())
+      } else if (pendingVault.kind === 'rename-vault-save') {
+        // Issue #969 P1a: user tapped Rename on a vault_request_save
+        // card and is now telling us the new key name. Validate the
+        // slug, update the staged entry, refresh the card.
+        const newKey = text.trim()
+        const staged = pendingVaultRequestSaves.get(pendingVault.stageId)
+        if (!staged) {
+          await switchroomReply(ctx, '⌛ That save card expired before you renamed. Ask the agent to re-issue.', { html: true })
+          return
+        }
+        if (!/^[A-Za-z0-9_.-]{1,200}$/.test(newKey)) {
+          // Re-arm the pending state so the user can try again.
+          pendingVaultOps.set(chat_id, { ...pendingVault, startedAt: Date.now() })
+          await switchroomReply(ctx, '⚠️ Key must match <code>[A-Za-z0-9_.-]</code> and be ≤ 200 chars. Send a different name.', { html: true })
+          return
+        }
+        staged.key = newKey
+        if (msgId != null) await deleteSensitiveMessage(chat_id, msgId, 'vault rename input')
+        // Edit the card in place with the new suggested key + same buttons.
+        if (staged.card_message_id != null) {
+          await ctx.api
+            .editMessageText(
+              staged.chat_id,
+              staged.card_message_id,
+              renderVaultRequestSaveCard(staged, staged.agent),
+              { parse_mode: 'HTML', reply_markup: buildVaultRequestSaveKeyboard(pendingVault.stageId) },
+            )
+            .catch(() => {})
+        }
       }
       return
     }
@@ -4871,7 +5040,15 @@ async function handleInbound(
         while (existing.has(slug)) slug = `${slugBase}_${n++}`
         const write = defaultVaultWrite(slug, staged.detection.matched_text, cached.passphrase)
         if (!write.ok) {
-          await switchroomReply(ctx, `<b>vault write failed:</b>\n${preBlock(write.output)}`, { html: true })
+          // Route P0a markers (#969) through the structured renderer so
+          // a "new key, needs operator approval" failure surfaces a
+          // host-CLI hint instead of a raw stderr blob.
+          const parsed = parseVaultCliError(write.output)
+          const rendered = renderVaultCliError(parsed, { verb: 'save', key: slug })
+          const body = rendered.suppressRaw
+            ? rendered.html
+            : `<b>vault write failed:</b>\n${preBlock(write.output)}`
+          await switchroomReply(ctx, body, { html: true })
           return
         }
         secretStaging.delete(staged.chat_id, staged.message_id)
@@ -5939,16 +6116,37 @@ function runVaultCli(args: string[], passphrase: string, stdinValue?: string): {
   }
 }
 
+/**
+ * Render a vault-CLI failure as Telegram HTML. Routes recognised P0a
+ * stderr markers (VAULT-SANDBOX-CONTEXT / VAULT-NEEDS-APPROVAL /
+ * VAULT-BROKER-UNREACHABLE / VAULT-BROKER-DENIED) through the structured
+ * renderer; falls back to a raw pre-block for anything else.
+ */
+function renderVaultOpFailure(
+  verbLabel: 'list' | 'get' | 'set' | 'delete',
+  cliOutput: string,
+  key: string | undefined,
+): string {
+  const parsed = parseVaultCliError(cliOutput)
+  // Map the gateway-internal op label onto the renderer's verb. 'delete'
+  // surfaces in the host hint as `switchroom vault remove <key>` (the
+  // canonical CLI name); 'list' has no key.
+  const verb = verbLabel === 'delete' ? 'remove' : verbLabel
+  const rendered = renderVaultCliError(parsed, { verb, key })
+  if (rendered.suppressRaw) return rendered.html
+  return `<b>vault ${verbLabel} failed:</b>\n${preBlock(cliOutput)}`
+}
+
 async function executeVaultOp(ctx: Context, chatId: string, op: 'list' | 'get' | 'set' | 'delete', key: string | undefined, passphrase: string, setValue: string | undefined): Promise<void> {
   if (op === 'list') {
     const r = runVaultCli(['list'], passphrase)
-    if (!r.ok) { await switchroomReply(ctx, `<b>vault list failed:</b>\n${preBlock(r.output)}`, { html: true }); return }
+    if (!r.ok) { await switchroomReply(ctx, renderVaultOpFailure('list', r.output, undefined), { html: true }); return }
     const keys = r.output.split('\n').filter(Boolean)
     if (keys.length === 0) { await switchroomReply(ctx, 'Vault is empty.', { html: true }) }
     else { await switchroomReply(ctx, `<b>Vault keys (${keys.length}):</b>\n${keys.map(k => `• <code>${escapeHtmlForTg(k)}</code>`).join('\n')}`, { html: true }) }
   } else if (op === 'get') {
     const r = runVaultCli(['get', key!], passphrase)
-    if (!r.ok) { await switchroomReply(ctx, `<b>vault get failed:</b>\n${preBlock(r.output)}`, { html: true }); return }
+    if (!r.ok) { await switchroomReply(ctx, renderVaultOpFailure('get', r.output, key), { html: true }); return }
     await switchroomReply(ctx, `<code>${escapeHtmlForTg(key!)}</code> =\n<code>${escapeHtmlForTg(r.output)}</code>`, { html: true })
   } else if (op === 'set') {
     if (setValue === undefined) {
@@ -5957,11 +6155,11 @@ async function executeVaultOp(ctx: Context, chatId: string, op: 'list' | 'get' |
       return
     }
     const r = runVaultCli(['set', key!], passphrase, setValue)
-    if (!r.ok) { await switchroomReply(ctx, `<b>vault set failed:</b>\n${preBlock(r.output)}`, { html: true }) }
+    if (!r.ok) { await switchroomReply(ctx, renderVaultOpFailure('set', r.output, key), { html: true }) }
     else { await switchroomReply(ctx, `✅ <code>${escapeHtmlForTg(key!)}</code> saved to vault.`, { html: true }) }
   } else if (op === 'delete') {
     const r = runVaultCli(['remove', key!], passphrase)
-    if (!r.ok) { await switchroomReply(ctx, `<b>vault delete failed:</b>\n${preBlock(r.output)}`, { html: true }) }
+    if (!r.ok) { await switchroomReply(ctx, renderVaultOpFailure('delete', r.output, key), { html: true }) }
     else { await switchroomReply(ctx, `✅ <code>${escapeHtmlForTg(key!)}</code> removed from vault.`, { html: true }) }
   }
 }
@@ -7479,6 +7677,152 @@ function resolveAgentDirForName(agent: string): string | null {
  * Authorization mirrors the operator-event callback: only senders on the
  * configured allowlist get to act on the buttons.
  */
+/**
+ * Issue #969 P1a — handle the agent-initiated vault-save approval card
+ * (`vault_request_save` MCP tool).
+ *
+ * Callbacks:
+ *   vrs:save:<stageId>     — confirm save; write to vault using broker put
+ *                            with operator-passphrase attestation (#969 P1a)
+ *                            so even new keys go through in one tap.
+ *   vrs:discard:<stageId>  — drop the staged secret; never touches disk.
+ *   vrs:rename:<stageId>   — set up a pending-op intercept so the user's
+ *                            next message is taken as a new key name.
+ */
+async function handleVaultRequestSaveCallback(ctx: Context, data: string): Promise<void> {
+  const senderId = String(ctx.from?.id ?? '')
+  const access = loadAccess()
+  if (!access.allowFrom.includes(senderId)) {
+    await ctx.answerCallbackQuery({ text: 'Not authorized.' }).catch(() => {})
+    return
+  }
+
+  const parts = data.split(':')
+  if (parts.length < 3) {
+    await ctx.answerCallbackQuery({ text: 'Bad request' }).catch(() => {})
+    return
+  }
+  const action = parts[1]
+  const stageId = parts.slice(2).join(':')
+  const pending = pendingVaultRequestSaves.get(stageId)
+  if (!pending) {
+    await ctx.answerCallbackQuery({ text: 'Card expired — ask the agent to re-send.' }).catch(() => {})
+    if (ctx.callbackQuery?.message) {
+      await ctx.api
+        .editMessageText(
+          ctx.callbackQuery.message.chat.id,
+          ctx.callbackQuery.message.message_id,
+          '⌛ <i>This vault-save card expired before you tapped. Ask the agent to re-issue if you still want to save.</i>',
+          { parse_mode: 'HTML', reply_markup: { inline_keyboard: [] } },
+        )
+        .catch(() => {})
+    }
+    return
+  }
+
+  if (action === 'discard') {
+    pendingVaultRequestSaves.delete(stageId)
+    await ctx.answerCallbackQuery({ text: '🚫 Discarded' }).catch(() => {})
+    if (pending.card_message_id != null) {
+      await ctx.api
+        .editMessageText(
+          pending.chat_id,
+          pending.card_message_id,
+          `🚫 <i>Discarded. The secret was not written to the vault.</i>`,
+          { parse_mode: 'HTML', reply_markup: { inline_keyboard: [] } },
+        )
+        .catch(() => {})
+    }
+    return
+  }
+
+  if (action === 'rename') {
+    // Set up a pending-op intercept so the user's next message is read
+    // as the new key name. Same shape as the existing /vault set value
+    // capture (gateway.ts uses pendingVaultOps for this).
+    pendingVaultOps.set(pending.chat_id, {
+      kind: 'rename-vault-save',
+      stageId,
+      startedAt: Date.now(),
+    } as PendingVaultOp)
+    await ctx.answerCallbackQuery({ text: 'Send the new key name as your next message.' }).catch(() => {})
+    return
+  }
+
+  if (action === 'save') {
+    // Acknowledge the tap immediately so Telegram doesn't show a
+    // stale "spinning" state on the button while we run the write.
+    await ctx.answerCallbackQuery({ text: '⏳ Saving…' }).catch(() => {})
+
+    // Fetch the cached passphrase for this chat. If the gateway hasn't
+    // seen the user unlock the vault yet, we can't attest the write —
+    // surface the unlock card via the same path the deferred-secret
+    // flow uses (issue #44).
+    const cached = vaultPassphraseCache.get(pending.chat_id)
+    if (!cached || cached.expiresAt <= Date.now()) {
+      if (pending.card_message_id != null) {
+        await ctx.api
+          .editMessageText(
+            pending.chat_id,
+            pending.card_message_id,
+            `🔒 <b>Vault is locked.</b> Run <code>/vault unlock</code> (or any /vault command) to cache the passphrase, then tap Save again on the next card.`,
+            { parse_mode: 'HTML', reply_markup: { inline_keyboard: [] } },
+          )
+          .catch(() => {})
+      }
+      pendingVaultRequestSaves.delete(stageId)
+      return
+    }
+
+    // Run the write. defaultVaultWrite spawns `switchroom vault set
+    // <key>` with the passphrase env set; the CLI in turn forwards the
+    // passphrase to the broker put as operator-attestation (#969 P1a),
+    // which authorizes new-key creation.
+    const write = defaultVaultWrite(pending.key, pending.value, cached.passphrase)
+
+    if (!write.ok) {
+      // Route through the structured-error renderer from #969 P0b so
+      // failures show the actionable host hint instead of a raw blob.
+      const parsed = parseVaultCliError(write.output)
+      const rendered = renderVaultCliError(parsed, { verb: 'save', key: pending.key })
+      const body = rendered.suppressRaw
+        ? rendered.html
+        : `⚠️ vault write failed:\n<pre>${escapeHtmlForTg(write.output)}</pre>`
+      if (pending.card_message_id != null) {
+        await ctx.api
+          .editMessageText(
+            pending.chat_id,
+            pending.card_message_id,
+            `${body}\n\n<i>Tap a fresh card after fixing the underlying issue.</i>`,
+            { parse_mode: 'HTML', reply_markup: { inline_keyboard: [] } },
+          )
+          .catch(() => {})
+      }
+      // Leave the staged secret in memory until TTL — operator might
+      // 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)
+      return
+    }
+
+    // Success — mask the value in the card for visual confirmation.
+    pendingVaultRequestSaves.delete(stageId)
+    if (pending.card_message_id != null) {
+      await ctx.api
+        .editMessageText(
+          pending.chat_id,
+          pending.card_message_id,
+          `✅ saved as <code>vault:${escapeHtmlForTg(pending.key)}</code> (masked: <code>${escapeHtmlForTg(maskToken(pending.value))}</code>)\n<i>The agent can now reference this as <code>vault:${escapeHtmlForTg(pending.key)}</code>.</i>`,
+          { parse_mode: 'HTML', reply_markup: { inline_keyboard: [] } },
+        )
+        .catch(() => {})
+    }
+    return
+  }
+
+  await ctx.answerCallbackQuery({ text: 'Unknown action' }).catch(() => {})
+}
+
 async function handleVaultDeferCallback(ctx: Context, data: string): Promise<void> {
   const senderId = String(ctx.from?.id ?? '')
   const access = loadAccess()
@@ -8087,13 +8431,26 @@ async function executeDeferredSecretSave(
 
   const write = defaultVaultWrite(slug, deferred.text, passphrase)
   if (!write.ok) {
-    // Keep the deferred entry so the user can retry by tapping again.
+    // Classify the failure via the structured stderr markers emitted by
+    // `switchroom vault` (issue #969 P0a). If it's a recognised marker,
+    // render a clean actionable message instead of dumping the raw
+    // "Vault file not found …" / "VAULT-NEEDS-APPROVAL …" blob the CLI
+    // emits — that was the misleading-error half of #968.
+    //
+    // Keep the deferred entry so the user can retry by tapping again
+    // once the underlying condition is fixed (broker started, host
+    // approval granted, etc.).
+    const parsed = parseVaultCliError(write.output)
+    const rendered = renderVaultCliError(parsed, { verb: "save", key: slug })
+    const body = rendered.suppressRaw
+      ? rendered.html
+      : `⚠️ vault write failed:\n<pre>${escapeHtmlForTg(write.output)}</pre>`
     if (cardMessageId != null) {
       await ctx.api
         .editMessageText(
           deferred.chat_id,
           cardMessageId,
-          `⚠️ vault write failed:\n<pre>${escapeHtmlForTg(write.output)}</pre>\n\nRe-tap to retry.`,
+          `${body}\n\nRe-tap to retry.`,
           {
             parse_mode: 'HTML',
             reply_markup: buildDeferredSecretKeyboard(deferKey).inline_keyboard.length > 0
@@ -8587,12 +8944,134 @@ bot.command('vault', async ctx => {
       '/vault lock — lock the broker',
       '/vault grant — mint a capability token (inline wizard)',
       '/vault grants [agent] — list active capability grants (tap to revoke)',
+      '/vault audit &lt;agent&gt; — unified view of an agent\'s vault access',
       '',
       'Your passphrase is cached in memory for 30 min after first use.',
     ].join('\n'), { html: true })
     return
   }
 
+  // Issue #969 P2c: /vault audit <agent> — unified view of an agent's
+  // vault access (grants + cron-declared schedule.secrets[]). Single
+  // mental model for operators auditing the agent's credential surface.
+  if (sub === 'audit') {
+    const targetAgent = args[1]
+    if (!targetAgent) {
+      await switchroomReply(ctx, 'Usage: /vault audit &lt;agent&gt;', { html: true })
+      return
+    }
+    // Sanity-check the agent name shape — same charset constraint as
+    // assertSafeAgentName, applied here so we don't blindly shell-out
+    // or read filesystem paths derived from user input.
+    if (!/^[a-z][a-z0-9-]{0,62}$/i.test(targetAgent)) {
+      await switchroomReply(ctx, '⚠️ Invalid agent name shape.', { html: true })
+      return
+    }
+
+    // 1. Fetch grants from broker, filtered to this agent.
+    const grantsResult = await listGrantsViaBroker(targetAgent)
+    let readGrants: Array<{ id: string; keys: string[]; expiresAt: number | null }> = []
+    let writeGrants: Array<{ id: string; keys: string[]; expiresAt: number | null }> = []
+    let grantsError: string | null = null
+    if (grantsResult.kind === 'unreachable') {
+      grantsError = 'broker unreachable'
+    } else if (grantsResult.kind === 'error') {
+      grantsError = grantsResult.msg
+    } else {
+      for (const g of grantsResult.grants) {
+        if (g.key_allow.length > 0) {
+          readGrants.push({ id: g.id, keys: g.key_allow, expiresAt: g.expires_at })
+        }
+        if (g.write_allow && g.write_allow.length > 0) {
+          writeGrants.push({ id: g.id, keys: g.write_allow, expiresAt: g.expires_at })
+        }
+      }
+    }
+
+    // 2. Load schedule[i].secrets[] from local config for this agent.
+    let cronEntries: Array<{ index: number; secrets: string[]; cron?: string }> = []
+    let configError: string | null = null
+    try {
+      const cfg = loadSwitchroomConfig()
+      const agentCfg = cfg.agents?.[targetAgent]
+      if (!agentCfg) {
+        configError = `agent '${targetAgent}' not found in switchroom.yaml`
+      } else {
+        const schedule = (agentCfg as { schedule?: Array<{ secrets?: string[]; cron?: string }> }).schedule
+        if (Array.isArray(schedule)) {
+          schedule.forEach((entry, i) => {
+            if (entry?.secrets && Array.isArray(entry.secrets) && entry.secrets.length > 0) {
+              cronEntries.push({
+                index: i,
+                secrets: entry.secrets,
+                cron: typeof entry.cron === 'string' ? entry.cron : undefined,
+              })
+            }
+          })
+        }
+      }
+    } catch (err) {
+      configError = (err instanceof Error ? err.message : String(err))
+    }
+
+    // 3. Compose the rendered audit view.
+    const lines: string[] = [`<b>🔐 ${escapeHtmlForTg(targetAgent)} — vault access</b>`, '']
+
+    if (grantsError) {
+      lines.push(`<i>Grants: ⚠️ ${escapeHtmlForTg(grantsError)}</i>`)
+      lines.push('')
+    } else {
+      lines.push('<b>Read grants:</b>')
+      if (readGrants.length === 0) {
+        lines.push('  <i>none</i>')
+      } else {
+        for (const g of readGrants) {
+          const expiry = g.expiresAt
+            ? new Date(g.expiresAt * 1000).toISOString().slice(0, 10)
+            : 'no expiry'
+          const keysJoined = g.keys.join(', ')
+          lines.push(`  <code>${escapeHtmlForTg(g.id)}</code> · ${escapeHtmlForTg(keysJoined)} · expires ${expiry}`)
+        }
+      }
+      lines.push('')
+      lines.push('<b>Write grants:</b>')
+      if (writeGrants.length === 0) {
+        lines.push('  <i>none</i>')
+      } else {
+        for (const g of writeGrants) {
+          const expiry = g.expiresAt
+            ? new Date(g.expiresAt * 1000).toISOString().slice(0, 10)
+            : 'no expiry'
+          const keysJoined = g.keys.join(', ')
+          lines.push(`  <code>${escapeHtmlForTg(g.id)}</code> · ${escapeHtmlForTg(keysJoined)} · expires ${expiry}`)
+        }
+      }
+      lines.push('')
+    }
+
+    lines.push('<b>Cron-declared secrets:</b>')
+    if (configError) {
+      lines.push(`  <i>⚠️ ${escapeHtmlForTg(configError)}</i>`)
+    } else if (cronEntries.length === 0) {
+      lines.push('  <i>none</i>')
+    } else {
+      for (const entry of cronEntries) {
+        const cronLabel = entry.cron ? ` (<code>${escapeHtmlForTg(entry.cron)}</code>)` : ''
+        const keysJoined = entry.secrets.join(', ')
+        lines.push(`  schedule[${entry.index}]${cronLabel}: ${escapeHtmlForTg(keysJoined)}`)
+      }
+    }
+    lines.push('')
+    lines.push(
+      `<i>Summary: ${readGrants.length} read grant${readGrants.length === 1 ? '' : 's'}, ` +
+      `${writeGrants.length} write grant${writeGrants.length === 1 ? '' : 's'}, ` +
+      `${cronEntries.length} cron entr${cronEntries.length === 1 ? 'y' : 'ies'}.</i>`,
+    )
+
+    await switchroomReply(ctx, lines.join('\n'), { html: true })
+    return
+  }
+
   // Issue #228: /vault grants [agent] — list active grants grouped by agent
   if (sub === 'grants') {
     const agentFilter = args[1]  // optional agent name filter
@@ -8955,6 +9434,15 @@ bot.on('callback_query:data', async ctx => {
     return
   }
 
+  // Issue #969 P1a: agent-initiated vault-save approval card.
+  // vrs:save:<stageId>     — write the staged value, edit card to success
+  // vrs:discard:<stageId>  — drop the staged value, edit card to discarded
+  // vrs:rename:<stageId>   — prompt for a new key name, then resume
+  if (data.startsWith('vrs:')) {
+    await handleVaultRequestSaveCallback(ctx, data)
+    return
+  }
+
   // ask_user callback (#574). aq:<idx>:<askId>. Same authorization
   // gate as permission buttons — only allowFrom users can answer.
   // Tapped option resolves the originating ask_user tool call's