switchroom 0.15.36 → 0.15.37

package/telegram-plugin/gateway/gateway.ts

@@ -487,7 +487,10 @@ import {
   listGrantsViaBroker,
   revokeGrantViaBroker,
 } from '../../src/vault/broker/client.js'
-import { emitLinearAgentActivity, createLinearIssue } from './linear-activity.js'
+import { emitLinearAgentActivity, createLinearIssue, buildLinearAuthDeadMessage, brokerRefreshIO, type LinearAuthDeadReason } from './linear-activity.js'
+import { runLinearAgentSetup } from './linear-setup.js'
+import { runLinearAuthCheck } from './linear-auth-watch.js'
+import { performLinearRefresh } from '../../src/linear/oauth-refresh.js'
 import {
   approvalRequest,
   approvalConsume,
@@ -6883,6 +6886,7 @@ const ALLOWED_TOOLS = new Set([
   'request_secret',
   'linear_agent_activity',
   'linear_create_issue',
+  'linear_agent_setup',
 ])
 
 async function executeToolCall(tool: string, args: Record<string, unknown>): Promise<unknown> {
@@ -6932,6 +6936,8 @@ async function executeToolCall(tool: string, args: Record<string, unknown>): Pro
       return executeLinearAgentActivity(args)
     case 'linear_create_issue':
       return executeLinearCreateIssue(args)
+    case 'linear_agent_setup':
+      return executeLinearAgentSetup(args)
     default:
       throw new Error(`unknown tool: ${tool}`)
   }
@@ -6963,12 +6969,66 @@ async function executeSendChecklist(args: Record<string, unknown>): Promise<{ co
   return { content: [{ type: 'text', text: `checklist sent (id: ${sent.message_id})` }] }
 }
 
+/**
+ * Per-(agent,reason) cooldown for the Linear-auth-dead operator alert. The
+ * triggering 401 recurs on every Linear call once the token expires, so
+ * without a cooldown the operator would be paged on every capture/activity.
+ * One alert per reason per window is enough to surface the action item.
+ */
+const linearAuthAlertLast = new Map<string, number>()
+const LINEAR_AUTH_ALERT_COOLDOWN_MS = 6 * 60 * 60 * 1000
+
+/**
+ * Surface an un-healable Linear auth failure (no refresh bundle / revoked
+ * refresh token) to the operator as a Telegram message — not just a gateway
+ * log line. Deduped per (agent,reason) and gated by SWITCHROOM_LINEAR_AUTH_ALERT=0.
+ * Best-effort: a failed send never affects the agent's turn.
+ */
+function notifyLinearAuthDead(info: { agent: string; reason: LinearAuthDeadReason; detail: string }): void {
+  if (process.env.SWITCHROOM_LINEAR_AUTH_ALERT === '0') return
+  const key = `${info.agent}:${info.reason}`
+  const now = Date.now()
+  const last = linearAuthAlertLast.get(key)
+  if (last != null && now - last < LINEAR_AUTH_ALERT_COOLDOWN_MS) return
+  void (async () => {
+    try {
+      const chatId = loadAccess().allowFrom[0]
+      if (!chatId) return
+      const threadId = topicForRecipient({
+        recipientChatId: chatId,
+        resolvedTopic: resolveAgentOutboundTopic({ kind: 'linear-auth' }) ?? chatThreadMap.get(chatId),
+        supergroupChatId: resolveAgentSupergroupChatId(),
+      })
+      const text = buildLinearAuthDeadMessage(info.agent, info.reason)
+      await swallowingApiCall(
+        () =>
+          bot.api.sendMessage(chatId, text, {
+            parse_mode: 'HTML',
+            ...(threadId != null ? { message_thread_id: threadId } : {}),
+          }),
+        { chat_id: chatId, verb: 'linearAuthDead' },
+      )
+      // Stamp the cooldown only after a successful send so a transient
+      // Telegram failure doesn't burn the 6h window (the 401 recurs and will
+      // retry the page on the next Linear call).
+      linearAuthAlertLast.set(key, now)
+      process.stderr.write(`telegram gateway: linear auth-dead alert sent agent=${info.agent} reason=${info.reason}\n`)
+    } catch {
+      /* best-effort */
+    }
+  })()
+}
+
 async function executeLinearAgentActivity(args: Record<string, unknown>): Promise<{ content: Array<{ type: string; text: string }> }> {
-  return emitLinearAgentActivity(args)
+  return emitLinearAgentActivity(args, { onAuthUnrecoverable: notifyLinearAuthDead })
 }
 
 async function executeLinearCreateIssue(args: Record<string, unknown>): Promise<{ content: Array<{ type: string; text: string }> }> {
-  return createLinearIssue(args)
+  return createLinearIssue(args, { onAuthUnrecoverable: notifyLinearAuthDead })
+}
+
+async function executeLinearAgentSetup(args: Record<string, unknown>): Promise<{ content: Array<{ type: string; text: string }> }> {
+  return runLinearAgentSetup(args)
 }
 
 async function executeUpdateChecklist(args: Record<string, unknown>): Promise<{ content: Array<{ type: string; text: string }> }> {
@@ -13179,6 +13239,46 @@ function resolveAgentSupergroupChatId(): string | undefined {
   }
 }
 
+/** Whether THIS agent has `channels.telegram.linear_agent.enabled`. Used by the
+ *  proactive Linear-auth watch to skip agents that aren't Linear actors. */
+function isSelfLinearAgentEnabled(): boolean {
+  const agentName = process.env.SWITCHROOM_AGENT_NAME
+  if (!agentName) return false
+  try {
+    const cfg = loadSwitchroomConfig()
+    const rawAgent = cfg.agents?.[agentName]
+    if (!rawAgent) return false
+    const resolved = resolveAgentConfig(cfg.defaults, cfg.profiles, rawAgent)
+    const la = (resolved.channels?.telegram as { linear_agent?: { enabled?: boolean } } | undefined)?.linear_agent
+    return la?.enabled === true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * One proactive Linear-auth check for this agent (boot + interval). Reads the
+ * refresh bundle via the broker; missing → operator alert, near-expiry →
+ * proactive rotate, revoked → operator alert. Best-effort, never throws.
+ * Disabled with SWITCHROOM_LINEAR_AUTH_WATCH_POLL_MS=0.
+ */
+async function runLinearAuthWatch(): Promise<void> {
+  const agent = process.env.SWITCHROOM_AGENT_NAME
+  if (!agent) return
+  const io = brokerRefreshIO(agent)
+  const status = await runLinearAuthCheck({
+    agent,
+    linearEnabled: isSelfLinearAgentEnabled,
+    readBundle: io.readBundle,
+    refresh: () => performLinearRefresh(io),
+    onAuthDead: notifyLinearAuthDead,
+    log: (s) => process.stderr.write(s),
+  })
+  if (status !== 'disabled' && status !== 'fresh') {
+    process.stderr.write(`telegram gateway: linear-auth-watch agent=${agent} status=${status}\n`)
+  }
+}
+
 /**
  * Stamp a user-facing restart reason into the clean-shutdown marker
  * (same file the SIGTERM handler writes to and the next session greeting
@@ -21401,6 +21501,24 @@ void (async () => {
           }, QUOTA_WATCH_POLL_MS).unref()
         }
 
+        // Proactive Linear-auth watch (FIX 3): catch a dead/missing/near-expiry
+        // Linear bundle BEFORE the agent needs Linear, instead of only on a live
+        // 401. Boot run (delayed so the broker connection settles) + interval.
+        // SWITCHROOM_LINEAR_AUTH_WATCH_POLL_MS=0 disables it.
+        const LINEAR_AUTH_WATCH_POLL_MS = Number(process.env.SWITCHROOM_LINEAR_AUTH_WATCH_POLL_MS ?? 6 * 60 * 60_000)
+        if (LINEAR_AUTH_WATCH_POLL_MS > 0) {
+          setTimeout(() => {
+            void runLinearAuthWatch().catch((err) => {
+              process.stderr.write(`telegram gateway: linear-auth-watch initial run failed: ${err}\n`)
+            })
+          }, 35_000)
+          setInterval(() => {
+            void runLinearAuthWatch().catch((err) => {
+              process.stderr.write(`telegram gateway: linear-auth-watch scheduled run failed: ${err}\n`)
+            })
+          }, LINEAR_AUTH_WATCH_POLL_MS).unref()
+        }
+
         // Restart-watchdog: poll systemd's NRestarts for the agent unit.
         // When the count ticks up without a corresponding restart-pending
         // marker (= user-initiated /restart), emit an operator event.

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

@@ -24,6 +24,37 @@ import { performLinearRefresh, type RefreshIO } from '../../src/linear/oauth-ref
 
 export const LINEAR_GRAPHQL_ENDPOINT = 'https://api.linear.app/graphql'
 
+/** The two operator-action reasons a Linear 401 can't self-heal. */
+export type LinearAuthDeadReason = 'no_bundle' | 'revoked'
+
+/** Minimal HTML-escape (Telegram parse_mode: 'HTML'). Kept local so the
+ *  message builder is self-contained + unit-testable without reaching into a
+ *  gateway-only escaper (the bug that shipped the first cut of this alert). */
+function escapeHtmlMin(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+/**
+ * Build the operator-facing Telegram alert (HTML) for an un-healable Linear
+ * auth failure. Pure + self-escaping so it can be unit-tested directly. The
+ * gateway's `notifyLinearAuthDead` only handles dedup + transport.
+ */
+export function buildLinearAuthDeadMessage(agent: string, reason: LinearAuthDeadReason): string {
+  const a = escapeHtmlMin(agent)
+  const why =
+    reason === 'no_bundle'
+      ? `no refresh credentials are stored (<code>linear/${a}/oauth</code> is missing), so its daily-expiring token can't renew`
+      : `its Linear refresh token was revoked`
+  return (
+    `🔑 <b>Linear auth needs you</b>\n` +
+    `<b>${a}</b> can't reach Linear — ${why}. ` +
+    `Its access token will keep failing until you re-authorize.\n\n` +
+    `Re-auth (actor=app) then run <code>switchroom linear-agent setup --agent ${a} ` +
+    `--token … --refresh-token … --client-id … --client-secret …</code> on the host, ` +
+    `or ask me to walk you through it.`
+  )
+}
+
 export type LinearTokenResult =
   | { ok: true; token: string }
   | { ok: false; reason: 'denied' | 'unreachable' | 'not_found' | 'unknown' }
@@ -44,6 +75,14 @@ export interface LinearActivityDeps {
   defaultTeamId?: string
   /** Log sink — stderr in production. */
   log?: (line: string) => void
+  /** Invoked when a Linear 401 CANNOT self-heal because the situation needs
+   *  an operator to act: `no_bundle` (no refresh credentials were ever
+   *  stored — the silent-setup-failure case) or `revoked` (the refresh token
+   *  itself is dead). The gateway wires this to a deduped operator-facing
+   *  Telegram alert so a daily-expiring token stops failing invisibly. NOT
+   *  called for transient reasons (network/http_error/bad_response) — those
+   *  retry on their own. */
+  onAuthUnrecoverable?: (info: { agent: string; reason: LinearAuthDeadReason; detail: string }) => void
 }
 
 export type ToolTextResult = { content: Array<{ type: string; text: string }> }
@@ -106,6 +145,7 @@ async function linearPostWithRefresh(
   fetchImpl: typeof fetch,
   log: (s: string) => void,
   refreshIO?: (agent: string) => RefreshIO,
+  onAuthUnrecoverable?: (info: { agent: string; reason: LinearAuthDeadReason; detail: string }) => void,
 ): Promise<{ resp: Response; token: string }> {
   const post = (t: string) =>
     fetchImpl(LINEAR_GRAPHQL_ENDPOINT, {
@@ -125,7 +165,21 @@ async function linearPostWithRefresh(
         `telegram gateway: linear token REVOKED agent=${agent} — refresh token is dead; ` +
           `operator must re-authorize (linear-agent setup --refresh-token …)\n`,
       )
+      onAuthUnrecoverable?.({ agent, reason: 'revoked', detail: refreshed.detail })
+    } else if (refreshed.reason === 'no_bundle') {
+      // No refresh bundle was ever stored (the silent-setup-failure case):
+      // the access token expires ~daily and there is nothing to renew from.
+      // This is invisible in the gateway log alone — surface it to the
+      // operator so they can re-provision instead of the agent failing
+      // every day forever.
+      log(
+        `telegram gateway: linear token DEAD agent=${agent} — no refresh bundle stored ` +
+          `(linear/${agent}/oauth absent); operator must re-authorize\n`,
+      )
+      onAuthUnrecoverable?.({ agent, reason: 'no_bundle', detail: refreshed.detail })
     } else {
+      // Transient (network / http_error / bad_response): retries on its own,
+      // no operator action — log only, don't page.
       log(`telegram gateway: linear token refresh failed agent=${agent} reason=${refreshed.reason}\n`)
     }
     return { resp, token } // surface the original 401
@@ -206,6 +260,7 @@ export async function emitLinearAgentActivity(
       fetchImpl,
       log,
       deps.refreshIO,
+      deps.onAuthUnrecoverable,
     ))
   } catch (err) {
     return {
@@ -312,6 +367,7 @@ export async function createLinearIssue(
         fetchImpl,
         log,
         deps.refreshIO,
+        deps.onAuthUnrecoverable,
       )
       resp = out.resp
       activeToken = out.token

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/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([])
+  })
+})