@calltelemetry/openclaw-linear 0.9.8 → 0.9.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calltelemetry/openclaw-linear",
-  "version": "0.9.8",
+  "version": "0.9.10",
   "description": "Linear Agent plugin for OpenClaw — webhook-driven AI pipeline with OAuth, multi-agent routing, and issue triage",
   "type": "module",
   "license": "MIT",

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-22T02:12:13.118Z
+ * Last recorded: 2026-02-22T02:38:53.901Z
  */
 
 export const RECORDED = {
@@ -44,20 +44,20 @@ export const RECORDED = {
     }
   ],
   "createParent": {
-    "id": "b2794dc5-82a1-4942-b999-36c7093b7477",
-    "identifier": "UAT-285"
+    "id": "953324f8-878f-40ba-b773-8d8815ee7987",
+    "identifier": "UAT-320"
   },
   "createSubIssue1": {
-    "id": "5a928cd6-7dd8-4e3d-9aa0-4699ee2f3990",
-    "identifier": "UAT-286"
+    "id": "69ce9a01-3bdb-4f4a-a882-e28e23d1b628",
+    "identifier": "UAT-321"
   },
   "createSubIssue2": {
-    "id": "b5d88918-6f3f-43d9-9e3b-e98608707efe",
-    "identifier": "UAT-287"
+    "id": "b39cc5eb-ec05-44aa-917b-562a290ecab6",
+    "identifier": "UAT-322"
   },
   "subIssue1Details": {
-    "id": "5a928cd6-7dd8-4e3d-9aa0-4699ee2f3990",
-    "identifier": "UAT-286",
+    "id": "69ce9a01-3bdb-4f4a-a882-e28e23d1b628",
+    "identifier": "UAT-321",
     "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,
@@ -83,16 +83,16 @@ export const RECORDED = {
     },
     "project": null,
     "parent": {
-      "id": "b2794dc5-82a1-4942-b999-36c7093b7477",
-      "identifier": "UAT-285"
+      "id": "953324f8-878f-40ba-b773-8d8815ee7987",
+      "identifier": "UAT-320"
     },
     "relations": {
       "nodes": []
     }
   },
   "subIssue2Details": {
-    "id": "b5d88918-6f3f-43d9-9e3b-e98608707efe",
-    "identifier": "UAT-287",
+    "id": "b39cc5eb-ec05-44aa-917b-562a290ecab6",
+    "identifier": "UAT-322",
     "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,
@@ -118,18 +118,18 @@ export const RECORDED = {
     },
     "project": null,
     "parent": {
-      "id": "b2794dc5-82a1-4942-b999-36c7093b7477",
-      "identifier": "UAT-285"
+      "id": "953324f8-878f-40ba-b773-8d8815ee7987",
+      "identifier": "UAT-320"
     },
     "relations": {
       "nodes": []
     }
   },
   "parentDetails": {
-    "id": "b2794dc5-82a1-4942-b999-36c7093b7477",
-    "identifier": "UAT-285",
+    "id": "953324f8-878f-40ba-b773-8d8815ee7987",
+    "identifier": "UAT-320",
     "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-22T02:12:11.695Z",
+    "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-22T02:38:52.132Z",
     "estimate": null,
     "state": {
       "name": "Backlog",
@@ -158,11 +158,11 @@ export const RECORDED = {
     }
   },
   "createRelation": {
-    "id": "6db881b7-5a05-449f-85f2-3c03dbb1e3f0"
+    "id": "9207d26d-d65d-45a2-ac76-b9233acea181"
   },
   "subIssue1WithRelation": {
-    "id": "5a928cd6-7dd8-4e3d-9aa0-4699ee2f3990",
-    "identifier": "UAT-286",
+    "id": "69ce9a01-3bdb-4f4a-a882-e28e23d1b628",
+    "identifier": "UAT-321",
     "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,
@@ -188,16 +188,16 @@ export const RECORDED = {
     },
     "project": null,
     "parent": {
-      "id": "b2794dc5-82a1-4942-b999-36c7093b7477",
-      "identifier": "UAT-285"
+      "id": "953324f8-878f-40ba-b773-8d8815ee7987",
+      "identifier": "UAT-320"
     },
     "relations": {
       "nodes": [
         {
           "type": "blocks",
           "relatedIssue": {
-            "id": "b5d88918-6f3f-43d9-9e3b-e98608707efe",
-            "identifier": "UAT-287",
+            "id": "b39cc5eb-ec05-44aa-917b-562a290ecab6",
+            "identifier": "UAT-322",
             "title": "[SMOKE TEST] Sub-Issue 2: Frontend UI"
           }
         }
@@ -205,8 +205,8 @@ export const RECORDED = {
     }
   },
   "subIssue2WithRelation": {
-    "id": "b5d88918-6f3f-43d9-9e3b-e98608707efe",
-    "identifier": "UAT-287",
+    "id": "b39cc5eb-ec05-44aa-917b-562a290ecab6",
+    "identifier": "UAT-322",
     "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,
@@ -232,14 +232,14 @@ export const RECORDED = {
         {
           "body": "This thread is for an agent session with ctclaw.",
           "user": null,
-          "createdAt": "2026-02-22T02:12:12.989Z"
+          "createdAt": "2026-02-22T02:38:53.699Z"
         }
       ]
     },
     "project": null,
     "parent": {
-      "id": "b2794dc5-82a1-4942-b999-36c7093b7477",
-      "identifier": "UAT-285"
+      "id": "953324f8-878f-40ba-b773-8d8815ee7987",
+      "identifier": "UAT-320"
     },
     "relations": {
       "nodes": []

package/src/__test__/webhook-scenarios.test.ts

@@ -649,7 +649,7 @@ describe("webhook scenario tests — full handler flows", () => {
 
       expect(mockRunAgent).toHaveBeenCalledOnce();
       const runArgs = mockRunAgent.mock.calls[0][0];
-      expect(runArgs.message).toContain("Additional Guidance");
+      expect(runArgs.message).toContain("Workspace Guidance");
       expect(runArgs.message).toContain("Always use the main branch");
     });
 
@@ -668,11 +668,12 @@ describe("webhook scenario tests — full handler flows", () => {
       expect(mockRunAgent).toHaveBeenCalledOnce();
       const msg = mockRunAgent.mock.calls[0][0].message;
 
-      // Guidance text should appear in the appendix section, not as the user's comment
-      const userMsgSection = msg.split("Additional Guidance")[0];
-      expect(userMsgSection).toContain("Please fix the routing bug");
-      // The guidance string itself should not appear before the appendix
-      expect(userMsgSection).not.toContain("Always use the main branch");
+      // Guidance text should appear in the guidance section, not as the user's latest message
+      expect(msg).toContain("Please fix the routing bug");
+      // The guidance text should be within the guidance section, not in the "Latest message" block
+      const latestMsgSection = msg.split("**Latest message:**")[1] ?? "";
+      expect(latestMsgSection).toContain("Please fix the routing bug");
+      expect(latestMsgSection).not.toContain("Always use the main branch");
     });
 
     it("prompted: includes guidance from promptContext", async () => {
@@ -688,7 +689,7 @@ describe("webhook scenario tests — full handler flows", () => {
       expect(mockRunAgent).toHaveBeenCalledOnce();
       const msg = mockRunAgent.mock.calls[0][0].message;
       expect(msg).toContain("Can you also fix the tests?");
-      expect(msg).toContain("Additional Guidance");
+      expect(msg).toContain("Workspace Guidance");
       expect(msg).toContain("Use TypeScript strict mode");
     });
 
@@ -704,7 +705,7 @@ describe("webhook scenario tests — full handler flows", () => {
 
       expect(mockRunAgent).toHaveBeenCalledOnce();
       const msg = mockRunAgent.mock.calls[0][0].message;
-      expect(msg).not.toContain("Additional Guidance");
+      expect(msg).not.toContain("Workspace Guidance");
       expect(msg).not.toContain("Should not appear in prompt");
     });
 
@@ -724,7 +725,7 @@ describe("webhook scenario tests — full handler flows", () => {
 
       expect(mockRunAgent).toHaveBeenCalledOnce();
       const msg = mockRunAgent.mock.calls[0][0].message;
-      expect(msg).not.toContain("Additional Guidance");
+      expect(msg).not.toContain("Workspace Guidance");
       expect(msg).not.toContain("Should be suppressed");
     });
 
@@ -782,7 +783,7 @@ describe("webhook scenario tests — full handler flows", () => {
 
       expect(mockRunAgent).toHaveBeenCalledOnce();
       const msg = mockRunAgent.mock.calls[0][0].message;
-      expect(msg).toContain("Additional Guidance");
+      expect(msg).toContain("Workspace Guidance");
       expect(msg).toContain("Cached guidance from session event");
     });
   });

package/src/infra/cli.ts

@@ -13,6 +13,7 @@ import { validateRepoPath } from "./multi-repo.js";
 import { LINEAR_OAUTH_AUTH_URL, LINEAR_OAUTH_TOKEN_URL, LINEAR_AGENT_SCOPES } from "../api/auth.js";
 import { listWorktrees } from "./codex-worktree.js";
 import { loadPrompts, clearPromptCache } from "../pipeline/pipeline.js";
+import { PROFILES_PATH, createAgentProfilesFile, loadAgentProfiles } from "./shared-profiles.js";
 import {
   formatMessage,
   parseNotificationsConfig,
@@ -213,6 +214,265 @@ export function registerCli(program: Command, api: OpenClawPluginApi): void {
       console.log();
     });
 
+  // --- interactive profile creation helper ---
+  async function createProfileInteractive(): Promise<void> {
+    const name = await prompt("  Agent name (lowercase, no spaces — e.g. bobbin): ");
+    if (!name) {
+      console.log("  Skipped.\n");
+      return;
+    }
+
+    const agentId = name.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+    if (!agentId) {
+      console.log("  Invalid name. Skipped.\n");
+      return;
+    }
+
+    const labelDefault = agentId.charAt(0).toUpperCase() + agentId.slice(1);
+    const labelInput = await prompt(`  Display label [${labelDefault}]: `);
+    const label = labelInput || labelDefault;
+
+    const aliasInput = await prompt(`  Additional @mention aliases (comma-separated, or blank): `);
+    const extraAliases = aliasInput
+      ? aliasInput.split(",").map(a => a.trim().toLowerCase()).filter(Boolean)
+      : [];
+    const mentionAliases = [agentId, ...extraAliases.filter(a => a !== agentId)];
+
+    try {
+      createAgentProfilesFile({ agentId, label, mentionAliases });
+      console.log(`\n  ✓ Created ${PROFILES_PATH}`);
+      console.log(`    Agent: ${agentId} (${label})`);
+      console.log(`    Aliases: ${mentionAliases.map(a => "@" + a).join(", ")}`);
+      console.log(`    Default: yes`);
+    } catch (err) {
+      console.log(`\n  ✗ Failed to create agent-profiles.json: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  // --- openclaw openclaw-linear setup ---
+  linear
+    .command("setup")
+    .description("Guided first-time setup — creates agent profile, checks auth, provisions webhook")
+    .action(async () => {
+      const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
+
+      console.log("\nLinear Plugin Setup");
+      console.log("═".repeat(50));
+
+      // ---------------------------------------------------------------
+      // Step 1: Agent Profile
+      // ---------------------------------------------------------------
+      console.log("\nStep 1: Agent Profile");
+      console.log("─".repeat(50));
+
+      if (existsSync(PROFILES_PATH)) {
+        const profiles = loadAgentProfiles();
+        const count = Object.keys(profiles).length;
+        if (count > 0) {
+          const names = Object.entries(profiles)
+            .map(([id, p]) => `${id}${p.isDefault ? " (default)" : ""}`)
+            .join(", ");
+          console.log(`  ✓ agent-profiles.json found (${count} agent${count > 1 ? "s" : ""}: ${names})`);
+        } else {
+          console.log("  ⚠ agent-profiles.json exists but has no agents.");
+          const fix = await prompt("  Overwrite with a new profile? [Y/n]: ");
+          if (fix.toLowerCase() === "n") {
+            console.log("  Skipped. Fix the file manually and re-run setup.\n");
+          } else {
+            await createProfileInteractive();
+          }
+        }
+      } else {
+        console.log("  No agent-profiles.json found — let's create one!\n");
+        console.log("  Your agent needs a name so Linear users can @mention it.");
+        console.log("  Example: if your agent is called \"bobbin\", users type @bobbin in comments.\n");
+        await createProfileInteractive();
+      }
+
+      // ---------------------------------------------------------------
+      // Step 2: Authentication
+      // ---------------------------------------------------------------
+      console.log("\nStep 2: Authentication");
+      console.log("─".repeat(50));
+
+      const tokenInfo = resolveLinearToken(pluginConfig);
+      if (tokenInfo.accessToken) {
+        // Verify the token works
+        try {
+          const authHeader = tokenInfo.refreshToken
+            ? `Bearer ${tokenInfo.accessToken}`
+            : tokenInfo.accessToken;
+          const res = await fetch(LINEAR_GRAPHQL_URL, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Authorization: authHeader },
+            body: JSON.stringify({ query: `{ viewer { name } organization { name } }` }),
+          });
+          if (res.ok) {
+            const payload = await res.json() as any;
+            if (payload.data?.viewer) {
+              console.log(`  ✓ Authenticated as ${payload.data.viewer.name} (${payload.data.organization.name})`);
+            } else {
+              console.log(`  ⚠ Token found but API returned errors. Run: openclaw openclaw-linear auth`);
+            }
+          } else {
+            console.log(`  ⚠ Token found but API returned ${res.status}. Run: openclaw openclaw-linear auth`);
+          }
+        } catch {
+          console.log(`  ⚠ Token found but API unreachable. Check network and retry.`);
+        }
+      } else {
+        console.log("  No Linear token found.\n");
+        const doAuth = await prompt("  Run OAuth authorization now? [Y/n]: ");
+        if (doAuth.toLowerCase() !== "n") {
+          const clientId = (pluginConfig?.clientId as string) ?? process.env.LINEAR_CLIENT_ID;
+          const clientSecret = (pluginConfig?.clientSecret as string) ?? process.env.LINEAR_CLIENT_SECRET;
+
+          if (!clientId || !clientSecret) {
+            console.log("\n  ✗ OAuth client ID and secret not configured.");
+            console.log("    Set LINEAR_CLIENT_ID and LINEAR_CLIENT_SECRET env vars,");
+            console.log("    or add clientId/clientSecret to the plugin config in openclaw.json.");
+            console.log("    Then re-run: openclaw openclaw-linear setup\n");
+          } else {
+            const gatewayPort = process.env.OPENCLAW_GATEWAY_PORT ?? "18789";
+            const redirectUri = (pluginConfig?.redirectUri as string)
+              ?? process.env.LINEAR_REDIRECT_URI
+              ?? `http://localhost:${gatewayPort}/linear/oauth/callback`;
+
+            const state = Math.random().toString(36).substring(7);
+            const authUrl = `${LINEAR_OAUTH_AUTH_URL}?client_id=${clientId}&redirect_uri=${encodeURIComponent(redirectUri)}&response_type=code&scope=${encodeURIComponent(LINEAR_AGENT_SCOPES)}&state=${state}&actor=app`;
+
+            console.log("\n  Opening Linear OAuth page...\n");
+            console.log(`    ${authUrl}\n`);
+            openBrowser(authUrl);
+
+            const code = await prompt("  Paste the authorization code from Linear: ");
+            if (code) {
+              try {
+                const response = await fetch(LINEAR_OAUTH_TOKEN_URL, {
+                  method: "POST",
+                  headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                  body: new URLSearchParams({
+                    grant_type: "authorization_code",
+                    code,
+                    client_id: clientId,
+                    client_secret: clientSecret,
+                    redirect_uri: redirectUri,
+                  }),
+                });
+
+                if (response.ok) {
+                  const tokens = await response.json() as any;
+                  let store: any = { version: 1, profiles: {} };
+                  try {
+                    const raw = readFileSync(AUTH_PROFILES_PATH, "utf8");
+                    store = JSON.parse(raw);
+                  } catch { /* fresh store */ }
+
+                  store.profiles = store.profiles ?? {};
+                  store.profiles["linear:default"] = {
+                    type: "oauth",
+                    provider: "linear",
+                    accessToken: tokens.access_token,
+                    access: tokens.access_token,
+                    refreshToken: tokens.refresh_token ?? null,
+                    refresh: tokens.refresh_token ?? null,
+                    expiresAt: tokens.expires_in ? Date.now() + tokens.expires_in * 1000 : null,
+                    expires: tokens.expires_in ? Date.now() + tokens.expires_in * 1000 : null,
+                    scope: tokens.scope,
+                  };
+
+                  writeFileSync(AUTH_PROFILES_PATH, JSON.stringify(store, null, 2), "utf8");
+                  console.log("  ✓ Token saved to auth-profiles.json");
+                } else {
+                  const error = await response.text();
+                  console.log(`  ✗ Token exchange failed (${response.status}): ${error}`);
+                }
+              } catch (err) {
+                console.log(`  ✗ Token exchange error: ${err instanceof Error ? err.message : String(err)}`);
+              }
+            } else {
+              console.log("  Skipped. Run: openclaw openclaw-linear auth later.");
+            }
+          }
+        } else {
+          console.log("  Skipped. Run: openclaw openclaw-linear auth when ready.");
+        }
+      }
+
+      // ---------------------------------------------------------------
+      // Step 3: Webhook
+      // ---------------------------------------------------------------
+      console.log("\nStep 3: Webhook");
+      console.log("─".repeat(50));
+
+      const freshToken = resolveLinearToken(pluginConfig);
+      if (!freshToken.accessToken) {
+        console.log("  ⚠ Skipped — no auth token available. Complete Step 2 first.");
+      } else {
+        const { provisionWebhook, getWebhookStatus } = await import("./webhook-provision.js");
+        const linearApi = new LinearAgentApi(freshToken.accessToken, {
+          refreshToken: freshToken.refreshToken,
+          expiresAt: freshToken.expiresAt,
+        });
+
+        const webhookUrl = (pluginConfig?.webhookUrl as string)
+          ?? "https://linear.calltelemetry.com/linear/webhook";
+
+        try {
+          const status = await getWebhookStatus(linearApi, webhookUrl);
+          if (status && status.issues.length === 0) {
+            console.log(`  ✓ Webhook already configured (${webhookUrl})`);
+          } else {
+            const result = await provisionWebhook(linearApi, webhookUrl, { allPublicTeams: true });
+            if (result.action === "created") {
+              console.log(`  ✓ Webhook created (${result.webhookId})`);
+            } else if (result.action === "updated") {
+              console.log(`  ✓ Webhook updated (${result.webhookId})`);
+            } else {
+              console.log(`  ✓ Webhook OK (${result.webhookId})`);
+            }
+          }
+        } catch (err) {
+          console.log(`  ⚠ Webhook check failed: ${err instanceof Error ? err.message : String(err)}`);
+          console.log("    Run: openclaw openclaw-linear webhooks setup");
+        }
+      }
+
+      // ---------------------------------------------------------------
+      // Step 4: Verify
+      // ---------------------------------------------------------------
+      console.log("\nStep 4: Verification");
+      console.log("─".repeat(50));
+
+      try {
+        const { runDoctor, formatReport } = await import("./doctor.js");
+        const report = await runDoctor({
+          fix: false,
+          json: false,
+          pluginConfig,
+        });
+
+        console.log(formatReport(report));
+
+        if (report.summary.errors === 0) {
+          const profiles = loadAgentProfiles();
+          const defaultAgent = Object.entries(profiles).find(([, p]) => p.isDefault);
+          const agentName = defaultAgent?.[1]?.label ?? defaultAgent?.[0] ?? "your agent";
+          console.log("─".repeat(50));
+          console.log(`Setup complete! ${agentName} is ready to receive Linear issues.`);
+          console.log(`\nRestart the gateway to apply changes:`);
+          console.log(`  systemctl --user restart openclaw-gateway\n`);
+        } else {
+          console.log("─".repeat(50));
+          console.log("Some issues remain. Fix them and run: openclaw openclaw-linear doctor --fix\n");
+          process.exitCode = 1;
+        }
+      } catch (err) {
+        console.log(`  ⚠ Doctor failed: ${err instanceof Error ? err.message : String(err)}`);
+        console.log("  Run: openclaw openclaw-linear doctor for details.\n");
+      }
+    });
+
   // --- openclaw openclaw-linear worktrees ---
   linear
     .command("worktrees")

package/src/infra/doctor.ts

@@ -14,6 +14,7 @@ import { loadPrompts, clearPromptCache } from "../pipeline/pipeline.js";
 import { listWorktrees } from "./codex-worktree.js";
 import { loadCodingConfig, resolveCodingBackend, type CodingBackend } from "../tools/code-tool.js";
 import { getWebhookStatus, provisionWebhook, REQUIRED_RESOURCE_TYPES } from "./webhook-provision.js";
+import { createAgentProfilesFile } from "./shared-profiles.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -227,22 +228,51 @@ export async function checkAuth(pluginConfig?: Record<string, unknown>): Promise
 // Section 2: Agent Configuration
 // ---------------------------------------------------------------------------
 
-export function checkAgentConfig(pluginConfig?: Record<string, unknown>): CheckResult[] {
+export function checkAgentConfig(pluginConfig?: Record<string, unknown>, fix = false): CheckResult[] {
   const checks: CheckResult[] = [];
 
   // Load profiles
   let profiles: Record<string, AgentProfile>;
   try {
     if (!existsSync(AGENT_PROFILES_PATH)) {
-      checks.push(fail(
-        "agent-profiles.json not found",
-        `Expected at: ${AGENT_PROFILES_PATH}`,
-      ));
-      return checks;
+      if (fix) {
+        try {
+          createAgentProfilesFile({
+            agentId: "my-agent",
+            label: "My Agent",
+            mentionAliases: ["my-agent"],
+          });
+          checks.push(pass('agent-profiles.json created with default "my-agent" profile (--fix)'));
+          checks.push(warn(
+            'Customize your agent profile',
+            undefined,
+            { fix: `Edit ${AGENT_PROFILES_PATH} to set your agent's name and aliases, or run: openclaw openclaw-linear setup` },
+          ));
+          // Reload after creation
+          const raw = readFileSync(AGENT_PROFILES_PATH, "utf8");
+          profiles = JSON.parse(raw).agents ?? {};
+          // Continue to remaining checks below
+        } catch (err) {
+          checks.push(fail(
+            "Failed to create agent-profiles.json",
+            err instanceof Error ? err.message : String(err),
+            "Run: openclaw openclaw-linear setup",
+          ));
+          return checks;
+        }
+      } else {
+        checks.push(fail(
+          "agent-profiles.json not found",
+          `Expected at: ${AGENT_PROFILES_PATH}`,
+          "Run: openclaw openclaw-linear setup",
+        ));
+        return checks;
+      }
+    } else {
+      const raw = readFileSync(AGENT_PROFILES_PATH, "utf8");
+      const parsed = JSON.parse(raw);
+      profiles = parsed.agents ?? {};
     }
-    const raw = readFileSync(AGENT_PROFILES_PATH, "utf8");
-    const parsed = JSON.parse(raw);
-    profiles = parsed.agents ?? {};
   } catch (err) {
     checks.push(fail(
       "agent-profiles.json invalid JSON",
@@ -730,7 +760,7 @@ export async function runDoctor(opts: DoctorOptions): Promise<DoctorReport> {
   sections.push({ name: "Authentication & Tokens", checks: auth.checks });
 
   // 2. Agent config
-  sections.push({ name: "Agent Configuration", checks: checkAgentConfig(opts.pluginConfig) });
+  sections.push({ name: "Agent Configuration", checks: checkAgentConfig(opts.pluginConfig, opts.fix) });
 
   // 3. Coding tools
   sections.push({ name: "Coding Tools", checks: checkCodingTools(opts.pluginConfig) });

package/src/infra/shared-profiles.test.ts

@@ -4,12 +4,18 @@ import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 // Mocks
 // ---------------------------------------------------------------------------
 
-const { mockReadFileSync } = vi.hoisted(() => ({
+const { mockReadFileSync, mockWriteFileSync, mockMkdirSync, mockExistsSync } = vi.hoisted(() => ({
   mockReadFileSync: vi.fn(),
+  mockWriteFileSync: vi.fn(),
+  mockMkdirSync: vi.fn(),
+  mockExistsSync: vi.fn().mockReturnValue(true),
 }));
 
 vi.mock("node:fs", () => ({
   readFileSync: mockReadFileSync,
+  writeFileSync: mockWriteFileSync,
+  mkdirSync: mockMkdirSync,
+  existsSync: mockExistsSync,
 }));
 
 // ---------------------------------------------------------------------------
@@ -21,6 +27,9 @@ import {
   buildMentionPattern,
   resolveAgentFromAlias,
   resolveDefaultAgent,
+  createAgentProfilesFile,
+  validateProfiles,
+  PROFILES_PATH,
   _resetProfilesCacheForTesting,
   type AgentProfile,
 } from "./shared-profiles.js";
@@ -61,6 +70,7 @@ beforeEach(() => {
   vi.clearAllMocks();
   _resetProfilesCacheForTesting();
   mockReadFileSync.mockReturnValue(PROFILES_JSON);
+  mockExistsSync.mockReturnValue(true);
 });
 
 afterEach(() => {
@@ -260,3 +270,115 @@ describe("resolveDefaultAgent", () => {
     expect(result).toBe("mal");
   });
 });
+
+// ---------------------------------------------------------------------------
+// createAgentProfilesFile
+// ---------------------------------------------------------------------------
+
+describe("createAgentProfilesFile", () => {
+  it("writes correct JSON structure to PROFILES_PATH", () => {
+    createAgentProfilesFile({
+      agentId: "bobbin",
+      label: "Bobbin",
+      mentionAliases: ["bobbin", "bob"],
+    });
+
+    expect(mockMkdirSync).toHaveBeenCalledTimes(1);
+    expect(mockWriteFileSync).toHaveBeenCalledTimes(1);
+
+    const [path, content] = mockWriteFileSync.mock.calls[0];
+    expect(path).toBe(PROFILES_PATH);
+
+    const parsed = JSON.parse(content);
+    expect(parsed.agents.bobbin).toEqual({
+      label: "Bobbin",
+      mission: "AI assistant for Linear issues",
+      isDefault: true,
+      mentionAliases: ["bobbin", "bob"],
+    });
+  });
+
+  it("uses custom mission when provided", () => {
+    createAgentProfilesFile({
+      agentId: "claw",
+      label: "The Claw",
+      mentionAliases: ["claw"],
+      mission: "Code review specialist",
+    });
+
+    const [, content] = mockWriteFileSync.mock.calls[0];
+    const parsed = JSON.parse(content);
+    expect(parsed.agents.claw.mission).toBe("Code review specialist");
+  });
+
+  it("creates parent directory recursively", () => {
+    createAgentProfilesFile({
+      agentId: "test",
+      label: "Test",
+      mentionAliases: ["test"],
+    });
+
+    expect(mockMkdirSync).toHaveBeenCalledWith(
+      expect.any(String),
+      { recursive: true },
+    );
+  });
+
+  it("busts the profile cache", () => {
+    // Load to populate cache
+    loadAgentProfiles();
+    expect(mockReadFileSync).toHaveBeenCalledTimes(1);
+
+    // Create a new profile — should bust cache
+    createAgentProfilesFile({
+      agentId: "fresh",
+      label: "Fresh",
+      mentionAliases: ["fresh"],
+    });
+
+    // Next load should re-read from disk (cache was busted)
+    loadAgentProfiles();
+    expect(mockReadFileSync).toHaveBeenCalledTimes(2);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// validateProfiles
+// ---------------------------------------------------------------------------
+
+describe("validateProfiles", () => {
+  it("returns error when file is missing", () => {
+    mockExistsSync.mockReturnValue(false);
+
+    const result = validateProfiles();
+    expect(result).not.toBeNull();
+    expect(result).toContain("not found");
+    expect(result).toContain("openclaw openclaw-linear setup");
+  });
+
+  it("returns null when file is valid with agents", () => {
+    mockExistsSync.mockReturnValue(true);
+    mockReadFileSync.mockReturnValue(PROFILES_JSON);
+
+    const result = validateProfiles();
+    expect(result).toBeNull();
+  });
+
+  it("returns error when JSON is invalid", () => {
+    mockExistsSync.mockReturnValue(true);
+    mockReadFileSync.mockImplementation(() => { throw new SyntaxError("Unexpected token"); });
+
+    const result = validateProfiles();
+    expect(result).not.toBeNull();
+    expect(result).toContain("could not be parsed");
+  });
+
+  it("returns error when agents object is empty", () => {
+    mockExistsSync.mockReturnValue(true);
+    mockReadFileSync.mockReturnValue(JSON.stringify({ agents: {} }));
+
+    const result = validateProfiles();
+    expect(result).not.toBeNull();
+    expect(result).toContain("no agents configured");
+  });
+});

package/src/infra/shared-profiles.ts

@@ -5,8 +5,8 @@
  * resolveAgentFromAlias() implementations that were previously in
  * webhook.ts, intent-classify.ts, and tier-assess.ts.
  */
-import { readFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 
 // ---------------------------------------------------------------------------
@@ -26,7 +26,7 @@ export interface AgentProfile {
 // Cached profile loader (5s TTL)
 // ---------------------------------------------------------------------------
 
-const PROFILES_PATH = join(homedir(), ".openclaw", "agent-profiles.json");
+export const PROFILES_PATH = join(homedir(), ".openclaw", "agent-profiles.json");
 
 let profilesCache: { data: Record<string, AgentProfile>; loadedAt: number } | null = null;
 const PROFILES_CACHE_TTL_MS = 5_000;
@@ -137,7 +137,7 @@ export function validateProfiles(): string | null {
       `EOF\n` +
       "```\n\n" +
       `Then restart the gateway: \`systemctl --user restart openclaw-gateway\`\n\n` +
-      `Run \`openclaw openclaw-linear doctor\` to verify your setup.`
+      `Or run the guided setup: \`openclaw openclaw-linear setup\``
     );
   }
 
@@ -158,13 +158,45 @@ export function validateProfiles(): string | null {
     return (
       `**Critical setup error:** \`agent-profiles.json\` has no agents configured.\n\n` +
       `Add at least one agent entry to the \`"agents"\` object in \`${PROFILES_PATH}\`.\n` +
-      `Run \`openclaw openclaw-linear doctor\` for a guided setup check.`
+      `Run \`openclaw openclaw-linear setup\` for guided setup.`
     );
   }
 
   return null;
 }
 
+// ---------------------------------------------------------------------------
+// Profile creation (setup wizard / doctor --fix)
+// ---------------------------------------------------------------------------
+
+export interface CreateProfileOpts {
+  agentId: string;
+  label: string;
+  mentionAliases: string[];
+  mission?: string;
+}
+
+/**
+ * Create `agent-profiles.json` with a single default agent.
+ * Creates the parent directory if needed. Throws on write failure.
+ */
+export function createAgentProfilesFile(opts: CreateProfileOpts): void {
+  const data = {
+    agents: {
+      [opts.agentId]: {
+        label: opts.label,
+        mission: opts.mission ?? "AI assistant for Linear issues",
+        isDefault: true,
+        mentionAliases: opts.mentionAliases,
+      },
+    },
+  };
+  mkdirSync(dirname(PROFILES_PATH), { recursive: true });
+  writeFileSync(PROFILES_PATH, JSON.stringify(data, null, 2) + "\n", "utf8");
+  // Bust the cache so the next load picks up the new file
+  profilesCache = null;
+}
+
 // ---------------------------------------------------------------------------
 // Test-only: reset cache
 // ---------------------------------------------------------------------------

package/src/pipeline/active-session.ts

@@ -42,9 +42,16 @@ let _affinityTtlMs = 30 * 60_000; // 30 minutes default
 /**
  * Register the active session for an issue. Idempotent — calling again
  * for the same issue just updates the session.
+ *
+ * Also eagerly records agent affinity so that follow-up webhooks arriving
+ * during or after the run resolve to the correct agent — even if the
+ * gateway restarts before clearActiveSession is called.
  */
 export function setActiveSession(session: ActiveSession): void {
   sessions.set(session.issueId, session);
+  if (session.agentId) {
+    recordIssueAffinity(session.issueId, session.agentId);
+  }
 }
 
 /**

package/src/pipeline/guidance.test.ts

@@ -93,7 +93,7 @@ describe("extractGuidanceFromPromptContext", () => {
 describe("formatGuidanceAppendix", () => {
   it("formats guidance as appendix block", () => {
     const result = formatGuidanceAppendix("Use main branch.");
-    expect(result).toContain("## Additional Guidance");
+    expect(result).toContain("## IMPORTANT — Workspace Guidance");
     expect(result).toContain("Use main branch.");
     expect(result).toMatch(/^---\n/);
     expect(result).toMatch(/\n---$/);

package/src/pipeline/guidance.ts

@@ -119,7 +119,9 @@ export function formatGuidanceAppendix(guidance: string | null): string {
   const trimmed = guidance.trim().slice(0, MAX_GUIDANCE_CHARS);
   return [
     `---`,
-    `## Additional Guidance (from Linear workspace/team settings)`,
+    `## IMPORTANT — Workspace Guidance (MUST follow)`,
+    `The workspace owner has set the following mandatory instructions. You MUST incorporate these into your response:`,
+    ``,
     trimmed,
     `---`,
   ].join("\n");

package/src/pipeline/pipeline.test.ts

@@ -405,7 +405,7 @@ describe("buildWorkerTask (additional branches)", () => {
     const { task } = buildWorkerTask(issue, "/wt/API-42", {
       guidance: "Always use TypeScript strict mode",
     });
-    expect(task).toContain("Additional Guidance");
+    expect(task).toContain("Workspace Guidance");
     expect(task).toContain("Always use TypeScript strict mode");
   });
 
@@ -413,7 +413,7 @@ describe("buildWorkerTask (additional branches)", () => {
     const { task } = buildWorkerTask(issue, "/wt/API-42", {
       guidance: undefined,
     });
-    expect(task).not.toContain("Additional Guidance");
+    expect(task).not.toContain("Workspace Guidance");
   });
 
   it("uses undefined description as (no description)", () => {
@@ -443,7 +443,7 @@ describe("buildAuditTask (additional branches)", () => {
     const { task } = buildAuditTask(issue, "/wt/API-99", undefined, {
       guidance: "Focus on security",
     });
-    expect(task).toContain("Additional Guidance");
+    expect(task).toContain("Workspace Guidance");
     expect(task).toContain("Focus on security");
   });
 
@@ -451,7 +451,7 @@ describe("buildAuditTask (additional branches)", () => {
     const { task } = buildAuditTask(issue, "/wt/API-99", undefined, {
       guidance: undefined,
     });
-    expect(task).not.toContain("Additional Guidance");
+    expect(task).not.toContain("Workspace Guidance");
   });
 
   it("handles undefined description", () => {

package/src/pipeline/pipeline.ts

@@ -197,7 +197,7 @@ export function buildWorkerTask(
     attempt: String(opts?.attempt ?? 0),
     gaps: opts?.gaps?.length ? "- " + opts.gaps.join("\n- ") : "",
     guidance: opts?.guidance
-      ? `\n---\n## Additional Guidance (from Linear workspace/team settings)\n${opts.guidance.slice(0, 2000)}\n---`
+      ? `\n---\n## IMPORTANT — Workspace Guidance (MUST follow)\nThe workspace owner has set the following mandatory instructions. You MUST incorporate these into your response:\n\n${opts.guidance.slice(0, 2000)}\n---`
       : "",
   };
 
@@ -231,7 +231,7 @@ export function buildAuditTask(
     attempt: "0",
     gaps: "",
     guidance: opts?.guidance
-      ? `\n---\n## Additional Guidance (from Linear workspace/team settings)\n${opts.guidance.slice(0, 2000)}\n---`
+      ? `\n---\n## IMPORTANT — Workspace Guidance (MUST follow)\nThe workspace owner has set the following mandatory instructions. You MUST incorporate these into your response:\n\n${opts.guidance.slice(0, 2000)}\n---`
       : "",
   };
 

package/src/pipeline/webhook.ts

@@ -457,12 +457,17 @@ export async function handleLinearWebhook(
       ? [`**Your role:** Orchestrator with full Linear access. You can update issue fields, change status, and dispatch work via \`code_run\`. Do NOT post comments yourself — the handler posts your text output.`]
       : [`**Your role:** You are the dispatcher. For any coding or implementation work, use \`code_run\` to dispatch it. Workers return text output. You summarize results. You do NOT update issue status or post comments via linear_issues — the audit system handles lifecycle transitions.`];
 
+    if (guidanceAppendix) {
+      api.logger.info(`Guidance injected (${guidanceCtx.source}): ${guidanceCtx.guidance?.slice(0, 120)}...`);
+    }
+
     const message = [
       `You are an orchestrator responding in a Linear issue session. Your text output will be posted as activities visible to the user.`,
       ``,
       ...toolAccessLines,
       ``,
       ...roleLines,
+      guidanceAppendix ? `\n${guidanceAppendix}` : "",
       ``,
       `## Issue: ${issueRef} — ${enrichedIssue?.title ?? issue.title ?? "(untitled)"}`,
       `**Status:** ${enrichedIssue?.state?.name ?? "Unknown"} | **Assignee:** ${enrichedIssue?.assignee?.name ?? "Unassigned"}`,
@@ -473,17 +478,16 @@ export async function handleLinearWebhook(
       userMessage ? `\n**Latest message:**\n> ${userMessage}` : "",
       ``,
       `Respond to the user's request. For work requests, dispatch via \`code_run\` and summarize the result. Be concise and action-oriented.`,
-      guidanceAppendix,
     ].filter(Boolean).join("\n");
 
     // Run agent directly (non-blocking)
     activeRuns.add(issue.id);
     void (async () => {
       const profiles = loadAgentProfiles();
-      const defaultProfile = Object.entries(profiles).find(([, p]) => p.isDefault);
-      const label = defaultProfile?.[1]?.label ?? profiles[agentId]?.label ?? agentId;
+      const label = profiles[agentId]?.label ?? agentId;
 
       // Register active session for tool resolution (code_run, etc.)
+      // Also eagerly records affinity so follow-ups route to the same agent.
       setActiveSession({
         agentSessionId: session.id,
         issueIdentifier: enrichedIssue?.identifier ?? issue.identifier ?? issue.id,
@@ -527,7 +531,7 @@ export async function handleLinearWebhook(
         }).then(() => true).catch(() => false);
 
         if (!emitted) {
-          const avatarUrl = defaultProfile?.[1]?.avatarUrl ?? profiles[agentId]?.avatarUrl;
+          const avatarUrl = profiles[agentId]?.avatarUrl;
           const agentOpts = avatarUrl
             ? { createAsUser: label, displayIconUrl: avatarUrl }
             : undefined;
@@ -644,8 +648,7 @@ export async function handleLinearWebhook(
     activeRuns.add(issue.id);
     void (async () => {
       const profiles = loadAgentProfiles();
-      const defaultProfile = Object.entries(profiles).find(([, p]) => p.isDefault);
-      const label = defaultProfile?.[1]?.label ?? profiles[agentId]?.label ?? agentId;
+      const label = profiles[agentId]?.label ?? agentId;
 
       // Fetch full issue details for context
       let enrichedIssue: any = issue;
@@ -697,12 +700,17 @@ export async function handleLinearWebhook(
         ? [`**Your role:** Orchestrator with full Linear access. You can update issue fields, change status, and dispatch work via \`code_run\`. Do NOT post comments yourself — the handler posts your text output.`]
         : [`**Your role:** Dispatcher. For work requests, use \`code_run\`. You do NOT update issue status — the audit system handles lifecycle.`];
 
+      if (followUpGuidanceAppendix) {
+        api.logger.info(`Follow-up guidance injected: ${(guidanceCtxPrompted.guidance ?? "cached").slice(0, 120)}...`);
+      }
+
       const message = [
         `You are an orchestrator responding in a Linear issue session. Your text output will be posted as activities visible to the user.`,
         ``,
         ...followUpToolAccessLines,
         ``,
         ...followUpRoleLines,
+        followUpGuidanceAppendix ? `\n${followUpGuidanceAppendix}` : "",
         ``,
         `## Issue: ${followUpIssueRef} — ${enrichedIssue?.title ?? issue.title ?? "(untitled)"}`,
         `**Status:** ${enrichedIssue?.state?.name ?? "Unknown"} | **Assignee:** ${enrichedIssue?.assignee?.name ?? "Unassigned"}`,
@@ -713,7 +721,6 @@ export async function handleLinearWebhook(
         `\n**User's follow-up message:**\n> ${userMessage}`,
         ``,
         `Respond to the user's follow-up. For work requests, dispatch via \`code_run\`. Be concise and action-oriented.`,
-        followUpGuidanceAppendix,
       ].filter(Boolean).join("\n");
 
       setActiveSession({
@@ -756,7 +763,7 @@ export async function handleLinearWebhook(
         }).then(() => true).catch(() => false);
 
         if (!emitted) {
-          const avatarUrl = defaultProfile?.[1]?.avatarUrl ?? profiles[agentId]?.avatarUrl;
+          const avatarUrl = profiles[agentId]?.avatarUrl;
           const agentOpts = avatarUrl
             ? { createAsUser: label, displayIconUrl: avatarUrl }
             : undefined;
@@ -1142,9 +1149,8 @@ export async function handleLinearWebhook(
     // Dispatch triage (non-blocking)
     void (async () => {
       const profiles = loadAgentProfiles();
-      const defaultProfile = Object.entries(profiles).find(([, p]) => p.isDefault);
-      const label = defaultProfile?.[1]?.label ?? profiles[agentId]?.label ?? agentId;
-      const avatarUrl = defaultProfile?.[1]?.avatarUrl ?? profiles[agentId]?.avatarUrl;
+      const label = profiles[agentId]?.label ?? agentId;
+      const avatarUrl = profiles[agentId]?.avatarUrl;
       let agentSessionId: string | null = null;
 
       try {