switchroom 0.15.25 → 0.15.26

package/dist/cli/switchroom.js

@@ -50477,8 +50477,8 @@ var {
 } = import__.default;
 
 // src/build-info.ts
-var VERSION = "0.15.25";
-var COMMIT_SHA = "0d066743";
+var VERSION = "0.15.26";
+var COMMIT_SHA = "497e0d23";
 
 // src/cli/agent.ts
 init_source();
@@ -67478,6 +67478,23 @@ function addWebhookSource(yamlText, agentName, source) {
   }
   return String(doc);
 }
+function addAgentSecret(yamlText, agentName, key) {
+  const doc = import_yaml11.parseDocument(yamlText);
+  ensureAgent(doc, agentName);
+  const existing = doc.getIn(["agents", agentName, "secrets"]);
+  if (import_yaml11.isSeq(existing)) {
+    const seq = existing;
+    for (const item of seq.items) {
+      const v = item.value ?? item;
+      if (v === key)
+        return yamlText;
+    }
+    seq.add(key);
+  } else {
+    doc.setIn(["agents", agentName, "secrets"], [key]);
+  }
+  return String(doc);
+}
 function removeWebhookSource(yamlText, agentName, source) {
   const doc = import_yaml11.parseDocument(yamlText);
   if (!hasAgent(doc, agentName))
@@ -67860,6 +67877,22 @@ async function vaultPut(program3, key, value) {
   setStringSecret(passphrase, vaultPath, key, value);
   console.log(source_default.green(`\u2713 Stored secret in vault as '${key}'`));
 }
+async function vaultPutQuiet(program3, key, value) {
+  const configPath = program3.optsWithGlobals().config ?? undefined;
+  const vaultPath = resolveVaultPath(configPath);
+  const passphrase = await getVaultPassphrase();
+  if (!existsSync43(vaultPath))
+    createVault(passphrase, vaultPath);
+  setStringSecret(passphrase, vaultPath, key, value);
+}
+async function vaultGet(program3, key) {
+  const configPath = program3.optsWithGlobals().config ?? undefined;
+  const vaultPath = resolveVaultPath(configPath);
+  if (!existsSync43(vaultPath))
+    return null;
+  const passphrase = await getVaultPassphrase();
+  return getStringSecret(passphrase, vaultPath, key);
+}
 function resolveVaultPath(configPath) {
   try {
     const config = loadConfig(configPath);
@@ -67988,9 +68021,118 @@ function promptHidden2(prompt) {
 init_source();
 init_helpers();
 import { readFileSync as readFileSync39, writeFileSync as writeFileSync22 } from "node:fs";
+
+// src/linear/oauth-refresh.ts
+var LINEAR_TOKEN_ENDPOINT = "https://api.linear.app/oauth/token";
+var DEFAULT_REFRESH_SKEW_SEC = 2 * 3600;
+async function refreshLinearAppToken(bundle, opts = {}) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const nowSec = opts.nowSec ?? (() => Math.floor(Date.now() / 1000));
+  const form = new URLSearchParams({
+    grant_type: "refresh_token",
+    refresh_token: bundle.refreshToken,
+    client_id: bundle.clientId,
+    client_secret: bundle.clientSecret
+  });
+  let resp;
+  try {
+    resp = await fetchImpl(LINEAR_TOKEN_ENDPOINT, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: form.toString()
+    });
+  } catch (err) {
+    return { ok: false, reason: "network", detail: err.message };
+  }
+  if (!resp.ok) {
+    const txt = await resp.text().catch(() => "");
+    const revoked = resp.status === 400 || /invalid_grant|invalid_token/i.test(txt);
+    return {
+      ok: false,
+      reason: revoked ? "revoked" : "http_error",
+      detail: `HTTP ${resp.status}${txt ? ` ${txt.slice(0, 200)}` : ""}`
+    };
+  }
+  let json;
+  try {
+    json = await resp.json();
+  } catch {
+    return { ok: false, reason: "bad_response", detail: "non-JSON token response" };
+  }
+  const accessToken = json.access_token;
+  if (typeof accessToken !== "string" || accessToken.length === 0) {
+    return { ok: false, reason: "bad_response", detail: "no access_token in response" };
+  }
+  const expiresIn = typeof json.expires_in === "number" ? json.expires_in : 86400;
+  const rotated = typeof json.refresh_token === "string" && json.refresh_token.length > 0 ? json.refresh_token : bundle.refreshToken;
+  return {
+    ok: true,
+    accessToken,
+    refreshToken: rotated,
+    expiresAt: nowSec() + expiresIn,
+    ...typeof json.scope === "string" ? { scope: json.scope } : {}
+  };
+}
+function parseBundle(raw) {
+  if (raw == null || raw === "")
+    return null;
+  let o;
+  try {
+    o = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof o.client_id === "string" && typeof o.client_secret === "string" && typeof o.refresh_token === "string" && o.client_id.length > 0 && o.client_secret.length > 0 && o.refresh_token.length > 0) {
+    return {
+      clientId: o.client_id,
+      clientSecret: o.client_secret,
+      refreshToken: o.refresh_token,
+      ...typeof o.expires_at === "number" ? { expiresAt: o.expires_at } : {}
+    };
+  }
+  return null;
+}
+function serializeBundle(b) {
+  return JSON.stringify({
+    client_id: b.clientId,
+    client_secret: b.clientSecret,
+    refresh_token: b.refreshToken,
+    ...b.expiresAt != null ? { expires_at: b.expiresAt } : {}
+  });
+}
+async function performLinearRefresh(io) {
+  const raw = await io.readBundle();
+  const bundle = parseBundle(raw);
+  if (!bundle) {
+    return { ok: false, reason: "no_bundle", detail: "no/invalid refresh bundle" };
+  }
+  const res = await refreshLinearAppToken(bundle, {
+    ...io.fetchImpl ? { fetchImpl: io.fetchImpl } : {},
+    ...io.nowSec ? { nowSec: io.nowSec } : {}
+  });
+  if (!res.ok)
+    return { ok: false, reason: res.reason, detail: res.detail };
+  try {
+    await io.writeBundle(serializeBundle({
+      clientId: bundle.clientId,
+      clientSecret: bundle.clientSecret,
+      refreshToken: res.refreshToken,
+      expiresAt: res.expiresAt
+    }));
+    await io.writeToken(res.accessToken);
+  } catch (err) {
+    return { ok: false, reason: "persist_failed", detail: err.message };
+  }
+  return { ok: true, accessToken: res.accessToken, expiresAt: res.expiresAt };
+}
+
+// src/cli/linear-agent.ts
+function bundleKeyFor(agent) {
+  return `linear/${agent}/oauth`;
+}
 function registerLinearAgentCommand(program3) {
   const linear = program3.command("linear-agent").description("Install an agent into a Linear workspace as a first-class app actor (#2298) \u2014 @-mentionable, delegate-assignable, agent sessions wake it instantly.");
-  linear.command("setup").description("Provision <agent> as a Linear agent. Vault-stores the Linear OAuth app token (actor=app) under 'linear/<agent>/token' and enables the linear_agent block in switchroom.yaml. The OAuth browser authorize step is printed as instructions (it can't run headless); pass the already-obtained --token.").requiredOption("--agent <name>", "Agent name (must exist in switchroom.yaml)").requiredOption("--token <token>", "The Linear OAuth app token (actor=app), obtained out-of-band via the browser authorize step. Stored in the vault, never in switchroom.yaml.").option("--client-id <id>", "Linear OAuth app client id (for the printed authorize-URL hint).").option("--client-secret <secret>", "Linear OAuth app client secret (informational \u2014 not stored by this verb).").option("--redirect-uri <uri>", "OAuth redirect URI registered on the Linear app (for the authorize-URL hint).").option("--workspace-id <id>", "Optional Linear workspace (organization) id to record in config.").option("--webhook-base <url>", "Base URL of the switchroom web server (e.g. https://hooks.switchroom.ai). Used to print the webhook URL to register in Linear. Defaults to a placeholder.").option("--dry-run", "Print the YAML diff + instructions without writing or vaulting anything").action(withConfigError(async (opts) => {
+  linear.command("setup").description("Provision <agent> as a Linear agent. Vault-stores the Linear OAuth app token (actor=app) under 'linear/<agent>/token' and enables the linear_agent block in switchroom.yaml. The OAuth browser authorize step is printed as instructions (it can't run headless); pass the already-obtained --token.").requiredOption("--agent <name>", "Agent name (must exist in switchroom.yaml)").requiredOption("--token <token>", "The Linear OAuth app token (actor=app), obtained out-of-band via the browser authorize step. Stored in the vault, never in switchroom.yaml.").option("--client-id <id>", "Linear OAuth app client id. Stored (with --client-secret + --refresh-token) to enable unattended token refresh.").option("--client-secret <secret>", "Linear OAuth app client secret. Stored in the vault (with --client-id + --refresh-token) so the token can be refreshed without a browser re-auth.").option("--refresh-token <token>", "The refresh_token from the OAuth exchange. Stored so an expired access token self-heals (see 'linear-agent refresh').").option("--token-expires-in <seconds>", "expires_in from the OAuth token response (seconds). Records when the access token expires so refresh runs proactively. Defaults to 86400.").option("--redirect-uri <uri>", "OAuth redirect URI registered on the Linear app (for the authorize-URL hint).").option("--workspace-id <id>", "Optional Linear workspace (organization) id to record in config.").option("--webhook-base <url>", "Base URL of the switchroom web server (e.g. https://hooks.switchroom.ai). Used to print the webhook URL to register in Linear. Defaults to a placeholder.").option("--dry-run", "Print the YAML diff + instructions without writing or vaulting anything").action(withConfigError(async (opts) => {
     if (!/^[a-z][a-z0-9_-]{0,63}$/.test(opts.agent)) {
       fail2(`--agent must be a lowercase agent slug (got '${opts.agent}').`);
     }
@@ -67998,10 +68140,26 @@ function registerLinearAgentCommand(program3) {
       fail2("--token must be a non-empty Linear app token.");
     }
     const vaultKey = `linear/${opts.agent}/token`;
+    const bundleKey = bundleKeyFor(opts.agent);
+    const canRefresh = Boolean(opts.refreshToken && opts.clientId && opts.clientSecret);
     if (!opts.dryRun) {
       await vaultPut(program3, vaultKey, opts.token);
+      if (canRefresh) {
+        const expiresIn = Number.parseInt(opts.tokenExpiresIn ?? "", 10);
+        const ttl = Number.isFinite(expiresIn) && expiresIn > 0 ? expiresIn : 86400;
+        const bundle = serializeBundle({
+          clientId: opts.clientId,
+          clientSecret: opts.clientSecret,
+          refreshToken: opts.refreshToken,
+          expiresAt: Math.floor(Date.now() / 1000) + ttl
+        });
+        await vaultPutQuiet(program3, bundleKey, bundle);
+      }
     } else {
       console.log(source_default.gray(`[dry-run] would store the Linear token in the vault as '${vaultKey}'`));
+      if (canRefresh) {
+        console.log(source_default.gray(`[dry-run] would store the refresh bundle as '${bundleKey}' (enables auto-refresh)`));
+      }
     }
     const path4 = getConfigPath(program3);
     const before = readFileSync39(path4, "utf-8");
@@ -68011,6 +68169,10 @@ function registerLinearAgentCommand(program3) {
         token: `vault:${vaultKey}`,
         ...opts.workspaceId ? { workspaceId: opts.workspaceId } : {}
       });
+      if (canRefresh) {
+        after = addAgentSecret(after, opts.agent, bundleKey);
+        after = addAgentSecret(after, opts.agent, vaultKey);
+      }
     } catch (err) {
       fail2(err.message);
     }
@@ -68021,10 +68183,42 @@ function registerLinearAgentCommand(program3) {
       writeFileSync22(path4, after, "utf-8");
       console.log(source_default.green(`\u2713 Enabled linear-agent for agent '${opts.agent}'`));
       console.log(source_default.gray(`  Vault key: ${vaultKey}`));
+      if (canRefresh) {
+        console.log(source_default.green(`\u2713 Auto-refresh enabled \u2014 refresh bundle stored at '${bundleKey}'`));
+        console.log(source_default.gray(`  Granted ACL: '${bundleKey}' + '${vaultKey}' added to agents.${opts.agent}.secrets[] (agent rotates them in-container on a 401).`));
+      } else {
+        console.log(source_default.yellow(`\u26a0 No refresh bundle stored \u2014 the access token will expire (~24h) and need a manual re-auth.`));
+        console.log(source_default.gray(`  To enable auto-refresh, re-run with --refresh-token <rt> --client-id <id> --client-secret <secret> --token-expires-in <sec>.`));
+      }
       console.log(source_default.gray(`  Run 'switchroom agent restart ${opts.agent}' to pick up the change.`));
     }
     printLinearInstructions(opts, vaultKey);
   }));
+  linear.command("refresh").description("Refresh <agent>'s Linear app token using the stored refresh bundle (linear/<agent>/oauth). Exchanges the refresh_token for a fresh access token, writes it to linear/<agent>/token, and rotates the stored refresh_token + expiry. Use to recover an expired token or seed automation. Host-side write \u2014 the running agent picks it up on its next broker re-mirror / restart.").requiredOption("--agent <name>", "Agent name (must have a linear_agent block)").action(withConfigError(async (opts) => {
+    if (!/^[a-z][a-z0-9_-]{0,63}$/.test(opts.agent)) {
+      fail2(`--agent must be a lowercase agent slug (got '${opts.agent}').`);
+    }
+    const bundleKey = bundleKeyFor(opts.agent);
+    const res = await performLinearRefresh({
+      readBundle: () => vaultGet(program3, bundleKey),
+      writeToken: (t) => vaultPutQuiet(program3, `linear/${opts.agent}/token`, t),
+      writeBundle: (json) => vaultPutQuiet(program3, bundleKey, json)
+    });
+    if (!res.ok) {
+      if (res.reason === "no_bundle") {
+        fail2(`No refresh bundle at '${bundleKey}'. Provision one via 'linear-agent setup --agent ${opts.agent} ` + `--token <t> --refresh-token <rt> --client-id <id> --client-secret <secret>'.`);
+      }
+      if (res.reason === "revoked") {
+        fail2(`Refresh token is dead (revoked/expired) \u2014 re-authorize in a browser (actor=app) and re-run setup with the new --refresh-token. (${res.detail})`);
+      }
+      fail2(`Refresh failed (${res.reason}): ${res.detail}`);
+    }
+    if (res.ok) {
+      const hours = Math.max(1, Math.round((res.expiresAt - Date.now() / 1000) / 3600));
+      console.log(source_default.green(`\u2713 Refreshed Linear token for '${opts.agent}' (expires in ~${hours}h).`));
+      console.log(source_default.gray(`  Written to vault:linear/${opts.agent}/token (+ rotated bundle). Restart the agent or wait for the broker to re-mirror.`));
+    }
+  }));
   linear.command("set-team").description("Set (or clear) the default Linear team captured issues file into for <agent>. Only needed when the workspace has multiple teams \u2014 a single-team workspace auto-resolves. Pass --clear to remove the default.").requiredOption("--agent <name>", "Agent name (must have a linear_agent block)").option("--team <id>", "Linear team id new captured issues default to.").option("--clear", "Remove the configured default team (revert to auto-resolve).").action(withConfigError(async (opts) => {
     if (!/^[a-z][a-z0-9_-]{0,63}$/.test(opts.agent)) {
       fail2(`--agent must be a lowercase agent slug (got '${opts.agent}').`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.15.25",
+  "version": "0.15.26",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

package/telegram-plugin/dist/gateway/gateway.js

@@ -54424,10 +54424,10 @@ function readTurnActiveMarkerAgeMs(stateDir, now) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.15.25";
-var COMMIT_SHA = "0d066743";
-var COMMIT_DATE = "2026-06-15T02:15:36Z";
-var LATEST_PR = 2359;
+var VERSION = "0.15.26";
+var COMMIT_SHA = "497e0d23";
+var COMMIT_DATE = "2026-06-15T03:00:42Z";
+var LATEST_PR = 2362;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts
@@ -54720,6 +54720,112 @@ async function revokeGrantViaBroker(id, opts) {
 
 // gateway/linear-activity.ts
 init_client2();
+
+// ../src/linear/oauth-refresh.ts
+var LINEAR_TOKEN_ENDPOINT = "https://api.linear.app/oauth/token";
+var DEFAULT_REFRESH_SKEW_SEC = 2 * 3600;
+async function refreshLinearAppToken(bundle, opts = {}) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const nowSec = opts.nowSec ?? (() => Math.floor(Date.now() / 1000));
+  const form = new URLSearchParams({
+    grant_type: "refresh_token",
+    refresh_token: bundle.refreshToken,
+    client_id: bundle.clientId,
+    client_secret: bundle.clientSecret
+  });
+  let resp;
+  try {
+    resp = await fetchImpl(LINEAR_TOKEN_ENDPOINT, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: form.toString()
+    });
+  } catch (err) {
+    return { ok: false, reason: "network", detail: err.message };
+  }
+  if (!resp.ok) {
+    const txt = await resp.text().catch(() => "");
+    const revoked = resp.status === 400 || /invalid_grant|invalid_token/i.test(txt);
+    return {
+      ok: false,
+      reason: revoked ? "revoked" : "http_error",
+      detail: `HTTP ${resp.status}${txt ? ` ${txt.slice(0, 200)}` : ""}`
+    };
+  }
+  let json;
+  try {
+    json = await resp.json();
+  } catch {
+    return { ok: false, reason: "bad_response", detail: "non-JSON token response" };
+  }
+  const accessToken = json.access_token;
+  if (typeof accessToken !== "string" || accessToken.length === 0) {
+    return { ok: false, reason: "bad_response", detail: "no access_token in response" };
+  }
+  const expiresIn = typeof json.expires_in === "number" ? json.expires_in : 86400;
+  const rotated = typeof json.refresh_token === "string" && json.refresh_token.length > 0 ? json.refresh_token : bundle.refreshToken;
+  return {
+    ok: true,
+    accessToken,
+    refreshToken: rotated,
+    expiresAt: nowSec() + expiresIn,
+    ...typeof json.scope === "string" ? { scope: json.scope } : {}
+  };
+}
+function parseBundle(raw) {
+  if (raw == null || raw === "")
+    return null;
+  let o;
+  try {
+    o = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof o.client_id === "string" && typeof o.client_secret === "string" && typeof o.refresh_token === "string" && o.client_id.length > 0 && o.client_secret.length > 0 && o.refresh_token.length > 0) {
+    return {
+      clientId: o.client_id,
+      clientSecret: o.client_secret,
+      refreshToken: o.refresh_token,
+      ...typeof o.expires_at === "number" ? { expiresAt: o.expires_at } : {}
+    };
+  }
+  return null;
+}
+function serializeBundle(b) {
+  return JSON.stringify({
+    client_id: b.clientId,
+    client_secret: b.clientSecret,
+    refresh_token: b.refreshToken,
+    ...b.expiresAt != null ? { expires_at: b.expiresAt } : {}
+  });
+}
+async function performLinearRefresh(io) {
+  const raw = await io.readBundle();
+  const bundle = parseBundle(raw);
+  if (!bundle) {
+    return { ok: false, reason: "no_bundle", detail: "no/invalid refresh bundle" };
+  }
+  const res = await refreshLinearAppToken(bundle, {
+    ...io.fetchImpl ? { fetchImpl: io.fetchImpl } : {},
+    ...io.nowSec ? { nowSec: io.nowSec } : {}
+  });
+  if (!res.ok)
+    return { ok: false, reason: res.reason, detail: res.detail };
+  try {
+    await io.writeBundle(serializeBundle({
+      clientId: bundle.clientId,
+      clientSecret: bundle.clientSecret,
+      refreshToken: res.refreshToken,
+      expiresAt: res.expiresAt
+    }));
+    await io.writeToken(res.accessToken);
+  } catch (err) {
+    return { ok: false, reason: "persist_failed", detail: err.message };
+  }
+  return { ok: true, accessToken: res.accessToken, expiresAt: res.expiresAt };
+}
+
+// gateway/linear-activity.ts
 var LINEAR_GRAPHQL_ENDPOINT = "https://api.linear.app/graphql";
 async function defaultResolveLinearToken(agent) {
   const key = `linear/${agent}/token`;
@@ -54736,6 +54842,53 @@ async function defaultResolveLinearToken(agent) {
     return { ok: false, reason: "denied" };
   return { ok: false, reason: "unknown" };
 }
+function brokerRefreshIO(agent, fetchImpl) {
+  const token = readVaultTokenFile(agent) ?? undefined;
+  const opt = token ? { token } : {};
+  return {
+    readBundle: async () => {
+      const r = await getViaBrokerStructured(`linear/${agent}/oauth`, opt);
+      return r.kind === "ok" && r.entry.kind === "string" ? r.entry.value : null;
+    },
+    writeToken: async (t) => {
+      const r = await putViaBroker(`linear/${agent}/token`, { kind: "string", value: t }, opt);
+      if (r.kind !== "ok")
+        throw new Error(`broker put linear/${agent}/token: ${r.kind}`);
+    },
+    writeBundle: async (j) => {
+      const r = await putViaBroker(`linear/${agent}/oauth`, { kind: "string", value: j }, opt);
+      if (r.kind !== "ok")
+        throw new Error(`broker put linear/${agent}/oauth: ${r.kind}`);
+    },
+    ...fetchImpl ? { fetchImpl } : {}
+  };
+}
+async function linearPostWithRefresh(body, token, agent, fetchImpl, log, refreshIO) {
+  const post = (t) => fetchImpl(LINEAR_GRAPHQL_ENDPOINT, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Authorization: t },
+    body
+  });
+  let resp = await post(token);
+  if (resp.status !== 401)
+    return { resp, token };
+  const io = (refreshIO ?? ((a) => brokerRefreshIO(a, fetchImpl)))(agent);
+  const refreshed = await performLinearRefresh({ ...io, fetchImpl });
+  if (!refreshed.ok) {
+    if (refreshed.reason === "revoked") {
+      log(`telegram gateway: linear token REVOKED agent=${agent} \u2014 refresh token is dead; ` + `operator must re-authorize (linear-agent setup --refresh-token \u2026)
+`);
+    } else {
+      log(`telegram gateway: linear token refresh failed agent=${agent} reason=${refreshed.reason}
+`);
+    }
+    return { resp, token };
+  }
+  log(`telegram gateway: linear token auto-refreshed agent=${agent} (was 401)
+`);
+  resp = await post(refreshed.accessToken);
+  return { resp, token: refreshed.accessToken };
+}
 async function emitLinearAgentActivity(args, deps = {}) {
   const log = deps.log ?? ((s) => process.stderr.write(s));
   const sessionId = args.agent_session_id;
@@ -54780,14 +54933,7 @@ async function emitLinearAgentActivity(args, deps = {}) {
   const fetchImpl = deps.fetchImpl ?? fetch;
   let resp;
   try {
-    resp = await fetchImpl(LINEAR_GRAPHQL_ENDPOINT, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: tokenResult.token
-      },
-      body: JSON.stringify({ query: mutation, variables })
-    });
+    ({ resp } = await linearPostWithRefresh(JSON.stringify({ query: mutation, variables }), tokenResult.token, agent, fetchImpl, log, deps.refreshIO));
   } catch (err) {
     return {
       content: [{ type: "text", text: `linear_agent_activity failed: request error: ${err.message}` }]
@@ -54847,15 +54993,13 @@ async function createLinearIssue(args, deps = {}) {
       ]
     };
   }
-  const token = tokenResult.token;
+  let activeToken = tokenResult.token;
   const gql = async (query2, variables) => {
     let resp;
     try {
-      resp = await fetchImpl(LINEAR_GRAPHQL_ENDPOINT, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", Authorization: token },
-        body: JSON.stringify({ query: query2, variables })
-      });
+      const out = await linearPostWithRefresh(JSON.stringify({ query: query2, variables }), activeToken, agent, fetchImpl, log, deps.refreshIO);
+      resp = out.resp;
+      activeToken = out.token;
     } catch (err) {
       return { ok: false, text: `request error: ${err.message}` };
     }

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

@@ -17,8 +17,10 @@
 
 import {
   getViaBrokerStructured,
+  putViaBroker,
   readVaultTokenFile,
 } from '../../src/vault/broker/client.js'
+import { performLinearRefresh, type RefreshIO } from '../../src/linear/oauth-refresh.js'
 
 export const LINEAR_GRAPHQL_ENDPOINT = 'https://api.linear.app/graphql'
 
@@ -33,6 +35,10 @@ export interface LinearActivityDeps {
   fetchImpl?: typeof fetch
   /** Agent slug (defaults to SWITCHROOM_AGENT_NAME). */
   agent?: string
+  /** Build the RefreshIO used to auto-refresh on a 401 (tests inject a
+   *  fake; production uses the broker-backed `brokerRefreshIO`). When
+   *  omitted, on-401 refresh uses the broker. */
+  refreshIO?: (agent: string) => RefreshIO
   /** Default Linear team id for captured issues (multi-team workspaces);
    *  defaults to SWITCHROOM_LINEAR_DEFAULT_TEAM_ID. Tests inject directly. */
   defaultTeamId?: string
@@ -56,6 +62,79 @@ export async function defaultResolveLinearToken(agent: string): Promise<LinearTo
   return { ok: false, reason: 'unknown' }
 }
 
+/**
+ * Broker-backed RefreshIO: reads `linear/<agent>/oauth` and rotates both
+ * `linear/<agent>/token` and the bundle via the broker `put` op (#950 — an
+ * agent rotates keys it can already read, no operator passphrase, no host
+ * round-trip). Requires `linear/<agent>/oauth` to be in the agent's ACL
+ * (linear-agent setup adds it to `secrets[]`).
+ */
+export function brokerRefreshIO(agent: string, fetchImpl?: typeof fetch): RefreshIO {
+  const token = readVaultTokenFile(agent) ?? undefined
+  const opt = token ? { token } : {}
+  return {
+    readBundle: async () => {
+      const r = await getViaBrokerStructured(`linear/${agent}/oauth`, opt)
+      return r.kind === 'ok' && r.entry.kind === 'string' ? r.entry.value : null
+    },
+    writeToken: async (t) => {
+      const r = await putViaBroker(`linear/${agent}/token`, { kind: 'string', value: t }, opt)
+      if (r.kind !== 'ok') throw new Error(`broker put linear/${agent}/token: ${r.kind}`)
+    },
+    writeBundle: async (j) => {
+      const r = await putViaBroker(`linear/${agent}/oauth`, { kind: 'string', value: j }, opt)
+      if (r.kind !== 'ok') throw new Error(`broker put linear/${agent}/oauth: ${r.kind}`)
+    },
+    ...(fetchImpl ? { fetchImpl } : {}),
+  }
+}
+
+/**
+ * POST to Linear's GraphQL endpoint; on a 401 (expired/invalid app token)
+ * auto-refresh the token once via the stored refresh bundle and retry with
+ * the fresh token. This is the durable self-heal: a Linear app token that
+ * expired (~24h–30d) is silently rotated in-container on its next use rather
+ * than failing the agent's turn. A `revoked` refresh token (the one case
+ * needing operator re-auth) is logged loudly and the original 401 surfaces.
+ *
+ * Returns the final Response and the token in force (callers read the body).
+ */
+async function linearPostWithRefresh(
+  body: string,
+  token: string,
+  agent: string,
+  fetchImpl: typeof fetch,
+  log: (s: string) => void,
+  refreshIO?: (agent: string) => RefreshIO,
+): Promise<{ resp: Response; token: string }> {
+  const post = (t: string) =>
+    fetchImpl(LINEAR_GRAPHQL_ENDPOINT, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: t },
+      body,
+    })
+
+  let resp = await post(token)
+  if (resp.status !== 401) return { resp, token }
+
+  const io = (refreshIO ?? ((a) => brokerRefreshIO(a, fetchImpl)))(agent)
+  const refreshed = await performLinearRefresh({ ...io, fetchImpl })
+  if (!refreshed.ok) {
+    if (refreshed.reason === 'revoked') {
+      log(
+        `telegram gateway: linear token REVOKED agent=${agent} — refresh token is dead; ` +
+          `operator must re-authorize (linear-agent setup --refresh-token …)\n`,
+      )
+    } else {
+      log(`telegram gateway: linear token refresh failed agent=${agent} reason=${refreshed.reason}\n`)
+    }
+    return { resp, token } // surface the original 401
+  }
+  log(`telegram gateway: linear token auto-refreshed agent=${agent} (was 401)\n`)
+  resp = await post(refreshed.accessToken)
+  return { resp, token: refreshed.accessToken }
+}
+
 /**
  * Emit a Linear AgentActivity. Validates args, resolves the token, POSTs
  * the `agentActivityCreate` mutation, and returns an MCP text result. Never
@@ -118,14 +197,16 @@ export async function emitLinearAgentActivity(
   const fetchImpl = deps.fetchImpl ?? fetch
   let resp: Response
   try {
-    resp = await fetchImpl(LINEAR_GRAPHQL_ENDPOINT, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: tokenResult.token,
-      },
-      body: JSON.stringify({ query: mutation, variables }),
-    })
+    // Auto-refresh on a 401 (expired app token) and retry once — see
+    // linearPostWithRefresh.
+    ;({ resp } = await linearPostWithRefresh(
+      JSON.stringify({ query: mutation, variables }),
+      tokenResult.token,
+      agent,
+      fetchImpl,
+      log,
+      deps.refreshIO,
+    ))
   } catch (err) {
     return {
       content: [{ type: 'text', text: `linear_agent_activity failed: request error: ${(err as Error).message}` }],
@@ -217,16 +298,23 @@ export async function createLinearIssue(
       ],
     }
   }
-  const token = tokenResult.token
+  // Mutable so a 401-triggered refresh on one gql call carries the fresh
+  // token to subsequent calls in this issue-create flow.
+  let activeToken = tokenResult.token
 
   const gql = async (query: string, variables: Record<string, unknown>): Promise<{ ok: true; data: any } | { ok: false; text: string }> => {
     let resp: Response
     try {
-      resp = await fetchImpl(LINEAR_GRAPHQL_ENDPOINT, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json', Authorization: token },
-        body: JSON.stringify({ query, variables }),
-      })
+      const out = await linearPostWithRefresh(
+        JSON.stringify({ query, variables }),
+        activeToken,
+        agent,
+        fetchImpl,
+        log,
+        deps.refreshIO,
+      )
+      resp = out.resp
+      activeToken = out.token
     } catch (err) {
       return { ok: false, text: `request error: ${(err as Error).message}` }
     }

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

@@ -122,3 +122,78 @@ describe('emitLinearAgentActivity — behaviour (#2298)', () => {
     expect(r.content[0].text).toMatch(/Linear API 401/)
   })
 })
+
+import { serializeBundle, type RefreshIO } from '../../src/linear/oauth-refresh.js'
+
+/** fetch fake routing by URL: the GraphQL endpoint 401s on the first hit then
+ *  200s; the OAuth token endpoint returns a fresh token. Records the
+ *  Authorization header per call so we can prove the retry used the new token. */
+function refreshAwareFetch(opts: { tokenStatus?: number; tokenBody?: unknown } = {}) {
+  const calls: Array<{ url: string; auth?: string }> = []
+  let graphqlHits = 0
+  const fetchImpl = (async (url: string, init: { headers?: Record<string, string> }) => {
+    const auth = init?.headers?.Authorization
+    calls.push({ url, auth })
+    if (url.includes('/oauth/token')) {
+      const status = opts.tokenStatus ?? 200
+      const body = opts.tokenBody ?? { access_token: 'lin_fresh', refresh_token: 'rt_new', expires_in: 86400 }
+      return { ok: status >= 200 && status < 300, status, json: async () => body, text: async () => (typeof body === 'string' ? body : JSON.stringify(body)) } as unknown as Response
+    }
+    graphqlHits++
+    if (graphqlHits === 1) {
+      return { ok: false, status: 401, json: async () => ({}), text: async () => 'unauthorized' } as unknown as Response
+    }
+    return { ok: true, status: 200, json: async () => ({ data: { agentActivityCreate: { success: true } } }), text: async () => '' } as unknown as Response
+  }) as unknown as typeof fetch
+  return { fetchImpl, calls }
+}
+
+function fakeRefreshIO(): { io: RefreshIO; writes: { token?: string; bundle?: string } } {
+  const writes: { token?: string; bundle?: string } = {}
+  const io: RefreshIO = {
+    readBundle: async () => serializeBundle({ clientId: 'cid', clientSecret: 'csec', refreshToken: 'rt_old', expiresAt: 0 }),
+    writeToken: async (t) => { writes.token = t },
+    writeBundle: async (j) => { writes.bundle = j },
+  }
+  return { io, writes }
+}
+
+describe('linear_agent_activity — auto-refresh on 401 (#2298 durability)', () => {
+  it('refreshes the app token on a 401 and retries once with the fresh token', async () => {
+    const { fetchImpl, calls } = refreshAwareFetch()
+    const { io, writes } = fakeRefreshIO()
+    const r = await emitLinearAgentActivity(
+      { agent_session_id: 'sess', type: 'thought', body: 'hi' },
+      { agent: 'carrie', resolveToken: okToken('lin_expired'), fetchImpl, refreshIO: () => io, log: () => {} },
+    )
+    expect(r.content[0].text).toMatch(/emitted/)
+    // The refresh wrote the new access token; the GraphQL retry used it.
+    expect(writes.token).toBe('lin_fresh')
+    const graphqlAuths = calls.filter((c) => c.url.includes('/graphql')).map((c) => c.auth)
+    expect(graphqlAuths).toEqual(['lin_expired', 'lin_fresh'])
+  })
+
+  it('a revoked refresh token surfaces the 401 (one retry, no loop) and logs REVOKED', async () => {
+    const { fetchImpl } = refreshAwareFetch({ tokenStatus: 400, tokenBody: 'invalid_grant' })
+    const { io } = fakeRefreshIO()
+    const logs: string[] = []
+    const r = await emitLinearAgentActivity(
+      { agent_session_id: 'sess', type: 'thought', body: 'hi' },
+      { agent: 'carrie', resolveToken: okToken('lin_dead'), fetchImpl, refreshIO: () => io, log: (s) => logs.push(s) },
+    )
+    expect(r.content[0].text).toMatch(/Linear API 401/)
+    expect(logs.join('')).toMatch(/REVOKED/)
+  })
+
+  it('no 401 → no refresh attempt (happy path unchanged)', async () => {
+    const { fetchImpl, calls } = fakeFetch(200, { data: { agentActivityCreate: { success: true } } })
+    let refreshBuilt = false
+    const r = await emitLinearAgentActivity(
+      { agent_session_id: 'sess', type: 'message', body: 'ok' },
+      { agent: 'carrie', resolveToken: okToken('lin_good'), fetchImpl, refreshIO: () => { refreshBuilt = true; return fakeRefreshIO().io }, log: () => {} },
+    )
+    expect(r.content[0].text).toMatch(/emitted/)
+    expect(refreshBuilt).toBe(false)
+    expect(calls.length).toBe(1)
+  })
+})

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

@@ -209,3 +209,45 @@ describe('createLinearIssue — behaviour (#2312)', () => {
     expect(r.content[0].text).toMatch(/Linear API 401/)
   })
 })
+
+import { serializeBundle, type RefreshIO } from '../../src/linear/oauth-refresh.js'
+
+describe('createLinearIssue — token threading across gql calls after a 401 refresh', () => {
+  it('a 401 on the teams resolve refreshes, and issueCreate carries the FRESH token', async () => {
+    // No team_id + no dedup → flow is: teams(query) then issueCreate(mutation).
+    // The teams call 401s → refresh → retry; activeToken must then carry the
+    // fresh token to issueCreate. Pins the mutable-activeToken threading.
+    const auths: Array<{ op: string; auth?: string }> = []
+    let teamsHits = 0
+    const fetchImpl = (async (url: string, init: { headers?: Record<string, string>; body?: string }) => {
+      const auth = init?.headers?.Authorization
+      const body = init?.body ?? ''
+      if (url.includes('/oauth/token')) {
+        return { ok: true, status: 200, json: async () => ({ access_token: 'lin_fresh', expires_in: 3600 }), text: async () => '' } as unknown as Response
+      }
+      if (body.includes('teams(')) {
+        auths.push({ op: 'teams', auth })
+        teamsHits++
+        if (teamsHits === 1) return { ok: false, status: 401, json: async () => ({}), text: async () => 'unauthorized' } as unknown as Response
+        return { ok: true, status: 200, json: async () => ({ data: { teams: { nodes: [{ id: 'team_1', key: 'ENG', name: 'Eng' }] } } }), text: async () => '' } as unknown as Response
+      }
+      // issueCreate
+      auths.push({ op: 'issueCreate', auth })
+      return { ok: true, status: 200, json: async () => ({ data: { issueCreate: { success: true, issue: { identifier: 'ENG-1', url: 'https://linear.app/x/issue/ENG-1' } } } }), text: async () => '' } as unknown as Response
+    }) as unknown as typeof fetch
+
+    const io: RefreshIO = {
+      readBundle: async () => serializeBundle({ clientId: 'c', clientSecret: 's', refreshToken: 'rt', expiresAt: 0 }),
+      writeToken: async () => {},
+      writeBundle: async () => {},
+    }
+    const r = await createLinearIssue(
+      { title: 'a bug' },
+      { agent: 'carrie', resolveToken: okToken('lin_expired'), fetchImpl, refreshIO: () => io, log: () => {} },
+    )
+    expect(r.content[0].text).toMatch(/Filed:/)
+    // teams: expired then fresh (retry); issueCreate: fresh (threaded).
+    expect(auths.find((a) => a.op === 'issueCreate')?.auth).toBe('lin_fresh')
+    expect(auths.filter((a) => a.op === 'teams').map((a) => a.auth)).toEqual(['lin_expired', 'lin_fresh'])
+  })
+})