switchroom 0.5.0

package/telegram-plugin/tests/update-factory.ts

@@ -0,0 +1,305 @@
+/**
+ * Typed factories for Telegram Update objects, used by tests that drive
+ * a grammy bot via `bot.handleUpdate(update)`.
+ *
+ * Replaces raw-JSON update construction scattered across test files.
+ * Every builder takes a small `overrides` object so tests only have to
+ * specify the fields that matter for the behaviour under test; the rest
+ * gets sensible realistic defaults (date, message_id sequencing, etc).
+ *
+ * Shapes follow https://core.telegram.org/bots/api. `as` casts to grammy
+ * types are centralized here so the rest of the suite stays typed.
+ */
+
+import type { Update } from 'grammy/types'
+
+let updateIdCounter = 1000
+let messageIdCounter = 2000
+
+export function resetUpdateCounters(updateId = 1000, messageId = 2000): void {
+  updateIdCounter = updateId
+  messageIdCounter = messageId
+}
+
+export interface UserLike {
+  id: number
+  username?: string
+  first_name?: string
+  is_bot?: boolean
+}
+
+export interface ChatLike {
+  id: number
+  type: 'private' | 'group' | 'supergroup' | 'channel'
+  title?: string
+  username?: string
+  is_forum?: boolean
+}
+
+const DEFAULT_USER: UserLike = { id: 777, username: 'test_user', first_name: 'Test' }
+const DEFAULT_PRIVATE_CHAT: ChatLike = { id: 777, type: 'private' }
+const DEFAULT_FORUM_CHAT: ChatLike = {
+  id: -100123456789,
+  type: 'supergroup',
+  title: 'Test Forum',
+  is_forum: true,
+}
+
+function nowSec(): number { return Math.floor(Date.now() / 1000) }
+
+/** Build a text-message Update. */
+export function makeMessageUpdate(opts: {
+  text: string
+  chat?: Partial<ChatLike>
+  from?: Partial<UserLike>
+  message_thread_id?: number
+  is_topic_message?: boolean
+  reply_to_message?: { message_id: number; from?: Partial<UserLike>; text?: string }
+  entities?: Array<{ type: string; offset: number; length: number }>
+  update_id?: number
+  message_id?: number
+}): Update {
+  const chat: ChatLike = { ...DEFAULT_PRIVATE_CHAT, ...opts.chat }
+  const from: UserLike = { ...DEFAULT_USER, ...opts.from }
+  const message_id = opts.message_id ?? messageIdCounter++
+  const update_id = opts.update_id ?? updateIdCounter++
+
+  const reply_to_message = opts.reply_to_message
+    ? {
+        message_id: opts.reply_to_message.message_id,
+        chat,
+        from: { ...DEFAULT_USER, ...opts.reply_to_message.from },
+        date: nowSec(),
+        text: opts.reply_to_message.text ?? '',
+      }
+    : undefined
+
+  return {
+    update_id,
+    message: {
+      message_id,
+      chat,
+      from,
+      date: nowSec(),
+      text: opts.text,
+      ...(opts.message_thread_id != null ? { message_thread_id: opts.message_thread_id } : {}),
+      ...(opts.is_topic_message === true ? { is_topic_message: true } : {}),
+      ...(opts.entities ? { entities: opts.entities } : {}),
+      ...(reply_to_message ? { reply_to_message } : {}),
+    },
+  } as unknown as Update
+}
+
+/** Build a message in a forum topic. */
+export function makeTopicMessageUpdate(opts: {
+  text: string
+  message_thread_id: number
+  chat?: Partial<ChatLike>
+  from?: Partial<UserLike>
+}): Update {
+  return makeMessageUpdate({
+    ...opts,
+    chat: { ...DEFAULT_FORUM_CHAT, ...opts.chat },
+    is_topic_message: true,
+  })
+}
+
+/** Build a callback_query Update (inline button tap). */
+export function makeCallbackQueryUpdate(opts: {
+  data: string
+  chat?: Partial<ChatLike>
+  from?: Partial<UserLike>
+  inline_message_id?: string
+  message_id?: number
+  update_id?: number
+}): Update {
+  const from: UserLike = { ...DEFAULT_USER, ...opts.from }
+  const chat: ChatLike = { ...DEFAULT_PRIVATE_CHAT, ...opts.chat }
+  const update_id = opts.update_id ?? updateIdCounter++
+  const message_id = opts.message_id ?? messageIdCounter++
+  return {
+    update_id,
+    callback_query: {
+      id: 'cbq-' + update_id,
+      from,
+      chat_instance: 'inst-' + update_id,
+      data: opts.data,
+      ...(opts.inline_message_id
+        ? { inline_message_id: opts.inline_message_id }
+        : {
+            message: {
+              message_id,
+              chat,
+              date: nowSec(),
+              text: '',
+            },
+          }),
+    },
+  } as unknown as Update
+}
+
+/** Build a my_chat_member Update (bot added/removed). */
+export function makeMyChatMemberUpdate(opts: {
+  chat?: Partial<ChatLike>
+  from?: Partial<UserLike>
+  oldStatus?: 'left' | 'kicked' | 'member' | 'administrator' | 'creator'
+  newStatus?: 'left' | 'kicked' | 'member' | 'administrator' | 'creator'
+  update_id?: number
+}): Update {
+  const chat: ChatLike = { ...DEFAULT_FORUM_CHAT, ...opts.chat }
+  const from: UserLike = { ...DEFAULT_USER, ...opts.from }
+  const update_id = opts.update_id ?? updateIdCounter++
+  const bot: UserLike = { id: 999, username: 'test_bot', first_name: 'TestBot', is_bot: true }
+  return {
+    update_id,
+    my_chat_member: {
+      chat,
+      from,
+      date: nowSec(),
+      old_chat_member: {
+        user: bot,
+        status: opts.oldStatus ?? 'left',
+      },
+      new_chat_member: {
+        user: bot,
+        status: opts.newStatus ?? 'administrator',
+      },
+    },
+  } as unknown as Update
+}
+
+/** Build a photo-attachment Update. */
+export function makePhotoUpdate(opts: {
+  caption?: string
+  chat?: Partial<ChatLike>
+  from?: Partial<UserLike>
+  file_id?: string
+  file_size?: number
+}): Update {
+  const chat: ChatLike = { ...DEFAULT_PRIVATE_CHAT, ...opts.chat }
+  const from: UserLike = { ...DEFAULT_USER, ...opts.from }
+  const update_id = updateIdCounter++
+  const message_id = messageIdCounter++
+  const file_id = opts.file_id ?? 'AgACAgIAAx0C-photo-' + update_id
+  const file_size = opts.file_size ?? 54321
+  return {
+    update_id,
+    message: {
+      message_id,
+      chat,
+      from,
+      date: nowSec(),
+      ...(opts.caption ? { caption: opts.caption } : {}),
+      photo: [
+        { file_id, file_unique_id: 'unique-' + file_id, file_size, width: 800, height: 600 },
+      ],
+    },
+  } as unknown as Update
+}
+
+/** Build an `edited_message` Update — user edits an existing message. */
+export function makeEditedMessageUpdate(opts: {
+  message_id: number
+  text: string
+  chat?: Partial<ChatLike>
+  from?: Partial<UserLike>
+  message_thread_id?: number
+  /** Original send time. Defaults to "30 seconds ago" so edit_date > date stays plausible. */
+  date?: number
+  /** Edit time. Defaults to now. */
+  edit_date?: number
+  update_id?: number
+}): Update {
+  const chat: ChatLike = { ...DEFAULT_PRIVATE_CHAT, ...opts.chat }
+  const from: UserLike = { ...DEFAULT_USER, ...opts.from }
+  const update_id = opts.update_id ?? updateIdCounter++
+  const date = opts.date ?? nowSec() - 30
+  const edit_date = opts.edit_date ?? nowSec()
+  return {
+    update_id,
+    edited_message: {
+      message_id: opts.message_id,
+      chat,
+      from,
+      date,
+      edit_date,
+      text: opts.text,
+      ...(opts.message_thread_id != null ? { message_thread_id: opts.message_thread_id } : {}),
+    },
+  } as unknown as Update
+}
+
+/**
+ * Build a `message_reaction` Update — a user adds/removes a reaction
+ * to a message. Telegram delivers these only if the bot has reactions
+ * subscribed (allowed_updates includes "message_reaction").
+ *
+ * Shape: `old_reaction` and `new_reaction` are arrays of ReactionType
+ * objects (`{ type: 'emoji', emoji: '👍' }` for standard, or
+ * `{ type: 'custom_emoji', custom_emoji_id: '...' }` for custom).
+ *
+ * Common usage: a user reacts with 👍 (old=[], new=[👍]) or removes
+ * the reaction (old=[👍], new=[]).
+ */
+export function makeMessageReactionUpdate(opts: {
+  message_id: number
+  /** Emoji currently NOT yet on the message (transitioning to). Default: 👍. */
+  newEmoji?: string | null
+  /** Emoji previously on the message. Default: null (none). */
+  oldEmoji?: string | null
+  chat?: Partial<ChatLike>
+  user?: Partial<UserLike>
+  update_id?: number
+}): Update {
+  const chat: ChatLike = { ...DEFAULT_PRIVATE_CHAT, ...opts.chat }
+  const user: UserLike = { ...DEFAULT_USER, ...opts.user }
+  const update_id = opts.update_id ?? updateIdCounter++
+  const oldEmoji = opts.oldEmoji ?? null
+  const newEmoji = opts.newEmoji === undefined ? '👍' : opts.newEmoji
+  const old_reaction = oldEmoji == null ? [] : [{ type: 'emoji', emoji: oldEmoji }]
+  const new_reaction = newEmoji == null ? [] : [{ type: 'emoji', emoji: newEmoji }]
+  return {
+    update_id,
+    message_reaction: {
+      chat,
+      message_id: opts.message_id,
+      user,
+      date: nowSec(),
+      old_reaction,
+      new_reaction,
+    },
+  } as unknown as Update
+}
+
+/** Build a document-attachment Update. */
+export function makeDocumentUpdate(opts: {
+  file_name: string
+  mime_type?: string
+  chat?: Partial<ChatLike>
+  from?: Partial<UserLike>
+  file_id?: string
+  file_size?: number
+}): Update {
+  const chat: ChatLike = { ...DEFAULT_PRIVATE_CHAT, ...opts.chat }
+  const from: UserLike = { ...DEFAULT_USER, ...opts.from }
+  const update_id = updateIdCounter++
+  const message_id = messageIdCounter++
+  const file_id = opts.file_id ?? 'BQACAgIAAx0C-doc-' + update_id
+  const file_size = opts.file_size ?? 1024
+  return {
+    update_id,
+    message: {
+      message_id,
+      chat,
+      from,
+      date: nowSec(),
+      document: {
+        file_id,
+        file_unique_id: 'unique-' + file_id,
+        file_name: opts.file_name,
+        mime_type: opts.mime_type ?? 'application/octet-stream',
+        file_size,
+      },
+    },
+  } as unknown as Update
+}

package/telegram-plugin/tests/vault-grant-wizard.test.ts

@@ -0,0 +1,84 @@
+/**
+ * Structural tests for the /vault grant inline-keyboard wizard added in #227.
+ *
+ * Why structural: gateway/gateway.ts and server.ts do not export the bot
+ * command handlers — pure-functional invocation would require a full
+ * Grammy/Bot harness. We pin the behaviour at the file level with grep
+ * against the source so a regression in either file is caught.
+ *
+ * Both surfaces are tested in parallel: server.ts (monolith polling
+ * mode) and gateway/gateway.ts (split mode). The gateway port landed
+ * in PR #262; this file's gateway describe-block was added in
+ * follow-up #265.
+ */
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// Resolve paths relative to the repo root, derived from this test file's
+// own location, instead of process.cwd() — which is brittle across run
+// modes (vitest from repo root vs `bun test` from telegram-plugin/ vs
+// CI's `cd telegram-plugin && bun test`). The repo root is two levels
+// up from this file (telegram-plugin/tests/vault-grant-wizard.test.ts).
+const TEST_DIR = (() => {
+  try {
+    return resolve(fileURLToPath(import.meta.url), '..')
+  } catch {
+    return resolve('.')
+  }
+})()
+const REPO_ROOT = resolve(TEST_DIR, '..', '..')
+
+function readSrc(rel: string): string {
+  return readFileSync(join(REPO_ROOT, rel), 'utf8')
+}
+
+// #235 Wave 3 F4: server.ts monolith removed; assertions below now live
+// only against gateway.ts (the single source of truth for the wizard).
+// Pre-removal there was a parallel server.ts describe block here; see
+// `telegram-plugin/docs/gateway-server-split.md` for the F4 cleanup notes.
+
+describe('/vault grant inline-keyboard wizard — gateway (#227, #262, #265)', () => {
+  const gatewaySrc = readSrc('telegram-plugin/gateway/gateway.ts')
+
+  it('gateway.ts: dispatches /vault grant to the wizard entry', () => {
+    expect(gatewaySrc).toMatch(/\/vault grant/i)
+    expect(gatewaySrc).toContain("kind: 'grant-wizard'")
+  })
+
+  it('gateway.ts: wizard state-machine has step transitions', () => {
+    expect(gatewaySrc).toContain('grantWizardStep3')
+    expect(gatewaySrc).toContain('grantWizardConfirm')
+    expect(gatewaySrc).toContain('executeGrantWizard')
+  })
+
+  it('gateway.ts: wizard callback prefix vg: is registered', () => {
+    expect(gatewaySrc).toContain('vg:')
+  })
+
+  it('gateway.ts: expired-wizard sessions reply with a clear error', () => {
+    expect(gatewaySrc).toMatch(/Wizard session expired|Run \/vault grant to start again/i)
+  })
+
+  it('gateway.ts: custom-duration text-reply path exists', () => {
+    expect(gatewaySrc).toContain('awaitingCustomDuration')
+  })
+
+  it('gateway.ts: agent name validated before path join (#265 item 1)', () => {
+    const slice = gatewaySrc.slice(
+      gatewaySrc.indexOf('async function executeGrantWizard'),
+      gatewaySrc.indexOf('async function executeGrantWizard') + 4000,
+    )
+    expect(slice).toMatch(/assertSafeAgentName\(\s*state\.agent/)
+  })
+
+  it('gateway.ts: keys-continue empty branch can show its toast (#265 item 2)', () => {
+    const wizardSlice = gatewaySrc.slice(
+      gatewaySrc.indexOf("// #227 grant wizard callbacks"),
+      gatewaySrc.indexOf("// #227 grant wizard callbacks") + 6000,
+    )
+    expect(wizardSlice).toContain("Select at least one key.")
+    expect(wizardSlice).toContain('const ackSilently')
+  })
+})

package/telegram-plugin/tests/vault-grants-revoke.test.ts

@@ -0,0 +1,265 @@
+/**
+ * Structural tests for the /vault grants list + revoke implementation
+ * added in issue #228.
+ *
+ * Why structural: gateway/gateway.ts and server.ts do not export the bot
+ * command handlers, so pure-functional invocation would require a full
+ * Grammy/Bot harness. The broker client functions (listGrantsViaBroker,
+ * revokeGrantViaBroker) are separately unit-tested in
+ * src/vault/broker/server-grants.test.ts. What we pin here is:
+ *
+ *   1. Both server.ts and gateway/gateway.ts import listGrantsViaBroker and
+ *      revokeGrantViaBroker from the broker client module.
+ *   2. The /vault command handler contains a `grants` branch that calls
+ *      listGrantsViaBroker.
+ *   3. The grants list renders an inline keyboard with vg:revoke:<id> buttons.
+ *   4. A callback_query handler intercepts vg: prefixed data in both files.
+ *   5. The revoke callback handler invokes revokeGrantViaBroker on vg:confirm.
+ *   6. The confirmation flow uses an intermediate vg:confirm/<vg:cancel> card
+ *      (not immediate revoke on first tap) — two-step confirmation.
+ *   7. /vault grants <agent> filter form parses the agent argument.
+ *   8. Help text in both files mentions /vault grants.
+ *   9. welcome-text.ts /vault section lists the grants subcommand.
+ *
+ * Each assertion covers BOTH server.ts (monolith polling mode) and
+ * gateway/gateway.ts (persistent gateway mode) so a regression in either
+ * file is caught.
+ */
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join, dirname } from 'node:path'
+
+const __dir = dirname(fileURLToPath(import.meta.url))
+const pluginDir = join(__dir, '..')
+
+const gatewaySrc = readFileSync(join(pluginDir, 'gateway', 'gateway.ts'), 'utf8')
+
+// ─── helpers ─────────────────────────────────────────────────────────────────
+
+/** Slice the source from the first occurrence of `marker` for `len` chars. */
+function sliceFrom(src: string, marker: string, len = 4000): string {
+  const idx = src.indexOf(marker)
+  if (idx === -1) return ''
+  return src.slice(idx, idx + len)
+}
+
+/** Returns the portion of `src` inside the `/vault` bot.command() handler. */
+function vaultHandlerBlock(src: string): string {
+  const start = src.indexOf("bot.command('vault'")
+  if (start === -1) return ''
+  const nextCmd = src.indexOf('\nbot.command(', start + 1)
+  const end = nextCmd === -1 ? start + 12000 : nextCmd
+  return src.slice(start, end)
+}
+
+// ─── broker client imports ────────────────────────────────────────────────────
+
+describe('/vault grants #228 — broker client imports', () => {
+  for (const [label, src] of [['gateway.ts', gatewaySrc]] as const) {
+    it(`${label} imports listGrantsViaBroker`, () => {
+      expect(src).toMatch(/listGrantsViaBroker/)
+    })
+
+    it(`${label} imports revokeGrantViaBroker`, () => {
+      expect(src).toMatch(/revokeGrantViaBroker/)
+    })
+  }
+})
+
+// ─── /vault grants dispatcher ────────────────────────────────────────────────
+
+describe('/vault grants — dispatcher entry', () => {
+  for (const [label, src] of [['gateway.ts', gatewaySrc]] as const) {
+    const block = vaultHandlerBlock(src)
+
+    it(`${label}: has a grants branch inside the vault handler`, () => {
+      expect(block).toMatch(/sub === ['"]grants['"]/)
+    })
+
+    it(`${label}: grants branch calls listGrantsViaBroker`, () => {
+      // Use a larger slice (2000) — the keyboard.text('vg:revoke') call comes ~1580 chars in
+      const grantsBranch = sliceFrom(block, "sub === 'grants'", 2000)
+      expect(grantsBranch).toMatch(/listGrantsViaBroker\(/)
+    })
+  }
+})
+
+// ─── /vault grants — list rendering ──────────────────────────────────────────
+
+describe('/vault grants — list rendering wires to list_grants', () => {
+  for (const [label, src] of [['gateway.ts', gatewaySrc]] as const) {
+    const block = vaultHandlerBlock(src)
+
+    it(`${label}: renders grouped grants with agent names as headers`, () => {
+      const grantsBranch = sliceFrom(block, "sub === 'grants'", 2000)
+      // Groups grants by agent_slug and renders agent name as a bold header
+      expect(grantsBranch).toMatch(/agent_slug/)
+      expect(grantsBranch).toMatch(/byAgent/)
+    })
+
+    it(`${label}: attaches inline keyboard with vg:revoke buttons`, () => {
+      // keyboard.text('Revoke', 'vg:revoke:<id>') is ~1580 chars into the grants branch
+      const grantsBranch = sliceFrom(block, "sub === 'grants'", 2000)
+      expect(grantsBranch).toMatch(/vg:revoke:/)
+      expect(grantsBranch).toMatch(/InlineKeyboard/)
+    })
+
+    it(`${label}: handles empty grants list with friendly message`, () => {
+      const grantsBranch = sliceFrom(block, "sub === 'grants'", 2000)
+      expect(grantsBranch).toMatch(/No active grants/)
+    })
+
+    it(`${label}: handles broker unreachable with error message`, () => {
+      const grantsBranch = sliceFrom(block, "sub === 'grants'", 2000)
+      expect(grantsBranch).toMatch(/unreachable/i)
+    })
+  }
+})
+
+// ─── /vault grants <agent> — filter form ─────────────────────────────────────
+
+describe('/vault grants <agent> — agent filter argument', () => {
+  for (const [label, src] of [['gateway.ts', gatewaySrc]] as const) {
+    const block = vaultHandlerBlock(src)
+
+    it(`${label}: parses optional agent argument from args`, () => {
+      const grantsBranch = sliceFrom(block, "sub === 'grants'", 2000)
+      // Agent filter is read from args[1]
+      expect(grantsBranch).toMatch(/args\[1\]/)
+    })
+
+    it(`${label}: passes agentFilter to listGrantsViaBroker`, () => {
+      const grantsBranch = sliceFrom(block, "sub === 'grants'", 2000)
+      expect(grantsBranch).toMatch(/listGrantsViaBroker\(agentFilter\)/)
+    })
+
+    it(`${label}: filter note appears in empty-grants message when agent filter is set`, () => {
+      const grantsBranch = sliceFrom(block, "sub === 'grants'", 2000)
+      expect(grantsBranch).toMatch(/filterNote/)
+    })
+  }
+})
+
+// ─── vg: callback dispatch ────────────────────────────────────────────────────
+
+describe('vg: callback query handler exists', () => {
+  for (const [label, src] of [['gateway.ts', gatewaySrc]] as const) {
+    it(`${label}: has a handler block that checks data.startsWith('vg:')`, () => {
+      expect(src).toMatch(/data\.startsWith\(['"]vg:['"]\)/)
+    })
+
+    it(`${label}: has a revokeMatch handler for vg:revoke: prefix`, () => {
+      // Use 'const revokeMatch' as a specific code marker (not a comment)
+      expect(src).toMatch(/const revokeMatch = \/\^vg:revoke:/)
+    })
+
+    it(`${label}: has a confirmMatch handler for vg:confirm: prefix`, () => {
+      expect(src).toMatch(/const confirmMatch = \/\^vg:confirm:/)
+    })
+
+    it(`${label}: has a cancelMatch handler for vg:cancel: prefix`, () => {
+      expect(src).toMatch(/const cancelMatch = \/\^vg:cancel:/)
+    })
+  }
+})
+
+// ─── revoke callback — invokes revokeGrantViaBroker ──────────────────────────
+
+describe('vg:confirm callback invokes revokeGrantViaBroker', () => {
+  for (const [label, src] of [['gateway.ts', gatewaySrc]] as const) {
+    it(`${label}: vg:confirm branch calls revokeGrantViaBroker with the grant ID`, () => {
+      // Use 'const confirmMatch =' as the unique code marker (avoids comment occurrences)
+      const confirmArea = sliceFrom(src, 'const confirmMatch = /^vg:confirm:', 800)
+      expect(confirmArea).toMatch(/revokeGrantViaBroker\(grantId\)/)
+    })
+
+    it(`${label}: vg:confirm success replies with revoked confirmation text`, () => {
+      const confirmArea = sliceFrom(src, 'const confirmMatch = /^vg:confirm:', 800)
+      expect(confirmArea).toMatch(/revoked|Revoked/i)
+    })
+
+    it(`${label}: vg:confirm handles broker unreachable`, () => {
+      const confirmArea = sliceFrom(src, 'const confirmMatch = /^vg:confirm:', 800)
+      expect(confirmArea).toMatch(/unreachable/i)
+    })
+
+    it(`${label}: vg:confirm handles error result from broker`, () => {
+      const confirmArea = sliceFrom(src, 'const confirmMatch = /^vg:confirm:', 800)
+      expect(confirmArea).toMatch(/Revoke failed/i)
+    })
+  }
+})
+
+// ─── two-step confirmation flow ───────────────────────────────────────────────
+
+describe('revoke flow uses two-step confirmation (no immediate revoke on first tap)', () => {
+  for (const [label, src] of [['gateway.ts', gatewaySrc]] as const) {
+    it(`${label}: vg:revoke tap shows confirmation card, not immediate revoke`, () => {
+      // Use 'const revokeMatch =' as the unique code marker
+      const revokeArea = sliceFrom(src, 'const revokeMatch = /^vg:revoke:', 1500)
+      // Must show a confirmation card with confirm/cancel buttons
+      expect(revokeArea).toMatch(/Confirm Revoke|confirm.*revoke/i)
+      // Must NOT call revokeGrantViaBroker in the first-tap handler
+      // (revokeGrantViaBroker is only called from confirmMatch, which appears later)
+      const firstTapArea = sliceFrom(src, 'const revokeMatch = /^vg:revoke:', 900)
+      expect(firstTapArea).not.toMatch(/revokeGrantViaBroker/)
+    })
+
+    it(`${label}: confirmation card shows vg:confirm and vg:cancel options`, () => {
+      const revokeArea = sliceFrom(src, 'const revokeMatch = /^vg:revoke:', 1500)
+      expect(revokeArea).toMatch(/vg:confirm:/)
+      expect(revokeArea).toMatch(/vg:cancel:/)
+    })
+  }
+})
+
+// ─── vg:cancel — dismiss without revoke ──────────────────────────────────────
+
+describe('vg:cancel dismisses without revoking', () => {
+  for (const [label, src] of [['gateway.ts', gatewaySrc]] as const) {
+    it(`${label}: vg:cancel does NOT call revokeGrantViaBroker`, () => {
+      const cancelArea = sliceFrom(src, 'const cancelMatch = /^vg:cancel:', 500)
+      expect(cancelArea).not.toMatch(/revokeGrantViaBroker/)
+    })
+
+    it(`${label}: vg:cancel clears the inline keyboard`, () => {
+      const cancelArea = sliceFrom(src, 'const cancelMatch = /^vg:cancel:', 500)
+      expect(cancelArea).toMatch(/editMessageReplyMarkup|inline_keyboard/)
+    })
+  }
+})
+
+// ─── help text ───────────────────────────────────────────────────────────────
+
+describe('/vault help text includes grants subcommand', () => {
+  for (const [label, src] of [['gateway.ts', gatewaySrc]] as const) {
+    const block = vaultHandlerBlock(src)
+
+    it(`${label}: /vault help lists grants subcommand`, () => {
+      const helpBranch = sliceFrom(block, "sub === 'help'", 1200)
+      expect(helpBranch).toMatch(/grants/)
+    })
+
+    it(`${label}: grants help entry mentions agent filter or 'tap to revoke'`, () => {
+      const helpBranch = sliceFrom(block, "sub === 'help'", 1200)
+      expect(helpBranch).toMatch(/revoke|agent/i)
+    })
+  }
+})
+
+// ─── switchroomHelpText (welcome-text.ts) ────────────────────────────────────
+
+describe('switchroomHelpText — /vault grants entry', () => {
+  it('lists vault grants as a separate entry', async () => {
+    const { switchroomHelpText } = await import('../welcome-text.js')
+    const out = switchroomHelpText('assistant')
+    expect(out).toMatch(/vault.*grants/i)
+  })
+
+  it('grants entry mentions revoke capability', async () => {
+    const { switchroomHelpText } = await import('../welcome-text.js')
+    const out = switchroomHelpText('assistant')
+    expect(out).toMatch(/revoke/i)
+  })
+})