@calltelemetry/openclaw-linear 0.9.12 → 0.9.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calltelemetry/openclaw-linear",
-  "version": "0.9.12",
+  "version": "0.9.14",
   "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-22T03:20:08.396Z
+ * Last recorded: 2026-02-22T03:40:54.418Z
  */
 
 export const RECORDED = {
@@ -44,20 +44,20 @@ export const RECORDED = {
     }
   ],
   "createParent": {
-    "id": "2becfd65-c313-4d4b-9362-b3ac431872c6",
-    "identifier": "UAT-354"
+    "id": "933fa3c0-981a-4d9e-8b2c-7c5c4d5b4349",
+    "identifier": "UAT-438"
   },
   "createSubIssue1": {
-    "id": "b7433275-83a2-4e6e-a98c-5fe2b3aa1147",
-    "identifier": "UAT-355"
+    "id": "4caa7593-5a51-4795-b98c-29e532589dfe",
+    "identifier": "UAT-439"
   },
   "createSubIssue2": {
-    "id": "3526cea7-2261-4eee-bd8a-5206e12c6124",
-    "identifier": "UAT-356"
+    "id": "0519065b-95eb-4752-966b-2099bbc5f3d1",
+    "identifier": "UAT-440"
   },
   "subIssue1Details": {
-    "id": "b7433275-83a2-4e6e-a98c-5fe2b3aa1147",
-    "identifier": "UAT-355",
+    "id": "4caa7593-5a51-4795-b98c-29e532589dfe",
+    "identifier": "UAT-439",
     "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": "2becfd65-c313-4d4b-9362-b3ac431872c6",
-      "identifier": "UAT-354"
+      "id": "933fa3c0-981a-4d9e-8b2c-7c5c4d5b4349",
+      "identifier": "UAT-438"
     },
     "relations": {
       "nodes": []
     }
   },
   "subIssue2Details": {
-    "id": "3526cea7-2261-4eee-bd8a-5206e12c6124",
-    "identifier": "UAT-356",
+    "id": "0519065b-95eb-4752-966b-2099bbc5f3d1",
+    "identifier": "UAT-440",
     "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": "2becfd65-c313-4d4b-9362-b3ac431872c6",
-      "identifier": "UAT-354"
+      "id": "933fa3c0-981a-4d9e-8b2c-7c5c4d5b4349",
+      "identifier": "UAT-438"
     },
     "relations": {
       "nodes": []
     }
   },
   "parentDetails": {
-    "id": "2becfd65-c313-4d4b-9362-b3ac431872c6",
-    "identifier": "UAT-354",
+    "id": "933fa3c0-981a-4d9e-8b2c-7c5c4d5b4349",
+    "identifier": "UAT-438",
     "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:20:04.703Z",
+    "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",
     "estimate": null,
     "state": {
       "name": "Backlog",
@@ -149,7 +149,13 @@ export const RECORDED = {
       "issueEstimationType": "tShirt"
     },
     "comments": {
-      "nodes": []
+      "nodes": [
+        {
+          "body": "This thread is for an agent session with ctclaw.",
+          "user": null,
+          "createdAt": "2026-02-22T03:40:53.165Z"
+        }
+      ]
     },
     "project": null,
     "parent": null,
@@ -158,11 +164,11 @@ export const RECORDED = {
     }
   },
   "createRelation": {
-    "id": "a9cac881-3d13-45ab-b000-855777698d71"
+    "id": "185dfd6c-362e-48a4-b717-e900407ced84"
   },
   "subIssue1WithRelation": {
-    "id": "b7433275-83a2-4e6e-a98c-5fe2b3aa1147",
-    "identifier": "UAT-355",
+    "id": "4caa7593-5a51-4795-b98c-29e532589dfe",
+    "identifier": "UAT-439",
     "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,22 +194,22 @@ export const RECORDED = {
         {
           "body": "This thread is for an agent session with ctclaw.",
           "user": null,
-          "createdAt": "2026-02-22T03:20:06.930Z"
+          "createdAt": "2026-02-22T03:40:53.603Z"
         }
       ]
     },
     "project": null,
     "parent": {
-      "id": "2becfd65-c313-4d4b-9362-b3ac431872c6",
-      "identifier": "UAT-354"
+      "id": "933fa3c0-981a-4d9e-8b2c-7c5c4d5b4349",
+      "identifier": "UAT-438"
     },
     "relations": {
       "nodes": [
         {
           "type": "blocks",
           "relatedIssue": {
-            "id": "3526cea7-2261-4eee-bd8a-5206e12c6124",
-            "identifier": "UAT-356",
+            "id": "0519065b-95eb-4752-966b-2099bbc5f3d1",
+            "identifier": "UAT-440",
             "title": "[SMOKE TEST] Sub-Issue 2: Frontend UI"
           }
         }
@@ -211,8 +217,8 @@ export const RECORDED = {
     }
   },
   "subIssue2WithRelation": {
-    "id": "3526cea7-2261-4eee-bd8a-5206e12c6124",
-    "identifier": "UAT-356",
+    "id": "0519065b-95eb-4752-966b-2099bbc5f3d1",
+    "identifier": "UAT-440",
     "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,
@@ -238,14 +244,14 @@ export const RECORDED = {
         {
           "body": "This thread is for an agent session with ctclaw.",
           "user": null,
-          "createdAt": "2026-02-22T03:20:06.960Z"
+          "createdAt": "2026-02-22T03:40:53.840Z"
         }
       ]
     },
     "project": null,
     "parent": {
-      "id": "2becfd65-c313-4d4b-9362-b3ac431872c6",
-      "identifier": "UAT-354"
+      "id": "933fa3c0-981a-4d9e-8b2c-7c5c4d5b4349",
+      "identifier": "UAT-438"
     },
     "relations": {
       "nodes": []

package/src/agent/agent.ts

@@ -323,7 +323,7 @@ async function runEmbedded(
       }
     },
 
-    // Raw agent events — capture tool starts/ends
+    // Raw agent events — capture tool starts/ends/updates
     onAgentEvent: (evt) => {
       watchdog.tick();
       const { stream, data } = evt;
@@ -333,16 +333,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 : "";
 
-      // Tool execution start — emit action with tool name + meta
+      // Tool execution start — emit action with tool name + available context
       if (phase === "start") {
         lastToolAction = toolName;
-        emit({ type: "action", action: `Running ${toolName}`, parameter: meta.slice(0, 200) || toolName });
+        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)
+      if (phase === "update") {
+        const detail = meta || input || "in progress";
+        emit({ type: "action", action: `${toolName}`, parameter: detail.slice(0, 300) });
+      }
+
+      // Tool execution completed successfully
+      if (phase === "result" && !data.isError) {
+        const detail = meta ? meta.slice(0, 300) : "completed";
+        emit({ type: "action", action: `${toolName} done`, parameter: detail });
       }
 
       // Tool execution result with error
       if (phase === "result" && data.isError) {
-        emit({ type: "action", action: `${toolName} failed`, parameter: meta.slice(0, 200) || "error" });
+        emit({ type: "action", action: `${toolName} failed`, parameter: (meta || "error").slice(0, 300) });
       }
     },
 

package/src/infra/doctor.test.ts

@@ -1630,621 +1630,120 @@ describe("checkFilesAndDirs — dispatch state non-Error exception", () => {
 });
 
 // ---------------------------------------------------------------------------
-// checkFilesAndDirs — lock file branches
+// checkFilesAndDirs — CLAUDE.md and AGENTS.md checks
 // ---------------------------------------------------------------------------
 
-describe("checkFilesAndDirs — lock file branches", () => {
+describe("checkFilesAndDirs — CLAUDE.md and AGENTS.md", () => {
   let tmpDir: string;
 
   beforeEach(() => {
-    tmpDir = mkdtempSync(join(tmpdir(), "doctor-lock-"));
+    tmpDir = mkdtempSync(join(tmpdir(), "doctor-md-"));
+    const { execFileSync } = require("node:child_process");
+    execFileSync("git", ["init"], { cwd: tmpDir, stdio: "ignore" });
   });
 
-  it("warns about stale lock file without --fix", async () => {
-    const statePath = join(tmpDir, "state.json");
-    const lockPath = statePath + ".lock";
-    writeFileSync(statePath, '{}');
-    writeFileSync(lockPath, "locked");
-    // Make the lock file appear stale by backdating its mtime
-    const staleTime = Date.now() - 60_000; // 60 seconds old (> 30s LOCK_STALE_MS)
-    const { utimesSync } = await import("node:fs");
-    utimesSync(lockPath, staleTime / 1000, staleTime / 1000);
-
-    vi.mocked(readDispatchState).mockResolvedValueOnce({
-      dispatches: { active: {}, completed: {} },
-      sessionMap: {},
-      processedEvents: [],
-    });
-
-    const checks = await checkFilesAndDirs({ dispatchStatePath: statePath }, false);
-    const lockCheck = checks.find((c) => c.label.includes("Stale lock file"));
-    expect(lockCheck?.severity).toBe("warn");
-    expect(lockCheck?.fixable).toBe(true);
+  it("passes when CLAUDE.md exists in base repo", async () => {
+    writeFileSync(join(tmpDir, "CLAUDE.md"), "# My Project\n## Tech Stack\n- TypeScript");
+    const checks = await checkFilesAndDirs({ codexBaseRepo: tmpDir });
+    const claudeCheck = checks.find((c) => c.label.includes("CLAUDE.md found"));
+    expect(claudeCheck).toBeDefined();
+    expect(claudeCheck?.severity).toBe("pass");
   });
 
-  it("removes stale lock file with --fix", async () => {
-    const statePath = join(tmpDir, "state.json");
-    const lockPath = statePath + ".lock";
-    writeFileSync(statePath, '{}');
-    writeFileSync(lockPath, "locked");
-    const staleTime = Date.now() - 60_000;
-    const { utimesSync } = await import("node:fs");
-    utimesSync(lockPath, staleTime / 1000, staleTime / 1000);
-
-    vi.mocked(readDispatchState).mockResolvedValueOnce({
-      dispatches: { active: {}, completed: {} },
-      sessionMap: {},
-      processedEvents: [],
-    });
-
-    const checks = await checkFilesAndDirs({ dispatchStatePath: statePath }, true);
-    const lockCheck = checks.find((c) => c.label.includes("Stale lock file removed"));
-    expect(lockCheck?.severity).toBe("pass");
-    expect(existsSync(lockPath)).toBe(false);
+  it("warns when CLAUDE.md is missing from base repo", async () => {
+    const checks = await checkFilesAndDirs({ codexBaseRepo: tmpDir });
+    const claudeCheck = checks.find((c) => c.label.includes("No CLAUDE.md"));
+    expect(claudeCheck).toBeDefined();
+    expect(claudeCheck?.severity).toBe("warn");
+    expect(claudeCheck?.fix).toContain("CLAUDE.md");
   });
 
-  it("warns about active (non-stale) lock file", async () => {
-    const statePath = join(tmpDir, "state.json");
-    const lockPath = statePath + ".lock";
-    writeFileSync(statePath, '{}');
-    writeFileSync(lockPath, "locked");
-    // Lock file is fresh (just created), so lockAge < LOCK_STALE_MS
-
-    vi.mocked(readDispatchState).mockResolvedValueOnce({
-      dispatches: { active: {}, completed: {} },
-      sessionMap: {},
-      processedEvents: [],
-    });
-
-    const checks = await checkFilesAndDirs({ dispatchStatePath: statePath }, false);
-    const lockCheck = checks.find((c) => c.label.includes("Lock file active"));
-    expect(lockCheck?.severity).toBe("warn");
-    expect(lockCheck?.label).toContain("may be in use");
+  it("passes when AGENTS.md exists in base repo", async () => {
+    writeFileSync(join(tmpDir, "AGENTS.md"), "# Agent Guidelines\n## Code Style");
+    const checks = await checkFilesAndDirs({ codexBaseRepo: tmpDir });
+    const agentsCheck = checks.find((c) => c.label.includes("AGENTS.md found"));
+    expect(agentsCheck).toBeDefined();
+    expect(agentsCheck?.severity).toBe("pass");
   });
-});
-
-// ---------------------------------------------------------------------------
-// checkFilesAndDirs — prompt variable edge cases
-// ---------------------------------------------------------------------------
 
-describe("checkFilesAndDirs — prompt variable edge cases", () => {
-  it("reports when variable missing from worker.task but present in audit.task", async () => {
-    vi.mocked(loadPrompts).mockReturnValueOnce({
-      worker: {
-        system: "ok",
-        task: "Do something", // missing all vars
-      },
-      audit: {
-        system: "ok",
-        task: "Audit {{identifier}} {{title}} {{description}} in {{worktreePath}}", // has all vars
-      },
-      rework: { addendum: "Fix these gaps: {{gaps}}" },
-    } as any);
-
-    const checks = await checkFilesAndDirs();
-    const promptCheck = checks.find((c) => c.label.includes("Prompt issues"));
-    expect(promptCheck?.severity).toBe("fail");
-    expect(promptCheck?.label).toContain("worker.task missing");
-    // Crucially, audit.task should NOT be missing
-    expect(promptCheck?.label).not.toContain("audit.task missing");
+  it("warns when AGENTS.md is missing from base repo", async () => {
+    const checks = await checkFilesAndDirs({ codexBaseRepo: tmpDir });
+    const agentsCheck = checks.find((c) => c.label.includes("No AGENTS.md"));
+    expect(agentsCheck).toBeDefined();
+    expect(agentsCheck?.severity).toBe("warn");
+    expect(agentsCheck?.fix).toContain("AGENTS.md");
   });
 
-  it("reports loadPrompts throwing non-Error value", async () => {
-    vi.mocked(loadPrompts).mockImplementationOnce(() => { throw "raw string error"; });
+  it("passes both when both files exist", async () => {
+    writeFileSync(join(tmpDir, "CLAUDE.md"), "# Project");
+    writeFileSync(join(tmpDir, "AGENTS.md"), "# Guidelines");
+    const checks = await checkFilesAndDirs({ codexBaseRepo: tmpDir });
+    const claudeCheck = checks.find((c) => c.label.includes("CLAUDE.md found"));
+    const agentsCheck = checks.find((c) => c.label.includes("AGENTS.md found"));
+    expect(claudeCheck?.severity).toBe("pass");
+    expect(agentsCheck?.severity).toBe("pass");
+  });
 
-    const checks = await checkFilesAndDirs();
-    const promptCheck = checks.find((c) => c.label.includes("Failed to load prompts"));
-    expect(promptCheck?.severity).toBe("fail");
-    expect(promptCheck?.detail).toContain("raw string error");
+  it("shows file size in KB when CLAUDE.md exists", async () => {
+    writeFileSync(join(tmpDir, "CLAUDE.md"), "x".repeat(2048));
+    const checks = await checkFilesAndDirs({ codexBaseRepo: tmpDir });
+    const claudeCheck = checks.find((c) => c.label.includes("CLAUDE.md found"));
+    expect(claudeCheck?.label).toContain("2KB");
   });
 });
 
 // ---------------------------------------------------------------------------
-// checkFilesAndDirs — worktree & base repo edge cases
+// checkFilesAndDirs — multi-repo path validation
 // ---------------------------------------------------------------------------
 
-describe("checkFilesAndDirs — worktree & base repo edge cases", () => {
-  it("reports worktree base dir does not exist", async () => {
-    const checks = await checkFilesAndDirs({
-      worktreeBaseDir: "/tmp/nonexistent-worktree-dir-" + Date.now(),
-    });
-    const wtCheck = checks.find((c) => c.label.includes("Worktree base dir does not exist"));
-    expect(wtCheck?.severity).toBe("warn");
-    expect(wtCheck?.detail).toContain("Will be created on first dispatch");
+describe("checkFilesAndDirs — multi-repo validation", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "doctor-repos-"));
+    const { execFileSync } = require("node:child_process");
+    execFileSync("git", ["init"], { cwd: tmpDir, stdio: "ignore" });
   });
 
-  it("reports base repo does not exist", async () => {
+  it("passes for valid git repo paths", async () => {
+    const repoDir = join(tmpDir, "myrepo");
+    mkdirSync(repoDir);
+    const { execFileSync } = require("node:child_process");
+    execFileSync("git", ["init"], { cwd: repoDir, stdio: "ignore" });
+
     const checks = await checkFilesAndDirs({
-      codexBaseRepo: "/tmp/nonexistent-repo-" + Date.now(),
+      codexBaseRepo: tmpDir,
+      repos: { frontend: repoDir },
     });
-    const repoCheck = checks.find((c) => c.label.includes("Base repo does not exist"));
-    expect(repoCheck?.severity).toBe("fail");
-    expect(repoCheck?.fix).toContain("codexBaseRepo");
+    const repoCheck = checks.find((c) => c.label.includes('Repo "frontend"'));
+    expect(repoCheck).toBeDefined();
+    expect(repoCheck?.severity).toBe("pass");
+    expect(repoCheck?.label).toContain("valid git repo");
   });
 
-  it("reports base repo exists but is not a git repo", async () => {
-    const tmpDir = mkdtempSync(join(tmpdir(), "doctor-nongit-"));
+  it("fails for non-existent repo paths", async () => {
     const checks = await checkFilesAndDirs({
       codexBaseRepo: tmpDir,
+      repos: { backend: "/tmp/nonexistent-repo-path-12345" },
     });
-    const repoCheck = checks.find((c) => c.label.includes("Base repo is not a git repo"));
+    const repoCheck = checks.find((c) => c.label.includes('Repo "backend"'));
+    expect(repoCheck).toBeDefined();
     expect(repoCheck?.severity).toBe("fail");
-    expect(repoCheck?.fix).toContain("git init");
+    expect(repoCheck?.label).toContain("does not exist");
   });
-});
-
-// ---------------------------------------------------------------------------
-// checkFilesAndDirs — tilde path resolution branches
-// ---------------------------------------------------------------------------
-
-describe("checkFilesAndDirs — tilde path resolution", () => {
-  it("resolves ~/... dispatch state path", async () => {
-    vi.mocked(readDispatchState).mockRejectedValueOnce(new Error("ENOENT"));
 
-    // Providing a path with ~/ triggers the tilde resolution branch
-    const checks = await checkFilesAndDirs({
-      dispatchStatePath: "~/nonexistent-state-file.json",
-    });
-    // The file won't exist (tilde-resolved), so we get the "no file yet" message
-    const stateCheck = checks.find((c) => c.label.includes("Dispatch state"));
-    expect(stateCheck).toBeDefined();
-  });
+  it("fails for paths that exist but are not git repos", async () => {
+    // Create a dir outside the git repo so git rev-parse fails
+    const nonGitDir = mkdtempSync(join(tmpdir(), "doctor-nongit-"));
 
-  it("resolves ~/... worktree base dir path", async () => {
     const checks = await checkFilesAndDirs({
-      worktreeBaseDir: "~/nonexistent-worktree-base",
-    });
-    const wtCheck = checks.find((c) => c.label.includes("Worktree base dir"));
-    expect(wtCheck).toBeDefined();
-  });
-});
-
-// ---------------------------------------------------------------------------
-// checkDispatchHealth — orphaned worktree singular
-// ---------------------------------------------------------------------------
-
-describe("checkDispatchHealth — edge cases", () => {
-  it("reports single orphaned worktree (singular)", async () => {
-    vi.mocked(listWorktrees).mockReturnValueOnce([
-      { issueIdentifier: "ORPHAN-1", path: "/tmp/wt1" } as any,
-    ]);
-
-    const checks = await checkDispatchHealth();
-    const orphanCheck = checks.find((c) => c.label.includes("orphaned worktree"));
-    expect(orphanCheck?.severity).toBe("warn");
-    expect(orphanCheck?.label).toContain("1 orphaned worktree");
-    expect(orphanCheck?.label).not.toContain("worktrees"); // singular, not plural
-  });
-
-  it("prunes multiple old completed dispatches (plural)", async () => {
-    vi.mocked(readDispatchState).mockResolvedValueOnce({
-      dispatches: {
-        active: {},
-        completed: {
-          "A-1": { completedAt: new Date(Date.now() - 10 * 24 * 3_600_000).toISOString() } as any,
-          "A-2": { completedAt: new Date(Date.now() - 10 * 24 * 3_600_000).toISOString() } as any,
-        },
-      },
-      sessionMap: {},
-      processedEvents: [],
+      codexBaseRepo: tmpDir,
+      repos: { api: nonGitDir },
     });
-    vi.mocked(pruneCompleted).mockResolvedValueOnce(2);
-
-    const checks = await checkDispatchHealth(undefined, true);
-    const pruneCheck = checks.find((c) => c.label.includes("Pruned"));
-    expect(pruneCheck?.severity).toBe("pass");
-    expect(pruneCheck?.label).toContain("2 old completed dispatches");
-  });
-
-  it("reports single stale dispatch (singular)", async () => {
-    vi.mocked(listStaleDispatches).mockReturnValueOnce([
-      { issueIdentifier: "API-1", status: "working" } as any,
-    ]);
-
-    const checks = await checkDispatchHealth();
-    const staleCheck = checks.find((c) => c.label.includes("stale dispatch"));
-    expect(staleCheck?.severity).toBe("warn");
-    // Singular: "1 stale dispatch" not "1 stale dispatches"
-    expect(staleCheck?.label).toMatch(/1 stale dispatch(?!es)/);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// checkConnectivity — webhook self-test with ok but body !== "ok"
-// ---------------------------------------------------------------------------
-
-describe("checkConnectivity — webhook non-ok body", () => {
-  it("warns when webhook returns ok status but body is not 'ok'", async () => {
-    vi.stubGlobal("fetch", vi.fn(async (url: string) => {
-      if (url.includes("localhost")) {
-        return { ok: true, text: async () => "pong" };
-      }
-      throw new Error("unexpected");
-    }));
-
-    const checks = await checkConnectivity({}, { viewer: { name: "T" } });
-    const webhookCheck = checks.find((c) => c.label.includes("Webhook self-test:"));
-    // ok is true but body is "pong" not "ok" — the condition is `res.ok && body === "ok"`
-    // Since body !== "ok", it falls into the warn branch
-    expect(webhookCheck?.severity).toBe("warn");
-  });
-});
-
-// ---------------------------------------------------------------------------
-// formatReport — icon function TTY branches
-// ---------------------------------------------------------------------------
-
-describe("formatReport — TTY icon rendering", () => {
-  it("renders colored icons when stdout.isTTY is true", () => {
-    const origIsTTY = process.stdout.isTTY;
-    try {
-      Object.defineProperty(process.stdout, "isTTY", { value: true, writable: true, configurable: true });
-
-      const report = {
-        sections: [{
-          name: "Test",
-          checks: [
-            { label: "pass check", severity: "pass" as const },
-            { label: "warn check", severity: "warn" as const },
-            { label: "fail check", severity: "fail" as const },
-          ],
-        }],
-        summary: { passed: 1, warnings: 1, errors: 1 },
-      };
-
-      const output = formatReport(report);
-      // TTY output includes ANSI escape codes
-      expect(output).toContain("\x1b[32m"); // green for pass
-      expect(output).toContain("\x1b[33m"); // yellow for warn
-      expect(output).toContain("\x1b[31m"); // red for fail
-    } finally {
-      Object.defineProperty(process.stdout, "isTTY", { value: origIsTTY, writable: true, configurable: true });
-    }
+    const repoCheck = checks.find((c) => c.label.includes('Repo "api"'));
+    expect(repoCheck).toBeDefined();
+    expect(repoCheck?.severity).toBe("fail");
+    expect(repoCheck?.label).toContain("not a git repo");
   });
 });
 
-// ---------------------------------------------------------------------------
-// checkCodingTools — codingTool fallback to "codex" in label
-// ---------------------------------------------------------------------------
-
-describe("checkCodingTools — codingTool null fallback", () => {
-  it("shows 'codex' as default when codingTool is undefined but backends exist", () => {
-    vi.mocked(loadCodingConfig).mockReturnValueOnce({
-      codingTool: undefined,
-      backends: { codex: { aliases: ["codex"] } },
-    } as any);
-
-    const checks = checkCodingTools();
-    const configCheck = checks.find((c) => c.label.includes("coding-tools.json loaded"));
-    expect(configCheck?.severity).toBe("pass");
-    expect(configCheck?.label).toContain("codex"); // falls back to "codex" via ??
-  });
-});
-
-// ---------------------------------------------------------------------------
-// checkFilesAndDirs — dispatch state non-Error catch branch
-// ---------------------------------------------------------------------------
-
-describe("checkFilesAndDirs — dispatch state non-Error exception", () => {
-  it("handles non-Error thrown during dispatch state read", async () => {
-    const tmpDir = mkdtempSync(join(tmpdir(), "doctor-nonError-"));
-    const statePath = join(tmpDir, "state.json");
-    writeFileSync(statePath, '{}');
-    vi.mocked(readDispatchState).mockRejectedValueOnce("raw string dispatch error");
-
-    const checks = await checkFilesAndDirs({ dispatchStatePath: statePath });
-    const stateCheck = checks.find((c) => c.label.includes("Dispatch state corrupt"));
-    expect(stateCheck?.severity).toBe("fail");
-    expect(stateCheck?.detail).toContain("raw string dispatch error");
-  });
-});
-
-// ---------------------------------------------------------------------------
-// checkFilesAndDirs — lock file branches
-// ---------------------------------------------------------------------------
-
-describe("checkFilesAndDirs — lock file branches", () => {
-  let tmpDir: string;
-
-  beforeEach(() => {
-    tmpDir = mkdtempSync(join(tmpdir(), "doctor-lock-"));
-  });
-
-  it("warns about stale lock file without --fix", async () => {
-    const statePath = join(tmpDir, "state.json");
-    const lockPath = statePath + ".lock";
-    writeFileSync(statePath, '{}');
-    writeFileSync(lockPath, "locked");
-    // Make the lock file appear stale by backdating its mtime
-    const staleTime = Date.now() - 60_000; // 60 seconds old (> 30s LOCK_STALE_MS)
-    const { utimesSync } = await import("node:fs");
-    utimesSync(lockPath, staleTime / 1000, staleTime / 1000);
-
-    vi.mocked(readDispatchState).mockResolvedValueOnce({
-      dispatches: { active: {}, completed: {} },
-      sessionMap: {},
-      processedEvents: [],
-    });
-
-    const checks = await checkFilesAndDirs({ dispatchStatePath: statePath }, false);
-    const lockCheck = checks.find((c) => c.label.includes("Stale lock file"));
-    expect(lockCheck?.severity).toBe("warn");
-    expect(lockCheck?.fixable).toBe(true);
-  });
-
-  it("removes stale lock file with --fix", async () => {
-    const statePath = join(tmpDir, "state.json");
-    const lockPath = statePath + ".lock";
-    writeFileSync(statePath, '{}');
-    writeFileSync(lockPath, "locked");
-    const staleTime = Date.now() - 60_000;
-    const { utimesSync } = await import("node:fs");
-    utimesSync(lockPath, staleTime / 1000, staleTime / 1000);
-
-    vi.mocked(readDispatchState).mockResolvedValueOnce({
-      dispatches: { active: {}, completed: {} },
-      sessionMap: {},
-      processedEvents: [],
-    });
-
-    const checks = await checkFilesAndDirs({ dispatchStatePath: statePath }, true);
-    const lockCheck = checks.find((c) => c.label.includes("Stale lock file removed"));
-    expect(lockCheck?.severity).toBe("pass");
-    expect(existsSync(lockPath)).toBe(false);
-  });
-
-  it("warns about active (non-stale) lock file", async () => {
-    const statePath = join(tmpDir, "state.json");
-    const lockPath = statePath + ".lock";
-    writeFileSync(statePath, '{}');
-    writeFileSync(lockPath, "locked");
-    // Lock file is fresh (just created), so lockAge < LOCK_STALE_MS
-
-    vi.mocked(readDispatchState).mockResolvedValueOnce({
-      dispatches: { active: {}, completed: {} },
-      sessionMap: {},
-      processedEvents: [],
-    });
-
-    const checks = await checkFilesAndDirs({ dispatchStatePath: statePath }, false);
-    const lockCheck = checks.find((c) => c.label.includes("Lock file active"));
-    expect(lockCheck?.severity).toBe("warn");
-    expect(lockCheck?.label).toContain("may be in use");
-  });
-});
-
-// ---------------------------------------------------------------------------
-// checkFilesAndDirs — prompt variable edge cases
-// ---------------------------------------------------------------------------
-
-describe("checkFilesAndDirs — prompt variable edge cases", () => {
-  it("reports when variable missing from worker.task but present in audit.task", async () => {
-    vi.mocked(loadPrompts).mockReturnValueOnce({
-      worker: {
-        system: "ok",
-        task: "Do something", // missing all vars
-      },
-      audit: {
-        system: "ok",
-        task: "Audit {{identifier}} {{title}} {{description}} in {{worktreePath}}", // has all vars
-      },
-      rework: { addendum: "Fix these gaps: {{gaps}}" },
-    } as any);
-
-    const checks = await checkFilesAndDirs();
-    const promptCheck = checks.find((c) => c.label.includes("Prompt issues"));
-    expect(promptCheck?.severity).toBe("fail");
-    expect(promptCheck?.label).toContain("worker.task missing");
-    // Crucially, audit.task should NOT be missing
-    expect(promptCheck?.label).not.toContain("audit.task missing");
-  });
-
-  it("reports loadPrompts throwing non-Error value", async () => {
-    vi.mocked(loadPrompts).mockImplementationOnce(() => { throw "raw string error"; });
-
-    const checks = await checkFilesAndDirs();
-    const promptCheck = checks.find((c) => c.label.includes("Failed to load prompts"));
-    expect(promptCheck?.severity).toBe("fail");
-    expect(promptCheck?.detail).toContain("raw string error");
-  });
-});
-
-// ---------------------------------------------------------------------------
-// checkFilesAndDirs — worktree & base repo edge cases
-// ---------------------------------------------------------------------------
-
-describe("checkFilesAndDirs — worktree & base repo edge cases", () => {
-  it("reports worktree base dir does not exist", async () => {
-    const checks = await checkFilesAndDirs({
-      worktreeBaseDir: "/tmp/nonexistent-worktree-dir-" + Date.now(),
-    });
-    const wtCheck = checks.find((c) => c.label.includes("Worktree base dir does not exist"));
-    expect(wtCheck?.severity).toBe("warn");
-    expect(wtCheck?.detail).toContain("Will be created on first dispatch");
-  });
-
-  it("reports base repo does not exist", async () => {
-    const checks = await checkFilesAndDirs({
-      codexBaseRepo: "/tmp/nonexistent-repo-" + Date.now(),
-    });
-    const repoCheck = checks.find((c) => c.label.includes("Base repo does not exist"));
-    expect(repoCheck?.severity).toBe("fail");
-    expect(repoCheck?.fix).toContain("codexBaseRepo");
-  });
-
-  it("reports base repo exists but is not a git repo", async () => {
-    const tmpDir = mkdtempSync(join(tmpdir(), "doctor-nongit-"));
-    const checks = await checkFilesAndDirs({
-      codexBaseRepo: tmpDir,
-    });
-    const repoCheck = checks.find((c) => c.label.includes("Base repo is not a git repo"));
-    expect(repoCheck?.severity).toBe("fail");
-    expect(repoCheck?.fix).toContain("git init");
-  });
-});
-
-// ---------------------------------------------------------------------------
-// checkFilesAndDirs — tilde path resolution branches
-// ---------------------------------------------------------------------------
-
-describe("checkFilesAndDirs — tilde path resolution", () => {
-  it("resolves ~/... dispatch state path", async () => {
-    vi.mocked(readDispatchState).mockRejectedValueOnce(new Error("ENOENT"));
-
-    // Providing a path with ~/ triggers the tilde resolution branch
-    const checks = await checkFilesAndDirs({
-      dispatchStatePath: "~/nonexistent-state-file.json",
-    });
-    // The file won't exist (tilde-resolved), so we get the "no file yet" message
-    const stateCheck = checks.find((c) => c.label.includes("Dispatch state"));
-    expect(stateCheck).toBeDefined();
-  });
-
-  it("resolves ~/... worktree base dir path", async () => {
-    const checks = await checkFilesAndDirs({
-      worktreeBaseDir: "~/nonexistent-worktree-base",
-    });
-    const wtCheck = checks.find((c) => c.label.includes("Worktree base dir"));
-    expect(wtCheck).toBeDefined();
-  });
-});
-
-// ---------------------------------------------------------------------------
-// checkDispatchHealth — orphaned worktree singular
-// ---------------------------------------------------------------------------
-
-describe("checkDispatchHealth — edge cases", () => {
-  it("reports single orphaned worktree (singular)", async () => {
-    vi.mocked(listWorktrees).mockReturnValueOnce([
-      { issueIdentifier: "ORPHAN-1", path: "/tmp/wt1" } as any,
-    ]);
-
-    const checks = await checkDispatchHealth();
-    const orphanCheck = checks.find((c) => c.label.includes("orphaned worktree"));
-    expect(orphanCheck?.severity).toBe("warn");
-    expect(orphanCheck?.label).toContain("1 orphaned worktree");
-    expect(orphanCheck?.label).not.toContain("worktrees"); // singular, not plural
-  });
-
-  it("prunes multiple old completed dispatches (plural)", async () => {
-    vi.mocked(readDispatchState).mockResolvedValueOnce({
-      dispatches: {
-        active: {},
-        completed: {
-          "A-1": { completedAt: new Date(Date.now() - 10 * 24 * 3_600_000).toISOString() } as any,
-          "A-2": { completedAt: new Date(Date.now() - 10 * 24 * 3_600_000).toISOString() } as any,
-        },
-      },
-      sessionMap: {},
-      processedEvents: [],
-    });
-    vi.mocked(pruneCompleted).mockResolvedValueOnce(2);
-
-    const checks = await checkDispatchHealth(undefined, true);
-    const pruneCheck = checks.find((c) => c.label.includes("Pruned"));
-    expect(pruneCheck?.severity).toBe("pass");
-    expect(pruneCheck?.label).toContain("2 old completed dispatches");
-  });
-
-  it("reports single stale dispatch (singular)", async () => {
-    vi.mocked(listStaleDispatches).mockReturnValueOnce([
-      { issueIdentifier: "API-1", status: "working" } as any,
-    ]);
-
-    const checks = await checkDispatchHealth();
-    const staleCheck = checks.find((c) => c.label.includes("stale dispatch"));
-    expect(staleCheck?.severity).toBe("warn");
-    // Singular: "1 stale dispatch" not "1 stale dispatches"
-    expect(staleCheck?.label).toMatch(/1 stale dispatch(?!es)/);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// checkConnectivity — webhook self-test with ok but body !== "ok"
-// ---------------------------------------------------------------------------
-
-describe("checkConnectivity — webhook non-ok body", () => {
-  it("warns when webhook returns ok status but body is not 'ok'", async () => {
-    vi.stubGlobal("fetch", vi.fn(async (url: string) => {
-      if (url.includes("localhost")) {
-        return { ok: true, text: async () => "pong" };
-      }
-      throw new Error("unexpected");
-    }));
-
-    const checks = await checkConnectivity({}, { viewer: { name: "T" } });
-    const webhookCheck = checks.find((c) => c.label.includes("Webhook self-test:"));
-    // ok is true but body is "pong" not "ok" — the condition is `res.ok && body === "ok"`
-    // Since body !== "ok", it falls into the warn branch
-    expect(webhookCheck?.severity).toBe("warn");
-  });
-});
-
-// ---------------------------------------------------------------------------
-// formatReport — icon function TTY branches
-// ---------------------------------------------------------------------------
-
-describe("formatReport — TTY icon rendering", () => {
-  it("renders colored icons when stdout.isTTY is true", () => {
-    const origIsTTY = process.stdout.isTTY;
-    try {
-      Object.defineProperty(process.stdout, "isTTY", { value: true, writable: true, configurable: true });
-
-      const report = {
-        sections: [{
-          name: "Test",
-          checks: [
-            { label: "pass check", severity: "pass" as const },
-            { label: "warn check", severity: "warn" as const },
-            { label: "fail check", severity: "fail" as const },
-          ],
-        }],
-        summary: { passed: 1, warnings: 1, errors: 1 },
-      };
-
-      const output = formatReport(report);
-      // TTY output includes ANSI escape codes
-      expect(output).toContain("\x1b[32m"); // green for pass
-      expect(output).toContain("\x1b[33m"); // yellow for warn
-      expect(output).toContain("\x1b[31m"); // red for fail
-    } finally {
-      Object.defineProperty(process.stdout, "isTTY", { value: origIsTTY, writable: true, configurable: true });
-    }
-  });
-});
-
-// ---------------------------------------------------------------------------
-// checkCodingTools — codingTool fallback to "codex" in label
-// ---------------------------------------------------------------------------
-
-describe("checkCodingTools — codingTool null fallback", () => {
-  it("shows 'codex' as default when codingTool is undefined but backends exist", () => {
-    vi.mocked(loadCodingConfig).mockReturnValueOnce({
-      codingTool: undefined,
-      backends: { codex: { aliases: ["codex"] } },
-    } as any);
-
-    const checks = checkCodingTools();
-    const configCheck = checks.find((c) => c.label.includes("coding-tools.json loaded"));
-    expect(configCheck?.severity).toBe("pass");
-    expect(configCheck?.label).toContain("codex"); // falls back to "codex" via ??
-  });
-});
-
-// ---------------------------------------------------------------------------
-// checkFilesAndDirs — dispatch state non-Error catch branch
-// ---------------------------------------------------------------------------
-
-describe("checkFilesAndDirs — dispatch state non-Error exception", () => {
-  it("handles non-Error thrown during dispatch state read", async () => {
-    const tmpDir = mkdtempSync(join(tmpdir(), "doctor-nonError-"));
-    const statePath = join(tmpDir, "state.json");
-    writeFileSync(statePath, '{}');
-    vi.mocked(readDispatchState).mockRejectedValueOnce("raw string dispatch error");
-
-    const checks = await checkFilesAndDirs({ dispatchStatePath: statePath });
-    const stateCheck = checks.find((c) => c.label.includes("Dispatch state corrupt"));
-    expect(stateCheck?.severity).toBe("fail");
-    expect(stateCheck?.detail).toContain("raw string dispatch error");
-  });
-});

package/src/pipeline/webhook.ts

@@ -477,7 +477,14 @@ export async function handleLinearWebhook(
       commentContext ? `\n**Conversation:**\n${commentContext}` : "",
       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.`,
+      `## Scope Rules`,
+      `1. **Read the issue first.** The issue title + description define your scope. Everything you do must serve the issue as written.`,
+      `2. **\`code_run\` is ONLY for issue-body work.** Only dispatch \`code_run\` when the issue description contains implementation requirements. A greeting, question, or conversational issue gets a conversational response — NOT code_run.`,
+      `3. **Comments explore, issue body builds.** User comments may explore scope or ask questions but NEVER trigger \`code_run\` alone. If a comment requests new implementation, update the issue description first, then build from the issue text.`,
+      `4. **Plan before building.** For non-trivial work, respond with a plan first. Only dispatch \`code_run\` after the plan is clear and grounded in the issue body.`,
+      `5. **Match response to request.** Greeting → greet. Question → answer. No implementation requirements → no code_run.`,
+      ``,
+      `Respond within the scope defined above. Be concise and action-oriented.`,
     ].filter(Boolean).join("\n");
 
     // Run agent directly (non-blocking)
@@ -720,7 +727,12 @@ export async function handleLinearWebhook(
         commentContext ? `\n**Recent conversation:**\n${commentContext}` : "",
         `\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.`,
+        `## Scope Rules`,
+        `1. **The issue body is your scope.** Re-read the description above before acting.`,
+        `2. **Comments explore, issue body builds.** The follow-up may refine understanding or ask questions — NEVER dispatch \`code_run\` from a comment alone. If the user requests implementation, suggest updating the issue description first.`,
+        `3. **Match response to request.** Answer questions with answers. Do NOT escalate conversational messages into builds.`,
+        ``,
+        `Respond to the follow-up within the scope defined above. Be concise and action-oriented.`,
       ].filter(Boolean).join("\n");
 
       setActiveSession({

package/src/tools/code-tool.ts

@@ -178,6 +178,11 @@ export function createCodeTool(
       required: ["prompt"],
     },
     execute: async (toolCallId: string, params: CliToolParams & { backend?: string }, ...rest: unknown[]) => {
+      // Extract onUpdate callback for progress reporting to Linear
+      const onUpdate = typeof rest[1] === "function"
+        ? rest[1] as (update: Record<string, unknown>) => void
+        : undefined;
+
       // Resolve backend: explicit alias → per-agent config → global default
       const currentSession = getCurrentSession();
       const agentId = currentSession?.agentId;
@@ -189,6 +194,13 @@ export function createCodeTool(
 
       api.logger.info(`code_run: backend=${backend} agent=${agentId ?? "unknown"}`);
 
+      // Emit prompt summary so Linear users see what's being built
+      const promptSummary = (params.prompt ?? "").slice(0, 200);
+      api.logger.info(`code_run prompt: [${backend}] ${promptSummary}`);
+      if (onUpdate) {
+        try { onUpdate({ status: "running", summary: `[${backend}] ${promptSummary}` }); } catch {}
+      }
+
       const result = await runner(api, params, pluginConfig);
 
       return jsonResult({