@calltelemetry/openclaw-linear 0.9.7 → 0.9.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calltelemetry/openclaw-linear",
-  "version": "0.9.7",
+  "version": "0.9.9",
   "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:01:43.760Z
+ * Last recorded: 2026-02-22T02:27:42.743Z
  */
 
 export const RECORDED = {
@@ -44,20 +44,20 @@ export const RECORDED = {
     }
   ],
   "createParent": {
-    "id": "7b5cc5d3-ec16-47e0-b0c4-caf8eea47609",
-    "identifier": "UAT-265"
+    "id": "fa2dd666-d1bc-4d53-bc18-db2d02caef96",
+    "identifier": "UAT-305"
   },
   "createSubIssue1": {
-    "id": "de6d1ea0-3358-406a-bcfd-1d19b1516442",
-    "identifier": "UAT-266"
+    "id": "f342ec90-c5f1-483d-987b-9de406d65fac",
+    "identifier": "UAT-306"
   },
   "createSubIssue2": {
-    "id": "7ca89fc7-b246-44b6-8400-0e2a4d169f47",
-    "identifier": "UAT-267"
+    "id": "210a5f52-a2bd-41a9-871f-b92563446d06",
+    "identifier": "UAT-307"
   },
   "subIssue1Details": {
-    "id": "de6d1ea0-3358-406a-bcfd-1d19b1516442",
-    "identifier": "UAT-266",
+    "id": "f342ec90-c5f1-483d-987b-9de406d65fac",
+    "identifier": "UAT-306",
     "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": "7b5cc5d3-ec16-47e0-b0c4-caf8eea47609",
-      "identifier": "UAT-265"
+      "id": "fa2dd666-d1bc-4d53-bc18-db2d02caef96",
+      "identifier": "UAT-305"
     },
     "relations": {
       "nodes": []
     }
   },
   "subIssue2Details": {
-    "id": "7ca89fc7-b246-44b6-8400-0e2a4d169f47",
-    "identifier": "UAT-267",
+    "id": "210a5f52-a2bd-41a9-871f-b92563446d06",
+    "identifier": "UAT-307",
     "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,
@@ -114,22 +114,28 @@ export const RECORDED = {
       "issueEstimationType": "tShirt"
     },
     "comments": {
-      "nodes": []
+      "nodes": [
+        {
+          "body": "This thread is for an agent session with ctclaw.",
+          "user": null,
+          "createdAt": "2026-02-22T02:27:41.198Z"
+        }
+      ]
     },
     "project": null,
     "parent": {
-      "id": "7b5cc5d3-ec16-47e0-b0c4-caf8eea47609",
-      "identifier": "UAT-265"
+      "id": "fa2dd666-d1bc-4d53-bc18-db2d02caef96",
+      "identifier": "UAT-305"
     },
     "relations": {
       "nodes": []
     }
   },
   "parentDetails": {
-    "id": "7b5cc5d3-ec16-47e0-b0c4-caf8eea47609",
-    "identifier": "UAT-265",
+    "id": "fa2dd666-d1bc-4d53-bc18-db2d02caef96",
+    "identifier": "UAT-305",
     "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:01:42.469Z",
+    "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:27:39.194Z",
     "estimate": null,
     "state": {
       "name": "Backlog",
@@ -149,7 +155,13 @@ export const RECORDED = {
       "issueEstimationType": "tShirt"
     },
     "comments": {
-      "nodes": []
+      "nodes": [
+        {
+          "body": "This thread is for an agent session with ctclaw.",
+          "user": null,
+          "createdAt": "2026-02-22T02:27:39.821Z"
+        }
+      ]
     },
     "project": null,
     "parent": null,
@@ -158,11 +170,11 @@ export const RECORDED = {
     }
   },
   "createRelation": {
-    "id": "4c97b0aa-563e-4aad-84aa-826078f012fd"
+    "id": "b7040537-aa53-4e7d-a76d-fd220df3e527"
   },
   "subIssue1WithRelation": {
-    "id": "de6d1ea0-3358-406a-bcfd-1d19b1516442",
-    "identifier": "UAT-266",
+    "id": "f342ec90-c5f1-483d-987b-9de406d65fac",
+    "identifier": "UAT-306",
     "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,
@@ -184,20 +196,26 @@ export const RECORDED = {
       "issueEstimationType": "tShirt"
     },
     "comments": {
-      "nodes": []
+      "nodes": [
+        {
+          "body": "This thread is for an agent session with ctclaw.",
+          "user": null,
+          "createdAt": "2026-02-22T02:27:40.662Z"
+        }
+      ]
     },
     "project": null,
     "parent": {
-      "id": "7b5cc5d3-ec16-47e0-b0c4-caf8eea47609",
-      "identifier": "UAT-265"
+      "id": "fa2dd666-d1bc-4d53-bc18-db2d02caef96",
+      "identifier": "UAT-305"
     },
     "relations": {
       "nodes": [
         {
           "type": "blocks",
           "relatedIssue": {
-            "id": "7ca89fc7-b246-44b6-8400-0e2a4d169f47",
-            "identifier": "UAT-267",
+            "id": "210a5f52-a2bd-41a9-871f-b92563446d06",
+            "identifier": "UAT-307",
             "title": "[SMOKE TEST] Sub-Issue 2: Frontend UI"
           }
         }
@@ -205,8 +223,8 @@ export const RECORDED = {
     }
   },
   "subIssue2WithRelation": {
-    "id": "7ca89fc7-b246-44b6-8400-0e2a4d169f47",
-    "identifier": "UAT-267",
+    "id": "210a5f52-a2bd-41a9-871f-b92563446d06",
+    "identifier": "UAT-307",
     "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 +250,14 @@ export const RECORDED = {
         {
           "body": "This thread is for an agent session with ctclaw.",
           "user": null,
-          "createdAt": "2026-02-22T02:01:43.418Z"
+          "createdAt": "2026-02-22T02:27:41.198Z"
         }
       ]
     },
     "project": null,
     "parent": {
-      "id": "7b5cc5d3-ec16-47e0-b0c4-caf8eea47609",
-      "identifier": "UAT-265"
+      "id": "fa2dd666-d1bc-4d53-bc18-db2d02caef96",
+      "identifier": "UAT-305"
     },
     "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/agent/agent.test.ts

@@ -204,6 +204,52 @@ describe("runAgent subprocess", () => {
   });
 });
 
+  it("extracts text from flat envelope (payloads at top level)", async () => {
+    const api = createApi();
+    (api.runtime.system as any).runCommandWithTimeout = vi.fn().mockResolvedValue({
+      code: 0,
+      stdout: JSON.stringify({ payloads: [{ text: "flat response" }], meta: {} }),
+      stderr: "",
+    });
+
+    const result = await runAgent({
+      api,
+      agentId: "test",
+      sessionId: "s1",
+      message: "test",
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.output).toBe("flat response");
+  });
+
+  it("strips plugin init log noise before JSON blob", async () => {
+    const api = createApi();
+    const noisyOutput = [
+      "[plugins] Dispatch gateway methods registered",
+      "[plugins] Linear agent extension registered (agent: zoe)",
+      '[plugins] code_run: default backend=codex, aliases={"claude":"claude"}',
+      JSON.stringify({ payloads: [{ text: "clean response" }], meta: {} }),
+    ].join("\n");
+    (api.runtime.system as any).runCommandWithTimeout = vi.fn().mockResolvedValue({
+      code: 0,
+      stdout: noisyOutput,
+      stderr: "",
+    });
+
+    const result = await runAgent({
+      api,
+      agentId: "test",
+      sessionId: "s1",
+      message: "test",
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.output).toBe("clean response");
+    expect(result.output).not.toContain("[plugins]");
+    expect(result.output).not.toContain("payloads");
+  });
+
 describe("runAgent date/time injection", () => {
   it("injects current date/time into the message sent to subprocess", async () => {
     const api = createApi();

package/src/agent/agent.ts

@@ -38,9 +38,12 @@ function resolveAgentDirs(agentId: string, config: Record<string, any>): AgentDi
 let _extensionAPI: any | null = null;
 async function getExtensionAPI() {
   if (!_extensionAPI) {
-    // Resolve the openclaw package location dynamically, then import extensionAPI
+    // Resolve the openclaw package location dynamically, then import extensionAPI.
+    // openclaw's package.json exports don't expose ./package.json, so resolve
+    // via the main entry point and walk up to the package root.
     const _require = createRequire(import.meta.url);
-    const openclawDir = dirname(_require.resolve("openclaw/package.json"));
+    const mainEntry = _require.resolve("openclaw");
+    const openclawDir = dirname(dirname(mainEntry));
     _extensionAPI = await import(join(openclawDir, "dist", "extensionAPI.js"));
   }
   return _extensionAPI;
@@ -415,17 +418,47 @@ async function runSubprocess(
   const raw = result.stdout || "";
   api.logger.info(`Agent ${agentId} completed for session ${sessionId}`);
 
-  // Extract clean text from --json output
-  try {
-    const parsed = JSON.parse(raw);
-    const payloads = parsed?.result?.payloads;
-    if (Array.isArray(payloads) && payloads.length > 0) {
-      const text = payloads.map((p: any) => p.text).filter(Boolean).join("\n\n");
-      if (text) return { success: true, output: text };
+  // Extract clean text from --json output.
+  // The subprocess stdout may contain plugin init log lines before the JSON blob.
+  // Strip everything before the first `{` to isolate the JSON envelope.
+  const extracted = extractJsonFromOutput(raw);
+  if (extracted) return { success: true, output: extracted };
+
+  return { success: true, output: raw };
+}
+
+/**
+ * Extract text from subprocess --json output. Handles:
+ * - Log noise before the JSON blob (plugin init lines)
+ * - Both envelope shapes: `{ payloads }` (flat) and `{ result: { payloads } }` (nested)
+ */
+function extractJsonFromOutput(raw: string): string | null {
+  // The subprocess stdout may contain plugin init log lines before the JSON
+  // result blob. Try parsing the whole thing first; if that fails, scan lines
+  // backwards for a `{` that starts a valid JSON envelope with payloads.
+  const candidates: string[] = [raw];
+
+  // Also try from each line that starts with `{` (the JSON blob typically
+  // starts on its own line after log noise).
+  const lines = raw.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trimStart().startsWith("{")) {
+      candidates.push(lines.slice(i).join("\n"));
     }
-  } catch {
-    // Not JSON — use raw output as-is
   }
 
-  return { success: true, output: raw };
+  for (const candidate of candidates) {
+    try {
+      const parsed = JSON.parse(candidate);
+      // Try both envelope shapes: flat `{ payloads }` and nested `{ result: { payloads } }`
+      const payloads = parsed?.payloads ?? parsed?.result?.payloads;
+      if (Array.isArray(payloads) && payloads.length > 0) {
+        const text = payloads.map((p: any) => p.text).filter(Boolean).join("\n\n");
+        if (text) return text;
+      }
+    } catch {
+      // Not valid JSON at this position — try next candidate
+    }
+  }
+  return null;
 }

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.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/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,7 +478,6 @@ 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)
@@ -697,12 +701,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 +722,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({