@calltelemetry/openclaw-linear 0.8.4 → 0.8.5

package/README.md

@@ -904,9 +904,45 @@ Example output:
 
 Every warning and error includes a `→` line telling you what to do. Run `doctor --fix` to auto-repair what it can.
 
+### Code-run health check
+
+For deeper diagnostics on coding tool backends (Claude Code, Codex, Gemini CLI), run the dedicated code-run doctor. It checks binary installation, API key configuration, and actually invokes each backend to verify it can authenticate and respond:
+
+```bash
+openclaw openclaw-linear code-run doctor
+```
+
+Example output:
+
+```
+Code Run: Claude Code (Anthropic)
+  ✓ Binary: 2.1.50 (/home/claw/.npm-global/bin/claude)
+  ✓ API key: configured (ANTHROPIC_API_KEY)
+  ✓ Live test: responded in 3.2s
+
+Code Run: Codex (OpenAI)
+  ✓ Binary: 0.101.0 (/home/claw/.npm-global/bin/codex)
+  ✓ API key: configured (OPENAI_API_KEY)
+  ✓ Live test: responded in 2.8s
+
+Code Run: Gemini CLI (Google)
+  ✓ Binary: 0.28.2 (/home/claw/.npm-global/bin/gemini)
+  ✓ API key: configured (GEMINI_API_KEY)
+  ✓ Live test: responded in 4.1s
+
+Code Run: Routing
+  ✓ Default backend: codex
+  ✓ Mal → codex (default)
+  ✓ Kaylee → codex (default)
+  ✓ Inara → claude (override)
+  ✓ Callable backends: 3/3
+```
+
+This is separate from the main `doctor` because each live test spawns a real CLI subprocess (~5-10s per backend). Use `--json` for machine-readable output.
+
 ### Unit tests
 
-524 tests covering the full pipeline — triage, dispatch, audit, planning, intent classification, cross-model review, notifications, and infrastructure:
+532 tests covering the full pipeline — triage, dispatch, audit, planning, intent classification, cross-model review, notifications, and infrastructure:
 
 ```bash
 cd ~/claw-extensions/linear
@@ -1069,6 +1105,10 @@ openclaw openclaw-linear webhooks delete <id>        # Delete a webhook by ID
 openclaw openclaw-linear doctor                    # Run health checks
 openclaw openclaw-linear doctor --fix              # Auto-fix issues
 openclaw openclaw-linear doctor --json             # JSON output
+
+# Code-run backends
+openclaw openclaw-linear code-run doctor           # Deep check all backends (binary, API key, live test)
+openclaw openclaw-linear code-run doctor --json    # JSON output
 ```
 
 ---
@@ -1089,7 +1129,8 @@ journalctl --user -u openclaw-gateway -f         # Watch live logs
 |---|---|
 | Agent goes silent | Watchdog auto-kills after `inactivitySec` and retries. Check logs for `Watchdog KILL`. |
 | Dispatch stuck after watchdog | Both retries failed. Check `.claw/log.jsonl`. Re-assign issue to restart. |
-| `code_run` uses wrong backend | Check `coding-tools.json` — explicit backend > per-agent > global default. |
+| `code_run` uses wrong backend | Check `coding-tools.json` — explicit backend > per-agent > global default. Run `code-run doctor` to see routing. |
+| `code_run` fails at runtime | Run `openclaw openclaw-linear code-run doctor` — checks binary, API key, and live callability for each backend. |
 | Webhook events not arriving | Run `openclaw openclaw-linear webhooks setup` to auto-provision. Both webhooks must point to `/linear/webhook`. Check tunnel is running. |
 | OAuth token expired | Auto-refreshes. If stuck, re-run `openclaw openclaw-linear auth` and restart. |
 | Audit always fails | Run `openclaw openclaw-linear prompts validate` to check prompt syntax. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calltelemetry/openclaw-linear",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "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/linear-responses.ts

@@ -11,7 +11,8 @@ export function makeIssueDetails(overrides?: Record<string, unknown>) {
     title: "Fix webhook routing",
     description: "The webhook handler needs fixing.",
     estimate: 3,
-    state: { name: "In Progress" },
+    state: { name: "In Progress", type: "started" },
+    creator: { name: "Test User", email: "test@example.com" },
     assignee: { name: "Agent" },
     labels: { nodes: [] as Array<{ id: string; name: string }> },
     team: { id: "team-1", name: "Engineering", issueEstimationType: "notUsed" },

package/src/api/linear-api.ts

@@ -307,6 +307,7 @@ export class LinearAgentApi {
     description: string | null;
     estimate: number | null;
     state: { name: string; type: string };
+    creator: { name: string; email: string | null } | null;
     assignee: { name: string } | null;
     labels: { nodes: Array<{ id: string; name: string }> };
     team: { id: string; name: string; issueEstimationType: string };
@@ -324,6 +325,7 @@ export class LinearAgentApi {
           description
           estimate
           state { name type }
+          creator { name email }
           assignee { name }
           labels { nodes { id name } }
           team { id name issueEstimationType }

package/src/infra/cli.ts

@@ -645,6 +645,33 @@ export function registerCli(program: Command, api: OpenClawPluginApi): void {
       }
     });
 
+  // --- openclaw openclaw-linear code-run ---
+  const codeRunCmd = linear
+    .command("code-run")
+    .description("Manage and diagnose coding tool backends");
+
+  codeRunCmd
+    .command("doctor")
+    .description("Deep health check: verify each coding backend (Claude, Codex, Gemini) is callable")
+    .option("--json", "Output results as JSON")
+    .action(async (opts: { json?: boolean }) => {
+      const { checkCodeRunDeep, buildSummary, formatReport, formatReportJson } = await import("./doctor.js");
+      const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
+
+      const sections = await checkCodeRunDeep(pluginConfig);
+      const report = { sections, summary: buildSummary(sections) };
+
+      if (opts.json) {
+        console.log(formatReportJson(report));
+      } else {
+        console.log(formatReport(report));
+      }
+
+      if (report.summary.errors > 0) {
+        process.exitCode = 1;
+      }
+    });
+
   // --- openclaw openclaw-linear webhooks ---
   const webhooksCmd = linear
     .command("webhooks")

package/src/infra/doctor.test.ts

@@ -50,14 +50,18 @@ vi.mock("./codex-worktree.js", () => ({
 
 vi.mock("../tools/code-tool.js", () => ({
   loadCodingConfig: vi.fn(() => ({
-    codingTool: "claude",
-    agentCodingTools: {},
+    codingTool: "codex",
+    agentCodingTools: { inara: "claude" },
     backends: {
       claude: { aliases: ["claude", "anthropic"] },
       codex: { aliases: ["codex", "openai"] },
       gemini: { aliases: ["gemini", "google"] },
     },
   })),
+  resolveCodingBackend: vi.fn((config: any, agentId?: string) => {
+    if (agentId && config?.agentCodingTools?.[agentId]) return config.agentCodingTools[agentId];
+    return config?.codingTool ?? "codex";
+  }),
 }));
 
 vi.mock("./webhook-provision.js", () => ({
@@ -78,6 +82,8 @@ import {
   checkConnectivity,
   checkDispatchHealth,
   checkWebhooks,
+  checkCodeRunDeep,
+  buildSummary,
   runDoctor,
   formatReport,
   formatReportJson,
@@ -199,7 +205,7 @@ describe("checkCodingTools", () => {
     const checks = checkCodingTools();
     const configCheck = checks.find((c) => c.label.includes("coding-tools.json"));
     expect(configCheck?.severity).toBe("pass");
-    expect(configCheck?.label).toContain("claude");
+    expect(configCheck?.label).toContain("codex");
   });
 
   it("reports warn for missing CLIs", () => {
@@ -431,3 +437,124 @@ describe("formatReportJson", () => {
     expect(parsed.summary.passed).toBe(1);
   });
 });
+
+// ---------------------------------------------------------------------------
+// buildSummary
+// ---------------------------------------------------------------------------
+
+describe("buildSummary", () => {
+  it("counts pass/warn/fail across sections", () => {
+    const sections = [
+      { name: "A", checks: [{ label: "ok", severity: "pass" as const }, { label: "meh", severity: "warn" as const }] },
+      { name: "B", checks: [{ label: "bad", severity: "fail" as const }] },
+    ];
+    const summary = buildSummary(sections);
+    expect(summary).toEqual({ passed: 1, warnings: 1, errors: 1 });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// checkCodeRunDeep
+// ---------------------------------------------------------------------------
+
+describe("checkCodeRunDeep", () => {
+  // Run a single invocation and share results across assertions to avoid
+  // repeated 30s live CLI calls (the live test spawns all 3 backends).
+  let sections: Awaited<ReturnType<typeof checkCodeRunDeep>>;
+
+  beforeEach(async () => {
+    if (!sections) {
+      sections = await checkCodeRunDeep();
+    }
+  }, 120_000);
+
+  it("returns 4 sections (3 backends + routing)", () => {
+    expect(sections).toHaveLength(4);
+    expect(sections.map((s) => s.name)).toEqual([
+      "Code Run: Claude Code (Anthropic)",
+      "Code Run: Codex (OpenAI)",
+      "Code Run: Gemini CLI (Google)",
+      "Code Run: Routing",
+    ]);
+  });
+
+  it("each backend section has binary, API key, and live test checks", () => {
+    for (const section of sections.slice(0, 3)) {
+      const labels = section.checks.map((c) => c.label);
+      expect(labels.some((l) => l.includes("Binary:"))).toBe(true);
+      expect(labels.some((l) => l.includes("API key:"))).toBe(true);
+      expect(labels.some((l) => l.includes("Live test:"))).toBe(true);
+    }
+  });
+
+  it("all check results have valid severity", () => {
+    for (const section of sections) {
+      for (const check of section.checks) {
+        expect(check).toHaveProperty("label");
+        expect(check).toHaveProperty("severity");
+        expect(["pass", "warn", "fail"]).toContain(check.severity);
+      }
+    }
+  });
+
+  it("shows routing with default backend and callable count", () => {
+    const routing = sections.find((s) => s.name === "Code Run: Routing")!;
+    expect(routing).toBeDefined();
+
+    const defaultCheck = routing.checks.find((c) => c.label.includes("Default backend:"));
+    expect(defaultCheck?.severity).toBe("pass");
+    expect(defaultCheck?.label).toContain("codex");
+
+    const callableCheck = routing.checks.find((c) => c.label.includes("Callable backends:"));
+    expect(callableCheck?.severity).toBe("pass");
+    expect(callableCheck?.label).toMatch(/Callable backends: \d+\/3/);
+  });
+
+  it("shows agent override routing for inara", () => {
+    const routing = sections.find((s) => s.name === "Code Run: Routing")!;
+    const inaraCheck = routing.checks.find((c) => c.label.toLowerCase().includes("inara"));
+    if (inaraCheck) {
+      expect(inaraCheck.label).toContain("claude");
+      expect(inaraCheck.label).toContain("override");
+    }
+  });
+
+  // API key tests — these are fast (no live invocation), use separate calls
+  it("detects API key from plugin config", async () => {
+    const origKey = process.env.ANTHROPIC_API_KEY;
+    delete process.env.ANTHROPIC_API_KEY;
+
+    try {
+      const result = await checkCodeRunDeep({ claudeApiKey: "sk-from-config" });
+      const claudeKey = result[0].checks.find((c) => c.label.includes("API key:"));
+      expect(claudeKey?.severity).toBe("pass");
+      expect(claudeKey?.label).toContain("claudeApiKey");
+    } finally {
+      if (origKey) process.env.ANTHROPIC_API_KEY = origKey;
+      else delete process.env.ANTHROPIC_API_KEY;
+    }
+  });
+
+  it("warns when API key missing", async () => {
+    const origKeys = {
+      GEMINI_API_KEY: process.env.GEMINI_API_KEY,
+      GOOGLE_API_KEY: process.env.GOOGLE_API_KEY,
+      GOOGLE_GENAI_API_KEY: process.env.GOOGLE_GENAI_API_KEY,
+    };
+    delete process.env.GEMINI_API_KEY;
+    delete process.env.GOOGLE_API_KEY;
+    delete process.env.GOOGLE_GENAI_API_KEY;
+
+    try {
+      const result = await checkCodeRunDeep();
+      const geminiKey = result[2].checks.find((c) => c.label.includes("API key:"));
+      expect(geminiKey?.severity).toBe("warn");
+      expect(geminiKey?.label).toContain("not found");
+    } finally {
+      for (const [k, v] of Object.entries(origKeys)) {
+        if (v) process.env[k] = v;
+        else delete process.env[k];
+      }
+    }
+  });
+});

package/src/infra/doctor.ts

@@ -6,13 +6,13 @@
 import { existsSync, readFileSync, statSync, accessSync, unlinkSync, chmodSync, constants } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 
 import { resolveLinearToken, LinearAgentApi, AUTH_PROFILES_PATH, LINEAR_GRAPHQL_URL } from "../api/linear-api.js";
 import { readDispatchState, listActiveDispatches, listStaleDispatches, pruneCompleted, type DispatchState } from "../pipeline/dispatch-state.js";
 import { loadPrompts, clearPromptCache } from "../pipeline/pipeline.js";
 import { listWorktrees } from "./codex-worktree.js";
-import { loadCodingConfig, type CodingBackend } from "../tools/code-tool.js";
+import { loadCodingConfig, resolveCodingBackend, type CodingBackend } from "../tools/code-tool.js";
 import { getWebhookStatus, provisionWebhook, REQUIRED_RESOURCE_TYPES } from "./webhook-provision.js";
 
 // ---------------------------------------------------------------------------
@@ -767,19 +767,209 @@ export async function runDoctor(opts: DoctorOptions): Promise<DoctorReport> {
     }
   }
 
-  // Build summary
-  let passed = 0, warnings = 0, errors = 0;
-  for (const section of sections) {
-    for (const check of section.checks) {
-      switch (check.severity) {
-        case "pass": passed++; break;
-        case "warn": warnings++; break;
-        case "fail": errors++; break;
+  return { sections, summary: buildSummary(sections) };
+}
+
+// ---------------------------------------------------------------------------
+// Code Run Deep Checks
+// ---------------------------------------------------------------------------
+
+interface BackendSpec {
+  id: CodingBackend;
+  label: string;
+  bin: string;
+  /** CLI args for a minimal live invocation test */
+  testArgs: string[];
+  /** Environment variable names that provide an API key */
+  envKeys: string[];
+  /** Plugin config key for API key (if any) */
+  configKey?: string;
+  /** Env vars to unset before spawning (e.g. CLAUDECODE) */
+  unsetEnv?: string[];
+}
+
+const BACKEND_SPECS: BackendSpec[] = [
+  {
+    id: "claude",
+    label: "Claude Code (Anthropic)",
+    bin: "/home/claw/.npm-global/bin/claude",
+    testArgs: ["--print", "-p", "Respond with the single word hello", "--output-format", "stream-json", "--max-turns", "1", "--dangerously-skip-permissions"],
+    envKeys: ["ANTHROPIC_API_KEY"],
+    configKey: "claudeApiKey",
+    unsetEnv: ["CLAUDECODE"],
+  },
+  {
+    id: "codex",
+    label: "Codex (OpenAI)",
+    bin: "/home/claw/.npm-global/bin/codex",
+    testArgs: ["exec", "--json", "--ephemeral", "--full-auto", "echo hello"],
+    envKeys: ["OPENAI_API_KEY"],
+  },
+  {
+    id: "gemini",
+    label: "Gemini CLI (Google)",
+    bin: "/home/claw/.npm-global/bin/gemini",
+    testArgs: ["-p", "Respond with the single word hello", "-o", "stream-json", "--yolo"],
+    envKeys: ["GEMINI_API_KEY", "GOOGLE_API_KEY", "GOOGLE_GENAI_API_KEY"],
+  },
+];
+
+function checkBackendBinary(spec: BackendSpec): { installed: boolean; checks: CheckResult[] } {
+  const checks: CheckResult[] = [];
+
+  // Binary existence
+  try {
+    accessSync(spec.bin, constants.X_OK);
+  } catch {
+    checks.push(fail(
+      `Binary: not found at ${spec.bin}`,
+      undefined,
+      `Install ${spec.id}: npm install -g <package>`,
+    ));
+    return { installed: false, checks };
+  }
+
+  // Version check
+  try {
+    const env = { ...process.env } as Record<string, string | undefined>;
+    for (const key of spec.unsetEnv ?? []) delete env[key];
+    const raw = execFileSync(spec.bin, ["--version"], {
+      encoding: "utf8",
+      timeout: 15_000,
+      env: env as NodeJS.ProcessEnv,
+    }).trim();
+    checks.push(pass(`Binary: ${raw || "installed"} (${spec.bin})`));
+  } catch {
+    checks.push(pass(`Binary: installed (${spec.bin})`));
+  }
+
+  return { installed: true, checks };
+}
+
+function checkBackendApiKey(spec: BackendSpec, pluginConfig?: Record<string, unknown>): CheckResult {
+  // Check plugin config first
+  if (spec.configKey) {
+    const configVal = pluginConfig?.[spec.configKey];
+    if (typeof configVal === "string" && configVal) {
+      return pass(`API key: configured (${spec.configKey} in plugin config)`);
+    }
+  }
+
+  // Check env vars
+  for (const envKey of spec.envKeys) {
+    if (process.env[envKey]) {
+      return pass(`API key: configured (${envKey})`);
+    }
+  }
+
+  return warn(
+    `API key: not found`,
+    `Checked: ${spec.envKeys.join(", ")}${spec.configKey ? `, pluginConfig.${spec.configKey}` : ""}`,
+    { fix: `Set ${spec.envKeys[0]} environment variable or configure in plugin config` },
+  );
+}
+
+function checkBackendLive(spec: BackendSpec, pluginConfig?: Record<string, unknown>): CheckResult {
+  const env = { ...process.env } as Record<string, string | undefined>;
+  for (const key of spec.unsetEnv ?? []) delete env[key];
+
+  // Pass API key from plugin config if available (Claude-specific)
+  if (spec.configKey) {
+    const configVal = pluginConfig?.[spec.configKey] as string | undefined;
+    if (configVal && spec.envKeys[0]) {
+      env[spec.envKeys[0]] = configVal;
+    }
+  }
+
+  const start = Date.now();
+  try {
+    const result = spawnSync(spec.bin, spec.testArgs, {
+      encoding: "utf8",
+      timeout: 30_000,
+      env: env as NodeJS.ProcessEnv,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    const elapsed = ((Date.now() - start) / 1000).toFixed(1);
+
+    if (result.error) {
+      const msg = result.error.message ?? String(result.error);
+      if (msg.includes("ETIMEDOUT") || msg.includes("timed out")) {
+        return warn(`Live test: timed out after 30s`);
       }
+      return warn(`Live test: spawn error — ${msg.slice(0, 200)}`);
     }
+
+    if (result.status === 0) {
+      return pass(`Live test: responded in ${elapsed}s`);
+    }
+
+    // Non-zero exit
+    const stderr = (result.stderr ?? "").trim().slice(0, 200);
+    const stdout = (result.stdout ?? "").trim().slice(0, 200);
+    const detail = stderr || stdout || "(no output)";
+    return warn(`Live test: exit code ${result.status} (${elapsed}s) — ${detail}`);
+  } catch (err) {
+    const elapsed = ((Date.now() - start) / 1000).toFixed(1);
+    return warn(`Live test: error (${elapsed}s) — ${err instanceof Error ? err.message.slice(0, 200) : String(err)}`);
   }
+}
+
+/**
+ * Deep health checks for coding tool backends.
+ *
+ * Verifies binary installation, API key configuration, and live callability
+ * for each backend (Claude, Codex, Gemini). Also shows agent routing.
+ *
+ * Usage: openclaw openclaw-linear code-run doctor [--json]
+ */
+export async function checkCodeRunDeep(
+  pluginConfig?: Record<string, unknown>,
+): Promise<CheckSection[]> {
+  const sections: CheckSection[] = [];
+  const config = loadCodingConfig();
+  let callableCount = 0;
+
+  for (const spec of BACKEND_SPECS) {
+    const checks: CheckResult[] = [];
+
+    // 1. Binary check
+    const { installed, checks: binChecks } = checkBackendBinary(spec);
+    checks.push(...binChecks);
+
+    if (installed) {
+      // 2. API key check
+      checks.push(checkBackendApiKey(spec, pluginConfig));
+
+      // 3. Live invocation test
+      const liveResult = checkBackendLive(spec, pluginConfig);
+      checks.push(liveResult);
 
-  return { sections, summary: { passed, warnings, errors } };
+      if (liveResult.severity === "pass") callableCount++;
+    }
+
+    sections.push({ name: `Code Run: ${spec.label}`, checks });
+  }
+
+  // Routing summary section
+  const routingChecks: CheckResult[] = [];
+  const defaultBackend = resolveCodingBackend(config);
+  routingChecks.push(pass(`Default backend: ${defaultBackend}`));
+
+  const profiles = loadAgentProfiles();
+  for (const [agentId, profile] of Object.entries(profiles)) {
+    const resolved = resolveCodingBackend(config, agentId);
+    const isOverride = config.agentCodingTools?.[agentId] != null;
+    const label = profile.label ?? agentId;
+    routingChecks.push(pass(
+      `${label} → ${resolved}${isOverride ? " (override)" : " (default)"}`,
+    ));
+  }
+
+  routingChecks.push(pass(`Callable backends: ${callableCount}/${BACKEND_SPECS.length}`));
+  sections.push({ name: "Code Run: Routing", checks: routingChecks });
+
+  return sections;
 }
 
 // ---------------------------------------------------------------------------
@@ -831,3 +1021,18 @@ export function formatReport(report: DoctorReport): string {
 export function formatReportJson(report: DoctorReport): string {
   return JSON.stringify(report, null, 2);
 }
+
+/** Build a summary by counting pass/warn/fail across sections. */
+export function buildSummary(sections: CheckSection[]): { passed: number; warnings: number; errors: number } {
+  let passed = 0, warnings = 0, errors = 0;
+  for (const section of sections) {
+    for (const check of section.checks) {
+      switch (check.severity) {
+        case "pass": passed++; break;
+        case "warn": warnings++; break;
+        case "fail": errors++; break;
+      }
+    }
+  }
+  return { passed, warnings, errors };
+}

package/src/pipeline/webhook.ts

@@ -325,16 +325,35 @@ export async function handleLinearWebhook(
       .join("\n\n");
 
     const issueRef = enrichedIssue?.identifier ?? issue.identifier ?? issue.id;
+    const stateType = enrichedIssue?.state?.type ?? "";
+    const isTriaged = stateType === "started" || stateType === "completed" || stateType === "canceled";
+
+    const toolAccessLines = isTriaged
+      ? [
+        `**Tool access:**`,
+        `- \`linearis\` CLI: Full access. You can read, update, close, and comment on issues. Use \`linearis issues update ${issueRef} --state <state>\` to change status, \`linearis issues update ${issueRef} --priority <1-4>\` to set priority, etc.`,
+        `- \`code_run\`: Dispatch coding work to a worker. Workers return text — they cannot access linearis.`,
+        `- \`spawn_agent\`/\`ask_agent\`: Delegate to other crew agents.`,
+        `- Standard tools: exec, read, edit, write, web_search, etc.`,
+      ]
+      : [
+        `**Tool access:**`,
+        `- \`linearis\` CLI: READ ONLY. You can read issues (\`linearis issues read ${issueRef}\`), list issues (\`linearis issues list\`), and search (\`linearis issues search "..."\`). Do NOT use linearis to update, close, comment, or modify issues.`,
+        `- \`code_run\`: Dispatch coding work to a worker. Workers return text — they cannot access linearis.`,
+        `- \`spawn_agent\`/\`ask_agent\`: Delegate to other crew agents.`,
+        `- Standard tools: exec, read, edit, write, web_search, etc.`,
+      ];
+
+    const roleLines = isTriaged
+      ? [`**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 linearis comments — the audit system handles lifecycle transitions.`];
+
     const message = [
       `You are an orchestrator responding in a Linear issue session. Your text output will be posted as activities visible to the user.`,
       ``,
-      `**Tool access:**`,
-      `- \`linearis\` CLI: READ ONLY. You can read issues (\`linearis issues read ${issueRef}\`), list issues (\`linearis issues list\`), and search (\`linearis issues search "..."\`). Do NOT use linearis to update, close, comment, or modify issues.`,
-      `- \`code_run\`: Dispatch coding work to a worker. Workers return text — they cannot access linearis.`,
-      `- \`spawn_agent\`/\`ask_agent\`: Delegate to other crew agents.`,
-      `- Standard tools: exec, read, edit, write, web_search, etc.`,
+      ...toolAccessLines,
       ``,
-      `**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 linearis comments — the audit system handles lifecycle transitions.`,
+      ...roleLines,
       ``,
       `## Issue: ${issueRef} — ${enrichedIssue?.title ?? issue.title ?? "(untitled)"}`,
       `**Status:** ${enrichedIssue?.state?.name ?? "Unknown"} | **Assignee:** ${enrichedIssue?.assignee?.name ?? "Unassigned"}`,
@@ -367,7 +386,7 @@ export async function handleLinearWebhook(
         // Emit initial thought
         await linearApi.emitActivity(session.id, {
           type: "thought",
-          body: `Processing request for ${enrichedIssue?.identifier ?? issue.id}...`,
+          body: `${label} is processing request for ${enrichedIssue?.identifier ?? issue.id}...`,
         }).catch(() => {});
 
         // Run agent with streaming to Linear
@@ -503,16 +522,35 @@ export async function handleLinearWebhook(
         .join("\n\n");
 
       const followUpIssueRef = enrichedIssue?.identifier ?? issue.identifier ?? issue.id;
+      const followUpStateType = enrichedIssue?.state?.type ?? "";
+      const followUpIsTriaged = followUpStateType === "started" || followUpStateType === "completed" || followUpStateType === "canceled";
+
+      const followUpToolAccessLines = followUpIsTriaged
+        ? [
+          `**Tool access:**`,
+          `- \`linearis\` CLI: Full access. You can read, update, close, and comment on issues. Use \`linearis issues update ${followUpIssueRef} --state <state>\` to change status, \`linearis issues update ${followUpIssueRef} --priority <1-4>\` to set priority, etc.`,
+          `- \`code_run\`: Dispatch coding work to a worker. Workers return text — they cannot access linearis.`,
+          `- \`spawn_agent\`/\`ask_agent\`: Delegate to other crew agents.`,
+          `- Standard tools: exec, read, edit, write, web_search, etc.`,
+        ]
+        : [
+          `**Tool access:**`,
+          `- \`linearis\` CLI: READ ONLY. You can read issues (\`linearis issues read ${followUpIssueRef}\`), list, and search. Do NOT use linearis to update, close, comment, or modify issues.`,
+          `- \`code_run\`: Dispatch coding work to a worker. Workers return text — they cannot access linearis.`,
+          `- \`spawn_agent\`/\`ask_agent\`: Delegate to other crew agents.`,
+          `- Standard tools: exec, read, edit, write, web_search, etc.`,
+        ];
+
+      const followUpRoleLines = followUpIsTriaged
+        ? [`**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.`];
+
       const message = [
         `You are an orchestrator responding in a Linear issue session. Your text output will be posted as activities visible to the user.`,
         ``,
-        `**Tool access:**`,
-        `- \`linearis\` CLI: READ ONLY. You can read issues (\`linearis issues read ${followUpIssueRef}\`), list, and search. Do NOT use linearis to update, close, comment, or modify issues.`,
-        `- \`code_run\`: Dispatch coding work to a worker. Workers return text — they cannot access linearis.`,
-        `- \`spawn_agent\`/\`ask_agent\`: Delegate to other crew agents.`,
-        `- Standard tools: exec, read, edit, write, web_search, etc.`,
+        ...followUpToolAccessLines,
         ``,
-        `**Your role:** Dispatcher. For work requests, use \`code_run\`. You do NOT update issue status — the audit system handles lifecycle.`,
+        ...followUpRoleLines,
         ``,
         `## Issue: ${followUpIssueRef} — ${enrichedIssue?.title ?? issue.title ?? "(untitled)"}`,
         `**Status:** ${enrichedIssue?.state?.name ?? "Unknown"} | **Assignee:** ${enrichedIssue?.assignee?.name ?? "Unassigned"}`,
@@ -536,7 +574,7 @@ export async function handleLinearWebhook(
       try {
         await linearApi.emitActivity(session.id, {
           type: "thought",
-          body: `Processing follow-up for ${enrichedIssue?.identifier ?? issue.id}...`,
+          body: `${label} is processing follow-up for ${enrichedIssue?.identifier ?? issue.id}...`,
         }).catch(() => {});
 
         const sessionId = `linear-session-${session.id}`;
@@ -1006,11 +1044,18 @@ export async function handleLinearWebhook(
           }).catch(() => {});
         }
 
+        const creatorName = enrichedIssue?.creator?.name ?? "Unknown";
+        const creatorEmail = enrichedIssue?.creator?.email ?? null;
+        const creatorLine = creatorEmail
+          ? `**Created by:** ${creatorName} (${creatorEmail})`
+          : `**Created by:** ${creatorName}`;
+
         const message = [
           `IMPORTANT: You are triaging a new Linear issue. You MUST respond with a JSON block containing your triage decisions, followed by your assessment as plain text.`,
           ``,
           `## Issue: ${enrichedIssue?.identifier ?? issue.identifier ?? issue.id} — ${enrichedIssue?.title ?? issue.title ?? "(untitled)"}`,
           `**Status:** ${enrichedIssue?.state?.name ?? "Unknown"} | **Current Estimate:** ${enrichedIssue?.estimate ?? "None"} | **Current Labels:** ${currentLabelNames}`,
+          creatorLine,
           ``,
           `**Description:**`,
           description,
@@ -1038,6 +1083,8 @@ export async function handleLinearWebhook(
           `}`,
           '```',
           ``,
+          `IMPORTANT: Only reference real users from the issue data above. Do NOT fabricate or guess user names, emails, or identities. The issue creator is shown in the "Created by" field.`,
+          ``,
           `Then write your full assessment as markdown below the JSON block.`,
         ].filter(Boolean).join("\n");
 
@@ -1191,24 +1238,45 @@ async function dispatchCommentToAgent(
     .join("\n");
 
   const issueRef = enrichedIssue?.identifier ?? issue.identifier ?? issue.id;
+  const stateType = enrichedIssue?.state?.type ?? "";
+  const isTriaged = stateType === "started" || stateType === "completed" || stateType === "canceled";
+
+  const toolAccessLines = isTriaged
+    ? [
+      `**Tool access:**`,
+      `- \`linearis\` CLI: Full access. You can read, update, close, and comment on issues. Use \`linearis issues update ${issueRef} --state <state>\` to change status, \`linearis issues update ${issueRef} --priority <1-4>\` to set priority, etc.`,
+      `- \`code_run\`: Dispatch coding work to a worker. Workers return text — they cannot access linearis.`,
+      `- Standard tools: exec, read, edit, write, web_search, etc.`,
+    ]
+    : [
+      `**Tool access:**`,
+      `- \`linearis\` CLI: READ ONLY. You can read issues (\`linearis issues read ${issueRef}\`), list, and search. Do NOT use linearis to update, close, comment, or modify issues.`,
+      `- \`code_run\`: Dispatch coding work to a worker. Workers return text — they cannot access linearis.`,
+      `- Standard tools: exec, read, edit, write, web_search, etc.`,
+    ];
+
+  const roleLines = isTriaged
+    ? [`**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.`];
+
   const message = [
     `You are an orchestrator responding to a Linear comment. Your text output will be automatically posted as a comment on the issue (do NOT post a comment yourself — the handler does it).`,
     ``,
-    `**Tool access:**`,
-    `- \`linearis\` CLI: READ ONLY. You can read issues (\`linearis issues read ${issueRef}\`), list, and search. Do NOT use linearis to update, close, comment, or modify issues.`,
-    `- \`code_run\`: Dispatch coding work to a worker. Workers return text — they cannot access linearis.`,
-    `- Standard tools: exec, read, edit, write, web_search, etc.`,
+    ...toolAccessLines,
     ``,
-    `**Your role:** Dispatcher. For work requests, use \`code_run\`. You do NOT update issue status — the audit system handles lifecycle.`,
+    ...roleLines,
     ``,
     `## Issue: ${issueRef} — ${enrichedIssue?.title ?? issue.title ?? "(untitled)"}`,
     `**Status:** ${enrichedIssue?.state?.name ?? "Unknown"} | **Assignee:** ${enrichedIssue?.assignee?.name ?? "Unassigned"}`,
+    enrichedIssue?.creator ? `**Created by:** ${enrichedIssue.creator.name}${enrichedIssue.creator.email ? ` (${enrichedIssue.creator.email})` : ""}` : "",
     ``,
     `**Description:**`,
     description,
     commentSummary ? `\n**Recent comments:**\n${commentSummary}` : "",
     `\n**${commentor} says:**\n> ${commentBody}`,
     ``,
+    `IMPORTANT: Only reference real users from the issue data above. Do NOT fabricate or guess user names, emails, or identities.`,
+    ``,
     `Respond concisely. For work requests, dispatch via \`code_run\` and summarize the result.`,
   ].filter(Boolean).join("\n");
 
@@ -1354,12 +1422,15 @@ async function handleCloseIssue(
     ``,
     `## Issue: ${issueRef} — ${enrichedIssue?.title ?? issue.title ?? "(untitled)"}`,
     `**Status:** ${enrichedIssue?.state?.name ?? "Unknown"} | **Assignee:** ${enrichedIssue?.assignee?.name ?? "Unassigned"}`,
+    enrichedIssue?.creator ? `**Created by:** ${enrichedIssue.creator.name}${enrichedIssue.creator.email ? ` (${enrichedIssue.creator.email})` : ""}` : "",
     ``,
     `**Description:**`,
     description,
     commentSummary ? `\n**Comment history:**\n${commentSummary}` : "",
     `\n**${commentor} says (closure request):**\n> ${commentBody}`,
     ``,
+    `IMPORTANT: Only reference real users from the issue data above. Do NOT fabricate or guess user names, emails, or identities.`,
+    ``,
     `Write a concise closure report with:`,
     `- **Summary**: What was done (1-2 sentences)`,
     `- **Resolution**: How it was resolved`,
@@ -1404,9 +1475,13 @@ async function handleCloseIssue(
       readOnly: true,
     });
 
+    if (!result.success) {
+      api.logger.error(`Closure report agent failed for ${issueRef}: ${(result.output ?? "no output").slice(0, 500)}`);
+    }
+
     const closureReport = result.success
       ? result.output
-      : "Issue closed. (Closure report generation failed.)";
+      : `Issue closed by ${commentor}.\n\n> ${commentBody}\n\n*Closure report generation failed — agent returned: ${(result.output ?? "no output").slice(0, 200)}*`;
 
     const fullReport = `## Closure Report\n\n${closureReport}`;