@calltelemetry/openclaw-linear 0.9.14 → 0.9.16

package/src/__test__/fixtures/recorded-sub-issue-flow.ts

@@ -2,7 +2,7 @@
  * Recorded API responses from sub-issue decomposition smoke test.
  * Auto-generated — do not edit manually.
  * Re-generate by running: npx vitest run src/__test__/smoke-linear-api.test.ts
- * Last recorded: 2026-02-22T03:40:54.418Z
+ * Last recorded: 2026-02-24T05:15:32.100Z
  */
 
 export const RECORDED = {
@@ -44,20 +44,20 @@ export const RECORDED = {
     }
   ],
   "createParent": {
-    "id": "933fa3c0-981a-4d9e-8b2c-7c5c4d5b4349",
-    "identifier": "UAT-438"
+    "id": "f236a0f3-a365-4e05-9b84-7c965da87c03",
+    "identifier": "UAT-638"
   },
   "createSubIssue1": {
-    "id": "4caa7593-5a51-4795-b98c-29e532589dfe",
-    "identifier": "UAT-439"
+    "id": "a1702cad-3206-4a2b-bb0c-c6ad47df8983",
+    "identifier": "UAT-639"
   },
   "createSubIssue2": {
-    "id": "0519065b-95eb-4752-966b-2099bbc5f3d1",
-    "identifier": "UAT-440"
+    "id": "d988eb3a-7d45-4d9b-8ee2-4d7580dd183e",
+    "identifier": "UAT-640"
   },
   "subIssue1Details": {
-    "id": "4caa7593-5a51-4795-b98c-29e532589dfe",
-    "identifier": "UAT-439",
+    "id": "a1702cad-3206-4a2b-bb0c-c6ad47df8983",
+    "identifier": "UAT-639",
     "title": "[SMOKE TEST] Sub-Issue 1: Backend API",
     "description": "Implement the backend search API endpoint.\n\nGiven a search query, when the API is called, then matching results are returned.",
     "estimate": 2,
@@ -75,6 +75,7 @@ export const RECORDED = {
     },
     "team": {
       "id": "08cba264-d774-4afd-bc93-ee8213d12ef8",
+      "key": "UAT",
       "name": "UAT",
       "issueEstimationType": "tShirt"
     },
@@ -83,16 +84,16 @@ export const RECORDED = {
     },
     "project": null,
     "parent": {
-      "id": "933fa3c0-981a-4d9e-8b2c-7c5c4d5b4349",
-      "identifier": "UAT-438"
+      "id": "f236a0f3-a365-4e05-9b84-7c965da87c03",
+      "identifier": "UAT-638"
     },
     "relations": {
       "nodes": []
     }
   },
   "subIssue2Details": {
-    "id": "0519065b-95eb-4752-966b-2099bbc5f3d1",
-    "identifier": "UAT-440",
+    "id": "d988eb3a-7d45-4d9b-8ee2-4d7580dd183e",
+    "identifier": "UAT-640",
     "title": "[SMOKE TEST] Sub-Issue 2: Frontend UI",
     "description": "Build the frontend search UI component.\n\nGiven the search page loads, when the user types a query, then results display in real-time.",
     "estimate": 3,
@@ -110,6 +111,7 @@ export const RECORDED = {
     },
     "team": {
       "id": "08cba264-d774-4afd-bc93-ee8213d12ef8",
+      "key": "UAT",
       "name": "UAT",
       "issueEstimationType": "tShirt"
     },
@@ -118,18 +120,18 @@ export const RECORDED = {
     },
     "project": null,
     "parent": {
-      "id": "933fa3c0-981a-4d9e-8b2c-7c5c4d5b4349",
-      "identifier": "UAT-438"
+      "id": "f236a0f3-a365-4e05-9b84-7c965da87c03",
+      "identifier": "UAT-638"
     },
     "relations": {
       "nodes": []
     }
   },
   "parentDetails": {
-    "id": "933fa3c0-981a-4d9e-8b2c-7c5c4d5b4349",
-    "identifier": "UAT-438",
+    "id": "f236a0f3-a365-4e05-9b84-7c965da87c03",
+    "identifier": "UAT-638",
     "title": "[SMOKE TEST] Sub-Issue Parent: Search Feature",
-    "description": "Auto-generated by smoke test to verify sub-issue decomposition.\n\nThis parent issue should have two sub-issues created under it.\n\nCreated: 2026-02-22T03:40:52.229Z",
+    "description": "Auto-generated by smoke test to verify sub-issue decomposition.\n\nThis parent issue should have two sub-issues created under it.\n\nCreated: 2026-02-24T05:15:30.285Z",
     "estimate": null,
     "state": {
       "name": "Backlog",
@@ -145,17 +147,12 @@ export const RECORDED = {
     },
     "team": {
       "id": "08cba264-d774-4afd-bc93-ee8213d12ef8",
+      "key": "UAT",
       "name": "UAT",
       "issueEstimationType": "tShirt"
     },
     "comments": {
-      "nodes": [
-        {
-          "body": "This thread is for an agent session with ctclaw.",
-          "user": null,
-          "createdAt": "2026-02-22T03:40:53.165Z"
-        }
-      ]
+      "nodes": []
     },
     "project": null,
     "parent": null,
@@ -164,11 +161,11 @@ export const RECORDED = {
     }
   },
   "createRelation": {
-    "id": "185dfd6c-362e-48a4-b717-e900407ced84"
+    "id": "139541b2-b088-4290-9ded-5b0167a42741"
   },
   "subIssue1WithRelation": {
-    "id": "4caa7593-5a51-4795-b98c-29e532589dfe",
-    "identifier": "UAT-439",
+    "id": "a1702cad-3206-4a2b-bb0c-c6ad47df8983",
+    "identifier": "UAT-639",
     "title": "[SMOKE TEST] Sub-Issue 1: Backend API",
     "description": "Implement the backend search API endpoint.\n\nGiven a search query, when the API is called, then matching results are returned.",
     "estimate": 2,
@@ -186,30 +183,25 @@ export const RECORDED = {
     },
     "team": {
       "id": "08cba264-d774-4afd-bc93-ee8213d12ef8",
+      "key": "UAT",
       "name": "UAT",
       "issueEstimationType": "tShirt"
     },
     "comments": {
-      "nodes": [
-        {
-          "body": "This thread is for an agent session with ctclaw.",
-          "user": null,
-          "createdAt": "2026-02-22T03:40:53.603Z"
-        }
-      ]
+      "nodes": []
     },
     "project": null,
     "parent": {
-      "id": "933fa3c0-981a-4d9e-8b2c-7c5c4d5b4349",
-      "identifier": "UAT-438"
+      "id": "f236a0f3-a365-4e05-9b84-7c965da87c03",
+      "identifier": "UAT-638"
     },
     "relations": {
       "nodes": [
         {
           "type": "blocks",
           "relatedIssue": {
-            "id": "0519065b-95eb-4752-966b-2099bbc5f3d1",
-            "identifier": "UAT-440",
+            "id": "d988eb3a-7d45-4d9b-8ee2-4d7580dd183e",
+            "identifier": "UAT-640",
             "title": "[SMOKE TEST] Sub-Issue 2: Frontend UI"
           }
         }
@@ -217,8 +209,8 @@ export const RECORDED = {
     }
   },
   "subIssue2WithRelation": {
-    "id": "0519065b-95eb-4752-966b-2099bbc5f3d1",
-    "identifier": "UAT-440",
+    "id": "d988eb3a-7d45-4d9b-8ee2-4d7580dd183e",
+    "identifier": "UAT-640",
     "title": "[SMOKE TEST] Sub-Issue 2: Frontend UI",
     "description": "Build the frontend search UI component.\n\nGiven the search page loads, when the user types a query, then results display in real-time.",
     "estimate": 3,
@@ -236,22 +228,17 @@ export const RECORDED = {
     },
     "team": {
       "id": "08cba264-d774-4afd-bc93-ee8213d12ef8",
+      "key": "UAT",
       "name": "UAT",
       "issueEstimationType": "tShirt"
     },
     "comments": {
-      "nodes": [
-        {
-          "body": "This thread is for an agent session with ctclaw.",
-          "user": null,
-          "createdAt": "2026-02-22T03:40:53.840Z"
-        }
-      ]
+      "nodes": []
     },
     "project": null,
     "parent": {
-      "id": "933fa3c0-981a-4d9e-8b2c-7c5c4d5b4349",
-      "identifier": "UAT-438"
+      "id": "f236a0f3-a365-4e05-9b84-7c965da87c03",
+      "identifier": "UAT-638"
     },
     "relations": {
       "nodes": []

package/src/agent/agent.test.ts

@@ -228,7 +228,7 @@ describe("runAgent subprocess", () => {
     const noisyOutput = [
       "[plugins] Dispatch gateway methods registered",
       "[plugins] Linear agent extension registered (agent: zoe)",
-      '[plugins] code_run: default backend=codex, aliases={"claude":"claude"}',
+      '[plugins] cli tools registered: cli_codex, cli_claude, cli_gemini (agent default: cli_codex)',
       JSON.stringify({ payloads: [{ text: "clean response" }], meta: {} }),
     ].join("\n");
     (api.runtime.system as any).runCommandWithTimeout = vi.fn().mockResolvedValue({

package/src/agent/agent.ts

@@ -79,6 +79,8 @@ export async function runAgent(params: {
    * Subprocess fallback is blocked — only the embedded runner is safe.
    */
   readOnly?: boolean;
+  /** Additional tools to deny (merged with config + readOnly denies) */
+  toolsDeny?: string[];
 }): Promise<AgentRunResult> {
   const maxAttempts = 2;
 
@@ -138,8 +140,9 @@ async function runAgentOnce(params: {
   timeoutMs?: number;
   streaming?: AgentStreamCallbacks;
   readOnly?: boolean;
+  toolsDeny?: string[];
 }): Promise<AgentRunResult> {
-  const { api, agentId, sessionId, streaming, readOnly } = params;
+  const { api, agentId, sessionId, streaming, readOnly, toolsDeny } = params;
 
   // Inject current timestamp into every LLM request
   const message = `${buildDateContext()}\n\n${params.message}`;
@@ -153,7 +156,7 @@ async function runAgentOnce(params: {
   // Try embedded runner first (has streaming callbacks)
   if (streaming) {
     try {
-      return await runEmbedded(api, agentId, sessionId, message, timeoutMs, streaming, wdConfig.inactivityMs, readOnly);
+      return await runEmbedded(api, agentId, sessionId, message, timeoutMs, streaming, wdConfig.inactivityMs, readOnly, toolsDeny);
     } catch (err) {
       // Read-only mode MUST NOT fall back to subprocess — subprocess runs a
       // full agent with no way to enforce the tool deny policy.
@@ -211,11 +214,13 @@ async function runEmbedded(
   streaming: AgentStreamCallbacks,
   inactivityMs: number,
   readOnly?: boolean,
+  toolsDeny?: string[],
 ): Promise<AgentRunResult> {
   const ext = await getExtensionAPI();
 
   // Load config so we can resolve agent dirs and providers correctly.
-  let config = await api.runtime.config.loadConfig();
+  const origConfig = await api.runtime.config.loadConfig();
+  let config = origConfig;
   let configAny = config as Record<string, any>;
 
   // ── Read-only enforcement ──────────────────────────────────────────
@@ -231,6 +236,17 @@ async function runEmbedded(
     api.logger.info(`Read-only mode: tools.deny = [${configAny.tools.deny.join(", ")}]`);
   }
 
+  // ── Additional toolsDeny entries ─────────────────────────────────────
+  if (toolsDeny?.length) {
+    if (config === origConfig) {
+      configAny = JSON.parse(JSON.stringify(origConfig));
+      config = configAny as typeof config;
+    }
+    if (!configAny.tools) configAny.tools = {};
+    const existing: string[] = Array.isArray(configAny.tools.deny) ? configAny.tools.deny : [];
+    configAny.tools.deny = [...new Set([...existing, ...toolsDeny])];
+  }
+
   // Resolve workspace and agent dirs from config (ext API ignores agentId).
   const dirs = resolveAgentDirs(agentId, configAny);
   const { workspaceDir, agentDir } = dirs;
@@ -333,13 +349,30 @@ async function runEmbedded(
       const phase = String(data.phase ?? "");
       const toolName = String(data.name ?? "tool");
       const meta = typeof data.meta === "string" ? data.meta : "";
-      const input = typeof data.input === "string" ? data.input : "";
+      const rawInput = data.input;
+      const input = typeof rawInput === "string" ? rawInput : "";
+
+      // Parse structured input for richer detail on cli_* tools
+      let inputObj: Record<string, any> | null = null;
+      if (rawInput && typeof rawInput === "object") {
+        inputObj = rawInput as Record<string, any>;
+      } else if (input.startsWith("{")) {
+        try { inputObj = JSON.parse(input); } catch {}
+      }
 
       // Tool execution start — emit action with tool name + available context
       if (phase === "start") {
         lastToolAction = toolName;
-        const detail = input || meta || toolName;
-        emit({ type: "action", action: `Running ${toolName}`, parameter: detail.slice(0, 300) });
+
+        // cli_codex / cli_claude / cli_gemini: show working dir and prompt excerpt
+        if (toolName.startsWith("cli_") && inputObj) {
+          const prompt = String(inputObj.prompt ?? "").slice(0, 250);
+          const workDir = inputObj.workingDir ? ` in ${inputObj.workingDir}` : "";
+          emit({ type: "action", action: `Running ${toolName}${workDir}`, parameter: prompt });
+        } else {
+          const detail = input || meta || toolName;
+          emit({ type: "action", action: `Running ${toolName}`, parameter: detail.slice(0, 300) });
+        }
       }
 
       // Tool execution update — partial progress (keeps Linear UI alive for long tools)

package/src/api/linear-api.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach, type Mock } from "vitest";
-import { resolveLinearToken, LinearAgentApi, AUTH_PROFILES_PATH } from "./linear-api.js";
+import { resolveLinearToken, LinearAgentApi, AUTH_PROFILES_PATH, refreshTokenProactively } from "./linear-api.js";
 
 // ---------------------------------------------------------------------------
 // Mocks
@@ -621,3 +621,190 @@ describe("LinearAgentApi", () => {
     });
   });
 });
+
+// ===========================================================================
+// refreshTokenProactively
+// ===========================================================================
+
+describe("refreshTokenProactively", () => {
+  beforeEach(() => {
+    delete process.env.LINEAR_CLIENT_ID;
+    delete process.env.LINEAR_CLIENT_SECRET;
+  });
+
+  it("skips refresh when token is still valid (not near expiry)", async () => {
+    const profileStore = {
+      profiles: {
+        "linear:default": {
+          accessToken: "still-good",
+          refreshToken: "r-tok",
+          expiresAt: Date.now() + 10 * 3_600_000, // 10 hours from now
+        },
+      },
+    };
+    mockReadFileSync.mockReturnValue(JSON.stringify(profileStore));
+
+    const result = await refreshTokenProactively({ clientId: "cid", clientSecret: "csecret" });
+
+    expect(result.refreshed).toBe(false);
+    expect(result.reason).toBe("token still valid");
+  });
+
+  it("skips refresh when credentials are missing", async () => {
+    const profileStore = {
+      profiles: {
+        "linear:default": {
+          accessToken: "expired-tok",
+          refreshToken: "r-tok",
+          expiresAt: Date.now() - 1000, // expired
+        },
+      },
+    };
+    mockReadFileSync.mockReturnValue(JSON.stringify(profileStore));
+
+    // No clientId or clientSecret provided
+    const result = await refreshTokenProactively();
+
+    expect(result.refreshed).toBe(false);
+    expect(result.reason).toContain("missing credentials");
+  });
+
+  it("skips refresh when auth-profiles.json is not readable", async () => {
+    // Default mockReadFileSync throws ENOENT (from outer beforeEach)
+
+    const result = await refreshTokenProactively();
+
+    expect(result.refreshed).toBe(false);
+    expect(result.reason).toBe("auth-profiles.json not readable");
+  });
+
+  it("skips refresh when no linear:default profile exists", async () => {
+    mockReadFileSync.mockReturnValue(JSON.stringify({ profiles: {} }));
+
+    const result = await refreshTokenProactively();
+
+    expect(result.refreshed).toBe(false);
+    expect(result.reason).toBe("no linear:default profile found");
+  });
+
+  it("refreshes expired token and persists to file", async () => {
+    const profileStore = {
+      profiles: {
+        "linear:default": {
+          accessToken: "old-tok",
+          access: "old-tok",
+          refreshToken: "old-refresh",
+          refresh: "old-refresh",
+          expiresAt: Date.now() - 1000, // expired
+          expires: Date.now() - 1000,
+        },
+      },
+    };
+    mockReadFileSync.mockReturnValue(JSON.stringify(profileStore));
+
+    mockRefreshLinearToken.mockResolvedValue({
+      access_token: "proactive-new-tok",
+      refresh_token: "proactive-new-refresh",
+      expires_in: 3600,
+    });
+
+    const result = await refreshTokenProactively({ clientId: "cid", clientSecret: "csecret" });
+
+    expect(result.refreshed).toBe(true);
+    expect(result.reason).toBe("token refreshed successfully");
+
+    // Verify refreshLinearToken was called with correct args
+    // (may have stale calls from outer tests, so check the latest call)
+    const calls = mockRefreshLinearToken.mock.calls;
+    const lastCall = calls[calls.length - 1];
+    expect(lastCall).toEqual(["cid", "csecret", "old-refresh"]);
+
+    // Verify it wrote back to the file
+    const writeCalls = mockWriteFileSync.mock.calls;
+    expect(writeCalls.length).toBeGreaterThanOrEqual(1);
+    // Get the LAST write call (which is ours)
+    const lastWrite = writeCalls[writeCalls.length - 1];
+    expect(lastWrite[0]).toBe(AUTH_PROFILES_PATH);
+    const writtenData = JSON.parse(lastWrite[1]);
+    const profile = writtenData.profiles["linear:default"];
+    // Tokens should NOT be the old values
+    expect(profile.accessToken).not.toBe("old-tok");
+    expect(profile.refreshToken).not.toBe("old-refresh");
+    // accessToken and access should match each other
+    expect(profile.accessToken).toBe(profile.access);
+    expect(profile.refreshToken).toBe(profile.refresh);
+    expect(profile.expiresAt).toBeGreaterThan(Date.now());
+    expect(profile.expiresAt).toBe(profile.expires);
+  });
+
+  it("refreshes token that is within the 1-hour buffer", async () => {
+    const profileStore = {
+      profiles: {
+        "linear:default": {
+          accessToken: "almost-expired-tok",
+          refreshToken: "r-tok",
+          expiresAt: Date.now() + 30 * 60 * 1000, // 30 min from now (within 1h buffer)
+        },
+      },
+    };
+    mockReadFileSync.mockReturnValue(JSON.stringify(profileStore));
+
+    mockRefreshLinearToken.mockResolvedValue({
+      access_token: "buffer-refreshed-tok",
+      expires_in: 3600,
+    });
+
+    const result = await refreshTokenProactively({ clientId: "cid", clientSecret: "csecret" });
+
+    expect(result.refreshed).toBe(true);
+    expect(result.reason).toBe("token refreshed successfully");
+  });
+
+  it("propagates refresh error to caller", async () => {
+    const profileStore = {
+      profiles: {
+        "linear:default": {
+          accessToken: "expired-tok",
+          refreshToken: "bad-refresh",
+          expiresAt: Date.now() - 1000,
+        },
+      },
+    };
+    mockReadFileSync.mockReturnValue(JSON.stringify(profileStore));
+
+    mockRefreshLinearToken.mockRejectedValue(new Error("Linear token refresh failed (400): invalid_grant"));
+
+    await expect(
+      refreshTokenProactively({ clientId: "cid", clientSecret: "csecret" }),
+    ).rejects.toThrow(/Linear token refresh failed/);
+  });
+
+  it("uses env vars when pluginConfig credentials are missing", async () => {
+    const profileStore = {
+      profiles: {
+        "linear:default": {
+          accessToken: "expired-tok",
+          refreshToken: "r-tok",
+          expiresAt: Date.now() - 1000,
+        },
+      },
+    };
+    mockReadFileSync.mockReturnValue(JSON.stringify(profileStore));
+
+    process.env.LINEAR_CLIENT_ID = "env-cid";
+    process.env.LINEAR_CLIENT_SECRET = "env-csecret";
+
+    mockRefreshLinearToken.mockResolvedValue({
+      access_token: "env-refreshed",
+      expires_in: 3600,
+    });
+
+    const result = await refreshTokenProactively(); // no pluginConfig
+
+    expect(result.refreshed).toBe(true);
+    // Verify env vars were used
+    const calls = mockRefreshLinearToken.mock.calls;
+    const lastCall = calls[calls.length - 1];
+    expect(lastCall).toEqual(["env-cid", "env-csecret", "r-tok"]);
+  });
+});

package/src/api/linear-api.ts

@@ -41,8 +41,10 @@ export function resolveLinearToken(pluginConfig?: Record<string, unknown>): {
     return { accessToken: fromConfig, source: "config" };
   }
 
-  // 2. Auth profile store (from OAuth flow) — preferred because OAuth tokens
-  //    carry app:assignable/app:mentionable scopes needed for Agent Sessions
+  // 2. Auth profile store (from OAuth flow) — OAuth tokens carry
+  //    app:assignable/app:mentionable scopes needed for Agent Sessions.
+  //    Token refresh is handled by the 6-hour proactive timer; if it's
+  //    expired here, fail loudly so we know the refresh is broken.
   try {
     const raw = readFileSync(AUTH_PROFILES_PATH, "utf8");
     const store = JSON.parse(raw);
@@ -59,7 +61,7 @@ export function resolveLinearToken(pluginConfig?: Record<string, unknown>): {
     // Profile store doesn't exist or is unreadable
   }
 
-  // 3. Env var fallback (personal API key — works for comments but not Agent Sessions)
+  // 3. Env var fallback
   const fromEnv = process.env.LINEAR_ACCESS_TOKEN ?? process.env.LINEAR_API_KEY;
   if (fromEnv) {
     return { accessToken: fromEnv, source: "env" };
@@ -311,7 +313,7 @@ export class LinearAgentApi {
     creator: { name: string; email: string | null } | null;
     assignee: { name: string } | null;
     labels: { nodes: Array<{ id: string; name: string }> };
-    team: { id: string; name: string; issueEstimationType: string };
+    team: { id: string; key: string; name: string; issueEstimationType: string };
     comments: { nodes: Array<{ body: string; user: { name: string } | null; createdAt: string }> };
     project: { id: string; name: string } | null;
     parent: { id: string; identifier: string } | null;
@@ -329,7 +331,7 @@ export class LinearAgentApi {
           creator { name email }
           assignee { name }
           labels { nodes { id name } }
-          team { id name issueEstimationType }
+          team { id key name issueEstimationType }
           comments(last: 10) {
             nodes {
               body
@@ -685,4 +687,111 @@ export class LinearAgentApi {
     );
     return data.webhookDelete.success;
   }
+
+  /**
+   * Get repository suggestions from Linear for an issue.
+   * Uses Linear's ML to rank candidate repos by relevance to the issue.
+   */
+  async getRepositorySuggestions(
+    issueId: string,
+    agentSessionId: string,
+    candidates: Array<{ hostname: string; repositoryFullName: string }>,
+  ): Promise<Array<{ repositoryFullName: string; hostname: string; confidence: number }>> {
+    if (candidates.length === 0) return [];
+    try {
+      const data = await this.gql<{
+        issueRepositorySuggestions: {
+          suggestions: Array<{ repositoryFullName: string; hostname: string; confidence: number }>;
+        };
+      }>(
+        `query RepoSuggestions($issueId: String!, $agentSessionId: String!, $candidateRepositories: [CandidateRepository!]!) {
+          issueRepositorySuggestions(issueId: $issueId, agentSessionId: $agentSessionId, candidateRepositories: $candidateRepositories) {
+            suggestions {
+              repositoryFullName
+              hostname
+              confidence
+            }
+          }
+        }`,
+        { issueId, agentSessionId, candidateRepositories: candidates },
+      );
+      return data.issueRepositorySuggestions?.suggestions ?? [];
+    } catch {
+      // Best-effort — if the API doesn't support this or fails, return empty
+      return [];
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Proactive token refresh (standalone, no API call required)
+// ---------------------------------------------------------------------------
+
+const PROACTIVE_BUFFER_MS = 3_600_000; // 1 hour before expiry
+
+/**
+ * Proactively refresh the Linear OAuth token if it's expired or about to expire.
+ * Returns true if refreshed, false if skipped (not needed or can't refresh).
+ *
+ * This is a standalone function that can be called from a timer without making
+ * a Linear API request. It reads/writes auth-profiles.json directly.
+ */
+export async function refreshTokenProactively(
+  pluginConfig?: Record<string, unknown>,
+): Promise<{ refreshed: boolean; reason: string }> {
+  // 1. Read auth-profiles.json, get linear:default profile
+  let store: any;
+  try {
+    const raw = readFileSync(AUTH_PROFILES_PATH, "utf8");
+    store = JSON.parse(raw);
+  } catch {
+    return { refreshed: false, reason: "auth-profiles.json not readable" };
+  }
+
+  const profile = store?.profiles?.["linear:default"];
+  if (!profile) {
+    return { refreshed: false, reason: "no linear:default profile found" };
+  }
+
+  // 2. Check if token is expired or will expire within 1 hour
+  const expiresAt = profile.expiresAt ?? profile.expires;
+  if (typeof expiresAt === "number" && Date.now() < expiresAt - PROACTIVE_BUFFER_MS) {
+    return { refreshed: false, reason: "token still valid" };
+  }
+
+  // 3. Resolve credentials
+  const clientId = (pluginConfig?.clientId as string) ?? process.env.LINEAR_CLIENT_ID;
+  const clientSecret = (pluginConfig?.clientSecret as string) ?? process.env.LINEAR_CLIENT_SECRET;
+  const refreshToken = profile.refreshToken ?? profile.refresh;
+
+  if (!clientId || !clientSecret || !refreshToken) {
+    return { refreshed: false, reason: "missing credentials (clientId, clientSecret, or refreshToken)" };
+  }
+
+  // 4. Refresh the token
+  const result = await refreshLinearToken(clientId, clientSecret, refreshToken);
+
+  // 5. Persist updated tokens back to auth-profiles.json (same pattern as persistToken())
+  const newAccessToken = result.access_token;
+  const newRefreshToken = result.refresh_token ?? refreshToken;
+  const newExpiresAt = Date.now() + result.expires_in * 1000;
+
+  try {
+    // Re-read to avoid clobbering concurrent writes
+    const freshRaw = readFileSync(AUTH_PROFILES_PATH, "utf8");
+    const freshStore = JSON.parse(freshRaw);
+    if (freshStore.profiles?.["linear:default"]) {
+      freshStore.profiles["linear:default"].accessToken = newAccessToken;
+      freshStore.profiles["linear:default"].access = newAccessToken;
+      freshStore.profiles["linear:default"].refreshToken = newRefreshToken;
+      freshStore.profiles["linear:default"].refresh = newRefreshToken;
+      freshStore.profiles["linear:default"].expiresAt = newExpiresAt;
+      freshStore.profiles["linear:default"].expires = newExpiresAt;
+      writeFileSync(AUTH_PROFILES_PATH, JSON.stringify(freshStore, null, 2), "utf8");
+    }
+  } catch {
+    // Best-effort persistence — token was refreshed even if write fails
+  }
+
+  return { refreshed: true, reason: "token refreshed successfully" };
 }