switchroom 0.7.15 → 0.10.0

package/telegram-plugin/tests/boot-card-silent-on-operator.test.ts

@@ -0,0 +1,103 @@
+/**
+ * Pin the contract: the boot card silences its Telegram notification
+ * (passes `disable_notification: true` to `sendMessage`) iff the
+ * restart marker's `reason` text starts with `"operator:"`.
+ *
+ * Background: every agent in the fleet posts a boot card after a
+ * `switchroom update`. Without this gate the operator gets N push
+ * notifications for one planned redeploy — once-per-agent on every
+ * routine update. User-initiated restarts (`/restart` from chat,
+ * `cli: switchroom restart`) and unplanned events (crash, fresh) still
+ * notify because the user asked for them or needs to know something
+ * went wrong.
+ *
+ * The toggle is keyed on the reason TEXT (`opts.restartReasonDetail`),
+ * not the RestartReason enum, because the enum collapses all
+ * marker-bearing restarts into `'graceful'` — losing the operator-vs-
+ * user distinction. The reason text is the source of truth for who
+ * triggered the restart.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { startBootCard } from '../gateway/boot-card.js'
+import type { BotApiForBootCard } from '../gateway/boot-card.js'
+
+/** Capture sendMessage opts for assertion. editMessageText is a no-op. */
+function makeCapturingBot(): {
+  bot: BotApiForBootCard
+  sends: Array<{ chatId: string; text: string; opts: Record<string, unknown> }>
+} {
+  const sends: Array<{ chatId: string; text: string; opts: Record<string, unknown> }> = []
+  const bot: BotApiForBootCard = {
+    sendMessage: async (chatId, text, opts) => {
+      sends.push({ chatId, text, opts: opts ?? {} })
+      return { message_id: 42 }
+    },
+    editMessageText: async () => ({}),
+  }
+  return { bot, sends }
+}
+
+/** Common opts — only the reason-detail varies per test. */
+function mkOpts(overrides: { restartReasonDetail?: string; restartReason?: 'planned' | 'graceful' | 'crash' | 'fresh' } = {}) {
+  return {
+    agentName: 'TestAgent',
+    agentSlug: 'test-agent',
+    version: 'v0.0.0-test',
+    agentDir: '/tmp/test-agent',
+    gatewayInfo: { pid: 1, startedAtMs: Date.now() },
+    restartReason: overrides.restartReason ?? 'graceful' as const,
+    restartReasonDetail: overrides.restartReasonDetail,
+    // Disable the live loop + probes — we only want the initial sendMessage.
+    agentLiveWindowMs: 0,
+    settleWindowMs: 1_000_000,
+  }
+}
+
+describe('boot card — silent-on-operator-reason', () => {
+  it('passes disable_notification: true when restartReasonDetail starts with "operator:"', async () => {
+    const { bot, sends } = makeCapturingBot()
+    await startBootCard('chat1', undefined, bot, mkOpts({ restartReasonDetail: 'operator: switchroom update' }))
+    expect(sends).toHaveLength(1)
+    expect(sends[0]!.opts.disable_notification).toBe(true)
+  })
+
+  it('omits disable_notification when restartReasonDetail starts with "user:"', async () => {
+    const { bot, sends } = makeCapturingBot()
+    await startBootCard('chat1', undefined, bot, mkOpts({ restartReasonDetail: 'user: /restart from chat' }))
+    expect(sends).toHaveLength(1)
+    expect(sends[0]!.opts.disable_notification).toBeUndefined()
+  })
+
+  it('omits disable_notification when restartReasonDetail starts with "cli:"', async () => {
+    const { bot, sends } = makeCapturingBot()
+    await startBootCard('chat1', undefined, bot, mkOpts({ restartReasonDetail: 'cli: switchroom restart' }))
+    expect(sends).toHaveLength(1)
+    expect(sends[0]!.opts.disable_notification).toBeUndefined()
+  })
+
+  it('omits disable_notification when restartReasonDetail is undefined (crash / fresh path)', async () => {
+    const { bot, sends } = makeCapturingBot()
+    await startBootCard('chat1', undefined, bot, mkOpts({ restartReason: 'crash' }))
+    expect(sends).toHaveLength(1)
+    expect(sends[0]!.opts.disable_notification).toBeUndefined()
+  })
+
+  it('omits disable_notification when restartReasonDetail is empty string', async () => {
+    const { bot, sends } = makeCapturingBot()
+    await startBootCard('chat1', undefined, bot, mkOpts({ restartReasonDetail: '' }))
+    expect(sends).toHaveLength(1)
+    expect(sends[0]!.opts.disable_notification).toBeUndefined()
+  })
+
+  it('matches the "operator:" prefix exactly — "operator-ish" should NOT silence', async () => {
+    // Defence against future operator-side reasons that don't actually
+    // want silent — confirms we're matching the prefix-with-colon shape,
+    // not a fuzzy contains.
+    const { bot, sends } = makeCapturingBot()
+    await startBootCard('chat1', undefined, bot, mkOpts({ restartReasonDetail: 'operator-ish: rolled over' }))
+    expect(sends).toHaveLength(1)
+    // 'operator-ish:' does NOT start with 'operator:' so still notifies.
+    expect(sends[0]!.opts.disable_notification).toBeUndefined()
+  })
+})

package/telegram-plugin/tests/boot-probes.test.ts

@@ -3,15 +3,16 @@
  *
  * Covers:
  *   - #208: probeAgentProcess — deactivating → 🟡 (not 🔴), re-probe loop
- *   - #210: probeQuota — 429 → ok-with-note + 30 s cache
+ *   - #1163: probeQuota — uses /v1/messages headers path (was /api/oauth/usage)
  */
 
 import { describe, it, expect, beforeEach, afterEach } from 'bun:test'
-import { mkdtempSync, rmSync } from 'fs'
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'fs'
 import { tmpdir } from 'os'
 import { join } from 'path'
 
 import {
+  probeAccount,
   probeAgentProcess,
   probeScheduler,
   probeBroker,
@@ -242,7 +243,7 @@ describe('probeAgentProcess — #208: re-probe loop resolves transient', () => {
   })
 })
 
-// ── #210: probeQuota — 429 → ok-with-note + 30s cache ────────────────────
+// ── #1163: probeQuota — /v1/messages headers path ─────────────────────────
 
 import { writeFileSync, mkdirSync } from 'fs'
 import { writeQuotaCache } from '../gateway/quota-cache.js'
@@ -272,20 +273,38 @@ afterEach(() => {
   rmSync(tmp, { recursive: true, force: true })
 })
 
-describe('probeQuota — #210: 429 returns ok-with-note', () => {
-  it('returns ok with "quota check skipped: rate limited" on 429', async () => {
+describe('probeQuota — #1163: /v1/messages headers path', () => {
+  // The `/api/oauth/usage` endpoint has been deprecated/tightened —
+  // probeQuota now uses `fetchQuota` against `/v1/messages` and reads
+  // the unified-ratelimit response headers, same path /status uses.
+  it('reports ok with utilization line on a healthy response', async () => {
+    const headers = new Headers({
+      'anthropic-ratelimit-unified-5h-utilization': '0.42',
+      'anthropic-ratelimit-unified-7d-utilization': '0.18',
+    })
     const fakeFetch: typeof fetch = async () =>
-      new Response(null, { status: 429 }) as Response
+      new Response('{}', { status: 200, headers }) as Response
 
     const result = await probeQuota(claudeDir, agentDir, fakeFetch)
     expect(result.status).toBe('ok')
     expect(result.label).toBe('Quota')
-    expect(result.detail).toBe('quota check skipped: rate limited')
-    // #247: structured field so writeQuotaCache can key TTL off it
-    expect(result.rateLimited).toBe(true)
+    expect(result.detail).toContain('42% / 5h')
+    expect(result.detail).toContain('18% / 7d')
   })
 
-  it('writing 429 ok-result to cache produces a readable 30 s entry', () => {
+  it('surfaces auth rejection with the RFC-H replace-account hint on 403', async () => {
+    const fakeFetch: typeof fetch = async () =>
+      new Response(null, { status: 403 }) as Response
+
+    const result = await probeQuota(claudeDir, agentDir, fakeFetch)
+    expect(result.status).toBe('degraded')
+    // Post-RFC-H: per-agent `auth login` is retired. probeQuota emits the
+    // broker-aware "replace the account" hint pointing at `auth add ...
+    // --replace` instead. See telegram-plugin/gateway/boot-probes.ts.
+    expect(result.nextStep).toMatch(/switchroom auth add .*--from-oauth --replace/)
+  })
+
+  it('writing rate-limited result to cache produces a readable 30 s entry', () => {
     // Verify the cache contract: writeQuotaCache stores rate-limit results
     // with RATE_LIMIT_TTL_MS keyed off rateLimited:true, not the detail string.
     const rateLimitResult = {
@@ -855,6 +874,67 @@ describe('probeSkills', () => {
   })
 })
 
+// ── probeAccount nextStep interpolation (PR #1081 reviewer follow-up) ─────
+
+describe('probeAccount — nextStep agent-name interpolation', () => {
+  let tmpDir: string
+
+  function setupAgentDir(claudeJson: Record<string, unknown>, tokenMeta?: { expiresAt: number }): string {
+    const agentDir = mkdtempSync(join(tmpdir(), 'probe-account-'))
+    const claudeDir = join(agentDir, '.claude')
+    mkdirSync(claudeDir, { recursive: true })
+    writeFileSync(join(claudeDir, '.claude.json'), JSON.stringify(claudeJson))
+    if (tokenMeta) {
+      writeFileSync(join(claudeDir, '.oauth-token.meta.json'), JSON.stringify(tokenMeta))
+    }
+    return agentDir
+  }
+
+  afterEach(() => {
+    if (tmpDir) {
+      try { rmSync(tmpDir, { recursive: true, force: true }) } catch {}
+    }
+  })
+
+  it('not-signed-in hint interpolates agentName instead of <agent>', async () => {
+    tmpDir = setupAgentDir({})
+    const result = await probeAccount(tmpDir, { agentName: 'finn' })
+    expect(result.status).toBe('degraded')
+    expect(result.detail).toBe('not signed in')
+    expect(result.nextStep).toBeDefined()
+    expect(result.nextStep).toContain('switchroom auth login finn')
+    expect(result.nextStep).not.toContain('<agent>')
+  })
+
+  it('expired-token hint interpolates agentName', async () => {
+    tmpDir = setupAgentDir(
+      { oauthAccount: { emailAddress: 'me@example.com', billingType: 'max' } },
+      { expiresAt: Date.now() - 86_400_000 }, // expired yesterday
+    )
+    const result = await probeAccount(tmpDir, { agentName: 'klanker' })
+    expect(result.status).toBe('fail')
+    expect(result.nextStep).toContain('switchroom auth login klanker')
+    expect(result.nextStep).not.toContain('<agent>')
+  })
+
+  it('expiring-soon hint interpolates agentName', async () => {
+    tmpDir = setupAgentDir(
+      { oauthAccount: { emailAddress: 'me@example.com', billingType: 'max' } },
+      { expiresAt: Date.now() + 3 * 86_400_000 }, // 3 days left (< 7)
+    )
+    const result = await probeAccount(tmpDir, { agentName: 'lawgpt' })
+    expect(result.status).toBe('degraded')
+    expect(result.nextStep).toContain('switchroom auth login lawgpt')
+    expect(result.nextStep).not.toContain('<agent>')
+  })
+
+  it('falls back to <agent> placeholder when no agentName provided (backwards-compat)', async () => {
+    tmpDir = setupAgentDir({})
+    const result = await probeAccount(tmpDir)
+    expect(result.nextStep).toContain('<agent>')
+  })
+})
+
 // ── /proc parser unit tests (synthetic fs) ────────────────────────────────
 
 /** Build a /proc/<pid>/stat string for tests. */
@@ -1012,4 +1092,130 @@ describe('uptimeMsForStarttime', () => {
     expect(uptimeMsForStarttime(99999999, fs)).toBeNull()
   })
 })
+
+// ── nextStep remediation hints on degraded/fail probe branches ──────────────
+// Every fail/degraded result must carry an actionable `nextStep` per
+// reference/principles.md principle 1. These tests pin the hints across
+// the probes covered by the boot-card-dedup-and-next-steps PR so we don't
+// silently lose the hint on a future refactor.
+
+describe('nextStep — agent systemd states', () => {
+  it('attaches a journalctl hint when the unit is failed', async () => {
+    const exec = makeSequence([makeSystemctlOutput('failed')])
+    const r = await probeAgentProcess('klanker', {
+      execFileImpl: exec as unknown as (cmd: string, args: string[]) => Promise<{ stdout: string; stderr: string }>,
+      sleepImpl: async () => {},
+      retryIntervalMs: 1,
+      retryMaxMs: 0,
+    })
+    expect(r.status).toBe('fail')
+    expect(r.nextStep).toMatch(/journalctl/)
+    expect(r.nextStep).toMatch(/switchroom-klanker/)
+  })
+
+  it('attaches a transient-state hint when the unit is activating after retry budget', async () => {
+    const exec = makeSequence([makeSystemctlOutput('activating')])
+    const r = await probeAgentProcess('klanker', {
+      execFileImpl: exec as unknown as (cmd: string, args: string[]) => Promise<{ stdout: string; stderr: string }>,
+      sleepImpl: async () => {},
+      retryIntervalMs: 1,
+      retryMaxMs: 0,
+    })
+    expect(r.status).toBe('degraded')
+    expect(r.nextStep).toMatch(/transient/)
+    expect(r.nextStep).toMatch(/`activating`/)
+  })
+
+  it('attaches a docker-restart hint via the production dockerProbe when no claude in /proc', async () => {
+    // Inject a synthetic /proc with no claude entries — the production
+    // dockerProbe attaches the nextStep hint itself.
+    const { findAgentProcessInContainer } = await import('../gateway/boot-probes.js')
+    const fs = { readdir: () => [] as string[], readFile: () => '' }
+    const found = findAgentProcessInContainer(fs)
+    expect(found).toBeNull()
+    // Now run the docker probe under an override that mimics the
+    // production "claude not found" path so we exercise the nextStep
+    // attachment without depending on the test host's /proc state.
+    const r = await probeAgentProcess('klanker', {
+      dockerMode: true,
+      dockerProbeImpl: () => ({
+        status: 'fail',
+        label: 'Agent',
+        detail: 'claude process not found',
+        nextStep: 'No claude process in container — check container logs with `docker logs <container>` and restart with `switchroom agent restart <agent>`',
+      }),
+    })
+    expect(r.status).toBe('fail')
+    expect(r.nextStep).toMatch(/docker logs/)
+    expect(r.nextStep).toMatch(/restart/)
+  })
+})
+
+describe('nextStep — quota / hindsight / broker / kernel / scheduler', () => {
+  it('quota: no OAuth token → degraded with RFC-H add+use hint', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'quota-nextstep-'))
+    const oldCachePath = process.env.SWITCHROOM_QUOTA_CACHE_PATH
+    process.env.SWITCHROOM_QUOTA_CACHE_PATH = join(dir, 'cache.json')
+    try {
+      const r = await probeQuota(dir, dir, (async () => new Response('{}')) as unknown as typeof fetch)
+      expect(r.status).toBe('degraded')
+      // Post-RFC-H: the no-token nextStep points at `auth add` (register a
+      // fleet account) + `auth use` (set fleet active), not the retired
+      // per-agent `auth login`. See telegram-plugin/gateway/boot-probes.ts.
+      expect(r.nextStep).toMatch(/switchroom auth add .*--from-oauth/)
+      expect(r.nextStep).toMatch(/switchroom auth use/)
+    } finally {
+      if (oldCachePath) process.env.SWITCHROOM_QUOTA_CACHE_PATH = oldCachePath
+      else delete process.env.SWITCHROOM_QUOTA_CACHE_PATH
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('broker: socket missing → fail with docker compose hint', async () => {
+    const r = await probeBroker('/nonexistent/sock', { dockerMode: true })
+    expect(r.status).toBe('fail')
+    expect(r.nextStep).toMatch(/docker compose/)
+    expect(r.nextStep).toMatch(/vault-broker/)
+  })
+
+  it('kernel: socket missing → fail with docker compose hint', async () => {
+    const r = await probeKernel('/nonexistent/sock', { dockerMode: true })
+    expect(r.status).toBe('fail')
+    expect(r.nextStep).toMatch(/docker compose/)
+    expect(r.nextStep).toMatch(/approval-kernel/)
+  })
+
+  it('scheduler: no lockfile → fail with restart hint (or settling hint inside fresh-boot window)', async () => {
+    const fs: SchedulerFsImpl = { exists: () => false, readFile: () => '', mtimeMs: () => 0 }
+    const r = await probeScheduler('klanker', {
+      dockerMode: true,
+      fs,
+      lockPath: '/state/agent/scheduler.lock',
+      jsonlPath: '/state/agent/scheduler.jsonl',
+      now: () => Date.now(),
+      containerBootTimeMs: null, // disable softening
+    })
+    expect(r.status).toBe('fail')
+    expect(r.nextStep).toMatch(/restart/)
+  })
+
+  it('scheduler: lockfile holder pid dead → degraded with re-check hint', async () => {
+    const fs: SchedulerFsImpl = {
+      exists: (p) => p === '/state/agent/scheduler.lock',
+      readFile: () => '99999\n',
+      mtimeMs: () => 0,
+    }
+    const r = await probeScheduler('klanker', {
+      dockerMode: true,
+      fs,
+      lockPath: '/state/agent/scheduler.lock',
+      jsonlPath: '/state/agent/scheduler.jsonl',
+      isAlive: () => false,
+      now: () => Date.now(),
+      containerBootTimeMs: null,
+    })
+    expect(r.status).toBe('degraded')
+    expect(r.nextStep).toMatch(/re-check/i)
+  })
+})
 })

package/telegram-plugin/tests/finalize-callback.test.ts

@@ -0,0 +1,190 @@
+/**
+ * Pin the three-invariant contract for `finalizeCallback`. Every other
+ * inline-keyboard callback handler in the gateway routes through this
+ * helper, so a regression here breaks the audit-wide button UX
+ * (#1150 + follow-ups).
+ *
+ *   1. Visible press feedback (answerCallbackQuery with text).
+ *   2. Keyboard collapses + status line appended (one atomic edit).
+ *   3. synthInbound fires AFTER the message edit lands, errors
+ *      swallowed but logged.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { finalizeCallback, type FinalizeCallbackContext } from '../inline-keyboard-callbacks.js'
+
+interface Capture {
+  acks: Array<{ text?: string; show_alert?: boolean }>
+  edits: Array<{ text: string; opts: Record<string, unknown> }>
+  ackThrows?: Error
+  editThrows?: Error
+}
+
+function mkCtx(cap: Capture): FinalizeCallbackContext {
+  return {
+    answerCallbackQuery: async (opts) => {
+      cap.acks.push(opts ?? {})
+      if (cap.ackThrows) throw cap.ackThrows
+      return true
+    },
+    editMessageText: async (text, opts) => {
+      cap.edits.push({ text, opts: opts ?? {} })
+      if (cap.editThrows) throw cap.editThrows
+      return { message_id: 1 }
+    },
+  }
+}
+
+describe('finalizeCallback — three-invariant contract', () => {
+  it('invariant 1: acks the callback with the supplied toast text', async () => {
+    const cap: Capture = { acks: [], edits: [] }
+    await finalizeCallback(mkCtx(cap), {
+      ackText: 'Approved',
+      newText: 'Original prompt\n\n✓ Approved by @op',
+    })
+    expect(cap.acks).toHaveLength(1)
+    expect(cap.acks[0]?.text).toBe('Approved')
+    expect(cap.acks[0]?.show_alert).toBeUndefined()
+  })
+
+  it('invariant 1: alert=true renders as full modal (show_alert: true)', async () => {
+    const cap: Capture = { acks: [], edits: [] }
+    await finalizeCallback(mkCtx(cap), {
+      ackText: 'Vault grant revoked',
+      alert: true,
+      newText: '...',
+    })
+    expect(cap.acks[0]?.show_alert).toBe(true)
+  })
+
+  it('invariant 2: strips reply_markup AND edits the body in one atomic call', async () => {
+    const cap: Capture = { acks: [], edits: [] }
+    await finalizeCallback(mkCtx(cap), {
+      ackText: 'Approved',
+      newText: '✓ Approved\n\nGrant minted at 22:38 UTC',
+      parseMode: 'HTML',
+    })
+    expect(cap.edits).toHaveLength(1)
+    expect(cap.edits[0]?.text).toBe('✓ Approved\n\nGrant minted at 22:38 UTC')
+    expect(cap.edits[0]?.opts.reply_markup).toEqual({ inline_keyboard: [] })
+    expect(cap.edits[0]?.opts.parse_mode).toBe('HTML')
+    // link_preview_options disabled by default — keeps the edited
+    // status line from rendering a stale preview card.
+    expect(cap.edits[0]?.opts.link_preview_options).toEqual({ is_disabled: true })
+  })
+
+  it('invariant 2: omits parse_mode when not specified (plain text)', async () => {
+    const cap: Capture = { acks: [], edits: [] }
+    await finalizeCallback(mkCtx(cap), { ackText: 'ok', newText: 'plain' })
+    expect(cap.edits[0]?.opts.parse_mode).toBeUndefined()
+  })
+
+  it('invariant 3: synthInbound fires AFTER editMessageText resolves', async () => {
+    const order: string[] = []
+    const ctx: FinalizeCallbackContext = {
+      answerCallbackQuery: async () => { order.push('ack'); return true },
+      editMessageText: async () => {
+        order.push('edit-start')
+        await new Promise((r) => setTimeout(r, 5))
+        order.push('edit-end')
+        return { message_id: 1 }
+      },
+    }
+    await finalizeCallback(ctx, {
+      ackText: 'ok',
+      newText: '...',
+      synthInbound: () => { order.push('synth') },
+    })
+    // ack is fire-and-forget so its position is "no later than edit-start"
+    // but we don't pin its exact position. Pin that synth comes AFTER
+    // edit-end — that's the guarantee callers need.
+    const editEndIdx = order.indexOf('edit-end')
+    const synthIdx = order.indexOf('synth')
+    expect(editEndIdx).toBeGreaterThanOrEqual(0)
+    expect(synthIdx).toBeGreaterThan(editEndIdx)
+  })
+
+  it('invariant 3: async synthInbound is awaited', async () => {
+    let synthResolved = false
+    const cap: Capture = { acks: [], edits: [] }
+    await finalizeCallback(mkCtx(cap), {
+      ackText: 'ok',
+      newText: '...',
+      synthInbound: async () => {
+        await new Promise((r) => setTimeout(r, 5))
+        synthResolved = true
+      },
+    })
+    expect(synthResolved).toBe(true)
+  })
+
+  it('invariant 3: synthInbound errors are caught + logged, never propagated', async () => {
+    const logs: string[] = []
+    const cap: Capture = { acks: [], edits: [] }
+    await expect(
+      finalizeCallback(mkCtx(cap), {
+        ackText: 'ok',
+        newText: '...',
+        synthInbound: () => { throw new Error('inject_inbound IPC closed') },
+        log: (l) => logs.push(l),
+      }),
+    ).resolves.toBeUndefined()
+    expect(logs.some((l) => l.includes('inject_inbound IPC closed'))).toBe(true)
+  })
+
+  it('robustness: editMessageText failure does NOT block synthInbound', async () => {
+    // Operator deleted the card between tap and our edit — Telegram
+    // returns MESSAGE_TO_EDIT_NOT_FOUND. The model still needs to wake
+    // up: a stale/missing card is preferred to a stuck conversation.
+    const logs: string[] = []
+    let synthFired = false
+    const cap: Capture = {
+      acks: [],
+      edits: [],
+      editThrows: new Error('Bad Request: message to edit not found'),
+    }
+    await finalizeCallback(mkCtx(cap), {
+      ackText: 'Approved',
+      newText: '...',
+      synthInbound: () => { synthFired = true },
+      log: (l) => logs.push(l),
+    })
+    expect(synthFired).toBe(true)
+    expect(logs.some((l) => l.includes('message to edit not found'))).toBe(true)
+  })
+
+  it('robustness: answerCallbackQuery failure does NOT block edit or synth', async () => {
+    // Telegram rejects the ack (e.g. the callback_query is already
+    // older than the 60s timeout). The edit + synth still must proceed.
+    const logs: string[] = []
+    let synthFired = false
+    const cap: Capture = {
+      acks: [],
+      edits: [],
+      ackThrows: new Error('query is too old'),
+    }
+    await finalizeCallback(mkCtx(cap), {
+      ackText: 'Approved',
+      newText: 'edited body',
+      synthInbound: () => { synthFired = true },
+      log: (l) => logs.push(l),
+    })
+    expect(cap.edits).toHaveLength(1)
+    expect(cap.edits[0]?.text).toBe('edited body')
+    expect(synthFired).toBe(true)
+    // ack fire-and-forget — its catch fires asynchronously; give it a tick
+    // so the log assertion is stable across runs.
+    await new Promise((r) => setTimeout(r, 0))
+    expect(logs.some((l) => l.includes('query is too old'))).toBe(true)
+  })
+
+  it('synthInbound is optional — surfaces with no model in the loop just ack + edit', async () => {
+    const cap: Capture = { acks: [], edits: [] }
+    await finalizeCallback(mkCtx(cap), {
+      ackText: 'Dismissed',
+      newText: '✗ Dismissed',
+    })
+    expect(cap.acks).toHaveLength(1)
+    expect(cap.edits).toHaveLength(1)
+  })
+})

package/telegram-plugin/tests/gateway-message-validator.test.ts

@@ -88,6 +88,32 @@ describe('validateGatewayMessage', () => {
     it('rejects missing requestId', () => {
       expect(validateGatewayMessage({ type: 'permission', behavior: 'allow' })).toBe(false)
     })
+
+    // #1138: optional `rule` field on Always-allow broadcasts. Must be
+    // accepted when present + non-empty, accepted when absent, rejected
+    // when present-but-malformed (the bridge stashes the value verbatim
+    // into a Set<string> — empty strings or wrong types would poison
+    // the matcher).
+    it('accepts an optional rule when behavior is allow', () => {
+      expect(validateGatewayMessage({
+        type: 'permission', requestId: 'r', behavior: 'allow', rule: 'Edit',
+      })).toBe(true)
+      expect(validateGatewayMessage({
+        type: 'permission', requestId: 'r', behavior: 'allow', rule: 'Skill(mail)',
+      })).toBe(true)
+    })
+
+    it('rejects an empty-string rule', () => {
+      expect(validateGatewayMessage({
+        type: 'permission', requestId: 'r', behavior: 'allow', rule: '',
+      })).toBe(false)
+    })
+
+    it('rejects a non-string rule', () => {
+      expect(validateGatewayMessage({
+        type: 'permission', requestId: 'r', behavior: 'allow', rule: 42,
+      })).toBe(false)
+    })
   })
 
   describe('status', () => {

package/telegram-plugin/tests/gateway-secret-detect.test.ts

@@ -68,7 +68,13 @@ describe('gateway secret-detect intercept — structural wiring', () => {
     // Rewrites effectiveText so the broadcast carries the redacted text.
     expect(tail).toMatch(/effectiveText = pipeRes\.rewritten_text/)
     // Deletes the original Telegram message containing the raw bytes.
-    expect(tail).toMatch(/bot\.api\.deleteMessage\(chat_id, msgId\)/)
+    // 2026-05-12: migrated from raw `bot.api.deleteMessage` to the
+    // `deleteSensitiveMessage` helper so failures surface to the
+    // operator via in-chat warning instead of being silently
+    // swallowed. See
+    // tests/secret-detect-delete-must-surface-failures.test.ts for
+    // the full contract pin.
+    expect(tail).toMatch(/deleteSensitiveMessage\(chat_id, msgId, 'detected secret'\)/)
     // Tells the user what was captured (masked).
     expect(tail).toMatch(/captured \$\{pipeRes\.stored\.length\} secret/)
     // Surfaces the masked form (s.masked is computed via maskToken in the pipeline).
@@ -92,8 +98,11 @@ describe('gateway secret-detect intercept — structural wiring', () => {
     expect(tail).toMatch(/deferredSecrets\.set\(/)
     expect(tail).toMatch(/suggested_slug:/)
     // 2. The original message is deleted (so the raw bytes are scrubbed
-    //    from the chat client even before the user reacts).
-    expect(tail).toMatch(/bot\.api\.deleteMessage\(chat_id, msgId\)/)
+    //    from the chat client even before the user reacts). 2026-05-12:
+    //    migrated to deleteSensitiveMessage so failures surface to the
+    //    operator via in-chat warning. See
+    //    tests/secret-detect-delete-must-surface-failures.test.ts.
+    expect(tail).toMatch(/deleteSensitiveMessage\(chat_id, msgId, 'detected secret'\)/)
     // 4. The new inline keyboard helper is used in lieu of the legacy
     //    plain-text "run /vault list" warning.
     expect(tail).toMatch(/buildDeferredSecretKeyboard\(/)