switchroom 0.15.37 → 0.15.39

package/telegram-plugin/over-ping-safety-net.ts

@@ -2,7 +2,7 @@
  * over-ping-safety-net.ts — pure decision predicate for #1674's
  * "at-most-one device-ping per turn" framework safety net.
  *
- * Background. `reference/conversational-pacing.md` beat 5 is
+ * Background. `reference/rfcs/conversational-pacing.md` beat 5 is
  * explicit: the model should deliver the answer as a fresh `reply`
  * omitting `disable_notification` (i.e. pinging the device once).
  * EXACTLY ONE ping per turn. The model occasionally violates this

package/telegram-plugin/scoped-approval.ts

@@ -9,7 +9,7 @@
  * "Allow" means for a narrow safe scope, disclosed honestly on the post-tap
  * card ("won't ask again about <breadth> for 30 min" vs "allowed once").
  *
- * Design contract (reference/access-model.md — "you hold the leash"):
+ * Design contract (reference/rfcs/access-model.md — "you hold the leash"):
  *
  *  - **Operator-authored only.** Every cache entry is created by an
  *    `allowFrom`-authenticated Telegram tap. No tool call can seed an

package/telegram-plugin/secret-detect/vault-error.ts

@@ -158,7 +158,7 @@ export function renderVaultCliError(
       // Route the operator at the Telegram-native equivalent for the
       // verb in flight — only `init` needs a one-time host shell.
       // Closes the "leave Telegram for a verb that exists in Telegram"
-      // anti-pattern from reference/talk-to-agents-from-anywhere.md.
+      // anti-pattern from reference/jobs/talk-to-agents-from-anywhere.md.
       return {
         suppressRaw: true,
         html:

package/telegram-plugin/silence-poke.ts

@@ -10,7 +10,7 @@
  * 75s, firm at 180s) and the 60s user-visible awareness ping were
  * retired: their success rate was 0-7% by the design's own KPI, and they
  * duplicated a job the draft thinking-lane now does natively. See
- * `reference/conversational-pacing.md` § Safety net.
+ * `reference/rfcs/conversational-pacing.md` § Safety net.
  *
  * What remains: ONE silence clock and ONE terminal action.
  *
@@ -323,7 +323,7 @@ export function silenceMsForKey(key: string, now: number): number | null {
  * Verbatim framework-fallback text — the user-visible "still working / still
  * thinking" message the gateway sends at the 300s threshold when the model
  * hasn't broken its own silence. Wording is load-bearing (see
- * `reference/conversational-pacing.md` § Safety net). Two principles:
+ * `reference/rfcs/conversational-pacing.md` § Safety net). Two principles:
  *
  *   1. The parenthetical `(no update from agent in N min)` is honest —
  *      distinguishes from "the agent said something" so users learn to trust

package/telegram-plugin/silent-reply-anchor.ts

@@ -3,7 +3,7 @@
  * "consecutive silent replies edit one growing message" UX fix.
  *
  * Background. Modern Claude 2.1.x on this fleet implements
- * conversational pacing (`reference/conversational-pacing.md` beats
+ * conversational pacing (`reference/rfcs/conversational-pacing.md` beats
  * 1 + 3 + 5) by calling the `reply` MCP tool multiple times in a
  * turn — a silent ack, silent per-step updates, and one pinged
  * final answer. The over-ping safety net (#1674) caps the

package/telegram-plugin/slot-banner-driver.ts

@@ -17,7 +17,7 @@
  * unpinned message.
  *
  * See #421 (banner pin lifecycle) and JTBD
- * `reference/track-plan-quota-live.md` ("at a glance").
+ * `reference/jobs/track-plan-quota-live.md` ("at a glance").
  */
 
 import type { BannerState } from './slot-banner.js';

package/telegram-plugin/startup-reset.ts

@@ -17,7 +17,7 @@
  * idempotent and has no user-visible side effects beyond clearing the
  * (probably-empty) pending-updates queue.
  *
- * Reference: reference/restart-and-know-what-im-running.md — "silent
+ * Reference: reference/jobs/restart-and-know-what-im-running.md — "silent
  * respawn. Agent comes back and the user has to guess whether it's
  * the same agent." A gateway stuck in a 409 loop is exactly that
  * failure mode.

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

@@ -0,0 +1,66 @@
+/**
+ * Unit tests for probeConnections — the boot-card surface for
+ * configured-but-unauthed MCP connections (P3). The probe only READS the
+ * host-computed snapshot at <agentDir>/.claude/connection-health.json, so
+ * we drive it with an injected readFileImpl (no fs / no broker).
+ */
+
+import { describe, it, expect } from 'bun:test'
+import { probeConnections } from '../gateway/boot-probes.js'
+
+const ENOENT = () => {
+  const e = new Error('ENOENT') as NodeJS.ErrnoException
+  e.code = 'ENOENT'
+  throw e
+}
+
+describe('probeConnections', () => {
+  it('OK (silent) when the snapshot file is absent — assume healthy', async () => {
+    const r = await probeConnections('/agent', { readFileImpl: ENOENT })
+    expect(r.status).toBe('ok')
+  })
+
+  it('OK when the snapshot is malformed JSON', async () => {
+    const r = await probeConnections('/agent', { readFileImpl: () => 'not json{' })
+    expect(r.status).toBe('ok')
+  })
+
+  it('OK when there are zero issues', async () => {
+    const r = await probeConnections('/agent', {
+      readFileImpl: () => JSON.stringify({ computedAt: 1, issues: [] }),
+    })
+    expect(r.status).toBe('ok')
+    expect(r.detail).toContain('all authed')
+  })
+
+  it('DEGRADED (never fail) with named servers + a fix when connections are unauthed', async () => {
+    const snapshot = {
+      computedAt: 1,
+      issues: [
+        { server: 'meta', key: 'meta/token', kind: 'missing', detail: 'x', fix: 'switchroom vault set meta/token --allow marko' },
+        { server: 'postiz', key: 'postiz/key', kind: 'missing', detail: 'y', fix: 'switchroom vault set postiz/key --allow marko' },
+      ],
+    }
+    const r = await probeConnections('/agent', { readFileImpl: () => JSON.stringify(snapshot) })
+    expect(r.status).toBe('degraded')
+    expect(r.detail).toContain('2 integration(s)')
+    expect(r.detail).toContain('meta')
+    expect(r.detail).toContain('postiz')
+    // nextStep carries the first fix + a pointer to doctor for the rest.
+    expect(r.nextStep).toContain('switchroom vault set meta/token')
+    expect(r.nextStep).toContain('+1 more')
+  })
+
+  it('dedupes servers in the detail count', async () => {
+    const snapshot = {
+      computedAt: 1,
+      issues: [
+        { server: 'meta', key: 'meta/a', kind: 'missing', detail: 'x', fix: 'fixa' },
+        { server: 'meta', key: 'meta/b', kind: 'acl', detail: 'y', fix: 'fixb' },
+      ],
+    }
+    const r = await probeConnections('/agent', { readFileImpl: () => JSON.stringify(snapshot) })
+    expect(r.status).toBe('degraded')
+    expect(r.detail).toContain('1 integration(s)')
+  })
+})

package/telegram-plugin/tests/gateway-startup-reset.test.ts

@@ -16,7 +16,7 @@ import { clearStaleTelegramPollingState } from "../startup-reset";
  *
  * These tests pin that behaviour so we don't accidentally remove the
  * call during a future refactor and reintroduce the silent-respawn
- * anti-pattern from reference/restart-and-know-what-im-running.md.
+ * anti-pattern from reference/jobs/restart-and-know-what-im-running.md.
  */
 
 describe("clearStaleTelegramPollingState", () => {

package/telegram-plugin/tests/inbound-delivery-machine.test.ts

@@ -1,7 +1,7 @@
 /**
  * Property tests for `inbound-delivery-machine.ts`.
  *
- * Per RFC `docs/rfcs/inbound-delivery-state-machine.md`: 5 invariants
+ * Per RFC `reference/rfcs/inbound-delivery-state-machine.md`: 5 invariants
  * validated over arbitrary event schedules. A counterexample is the
  * minimal evidence that the machine has a bug. The wedge-cluster
  * bugs (v0.12.22 boot-wedge, overlapping-turn silence, #1564 sibling

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.

package/telegram-plugin/tests/tool-filter.test.ts

@@ -0,0 +1,87 @@
+/**
+ * Unit tests for the switchroom-telegram tool-surface right-sizing (P4):
+ * connection gating of linear_* (A) + per-tool alwaysLoad pins for the hot
+ * path (B). Pure function — no bridge.ts import (which has side effects).
+ */
+
+import { describe, it, expect } from 'bun:test'
+import {
+  buildEffectiveToolSchemas,
+  ALWAYS_LOAD_TOOLS,
+  LINEAR_TOOLS,
+  type NamedTool,
+} from '../bridge/tool-filter.js'
+
+// A representative slice mirroring the real TOOL_SCHEMAS names.
+const SAMPLE: NamedTool[] = [
+  { name: 'reply', description: 'r' },
+  { name: 'stream_reply', description: 's' },
+  { name: 'get_recent_messages', description: 'g' },
+  { name: 'react', description: 'k' },
+  { name: 'edit_message', description: 'e' },
+  { name: 'send_typing', description: 't' },
+  { name: 'download_attachment', description: 'd' },
+  { name: 'ask_user', description: 'a' }, // cold
+  { name: 'send_gif', description: 'gif' }, // cold
+  { name: 'vault_request_access', description: 'v' }, // cold
+  { name: 'linear_agent_activity', description: 'la' },
+  { name: 'linear_create_issue', description: 'lc' },
+  { name: 'linear_agent_setup', description: 'ls' },
+]
+
+const names = (tools: NamedTool[]) => tools.map((t) => t.name)
+const metaOf = (tools: Array<NamedTool & { _meta?: unknown }>, n: string) =>
+  tools.find((t) => t.name === n)?._meta
+
+describe('buildEffectiveToolSchemas — connection gating (A)', () => {
+  it('drops all linear_* tools when Linear is NOT enabled', () => {
+    const out = buildEffectiveToolSchemas(SAMPLE, { linearEnabled: false })
+    for (const t of LINEAR_TOOLS) expect(names(out)).not.toContain(t)
+    // non-linear tools all survive
+    expect(names(out)).toContain('reply')
+    expect(names(out)).toContain('ask_user')
+    expect(out.length).toBe(SAMPLE.length - LINEAR_TOOLS.size)
+  })
+
+  it('keeps linear_* tools when Linear IS enabled', () => {
+    const out = buildEffectiveToolSchemas(SAMPLE, { linearEnabled: true })
+    for (const t of LINEAR_TOOLS) expect(names(out)).toContain(t)
+    expect(out.length).toBe(SAMPLE.length)
+  })
+})
+
+describe('buildEffectiveToolSchemas — per-tool deferral pins (B)', () => {
+  it('pins exactly the hot tools with _meta anthropic/alwaysLoad', () => {
+    const out = buildEffectiveToolSchemas(SAMPLE, { linearEnabled: true })
+    for (const hot of ALWAYS_LOAD_TOOLS) {
+      expect(metaOf(out, hot)).toEqual({ 'anthropic/alwaysLoad': true })
+    }
+  })
+
+  it('the reply path (reply/stream_reply) is ALWAYS pinned — never defers', () => {
+    const out = buildEffectiveToolSchemas(SAMPLE, { linearEnabled: false })
+    expect(metaOf(out, 'reply')).toEqual({ 'anthropic/alwaysLoad': true })
+    expect(metaOf(out, 'stream_reply')).toEqual({ 'anthropic/alwaysLoad': true })
+  })
+
+  it('cold tools carry NO _meta (so they defer under tool-search)', () => {
+    const out = buildEffectiveToolSchemas(SAMPLE, { linearEnabled: true })
+    for (const cold of ['ask_user', 'send_gif', 'vault_request_access', 'linear_create_issue']) {
+      expect(metaOf(out, cold)).toBeUndefined()
+    }
+  })
+})
+
+describe('buildEffectiveToolSchemas — purity', () => {
+  it('does not mutate the input array or its objects', () => {
+    const input: NamedTool[] = [{ name: 'reply' }, { name: 'send_gif' }]
+    const snapshot = JSON.stringify(input)
+    buildEffectiveToolSchemas(input, { linearEnabled: true })
+    expect(JSON.stringify(input)).toBe(snapshot)
+  })
+
+  it('preserves order', () => {
+    const out = buildEffectiveToolSchemas(SAMPLE, { linearEnabled: true })
+    expect(names(out)).toEqual(names(SAMPLE))
+  })
+})

package/telegram-plugin/tests/turn-flush-safety.test.ts

@@ -237,7 +237,7 @@ describe('decideTurnFlush', () => {
   // Regression guard for the redundant-follow-up-message fix: this reverts
   // the #1291 post-reply-tail flush, which posted a duplicate recap on
   // essentially every turn because the model habitually writes a closing
-  // summary after its final reply. See reference/conversational-pacing.md
+  // summary after its final reply. See reference/rfcs/conversational-pacing.md
   // — "the framework owns the beat; the model authors the words".
   describe('reply-called turns never flush trailing terminal text', () => {
     it('skips even when a long substantive tail follows the reply', () => {

package/telegram-plugin/turn-flush-safety.ts

@@ -172,7 +172,7 @@ export interface FlushDecisionInput {
  * message second-guesses an explicit reply and posts a redundant duplicate
  * on essentially every turn, because the model habitually writes a closing
  * summary. The framework owns the *beat*; the model authors the *words*
- * and emits them via reply (`reference/conversational-pacing.md`).
+ * and emits them via reply (`reference/rfcs/conversational-pacing.md`).
  *
  * (This reverts the #1291 post-reply-tail flush. Its intent — catch a
  * soft-commit reply followed by the real answer in terminal text only —

package/telegram-plugin/uat/assertions.ts

@@ -395,7 +395,7 @@ export async function waitForCardPhase(
  * The actual card render uses emoji markers in the header: `✅` for
  * done, `❌` for errors, `⚙️` while working (foreground), `🌀` for
  * Background (parent done but fleet still running, see #862 /
- * reference/conversational-pacing.md),
+ * reference/rfcs/conversational-pacing.md),
  * and `⏳` during the boot-card window. These markers are stable
  * enough to key on for UAT — finer parsing (checklist items,
  * sub-agent row content) is out of scope.

package/telegram-plugin/uat/scenarios/bg-sub-agent-dispatch-dm.test.ts

@@ -1,6 +1,6 @@
 /**
  * Background sub-agent visibility scenario — closes #709 / #776 / #782 / #788
- * (the four-issue family analysed in `reference/sub-agent-visibility-rfc.md`).
+ * (the four-issue family analysed in `reference/rfcs/sub-agent-visibility.md`).
  *
  * Verifies three acceptance criteria from the RFC in a single run because
  * they share setup:

package/telegram-plugin/uat/scenarios/fuzz-extended-dm.test.ts

@@ -149,7 +149,7 @@ const FUZZ_CASES: readonly FuzzCase[] = [
   // The conservative regex set in `telegram-plugin/inbound-classifier.ts`
   // captures 10 standalone "ping" patterns that count toward the
   // primary lagging KPI `inbound_status_query`. Each fire is a JTBD
-  // failure (`reference/know-what-my-agent-is-doing.md`), so we
+  // failure (`reference/jobs/know-what-my-agent-is-doing.md`), so we
   // want every variant to (a) reach the agent unchanged, (b)
   // produce a sensible reply (no crash, no loop, no ghosting).
   // Tracks cause class CC-7 from

package/telegram-plugin/uat/scenarios/jtbd-fast-ack-dm.test.ts

@@ -1,7 +1,7 @@
 /**
  * JTBD scenario — guaranteed fast acknowledgement (human-feel UX epic).
  *
- * Serves: `reference/conversational-pacing.md` and the JTBD
+ * Serves: `reference/rfcs/conversational-pacing.md` and the JTBD
  * "talking to my agent feels like talking to a capable person".
  *
  * A person you message answers in a beat — "got it", "on it, checking

package/telegram-plugin/uat/scenarios/jtbd-fast-trivial-dm.test.ts

@@ -1,7 +1,7 @@
 /**
  * JTBD scenario — short happy path: trivial questions reply FAST.
  *
- * Serves: `reference/know-what-my-agent-is-doing.md` — the short-path
+ * Serves: `reference/jobs/know-what-my-agent-is-doing.md` — the short-path
  * contract: a question with no real work should produce a plain reply
  * with no ceremony (no soft-commit, no progress chunks) within a tight
  * budget. Users judge agent speed on THIS path more than any other.
@@ -12,7 +12,7 @@
  *
  * ## Targets
  *
- * From `reference/conversational-pacing.md` and the post-v0.12.22
+ * From `reference/rfcs/conversational-pacing.md` and the post-v0.12.22
  * baseline measurements:
  *
  *   - **TTFO p95 (vision target):** < 30s — the published contract.

package/telegram-plugin/uat/scenarios/jtbd-forwarded-burst-dm.test.ts

@@ -1,7 +1,7 @@
 /**
  * JTBD scenario — forwarded burst / split paste coalesces into ONE turn.
  *
- * Serves: `reference/steer-or-queue-mid-flight.md` — the "Forwarded
+ * Serves: `reference/jobs/steer-or-queue-mid-flight.md` — the "Forwarded
  * burst / split paste" UAT prompt. When several messages land in quick
  * succession from the same sender (a forward of 3-4 messages, or a long
  * paste Telegram split into chunks), inbound coalescing must merge them