switchroom 0.15.36 → 0.15.38

package/telegram-plugin/tests/linear-agent-activity.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect } from 'vitest'
 import { readFileSync } from 'node:fs'
 import {
   emitLinearAgentActivity,
+  buildLinearAuthDeadMessage,
   type LinearTokenResult,
 } from '../gateway/linear-activity.js'
 
@@ -197,3 +198,79 @@ describe('linear_agent_activity — auto-refresh on 401 (#2298 durability)', ()
     expect(calls.length).toBe(1)
   })
 })
+
+/** RefreshIO whose bundle is absent → performLinearRefresh returns no_bundle
+ *  (the silent-setup-failure case clerk/carrie hit in prod). */
+function noBundleRefreshIO(): RefreshIO {
+  return { readBundle: async () => null, writeToken: async () => {}, writeBundle: async () => {} }
+}
+
+describe('emitLinearAgentActivity — operator alert when auth is unrecoverable (FIX 1)', () => {
+  it('no refresh bundle → onAuthUnrecoverable(no_bundle) fires', async () => {
+    const { fetchImpl } = refreshAwareFetch()
+    const alerts: Array<{ agent: string; reason: string }> = []
+    const r = await emitLinearAgentActivity(
+      { agent_session_id: 'sess', type: 'thought', body: 'hi' },
+      {
+        agent: 'clerk',
+        resolveToken: okToken('lin_expired'),
+        fetchImpl,
+        refreshIO: () => noBundleRefreshIO(),
+        log: () => {},
+        onAuthUnrecoverable: (i) => alerts.push(i),
+      },
+    )
+    expect(r.content[0].text).toMatch(/Linear API 401/)
+    expect(alerts).toEqual([{ agent: 'clerk', reason: 'no_bundle', detail: expect.any(String) }])
+  })
+
+  it('revoked refresh token → onAuthUnrecoverable(revoked) fires', async () => {
+    const { fetchImpl } = refreshAwareFetch({ tokenStatus: 400, tokenBody: 'invalid_grant' })
+    const alerts: Array<{ agent: string; reason: string }> = []
+    await emitLinearAgentActivity(
+      { agent_session_id: 'sess', type: 'thought', body: 'hi' },
+      { agent: 'carrie', resolveToken: okToken('lin_dead'), fetchImpl, refreshIO: () => fakeRefreshIO().io, log: () => {}, onAuthUnrecoverable: (i) => alerts.push(i) },
+    )
+    expect(alerts.map((a) => a.reason)).toEqual(['revoked'])
+  })
+
+  it('transient refresh failure (HTTP 500) does NOT page the operator', async () => {
+    const { fetchImpl } = refreshAwareFetch({ tokenStatus: 500, tokenBody: 'upstream boom' })
+    const alerts: unknown[] = []
+    await emitLinearAgentActivity(
+      { agent_session_id: 'sess', type: 'thought', body: 'hi' },
+      { agent: 'carrie', resolveToken: okToken('lin_x'), fetchImpl, refreshIO: () => fakeRefreshIO().io, log: () => {}, onAuthUnrecoverable: (i) => alerts.push(i) },
+    )
+    expect(alerts).toEqual([])
+  })
+
+  it('buildLinearAuthDeadMessage: no_bundle names the missing oauth key + re-auth command', () => {
+    const msg = buildLinearAuthDeadMessage('clerk', 'no_bundle')
+    expect(msg).toMatch(/Linear auth needs you/)
+    expect(msg).toContain('<code>linear/clerk/oauth</code>')
+    expect(msg).toContain('switchroom linear-agent setup --agent clerk')
+  })
+
+  it('buildLinearAuthDeadMessage: revoked says the refresh token was revoked', () => {
+    const msg = buildLinearAuthDeadMessage('carrie', 'revoked')
+    expect(msg).toMatch(/refresh token was revoked/)
+    expect(msg).not.toContain('/oauth</code> is missing')
+  })
+
+  it('buildLinearAuthDeadMessage: HTML-escapes a hostile agent slug', () => {
+    const msg = buildLinearAuthDeadMessage('a<b>&c', 'no_bundle')
+    expect(msg).toContain('a&lt;b&gt;&amp;c')
+    expect(msg).not.toContain('a<b>&c')
+  })
+
+  it('successful auto-refresh does NOT page the operator', async () => {
+    const { fetchImpl } = refreshAwareFetch()
+    const alerts: unknown[] = []
+    const r = await emitLinearAgentActivity(
+      { agent_session_id: 'sess', type: 'thought', body: 'hi' },
+      { agent: 'carrie', resolveToken: okToken('lin_expired'), fetchImpl, refreshIO: () => fakeRefreshIO().io, log: () => {}, onAuthUnrecoverable: (i) => alerts.push(i) },
+    )
+    expect(r.content[0].text).toMatch(/emitted/)
+    expect(alerts).toEqual([])
+  })
+})

package/telegram-plugin/tests/linear-agent-setup.test.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { runLinearAgentSetup } from '../gateway/linear-setup.js'
+
+/**
+ * Tests for the `linear_agent_setup` MCP tool (FIX 2 — in-container,
+ * operator-approved Linear OAuth provisioning).
+ *
+ * Structural: assert the tool is declared in bridge.ts and allow-listed +
+ * dispatched in gateway.ts (the gateway IIFE can't be imported).
+ * Behavioural: the logic lives in gateway/linear-setup.ts with injected
+ * fetch + broker-put deps, so the OAuth exchange + write paths run offline.
+ */
+
+type PutOutcome = { kind: 'ok' } | { kind: 'denied'; msg: string } | { kind: 'not_found'; msg: string } | { kind: 'unreachable'; msg: string }
+
+function exchangeFetch(opts: { status?: number; body?: unknown } = {}): typeof fetch {
+  return (async () => {
+    const status = opts.status ?? 200
+    const body = opts.body ?? { access_token: 'lin_acc', refresh_token: 'lin_ref', expires_in: 86400, scope: 'read write' }
+    return {
+      ok: status >= 200 && status < 300,
+      status,
+      json: async () => body,
+      text: async () => (typeof body === 'string' ? body : JSON.stringify(body)),
+    } as unknown as Response
+  }) as unknown as typeof fetch
+}
+
+describe('linear_agent_setup — wiring', () => {
+  const gw = readFileSync(new URL('../gateway/gateway.ts', import.meta.url), 'utf8')
+  const bridge = readFileSync(new URL('../bridge/bridge.ts', import.meta.url), 'utf8')
+
+  it('declares the MCP tool with an action enum', () => {
+    const idx = bridge.indexOf(`name: 'linear_agent_setup'`)
+    expect(idx).toBeGreaterThan(0)
+    const schema = bridge.slice(idx, idx + 1600)
+    expect(schema).toMatch(/authorize_url/)
+    expect(schema).toMatch(/complete/)
+    expect(schema).toMatch(/client_id/)
+  })
+
+  it('is allow-listed and dispatched', () => {
+    expect(gw).toMatch(/'linear_agent_setup',/)
+    expect(gw).toMatch(/case 'linear_agent_setup':\s*\n\s*return executeLinearAgentSetup\(args\)/)
+  })
+})
+
+describe('runLinearAgentSetup — authorize_url', () => {
+  it('returns the actor=app authorize URL', async () => {
+    const r = await runLinearAgentSetup(
+      { action: 'authorize_url', client_id: 'cid', redirect_uri: 'http://localhost:3000/callback' },
+      { agent: 'clerk', log: () => {} },
+    )
+    expect(r.content[0].text).toContain('https://linear.app/oauth/authorize?')
+    expect(r.content[0].text).toContain('actor=app')
+    expect(r.content[0].text).toContain('client_id=cid')
+  })
+
+  it('rejects a non-http redirect_uri', async () => {
+    const r = await runLinearAgentSetup(
+      { action: 'authorize_url', client_id: 'cid', redirect_uri: 'not-a-url' },
+      { agent: 'clerk', log: () => {} },
+    )
+    expect(r.content[0].text).toMatch(/redirect_uri is required and must be an http/)
+  })
+})
+
+describe('runLinearAgentSetup — complete', () => {
+  const base = { action: 'complete', client_id: 'cid', client_secret: 'sec', redirect_uri: 'http://localhost:3000/callback', code: 'auth_code' }
+
+  it('exchanges the code and writes bundle THEN token', async () => {
+    const writes: Array<{ which: string; value: string }> = []
+    const r = await runLinearAgentSetup(base, {
+      agent: 'clerk',
+      fetchImpl: exchangeFetch(),
+      putBundle: async (_a, j) => { writes.push({ which: 'bundle', value: j }); return { kind: 'ok' } },
+      putToken: async (_a, t) => { writes.push({ which: 'token', value: t }); return { kind: 'ok' } },
+      log: () => {},
+    })
+    expect(writes.map((w) => w.which)).toEqual(['bundle', 'token']) // bundle first
+    expect(writes[1].value).toBe('lin_acc')
+    const storedBundle = JSON.parse(writes[0].value)
+    expect(storedBundle).toMatchObject({ client_id: 'cid', client_secret: 'sec', refresh_token: 'lin_ref' })
+    expect(r.content[0].text).toMatch(/stored for clerk/)
+    expect(r.content[0].text).toMatch(/config_propose_edit/)
+  })
+
+  it('bad authorization code → re-authorize guidance, no writes', async () => {
+    let wrote = false
+    const r = await runLinearAgentSetup(base, {
+      agent: 'clerk',
+      fetchImpl: exchangeFetch({ status: 400, body: 'invalid_grant' }),
+      putBundle: async () => { wrote = true; return { kind: 'ok' } },
+      putToken: async () => { wrote = true; return { kind: 'ok' } },
+      log: () => {},
+    })
+    expect(wrote).toBe(false)
+    expect(r.content[0].text).toMatch(/Re-run action "authorize_url"/)
+  })
+
+  it('vault has no write-grant (UNKNOWN_KEY) → write-grant guidance', async () => {
+    const r = await runLinearAgentSetup(base, {
+      agent: 'clerk',
+      fetchImpl: exchangeFetch(),
+      putBundle: async () => ({ kind: 'not_found', msg: 'Key not found' }),
+      putToken: async () => ({ kind: 'ok' }),
+      log: () => {},
+    })
+    expect(r.content[0].text).toMatch(/vault_request_access/)
+    expect(r.content[0].text).toContain('linear/clerk/oauth')
+    expect(r.content[0].text).toContain('linear/clerk/token')
+  })
+
+  it('requires client_secret and code', async () => {
+    const r1 = await runLinearAgentSetup({ ...base, client_secret: undefined }, { agent: 'clerk', log: () => {} })
+    expect(r1.content[0].text).toMatch(/client_secret is required/)
+    const r2 = await runLinearAgentSetup({ ...base, code: undefined }, { agent: 'clerk', log: () => {} })
+    expect(r2.content[0].text).toMatch(/code .*is required/)
+  })
+
+  it('never lets a write failure strand a half-provisioned state (token write fails → guidance)', async () => {
+    const r = await runLinearAgentSetup(base, {
+      agent: 'clerk',
+      fetchImpl: exchangeFetch(),
+      putBundle: async () => ({ kind: 'ok' }),
+      putToken: async () => ({ kind: 'denied', msg: 'scope-allow' }),
+      log: () => {},
+    })
+    expect(r.content[0].text).toMatch(/vault_request_access/)
+  })
+})

package/telegram-plugin/tests/linear-auth-watch.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect } from 'vitest'
+import { runLinearAuthCheck, type LinearAuthWatchDeps } from '../gateway/linear-auth-watch.js'
+import { serializeBundle } from '../../src/linear/oauth-refresh.js'
+
+function baseDeps(over: Partial<LinearAuthWatchDeps> = {}): { deps: LinearAuthWatchDeps; alerts: Array<{ reason: string }> } {
+  const alerts: Array<{ reason: string }> = []
+  const deps: LinearAuthWatchDeps = {
+    agent: 'clerk',
+    linearEnabled: () => true,
+    readBundle: async () => serializeBundle({ clientId: 'c', clientSecret: 's', refreshToken: 'rt', expiresAt: 10_000 }),
+    refresh: async () => ({ ok: true, accessToken: 'lin_new', expiresAt: 20_000 }),
+    onAuthDead: (i) => alerts.push(i),
+    nowSec: () => 1_000, // far before expiry → fresh
+    log: () => {},
+    ...over,
+  }
+  return { deps, alerts }
+}
+
+describe('runLinearAuthCheck (proactive Linear auth watch)', () => {
+  it('disabled agent → no-op, no alert', async () => {
+    const { deps, alerts } = baseDeps({ linearEnabled: () => false })
+    expect(await runLinearAuthCheck(deps)).toBe('disabled')
+    expect(alerts).toEqual([])
+  })
+
+  it('fresh token (not near expiry) → fresh, no refresh, no alert', async () => {
+    let refreshed = false
+    const { deps, alerts } = baseDeps({ refresh: async () => { refreshed = true; return { ok: true, accessToken: 'x', expiresAt: 1 } } })
+    expect(await runLinearAuthCheck(deps)).toBe('fresh')
+    expect(refreshed).toBe(false)
+    expect(alerts).toEqual([])
+  })
+
+  it('missing bundle → no_bundle + proactive operator alert', async () => {
+    const { deps, alerts } = baseDeps({ readBundle: async () => null })
+    expect(await runLinearAuthCheck(deps)).toBe('no_bundle')
+    expect(alerts).toEqual([{ agent: 'clerk', reason: 'no_bundle', detail: expect.any(String) }])
+  })
+
+  it('near-expiry token → proactively refreshes, no alert', async () => {
+    // now=9999 is within the 2h skew of expiresAt=10000
+    const { deps, alerts } = baseDeps({ nowSec: () => 9_999 })
+    expect(await runLinearAuthCheck(deps)).toBe('refreshed')
+    expect(alerts).toEqual([])
+  })
+
+  it('near-expiry + revoked refresh token → alert(revoked)', async () => {
+    const { deps, alerts } = baseDeps({
+      nowSec: () => 9_999,
+      refresh: async () => ({ ok: false, reason: 'revoked', detail: 'invalid_grant' }),
+    })
+    expect(await runLinearAuthCheck(deps)).toBe('revoked')
+    expect(alerts.map((a) => a.reason)).toEqual(['revoked'])
+  })
+
+  it('near-expiry + transient refresh failure → no alert (retries later)', async () => {
+    const { deps, alerts } = baseDeps({
+      nowSec: () => 9_999,
+      refresh: async () => ({ ok: false, reason: 'network', detail: 'boom' }),
+    })
+    expect(await runLinearAuthCheck(deps)).toBe('refresh_failed')
+    expect(alerts).toEqual([])
+  })
+
+  it('broker read error → refresh_failed, no alert (transient infra)', async () => {
+    const { deps, alerts } = baseDeps({ readBundle: async () => { throw new Error('broker down') } })
+    expect(await runLinearAuthCheck(deps)).toBe('refresh_failed')
+    expect(alerts).toEqual([])
+  })
+
+  it('expiry-untracked bundle (no expiresAt) → fresh (reactive path covers it)', async () => {
+    const { deps, alerts } = baseDeps({
+      readBundle: async () => serializeBundle({ clientId: 'c', clientSecret: 's', refreshToken: 'rt' }),
+    })
+    expect(await runLinearAuthCheck(deps)).toBe('fresh')
+    expect(alerts).toEqual([])
+  })
+})

package/telegram-plugin/tests/linear-create-issue.test.ts

@@ -75,7 +75,9 @@ describe('linear_create_issue — gateway wiring (#2312)', () => {
   })
 
   it('is allow-listed and dispatched', () => {
-    expect(gw).toMatch(/'linear_create_issue',\n\]\)/)
+    // Membership in ALLOWED_TOOLS (not position — new linear tools may be
+    // appended after it, e.g. linear_agent_setup).
+    expect(gw).toMatch(/^\s*'linear_create_issue',\s*$/m)
     expect(gw).toMatch(/case 'linear_create_issue':\s*\n\s*return executeLinearCreateIssue\(args\)/)
   })
 })

package/telegram-plugin/tests/permission-card-origin.test.ts

@@ -0,0 +1,97 @@
+/**
+ * Unit tests for the pure permission-card origin-recovery helper.
+ *
+ * Pins the behaviour that fixes the marko Rentals-budget incident
+ * (2026-06-17): when the gateway's `currentTurn` was force-closed by the
+ * orphaned-reply backstop but the claude session kept running into a
+ * permission-gated tool, the card must recover its origin from the most-recent
+ * still-fresh turn — so it lands in the forum topic the operator is working in
+ * rather than fanning out to operator DMs where it auto-denies on the 10-min
+ * TTL.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  pickRecoveredPermissionOrigin,
+  type RecoverableTurn,
+} from '../gateway/permission-card-origin.js'
+
+const NOW = 1_000_000_000_000
+const MAX_AGE = 30 * 60_000 // 30 min, mirrors PERMISSION_CARD_ORIGIN_MAX_AGE_MS
+
+function turn(
+  chatId: string,
+  threadId: number | undefined,
+  ageMs: number,
+): RecoverableTurn {
+  return { sessionChatId: chatId, sessionThreadId: threadId, startedAt: NOW - ageMs }
+}
+
+describe('pickRecoveredPermissionOrigin', () => {
+  it('returns null for an empty registry (caller keeps the DM fan-out)', () => {
+    expect(pickRecoveredPermissionOrigin([], NOW, MAX_AGE)).toBeNull()
+  })
+
+  it('recovers the supergroup chat + topic of the most-recent fresh turn', () => {
+    // The marko shape: the force-closed turn was in supergroup topic 3.
+    const recovered = pickRecoveredPermissionOrigin(
+      [turn('-1001234567890', 3, 11 * 60_000)],
+      NOW,
+      MAX_AGE,
+    )
+    expect(recovered).toEqual({ chatId: '-1001234567890', threadId: 3 })
+  })
+
+  it('picks the most-recently-started turn when several are fresh', () => {
+    const recovered = pickRecoveredPermissionOrigin(
+      [
+        turn('-100aaa', 1, 20 * 60_000),
+        turn('-100bbb', 3, 2 * 60_000), // most recent
+        turn('-100ccc', 4, 9 * 60_000),
+      ],
+      NOW,
+      MAX_AGE,
+    )
+    expect(recovered).toEqual({ chatId: '-100bbb', threadId: 3 })
+  })
+
+  it('selects by startedAt, not iteration order (robust to out-of-order inserts)', () => {
+    const recovered = pickRecoveredPermissionOrigin(
+      [
+        turn('-100recent', 1, 1 * 60_000), // freshest, but listed first
+        turn('-100older', 2, 15 * 60_000),
+      ],
+      NOW,
+      MAX_AGE,
+    )
+    expect(recovered).toEqual({ chatId: '-100recent', threadId: 1 })
+  })
+
+  it('ignores turns older than the freshness ceiling', () => {
+    expect(
+      pickRecoveredPermissionOrigin([turn('-100stale', 7, 45 * 60_000)], NOW, MAX_AGE),
+    ).toBeNull()
+  })
+
+  it('recovers a DM-origin turn thread-less (threadId undefined)', () => {
+    const recovered = pickRecoveredPermissionOrigin(
+      [turn('12345', undefined, 3 * 60_000)],
+      NOW,
+      MAX_AGE,
+    )
+    expect(recovered).toEqual({ chatId: '12345', threadId: undefined })
+  })
+
+  it('keeps the freshest in-window turn even when stale turns are present', () => {
+    const recovered = pickRecoveredPermissionOrigin(
+      [
+        turn('-100stale', 1, 90 * 60_000),
+        turn('-100fresh', 3, 5 * 60_000),
+        turn('-100ancient', 2, 600 * 60_000),
+      ],
+      NOW,
+      MAX_AGE,
+    )
+    expect(recovered).toEqual({ chatId: '-100fresh', threadId: 3 })
+  })
+})

package/telegram-plugin/tests/permission-card-routing.test.ts

@@ -74,4 +74,27 @@ describe('permission card routing', () => {
     const body = GATEWAY_SRC.slice(start, start + 1400)
     expect(body).toContain('resolvePermissionCardTargets()')
   })
+
+  // marko Rentals-budget incident (2026-06-17): a turn force-closed by the
+  // orphaned-reply backstop nulled currentTurn, so a permission gate that
+  // fired afterwards fell through to the operator-DM fan-out instead of the
+  // forum topic. The helper must first try to recover the origin from the
+  // recently-started turn registry.
+  it('resolvePermissionCardTargets recovers origin from recent turns when currentTurn is null', () => {
+    const start = GATEWAY_SRC.indexOf('function resolvePermissionCardTargets(')
+    expect(start).toBeGreaterThan(-1)
+    const end = GATEWAY_SRC.indexOf('\n}', start)
+    const body = GATEWAY_SRC.slice(start, end)
+    // Recovery is attempted via the pure helper over the turn registry...
+    expect(body).toContain('pickRecoveredPermissionOrigin')
+    expect(body).toContain('recentTurnsById')
+    // ...before the operator-DM fan-out (recovery branch precedes allowFrom).
+    expect(body.indexOf('pickRecoveredPermissionOrigin')).toBeLessThan(
+      body.indexOf('allowFrom'),
+    )
+  })
+
+  it('the origin-recovery path has a kill switch', () => {
+    expect(GATEWAY_SRC).toContain('SWITCHROOM_PERMISSION_CARD_ORIGIN_RECOVERY')
+  })
 })

package/telegram-plugin/tests/permission-no-repeat-wiring.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Source-text pins for the no-repeat-on-timeout wiring (marko Rentals-budget
+ * loop, 2026-06-17). gateway.ts / bridge.ts have top-level side effects and
+ * aren't unit-importable; the decision logic is unit-tested in
+ * permission-timeout.test.ts. These pins lock the wiring so it can't silently
+ * regress.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const read = (p: string) => readFileSync(resolve(__dirname, '..', p), 'utf8')
+const GATEWAY = read('gateway/gateway.ts')
+const BRIDGE = read('bridge/bridge.ts')
+const IPC_PROTOCOL = read('gateway/ipc-protocol.ts')
+const IPC_CLIENT = read('bridge/ipc-client.ts')
+
+function slice(src: string, fnHeader: string, span = 1600): string {
+  const start = src.indexOf(fnHeader)
+  expect(start, `expected to find ${fnHeader}`).toBeGreaterThan(-1)
+  return src.slice(start, start + span)
+}
+
+describe('no-repeat-on-timeout wiring', () => {
+  it('PermissionEvent carries an optional message field', () => {
+    const evt = slice(IPC_PROTOCOL, 'export interface PermissionEvent', 2400)
+    expect(evt).toMatch(/message\?:\s*string/)
+  })
+
+  it('the bridge IPC validator accepts an optional non-empty message', () => {
+    expect(IPC_CLIENT).toMatch(/m\.message === undefined/)
+  })
+
+  it('the bridge forwards message on the permission channel notification', () => {
+    const fn = slice(BRIDGE, 'function onPermission(', 1600)
+    expect(fn).toContain('notifications/claude/channel/permission')
+    expect(fn).toMatch(/msg\.message/)
+  })
+
+  it('the TTL auto-deny attaches a timeout message and records the signature', () => {
+    // Within the pending-permission sweep block.
+    const sweep = slice(GATEWAY, 'for (const [k, v] of pendingPermissions)', 2200)
+    expect(sweep).toContain('timeoutDenyMessage(')
+    expect(sweep).toContain('permissionTimeoutSignatures.set(')
+  })
+
+  it('onPermissionRequest short-circuits a recent-timeout duplicate before posting a card', () => {
+    const fn = slice(GATEWAY, 'onPermissionRequest(', 4000)
+    const dupIdx = fn.indexOf('isRecentTimeoutDuplicate(')
+    const cardIdx = fn.indexOf('pendingPermissions.set(requestId')
+    expect(dupIdx).toBeGreaterThan(-1)
+    expect(cardIdx).toBeGreaterThan(-1)
+    // The duplicate check must run BEFORE the card is registered/posted.
+    expect(dupIdx).toBeLessThan(cardIdx)
+    expect(fn).toContain('duplicateDenyMessage')
+  })
+
+  it('suppression is reset on operator activity (inbound + card verdict + slash)', () => {
+    // Three distinct reset points so a returning operator always gets a fresh card.
+    const resets = GATEWAY.match(/clearPermissionTimeoutSuppression\(/g) ?? []
+    // 1 definition call inside the helper + at least 3 reset callsites.
+    expect(resets.length).toBeGreaterThanOrEqual(3)
+    expect(GATEWAY).toContain("clearPermissionTimeoutSuppression('operator inbound')")
+  })
+
+  it('has a kill switch', () => {
+    expect(GATEWAY).toContain('SWITCHROOM_PERMISSION_NO_REPEAT')
+  })
+
+  it('sweeps stale suppression entries past the safety-cap window', () => {
+    expect(GATEWAY).toMatch(/permissionTimeoutSignatures\.delete\(sig\)/)
+  })
+})

package/telegram-plugin/tests/permission-timeout.test.ts

@@ -0,0 +1,87 @@
+/**
+ * Unit tests for the pure permission-timeout helpers (no-repeat-on-timeout).
+ *
+ * Pins the behaviour that closes the marko Rentals-budget retry loop
+ * (2026-06-17): a TTL auto-deny must be distinguishable from a real denial,
+ * and an identical retry shortly after a timeout (operator still absent) must
+ * be recognisable so the gateway can suppress the duplicate card.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  permissionSignature,
+  timeoutDenyMessage,
+  duplicateDenyMessage,
+  isRecentTimeoutDuplicate,
+} from '../gateway/permission-timeout.js'
+
+describe('permissionSignature', () => {
+  it('is stable for the same tool + input', () => {
+    expect(permissionSignature('mcp__meta_ads__set_budget', '{"id":"1","budget":1400}'))
+      .toBe(permissionSignature('mcp__meta_ads__set_budget', '{"id":"1","budget":1400}'))
+  })
+
+  it('differs when the tool differs', () => {
+    expect(permissionSignature('toolA', 'x')).not.toBe(permissionSignature('toolB', 'x'))
+  })
+
+  it('differs when the input differs', () => {
+    expect(permissionSignature('t', 'Rentals $14')).not.toBe(permissionSignature('t', 'Land $60'))
+  })
+
+  it('does not collide across the tool/input boundary (NUL-separated)', () => {
+    // A space separator would make ("a b","c") and ("a","b c") collide.
+    expect(permissionSignature('a b', 'c')).not.toBe(permissionSignature('a', 'b c'))
+  })
+})
+
+describe('timeoutDenyMessage', () => {
+  it('names the timeout, the minutes, and tells the model not to retry', () => {
+    const msg = timeoutDenyMessage(10)
+    expect(msg).toContain('10 minutes')
+    expect(msg).toMatch(/timeout/i)
+    expect(msg).toMatch(/not a denial/i)
+    expect(msg).toMatch(/do not retry/i)
+  })
+
+  it('is a non-empty string (wire-validator requires non-empty)', () => {
+    expect(timeoutDenyMessage(5).length).toBeGreaterThan(0)
+  })
+})
+
+describe('duplicateDenyMessage', () => {
+  it('tells the model to stop re-requesting and is non-empty', () => {
+    expect(duplicateDenyMessage).toMatch(/do not keep re-requesting/i)
+    expect(duplicateDenyMessage.length).toBeGreaterThan(0)
+  })
+})
+
+describe('isRecentTimeoutDuplicate', () => {
+  const WINDOW = 60 * 60_000
+  const NOW = 1_000_000_000_000
+
+  it('false when the signature was never recorded', () => {
+    expect(isRecentTimeoutDuplicate(new Map(), 'sig', NOW, WINDOW)).toBe(false)
+  })
+
+  it('true when the signature timed out within the window', () => {
+    const m = new Map([['sig', NOW - 5 * 60_000]])
+    expect(isRecentTimeoutDuplicate(m, 'sig', NOW, WINDOW)).toBe(true)
+  })
+
+  it('false when the timeout is older than the window', () => {
+    const m = new Map([['sig', NOW - 2 * WINDOW]])
+    expect(isRecentTimeoutDuplicate(m, 'sig', NOW, WINDOW)).toBe(false)
+  })
+
+  it('true exactly at the window boundary', () => {
+    const m = new Map([['sig', NOW - WINDOW]])
+    expect(isRecentTimeoutDuplicate(m, 'sig', NOW, WINDOW)).toBe(true)
+  })
+
+  it('only matches the exact signature', () => {
+    const m = new Map([[permissionSignature('t', 'Rentals'), NOW]])
+    expect(isRecentTimeoutDuplicate(m, permissionSignature('t', 'Land'), NOW, WINDOW)).toBe(false)
+    expect(isRecentTimeoutDuplicate(m, permissionSignature('t', 'Rentals'), NOW, WINDOW)).toBe(true)
+  })
+})

package/telegram-plugin/tests/scoped-approval.test.ts

@@ -3,7 +3,7 @@
  * the middle rung between "Allow once" and "🔁 Always".
  *
  * These pin the access-model invariants the adversarial review flagged as
- * load-bearing (reference/access-model.md "you hold the leash"):
+ * load-bearing (reference/rfcs/access-model.md "you hold the leash"):
  *   - no tool call can SEED a grant (first contact never auto-allows);
  *   - no tool call can EXTEND the window (fixed box — expiresAt is set once
  *     at the operator tap and never moves on a match);

package/telegram-plugin/tests/silence-poke.test.ts

@@ -528,7 +528,7 @@ describe('silence-poke — fallback handler errors do not break timer', () => {
 })
 
 // CC-4 from `docs/status-ask-cause-classes.md`: wording is load-bearing
-// (`reference/conversational-pacing.md` § Safety net). Snapshot the exact
+// (`reference/rfcs/conversational-pacing.md` § Safety net). Snapshot the exact
 // strings here so a refactor that drops a key phrase fails loud at test
 // time. If you genuinely need to change the wording, update the snapshot
 // AND the design doc together.