switchroom 0.15.36 → 0.15.38

package/telegram-plugin/gateway/linear-auth-watch.ts

@@ -0,0 +1,102 @@
+/**
+ * Proactive Linear auth watch (FIX 3 — observability).
+ *
+ * Before this, Linear auth was only ever checked REACTIVELY: a refresh (and the
+ * "🔑 Linear auth needs you" operator alert) happened only when an agent made a
+ * live Linear call and got a 401. A linear-enabled agent that rarely calls
+ * Linear could therefore sit dead-auth (missing bundle / revoked refresh /
+ * silently-expired token) completely unnoticed until the moment it needed
+ * Linear.
+ *
+ * This runs a small check on boot + on an interval (mirrors quota-watch):
+ *   - bundle missing/invalid  → fire the operator alert (no_bundle) NOW.
+ *   - bundle present + access token within the refresh skew → proactively
+ *     rotate it (so the next real call never eats a 401), and surface a revoked
+ *     refresh token via the operator alert.
+ *   - bundle present + token fresh → nothing.
+ *
+ * Pure orchestration over injected deps so it is unit-testable without a broker
+ * or the network. The gateway wires the broker-backed deps + notifyLinearAuthDead.
+ */
+
+import {
+  parseBundle,
+  needsRefresh,
+  type PerformRefreshResult,
+} from '../../src/linear/oauth-refresh.js'
+
+export type LinearAuthWatchStatus =
+  | 'disabled'
+  | 'fresh'
+  | 'no_bundle'
+  | 'refreshed'
+  | 'revoked'
+  | 'refresh_failed'
+
+export interface LinearAuthWatchDeps {
+  agent: string
+  /** Whether this agent has linear_agent enabled (reads config). */
+  linearEnabled: () => boolean
+  /** Read the raw JSON bundle from linear/<agent>/oauth (broker). */
+  readBundle: () => Promise<string | null>
+  /** Rotate the token via the stored bundle (performLinearRefresh over broker). */
+  refresh: () => Promise<PerformRefreshResult>
+  /** Operator alert (gateway's notifyLinearAuthDead). */
+  onAuthDead: (info: { agent: string; reason: 'no_bundle' | 'revoked'; detail: string }) => void
+  /** Epoch seconds (injectable for tests). */
+  nowSec?: () => number
+  log?: (line: string) => void
+}
+
+/**
+ * One proactive check. Never throws — returns a status the caller can log.
+ */
+export async function runLinearAuthCheck(deps: LinearAuthWatchDeps): Promise<LinearAuthWatchStatus> {
+  const log = deps.log ?? (() => {})
+  if (!deps.linearEnabled()) return 'disabled'
+
+  let raw: string | null
+  try {
+    raw = await deps.readBundle()
+  } catch (err) {
+    // A broker read failure is transient infra, not an auth problem — don't
+    // page the operator, just log.
+    log(`telegram gateway: linear-auth-watch agent=${deps.agent} bundle read error: ${(err as Error).message}\n`)
+    return 'refresh_failed'
+  }
+
+  const bundle = parseBundle(raw)
+  if (!bundle) {
+    // The silent-setup-failure case: linear_agent is enabled but no refresh
+    // bundle was ever stored. Surface it proactively.
+    log(`telegram gateway: linear-auth-watch agent=${deps.agent} — no refresh bundle (proactive)\n`)
+    deps.onAuthDead({ agent: deps.agent, reason: 'no_bundle', detail: 'proactive watch: linear/<agent>/oauth missing or invalid' })
+    return 'no_bundle'
+  }
+
+  const now = deps.nowSec ? deps.nowSec() : Math.floor(Date.now() / 1000)
+  if (!needsRefresh(bundle.expiresAt, now)) {
+    // Fresh, or expiry-untracked (older bundle) — the reactive-on-401 path
+    // covers untracked bundles; nothing to do proactively.
+    return 'fresh'
+  }
+
+  // Within the refresh skew → rotate now so the next real call never 401s.
+  const res = await deps.refresh()
+  if (res.ok) {
+    log(`telegram gateway: linear-auth-watch agent=${deps.agent} proactively refreshed (was near expiry)\n`)
+    return 'refreshed'
+  }
+  if (res.reason === 'revoked') {
+    log(`telegram gateway: linear-auth-watch agent=${deps.agent} refresh REVOKED (proactive)\n`)
+    deps.onAuthDead({ agent: deps.agent, reason: 'revoked', detail: res.detail })
+    return 'revoked'
+  }
+  if (res.reason === 'no_bundle') {
+    deps.onAuthDead({ agent: deps.agent, reason: 'no_bundle', detail: res.detail })
+    return 'no_bundle'
+  }
+  // Transient (network/http_error/bad_response/persist_failed) — log, don't page.
+  log(`telegram gateway: linear-auth-watch agent=${deps.agent} proactive refresh failed reason=${res.reason}\n`)
+  return 'refresh_failed'
+}

package/telegram-plugin/gateway/linear-setup.ts

@@ -0,0 +1,196 @@
+/**
+ * `linear_agent_setup` MCP tool — in-container, operator-approved Linear
+ * `actor=app` OAuth provisioning (FIX 2).
+ *
+ * Background: `switchroom linear-agent setup` is host-only (it writes the
+ * vault file directly with the operator passphrase). Run from inside an agent
+ * container it silently no-ops — there is no mounted vault and no passphrase —
+ * which is exactly how clerk/carrie ended up with an access token but no
+ * refresh bundle (a daily 401 with no self-heal). This tool gives the agent a
+ * sanctioned in-container path that uses ONLY operator-approved primitives:
+ *
+ *   1. `action: "authorize_url"` — pure. Returns the browser authorize URL the
+ *      operator opens to consent. No side effects, no approval.
+ *   2. `action: "complete"` — exchanges the `code` from the redirect for an
+ *      access token + refresh token, then writes BOTH
+ *      `linear/<agent>/token` (access) and `linear/<agent>/oauth` (the durable
+ *      refresh bundle) via the broker. Creating these NEW keys requires a
+ *      write-grant — `vault_request_access(scope: "write")` for each, which the
+ *      operator approves. On a vault denial the tool returns the exact
+ *      next-step text (mirrors `linear_agent_activity`'s vault_request_access
+ *      guidance) rather than failing opaquely.
+ *
+ * The durable `secrets[]` ACL + the `linear_agent` config block are added by
+ * the agent via `config_propose_edit` (also operator-approved) — see the
+ * returned guidance and the self-service playbook. The secret VALUES never
+ * pass through config (no leak); only the access token + bundle go to the
+ * broker, and the OAuth client_secret/code are used in-process for the
+ * exchange and never stored or logged.
+ */
+
+import { putViaBroker, readVaultTokenFile } from '../../src/vault/broker/client.js'
+import {
+  buildLinearAuthorizeUrl,
+  exchangeLinearAuthCode,
+  serializeBundle,
+} from '../../src/linear/oauth-refresh.js'
+
+export type ToolTextResult = { content: Array<{ type: string; text: string }> }
+
+/** Result of a single broker put (new-key create). */
+type PutOutcome = { kind: 'ok' } | { kind: 'denied'; msg: string } | { kind: 'not_found'; msg: string } | { kind: 'unreachable'; msg: string }
+
+export interface LinearSetupDeps {
+  /** Agent slug (defaults to SWITCHROOM_AGENT_NAME). */
+  agent?: string
+  /** Injectable fetch (tests). */
+  fetchImpl?: typeof fetch
+  /** Write `linear/<agent>/token`. Defaults to a broker put. */
+  putToken?: (agent: string, accessToken: string) => Promise<PutOutcome>
+  /** Write `linear/<agent>/oauth` (the JSON bundle). Defaults to a broker put. */
+  putBundle?: (agent: string, bundleJson: string) => Promise<PutOutcome>
+  /** Log sink — stderr in production. NEVER receives secret values. */
+  log?: (line: string) => void
+}
+
+const tokenKey = (agent: string) => `linear/${agent}/token`
+const bundleKey = (agent: string) => `linear/${agent}/oauth`
+
+/** Default broker put: path-as-identity + the agent's standing write-grant
+ *  token (so a new key authorized by `vault_request_access(write)` can be
+ *  created). Mirrors `brokerRefreshIO` in linear-activity.ts. */
+function defaultPut(agent: string, key: string, value: string): Promise<PutOutcome> {
+  const token = readVaultTokenFile(agent) ?? undefined
+  const opt = token ? { token } : {}
+  return putViaBroker(key, { kind: 'string', value }, opt).then((r) => {
+    if (r.kind === 'ok') return { kind: 'ok' as const }
+    if (r.kind === 'unreachable') return { kind: 'unreachable' as const, msg: r.msg }
+    if (r.kind === 'not_found') return { kind: 'not_found' as const, msg: r.msg }
+    return { kind: 'denied' as const, msg: r.msg }
+  })
+}
+
+function text(s: string): ToolTextResult {
+  return { content: [{ type: 'text', text: s }] }
+}
+
+/**
+ * Guidance the agent shows the operator + itself after a write is blocked
+ * because the key doesn't exist yet (no write-grant). This is the expected
+ * first-run path: the operator approves the grant, then the agent retries.
+ */
+function writeGrantGuidance(agent: string): string {
+  return (
+    `I need write access to store the Linear credentials. Call:\n` +
+    `• vault_request_access(key: "${tokenKey(agent)}", scope: "write", reason: "store Linear app access token")\n` +
+    `• vault_request_access(key: "${bundleKey(agent)}", scope: "write", reason: "store Linear OAuth refresh bundle")\n` +
+    `Once the operator approves both, re-run linear_agent_setup with action "complete" (same code is single-use — if it expired, re-open the authorize URL first).`
+  )
+}
+
+/** Guidance for the durable config (ACL + linear_agent block) the agent emits
+ *  after the values are stored, via the operator-approved config_propose_edit. */
+function durableConfigGuidance(agent: string): string {
+  return (
+    `Stored. To make this durable (survive restarts + enable auto-refresh), propose a config edit ` +
+    `(config_propose_edit) that, under agents.${agent}:\n` +
+    `  • adds channels.telegram.linear_agent: { enabled: true, token: "vault:${tokenKey(agent)}" }\n` +
+    `  • adds "${tokenKey(agent)}" and "${bundleKey(agent)}" to secrets[]\n` +
+    `Then the operator approves it and you restart to pick up the linear_agent block.`
+  )
+}
+
+/**
+ * Run the `linear_agent_setup` tool. Validates args, performs the requested
+ * step, and returns actionable MCP text. Never throws on a network/vault
+ * failure — returns guidance the agent can act on.
+ */
+export async function runLinearAgentSetup(
+  args: Record<string, unknown>,
+  deps: LinearSetupDeps = {},
+): Promise<ToolTextResult> {
+  const log = deps.log ?? ((s) => process.stderr.write(s))
+  const agent = deps.agent ?? process.env.SWITCHROOM_AGENT_NAME ?? '-'
+  if (agent === '-' || !/^[a-z][a-z0-9_-]{0,63}$/.test(agent)) {
+    return text(`linear_agent_setup failed: could not resolve a valid agent name (got '${agent}').`)
+  }
+
+  const action = args.action as string | undefined
+  if (action !== 'authorize_url' && action !== 'complete') {
+    return text(`linear_agent_setup failed: action must be "authorize_url" or "complete".`)
+  }
+
+  const clientId = (args.client_id as string | undefined)?.trim()
+  const redirectUri = (args.redirect_uri as string | undefined)?.trim()
+  if (!clientId) return text('linear_agent_setup failed: client_id is required.')
+  if (!redirectUri || !/^https?:\/\//.test(redirectUri)) {
+    return text('linear_agent_setup failed: redirect_uri is required and must be an http(s) URL registered on the Linear OAuth app.')
+  }
+
+  if (action === 'authorize_url') {
+    const url = buildLinearAuthorizeUrl({ clientId, redirectUri })
+    return text(
+      `Open this URL in a browser to authorize <b>${agent}</b> as a Linear app actor (actor=app):\n\n${url}\n\n` +
+        `After you approve, Linear redirects to ${redirectUri}?code=… (it may show a blank/error page — that's fine). ` +
+        `Copy the code value from the URL bar, then run linear_agent_setup with action "complete", the same client_id + redirect_uri, ` +
+        `your client_secret, and that code.`,
+    )
+  }
+
+  // action === 'complete'
+  const clientSecret = (args.client_secret as string | undefined)?.trim()
+  const code = (args.code as string | undefined)?.trim()
+  if (!clientSecret) return text('linear_agent_setup failed: client_secret is required for action "complete".')
+  if (!code) return text('linear_agent_setup failed: code (from the redirect URL) is required for action "complete".')
+
+  const exchanged = await exchangeLinearAuthCode(
+    { clientId, clientSecret, code, redirectUri },
+    deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {},
+  )
+  if (!exchanged.ok) {
+    log(`telegram gateway: linear_agent_setup exchange failed agent=${agent} reason=${exchanged.reason}\n`)
+    if (exchanged.reason === 'bad_code') {
+      return text(
+        `linear_agent_setup failed: Linear rejected the authorization code (expired, already used, or wrong redirect_uri). ` +
+          `Re-run action "authorize_url", open the fresh URL, and copy a new code.`,
+      )
+    }
+    return text(`linear_agent_setup failed: token exchange ${exchanged.reason} — ${exchanged.detail}. Retry shortly.`)
+  }
+
+  const bundle = serializeBundle({
+    clientId,
+    clientSecret,
+    refreshToken: exchanged.refreshToken,
+    expiresAt: exchanged.expiresAt,
+  })
+
+  const putBundle = deps.putBundle ?? ((a, j) => defaultPut(a, bundleKey(a), j))
+  const putToken = deps.putToken ?? ((a, t) => defaultPut(a, tokenKey(a), t))
+
+  // Write the bundle FIRST (same ordering rationale as performLinearRefresh:
+  // never leave a fresh access token whose refresh bundle didn't persist).
+  const b = await putBundle(agent, bundle)
+  if (b.kind !== 'ok') {
+    if (b.kind === 'not_found' || b.kind === 'denied') {
+      return text(writeGrantGuidance(agent))
+    }
+    log(`telegram gateway: linear_agent_setup bundle write ${b.kind} agent=${agent}\n`)
+    return text(`linear_agent_setup failed: couldn't store the refresh bundle (broker ${b.kind}: ${b.msg}).`)
+  }
+  const t = await putToken(agent, exchanged.accessToken)
+  if (t.kind !== 'ok') {
+    if (t.kind === 'not_found' || t.kind === 'denied') {
+      return text(writeGrantGuidance(agent))
+    }
+    log(`telegram gateway: linear_agent_setup token write ${t.kind} agent=${agent}\n`)
+    return text(`linear_agent_setup failed: couldn't store the access token (broker ${t.kind}: ${t.msg}).`)
+  }
+
+  const hours = Math.max(1, Math.round((exchanged.expiresAt - Date.now() / 1000) / 3600))
+  log(`telegram gateway: linear_agent_setup stored token+bundle agent=${agent} (expires ~${hours}h)\n`)
+  return text(
+    `✅ Linear app token + refresh bundle stored for ${agent} (access token expires in ~${hours}h; it now auto-renews).\n\n` +
+      durableConfigGuidance(agent),
+  )
+}

package/telegram-plugin/gateway/permission-card-origin.ts

@@ -0,0 +1,62 @@
+/**
+ * Pure origin-recovery for a permission/approval card when the gateway's live
+ * `currentTurn` has already been nulled.
+ *
+ * Why this exists (marko Rentals-budget incident, 2026-06-17). A
+ * supergroup-owned agent that delivers its final answer as plain transcript
+ * text — never calling the `reply` tool — has its turn force-closed by the
+ * gateway's orphaned-reply backstop ~30s later, which nulls `currentTurn`. If
+ * the single claude session is still running and then calls a permission-gated
+ * tool (the real case: retrying `meta_ads_set_budget` after a first card had
+ * auto-denied), the gate fires with `currentTurn == null`. The card emitter
+ * then fell through to broadcasting the card to the operator-DM allowlist,
+ * thread-stripped — so the card never reached the forum topic the operator was
+ * working in. Unanswered there, it hit the 10-minute TTL and auto-denied, and
+ * an explicitly-approved budget change silently never ran.
+ *
+ * A switchroom agent runs exactly ONE claude session, so a tool permission can
+ * only belong to the turn that session most recently had open. We recover that
+ * origin from the bounded recently-started turn registry: the most-recently-
+ * started turn still within `maxAgeMs`. A turn force-closed by the backstop is,
+ * by construction, seconds-to-minutes old, so the freshness ceiling costs
+ * nothing for the incident class while keeping a long-idle agent's stale
+ * registry entry from mis-routing a much later permission into an old topic —
+ * beyond the ceiling we return null and the caller keeps the existing
+ * operator-DM fan-out. This only ever ADDS topic recovery; it never changes the
+ * idle/turn-less path.
+ */
+
+/** The subset of a turn this recovery needs — kept structural so the gateway's
+ *  richer `CurrentTurn` satisfies it without a cast. */
+export interface RecoverableTurn {
+  sessionChatId: string
+  sessionThreadId: number | undefined
+  startedAt: number
+}
+
+export interface PermissionCardOrigin {
+  chatId: string
+  threadId: number | undefined
+}
+
+/**
+ * Pick the most-recently-started turn within the freshness window as the
+ * permission card's origin, or null when none qualifies (caller falls back to
+ * the operator-DM fan-out). Order-independent — selects by `startedAt`, not by
+ * the iteration order of the source registry, so it is robust to any
+ * out-of-order insertion.
+ */
+export function pickRecoveredPermissionOrigin(
+  recentTurns: Iterable<RecoverableTurn>,
+  now: number,
+  maxAgeMs: number,
+): PermissionCardOrigin | null {
+  let best: RecoverableTurn | null = null
+  for (const t of recentTurns) {
+    if (now - t.startedAt > maxAgeMs) continue
+    if (best == null || t.startedAt >= best.startedAt) best = t
+  }
+  return best == null
+    ? null
+    : { chatId: best.sessionChatId, threadId: best.sessionThreadId }
+}

package/telegram-plugin/gateway/permission-timeout.ts

@@ -0,0 +1,70 @@
+/**
+ * Pure helpers for permission-card TIMEOUT handling — making a "no operator
+ * responded" auto-deny distinguishable from a deliberate denial, and
+ * suppressing the duplicate card a model raises when it retries the identical
+ * call after such a timeout.
+ *
+ * Background (marko Rentals-budget loop, 2026-06-17). switchroom forwards a
+ * permission verdict to claude as `{ behavior, message? }`; with no `message`,
+ * claude renders the generic "the user said: Denied". A 10-minute TTL
+ * auto-deny was therefore indistinguishable from a real operator "Deny", so
+ * the model read it as transient and retried the SAME tool call — re-raising
+ * an identical card 10 minutes later, in a loop the operator never asked for.
+ *
+ * Two levers, both pure here and wired in gateway.ts:
+ *  1. `timeoutDenyMessage` — the `message` we attach ONLY to a TTL auto-deny,
+ *     telling the model it was a timeout (not a denial) and not to retry.
+ *  2. `permissionSignature` + `isRecentTimeoutDuplicate` — recognise a retry of
+ *     the exact same (tool, input) shortly after it timed out, so the gateway
+ *     can short-circuit it (deny with `duplicateDenyMessage`) WITHOUT posting a
+ *     second identical card. The suppression is reset on operator activity
+ *     (handled gateway-side), so it only ever holds while the operator is
+ *     genuinely absent — re-showing a card to an absent operator is the noise
+ *     this removes.
+ */
+
+// NUL — can appear in neither a tool name nor a rendered input preview, so it
+// safely delimits the two halves of a signature (a printable separator could
+// collide: ("a b","c") vs ("a","b c")). Built at runtime so the SOURCE file
+// stays plain text (a literal NUL byte would make git treat it as binary).
+const SIGNATURE_SEP = String.fromCharCode(0)
+
+/**
+ * Stable identity for a permission request: the tool plus its input preview
+ * (the same string the card renders). Same tool + same preview ⇒ same action.
+ */
+export function permissionSignature(toolName: string, inputPreview: string): string {
+  return toolName + SIGNATURE_SEP + inputPreview
+}
+
+/** The `message` attached to a TTL auto-deny so the model treats it as a
+ *  timeout, not a denial, and does not retry the identical call. */
+export function timeoutDenyMessage(timeoutMinutes: number): string {
+  return (
+    `No operator responded within ${timeoutMinutes} minutes, so this request timed out. ` +
+    `This is a TIMEOUT, not a denial — the operator is likely away. ` +
+    `Do NOT retry this exact action automatically. Tell the user it is still ` +
+    `awaiting their approval, then continue with other work or stop.`
+  )
+}
+
+/** The `message` attached when we short-circuit a duplicate retry of an
+ *  already-timed-out request (no new card posted). */
+export const duplicateDenyMessage =
+  `This exact action already timed out awaiting the operator, and they have not ` +
+  `responded since. Do NOT keep re-requesting it — tell the user it needs their ` +
+  `approval when they are back, and move on to other work or stop.`
+
+/**
+ * True when `sig` timed out within `windowMs` of `now` (so a fresh request for
+ * it is a retry to suppress). `timeouts` maps signature → last-timeout epoch ms.
+ */
+export function isRecentTimeoutDuplicate(
+  timeouts: ReadonlyMap<string, number>,
+  sig: string,
+  now: number,
+  windowMs: number,
+): boolean {
+  const at = timeouts.get(sig)
+  return at != null && now - at <= windowMs
+}

package/telegram-plugin/gateway/prefix-warmup.ts

@@ -1,7 +1,7 @@
 /**
  * Prefix-cache warmup turn — opt-in cold-start TTFO optimization.
  *
- * Per cold-start TTFO RFC (docs/rfcs/cold-start-ttfo.md, PR #1589),
+ * Per cold-start TTFO RFC (reference/rfcs/cold-start-ttfo.md, PR #1589),
  * Option A. On every bridge-up after a restart, synthesize a synthetic
  * inbound (`__WARMUP_PING__`, meta.source="warmup") and deliver it to
  * the just-registered bridge. Claude processes the message — paying

package/telegram-plugin/gateway/webhook-ingest-server.test.ts

@@ -1,6 +1,6 @@
 /**
  * Tests for the peercred-gated webhook ingest UDS server
- * (RFC docs/rfcs/webhook-via-gateway-socket.md).
+ * (RFC reference/rfcs/webhook-via-gateway-socket.md).
  *
  * MUST run under `bun test`: the peer-credential gate calls
  * `getPeerCred` (bun:ffi getsockopt SO_PEERCRED), which returns null

package/telegram-plugin/gateway/webhook-ingest-server.ts

@@ -1,5 +1,5 @@
 /**
- * Webhook ingest UDS server (RFC docs/rfcs/webhook-via-gateway-socket.md).
+ * Webhook ingest UDS server (RFC reference/rfcs/webhook-via-gateway-socket.md).
  *
  * A dedicated, peercred-gated Unix socket the host-side web receiver
  * forwards verified webhook events to. It is deliberately SEPARATE from

package/telegram-plugin/hooks/subagent-tracker-pretool.mjs

@@ -20,7 +20,7 @@
  *        writing to a registry.db nobody read, leaving every bg sub-agent
  *        invisible to the watcher. Surfaced by
  *        bg-sub-agent-dispatch-dm.test.ts; see RFC Phase 2 §Bug 2 in
- *        reference/sub-agent-visibility-rfc.md.
+ *        reference/rfcs/sub-agent-visibility.md.
  *     3. process.cwd() (legacy fallback for ad-hoc invocations).
  *
  * Performance: the actual DB write is deferred via setImmediate (Node 22+

package/telegram-plugin/interrupt-marker.ts

@@ -1,5 +1,5 @@
 /**
- * `!`-prefix interrupt marker — closes #575 / part of `reference/steer-or-queue-mid-flight.md`.
+ * `!`-prefix interrupt marker — closes #575 / part of `reference/jobs/steer-or-queue-mid-flight.md`.
  *
  * The product contract: when the user starts a Telegram message with
  * `!`, they're saying "drop what you're doing and handle this

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