@calltelemetry/openclaw-linear 0.5.0 → 0.5.2

package/index.ts

@@ -196,15 +196,21 @@ export default function register(api: OpenClawPluginApi) {
     try {
       const raw = execFileSync(bin, ["--version"], {
         encoding: "utf8",
-        timeout: 5_000,
+        timeout: 15_000,
         env: { ...process.env, CLAUDECODE: undefined } as any,
       }).trim();
       cliChecks[name] = raw || "unknown";
     } catch {
-      cliChecks[name] = "not found";
-      api.logger.warn(
-        `${name} CLI not found at ${bin}. The ${name}_run tool will fail. Install with: ${installCmd}`,
-      );
+      // Fallback: check if the file exists (execFileSync can fail in worker contexts)
+      try {
+        require("node:fs").accessSync(bin, require("node:fs").constants.X_OK);
+        cliChecks[name] = "installed (version check skipped)";
+      } catch {
+        cliChecks[name] = "not found";
+        api.logger.warn(
+          `${name} CLI not found at ${bin}. The ${name}_run tool will fail. Install with: ${installCmd}`,
+        );
+      }
     }
   }
 

package/package.json

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

package/prompts.yaml

@@ -5,13 +5,19 @@
 #
 # Edit these to customize worker/audit behavior without rebuilding the plugin.
 # Override path via `promptsPath` in plugin config.
+#
+# Access model:
+#   Zoe (orchestrator) — linearis READ ONLY (issues read/list/search)
+#   Worker             — NO linearis access. Return text output only.
+#   Auditor            — linearis READ + WRITE (can update status, close, comment)
 
 worker:
   system: |
-    You are implementing a Linear issue. Your job is to plan and code the solution.
-    Post an implementation summary as a Linear comment when done.
-    DO NOT mark the issue as Done — that is handled by the audit system.
-    DO NOT attempt to change the issue status or labels.
+    You are a coding worker implementing a Linear issue. Your ONLY job is to write code and return a text summary.
+    You do NOT have access to linearis or any Linear issue management tools.
+    Do NOT attempt to update, close, comment on, or modify the Linear issue in any way.
+    Do NOT mark the issue as Done — the audit system handles all issue lifecycle.
+    Just write code and return your implementation summary as text.
   task: |
     Implement issue {{identifier}}: {{title}}
 
@@ -25,15 +31,22 @@ worker:
     2. Plan your approach
     3. Implement the solution in the worktree
     4. Run tests to verify your changes
-    5. Post an implementation summary as a comment on the Linear issue
-    6. Include what was changed, what tests were run, and any notes
+    5. Return a text summary of what you changed, what tests you ran, and any notes
+
+    Your text output will be captured automatically. Do NOT use linearis or attempt to post comments.
 
 audit:
   system: |
-    You are an independent auditor. Your job is to verify that work was completed correctly.
+    You are an independent auditor. Your job is to verify that work was completed correctly
+    and then update the Linear issue accordingly.
     The Linear issue body is the SOURCE OF TRUTH for what "done" means.
-    Worker comments are secondary evidence of what was attempted.
+    Worker output is secondary evidence of what was attempted.
     You must be thorough and objective. Do not rubber-stamp.
+
+    You have WRITE access to linearis. After auditing, you are responsible for:
+    - Posting an audit summary comment on the issue
+    - Updating the issue status if the audit passes
+    Use `linearis` CLI via exec for these operations.
   task: |
     Audit issue {{identifier}}: {{title}}
 
@@ -44,12 +57,16 @@ audit:
 
     Checklist:
     1. Identify ALL acceptance criteria from the issue body
-    2. Read worker comments on the issue (use linearis)
+    2. Read worker comments: `linearis issues read {{identifier}}`
     3. Verify each acceptance criterion is addressed in the code
     4. Run tests in the worktree — verify they pass
     5. Check test coverage if expectations are stated in the issue
     6. Review the code diff for quality and correctness
 
+    After auditing:
+    - Post your audit findings as a comment: `linearis comments create {{identifier}} --body "..."`
+    - If PASS: update status: `linearis issues update {{identifier}} --status "Done"`
+
     You MUST return a JSON verdict as the last line of your response:
     {"pass": true/false, "criteria": ["list of criteria found"], "gaps": ["list of unmet criteria"], "testResults": "summary of test output"}
 
@@ -59,3 +76,4 @@ rework:
     {{gaps}}
 
     Address these specific issues in your rework. Focus on the gaps listed above.
+    Remember: you do NOT have linearis access. Just fix the code and return a text summary.

package/src/agent.ts

@@ -1,7 +1,36 @@
 import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { mkdirSync, readFileSync } from "node:fs";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import type { LinearAgentApi, ActivityContent } from "./linear-api.js";
 
+// ---------------------------------------------------------------------------
+// Agent directory resolution (config-based, not ext API which ignores agentId)
+// ---------------------------------------------------------------------------
+
+interface AgentDirs {
+  workspaceDir: string;
+  agentDir: string;
+}
+
+function resolveAgentDirs(agentId: string, config: Record<string, any>): AgentDirs {
+  const home = process.env.HOME ?? "/home/claw";
+  const agentList = config?.agents?.list as Array<Record<string, any>> | undefined;
+  const agentEntry = agentList?.find((a) => a.id === agentId);
+
+  // Workspace: agent-specific override → agents.defaults.workspace → fallback
+  const workspaceDir = agentEntry?.workspace
+    ?? config?.agents?.defaults?.workspace
+    ?? join(home, ".openclaw", "workspace");
+
+  // Agent runtime dir: always ~/.openclaw/agents/{agentId}/agent
+  // (matches OpenClaw's internal structure)
+  const agentDir = join(home, ".openclaw", "agents", agentId, "agent");
+  mkdirSync(agentDir, { recursive: true });
+
+  return { workspaceDir, agentDir };
+}
+
 // Import extensionAPI for embedded agent runner (internal, not in public SDK)
 let _extensionAPI: typeof import("/home/claw/.npm-global/lib/node_modules/openclaw/dist/extensionAPI.js") | null = null;
 async function getExtensionAPI() {
@@ -66,17 +95,22 @@ async function runEmbedded(
 ): Promise<AgentRunResult> {
   const ext = await getExtensionAPI();
 
-  const workspaceDir = ext.resolveAgentWorkspaceDir({ agentId });
-  const sessionFile = ext.resolveSessionFilePath(sessionId);
-  const agentDir = ext.resolveAgentDir({ agentId });
+  // Load config so we can resolve agent dirs and providers correctly.
+  const config = await api.runtime.config.loadConfig();
+  const configAny = config as Record<string, any>;
+
+  // Resolve workspace and agent dirs from config (ext API ignores agentId).
+  const dirs = resolveAgentDirs(agentId, configAny);
+  const { workspaceDir, agentDir } = dirs;
   const runId = randomUUID();
 
-  // Load config so embedded runner can resolve providers, API keys, etc.
-  const config = await api.runtime.config.loadConfig();
+  // Build session file path under the correct agent's sessions directory.
+  const sessionsDir = join(agentDir, "sessions");
+  try { mkdirSync(sessionsDir, { recursive: true }); } catch {}
+  const sessionFile = join(sessionsDir, `${sessionId}.jsonl`);
 
   // Resolve model/provider from config — default is anthropic which requires
   // a separate API key. Our agents use openrouter.
-  const configAny = config as Record<string, any>;
   const agentList = configAny?.agents?.list as Array<Record<string, any>> | undefined;
   const agentEntry = agentList?.find((a) => a.id === agentId);
   const modelRef: string =
@@ -89,7 +123,7 @@ async function runEmbedded(
   const provider = slashIdx > 0 ? modelRef.slice(0, slashIdx) : ext.DEFAULT_PROVIDER;
   const model = slashIdx > 0 ? modelRef.slice(slashIdx + 1) : modelRef;
 
-  api.logger.info(`Embedded agent run: agent=${agentId} session=${sessionId} runId=${runId} provider=${provider} model=${model}`);
+  api.logger.info(`Embedded agent run: agent=${agentId} session=${sessionId} runId=${runId} provider=${provider} model=${model} workspaceDir=${workspaceDir} agentDir=${agentDir}`);
 
   const emit = (content: ActivityContent) => {
     streaming.linearApi.emitActivity(streaming.agentSessionId, content).catch((err) => {

package/src/artifacts.ts

@@ -0,0 +1,265 @@
+/**
+ * artifacts.ts — .claw/ per-worktree artifact convention.
+ *
+ * Provides a standard directory structure for storing artifacts during
+ * the lifecycle of a dispatched issue. Any OpenClaw plugin that works
+ * with a worktree can write to {worktreePath}/.claw/.
+ *
+ * Structure:
+ *   .claw/
+ *     manifest.json     — issue metadata + lifecycle timestamps
+ *     plan.md           — implementation plan
+ *     worker-{N}.md     — worker output per attempt (truncated)
+ *     audit-{N}.json    — audit verdict per attempt
+ *     log.jsonl         — append-only interaction log
+ *     summary.md        — agent-curated final summary
+ */
+import { existsSync, mkdirSync, readFileSync, appendFileSync, writeFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import type { AuditVerdict } from "./pipeline.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const MAX_ARTIFACT_SIZE = 8192; // 8KB per output file
+const MAX_PREVIEW_SIZE = 500;   // For log entry previews
+const MAX_PROMPT_PREVIEW = 200; // For log entry prompt previews
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ClawManifest {
+  issueIdentifier: string;
+  issueTitle: string;
+  issueId: string;
+  tier: string;
+  model: string;
+  dispatchedAt: string;
+  worktreePath: string;
+  branch: string;
+  attempts: number;
+  status: string;
+  plugin: string;
+}
+
+export interface LogEntry {
+  ts: string;
+  phase: "worker" | "audit" | "verdict" | "dispatch";
+  attempt: number;
+  agent: string;
+  prompt: string;
+  outputPreview: string;
+  success: boolean;
+  durationMs?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Directory setup
+// ---------------------------------------------------------------------------
+
+function clawDir(worktreePath: string): string {
+  return join(worktreePath, ".claw");
+}
+
+/** Creates .claw/ directory. Returns the path. */
+export function ensureClawDir(worktreePath: string): string {
+  const dir = clawDir(worktreePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+/**
+ * Ensure .claw/ is in .gitignore at the worktree root.
+ * Appends if not already present. Idempotent.
+ */
+export function ensureGitignore(worktreePath: string): void {
+  const gitignorePath = join(worktreePath, ".gitignore");
+  try {
+    const content = existsSync(gitignorePath)
+      ? readFileSync(gitignorePath, "utf-8")
+      : "";
+    if (!content.split("\n").some((line) => line.trim() === ".claw" || line.trim() === ".claw/")) {
+      const nl = content.length > 0 && !content.endsWith("\n") ? "\n" : "";
+      appendFileSync(gitignorePath, `${nl}.claw/\n`, "utf-8");
+    }
+  } catch {
+    // Best effort — don't block pipeline
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Manifest
+// ---------------------------------------------------------------------------
+
+export function writeManifest(worktreePath: string, manifest: ClawManifest): void {
+  const dir = ensureClawDir(worktreePath);
+  writeFileSync(join(dir, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+}
+
+export function readManifest(worktreePath: string): ClawManifest | null {
+  try {
+    const raw = readFileSync(join(clawDir(worktreePath), "manifest.json"), "utf-8");
+    return JSON.parse(raw) as ClawManifest;
+  } catch {
+    return null;
+  }
+}
+
+export function updateManifest(worktreePath: string, updates: Partial<ClawManifest>): void {
+  const current = readManifest(worktreePath);
+  if (!current) return;
+  writeManifest(worktreePath, { ...current, ...updates });
+}
+
+// ---------------------------------------------------------------------------
+// Phase artifacts
+// ---------------------------------------------------------------------------
+
+/** Save worker output for a given attempt. Truncated to MAX_ARTIFACT_SIZE. */
+export function saveWorkerOutput(worktreePath: string, attempt: number, output: string): void {
+  const dir = ensureClawDir(worktreePath);
+  const truncated = output.length > MAX_ARTIFACT_SIZE
+    ? output.slice(0, MAX_ARTIFACT_SIZE) + "\n\n--- truncated ---"
+    : output;
+  writeFileSync(join(dir, `worker-${attempt}.md`), truncated, "utf-8");
+}
+
+/** Save a plan (extracted from worker output or provided directly). */
+export function savePlan(worktreePath: string, plan: string): void {
+  const dir = ensureClawDir(worktreePath);
+  writeFileSync(join(dir, "plan.md"), plan, "utf-8");
+}
+
+/** Save audit verdict for a given attempt. */
+export function saveAuditVerdict(worktreePath: string, attempt: number, verdict: AuditVerdict): void {
+  const dir = ensureClawDir(worktreePath);
+  writeFileSync(join(dir, `audit-${attempt}.json`), JSON.stringify(verdict, null, 2) + "\n", "utf-8");
+}
+
+// ---------------------------------------------------------------------------
+// Interaction log
+// ---------------------------------------------------------------------------
+
+/** Append a structured log entry to .claw/log.jsonl. */
+export function appendLog(worktreePath: string, entry: LogEntry): void {
+  const dir = ensureClawDir(worktreePath);
+  const truncated: LogEntry = {
+    ...entry,
+    prompt: entry.prompt.slice(0, MAX_PROMPT_PREVIEW),
+    outputPreview: entry.outputPreview.slice(0, MAX_PREVIEW_SIZE),
+  };
+  appendFileSync(join(dir, "log.jsonl"), JSON.stringify(truncated) + "\n", "utf-8");
+}
+
+// ---------------------------------------------------------------------------
+// Summary
+// ---------------------------------------------------------------------------
+
+/** Write the final curated summary. */
+export function writeSummary(worktreePath: string, summary: string): void {
+  const dir = ensureClawDir(worktreePath);
+  writeFileSync(join(dir, "summary.md"), summary, "utf-8");
+}
+
+/**
+ * Build a markdown summary from all .claw/ artifacts.
+ * Used at issue completion to generate a memory-friendly summary.
+ */
+export function buildSummaryFromArtifacts(worktreePath: string): string | null {
+  const manifest = readManifest(worktreePath);
+  if (!manifest) return null;
+
+  const parts: string[] = [];
+  parts.push(`# Dispatch: ${manifest.issueIdentifier} — ${manifest.issueTitle}`);
+  parts.push(`**Tier:** ${manifest.tier} | **Status:** ${manifest.status} | **Attempts:** ${manifest.attempts}`);
+  parts.push("");
+
+  // Include plan if exists
+  try {
+    const plan = readFileSync(join(clawDir(worktreePath), "plan.md"), "utf-8");
+    parts.push("## Plan");
+    parts.push(plan.slice(0, 2000));
+    parts.push("");
+  } catch { /* no plan */ }
+
+  // Include each attempt's worker + audit
+  for (let i = 0; i < manifest.attempts; i++) {
+    parts.push(`## Attempt ${i}`);
+
+    // Worker output preview
+    try {
+      const worker = readFileSync(join(clawDir(worktreePath), `worker-${i}.md`), "utf-8");
+      parts.push("### Worker Output");
+      parts.push(worker.slice(0, 1500));
+      parts.push("");
+    } catch { /* no worker output */ }
+
+    // Audit verdict
+    try {
+      const raw = readFileSync(join(clawDir(worktreePath), `audit-${i}.json`), "utf-8");
+      const verdict = JSON.parse(raw) as AuditVerdict;
+      parts.push(`### Audit: ${verdict.pass ? "PASS" : "FAIL"}`);
+      if (verdict.criteria.length) parts.push(`**Criteria:** ${verdict.criteria.join(", ")}`);
+      if (verdict.gaps.length) parts.push(`**Gaps:** ${verdict.gaps.join(", ")}`);
+      if (verdict.testResults) parts.push(`**Tests:** ${verdict.testResults}`);
+      parts.push("");
+    } catch { /* no audit */ }
+  }
+
+  parts.push("---");
+  parts.push(`*Artifacts: ${worktreePath}/.claw/*`);
+
+  return parts.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Memory integration
+// ---------------------------------------------------------------------------
+
+/**
+ * Write dispatch summary to the orchestrator's memory directory.
+ * Auto-indexed by OpenClaw's sqlite+embeddings memory system.
+ */
+export function writeDispatchMemory(
+  issueIdentifier: string,
+  summary: string,
+  workspaceDir: string,
+): void {
+  const memDir = join(workspaceDir, "memory");
+  if (!existsSync(memDir)) {
+    mkdirSync(memDir, { recursive: true });
+  }
+  writeFileSync(
+    join(memDir, `dispatch-${issueIdentifier}.md`),
+    summary,
+    "utf-8",
+  );
+}
+
+/**
+ * Resolve the orchestrator agent's workspace directory from config.
+ * Same config-based approach as resolveAgentDirs in agent.ts.
+ */
+export function resolveOrchestratorWorkspace(
+  api: any,
+  pluginConfig?: Record<string, unknown>,
+): string {
+  const home = process.env.HOME ?? "/home/claw";
+  const agentId = (pluginConfig?.defaultAgentId as string) ?? "default";
+
+  try {
+    const config = api.runtime.config.loadConfig() as Record<string, any>;
+    const agentList = config?.agents?.list as Array<Record<string, any>> | undefined;
+    const agentEntry = agentList?.find((a: any) => a.id === agentId);
+    return agentEntry?.workspace
+      ?? config?.agents?.defaults?.workspace
+      ?? join(home, ".openclaw", "workspace");
+  } catch {
+    return join(home, ".openclaw", "workspace");
+  }
+}

package/src/claude-tool.ts

@@ -138,7 +138,6 @@ export async function runClaude(
   if (model ?? pluginConfig?.claudeModel) {
     args.push("--model", (model ?? pluginConfig?.claudeModel) as string);
   }
-  args.push("-C", workingDir);
   args.push("-p", prompt);
 
   api.logger.info(`Claude exec: ${CLAUDE_BIN} ${args.join(" ").slice(0, 200)}...`);
@@ -150,6 +149,7 @@ export async function runClaude(
 
     const child = spawn(CLAUDE_BIN, args, {
       stdio: ["ignore", "pipe", "pipe"],
+      cwd: workingDir,
       env,
       timeout: 0,
     });

package/src/codex-worktree.ts

@@ -2,6 +2,7 @@ import { execFileSync } from "node:child_process";
 import { existsSync, statSync, readdirSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
+import { ensureGitignore } from "./artifacts.js";
 
 const DEFAULT_BASE_REPO = "/home/claw/ai-workspace";
 const DEFAULT_WORKTREE_BASE_DIR = path.join(homedir(), ".openclaw", "worktrees");
@@ -90,6 +91,7 @@ export function createWorktree(
     try {
       // Verify it's a valid git worktree
       git(["rev-parse", "--git-dir"], worktreePath);
+      ensureGitignore(worktreePath);
       return { path: worktreePath, branch, resumed: true };
     } catch {
       // Directory exists but isn't a valid worktree — remove and recreate
@@ -105,11 +107,13 @@ export function createWorktree(
   if (branchExists) {
     // Recreate worktree from existing branch — preserves previous work
     git(["worktree", "add", worktreePath, branch], repo);
+    ensureGitignore(worktreePath);
     return { path: worktreePath, branch, resumed: true };
   }
 
   // Fresh start: new branch off HEAD
   git(["worktree", "add", "-b", branch, worktreePath], repo);
+  ensureGitignore(worktreePath);
   return { path: worktreePath, branch, resumed: false };
 }
 

package/src/dispatch-state.ts

@@ -57,6 +57,7 @@ export interface ActiveDispatch {
   workerSessionKey?: string;    // session key for current worker sub-agent
   auditSessionKey?: string;     // session key for current audit sub-agent
   stuckReason?: string;         // only set when status === "stuck"
+  issueTitle?: string;          // for artifact summaries and memory headings
 }
 
 export interface CompletedDispatch {

package/src/pipeline.ts

@@ -34,6 +34,16 @@ import {
   getActiveDispatch,
 } from "./dispatch-state.js";
 import { type NotifyFn } from "./notify.js";
+import {
+  saveWorkerOutput,
+  saveAuditVerdict,
+  appendLog,
+  updateManifest,
+  writeSummary,
+  buildSummaryFromArtifacts,
+  writeDispatchMemory,
+  resolveOrchestratorWorkspace,
+} from "./artifacts.js";
 
 // ---------------------------------------------------------------------------
 // Prompt loading
@@ -264,6 +274,9 @@ export async function triggerAudit(
 
   api.logger.info(`${TAG} worker completed, triggering audit (attempt ${dispatch.attempt})`);
 
+  // Update .claw/ manifest
+  try { updateManifest(dispatch.worktreePath, { status: "auditing", attempts: dispatch.attempt }); } catch {}
+
   // Fetch fresh issue details for audit context
   const issueDetails = await linearApi.getIssueDetails(dispatch.issueId).catch(() => null);
   const issue: IssueContext = {
@@ -371,6 +384,15 @@ export async function processVerdict(
     }
   }
 
+  // Log audit interaction to .claw/
+  try {
+    appendLog(dispatch.worktreePath, {
+      ts: new Date().toISOString(), phase: "audit", attempt: dispatch.attempt,
+      agent: "auditor", prompt: "(audit task)",
+      outputPreview: auditOutput.slice(0, 500), success: event.success,
+    });
+  } catch {}
+
   // Parse verdict
   const verdict = parseVerdict(auditOutput);
   if (!verdict) {
@@ -406,9 +428,13 @@ async function handleAuditPass(
   dispatch: ActiveDispatch,
   verdict: AuditVerdict,
 ): Promise<void> {
-  const { api, linearApi, notify, configPath } = hookCtx;
+  const { api, linearApi, notify, pluginConfig, configPath } = hookCtx;
   const TAG = `[${dispatch.issueIdentifier}]`;
 
+  // Save audit verdict to .claw/
+  try { saveAuditVerdict(dispatch.worktreePath, dispatch.attempt, verdict); } catch {}
+  try { updateManifest(dispatch.worktreePath, { status: "done", attempts: dispatch.attempt + 1 }); } catch {}
+
   // CAS transition: auditing → done
   try {
     await transitionDispatch(dispatch.issueIdentifier, "auditing", "done", undefined, configPath);
@@ -428,11 +454,26 @@ async function handleAuditPass(
     project: dispatch.project,
   }, configPath);
 
-  // Post approval comment
+  // Build summary from .claw/ artifacts and write to memory
+  let summary: string | null = null;
+  try {
+    summary = buildSummaryFromArtifacts(dispatch.worktreePath);
+    if (summary) {
+      writeSummary(dispatch.worktreePath, summary);
+      const wsDir = resolveOrchestratorWorkspace(api, pluginConfig);
+      writeDispatchMemory(dispatch.issueIdentifier, summary, wsDir);
+      api.logger.info(`${TAG} .claw/ summary and memory written`);
+    }
+  } catch (err) {
+    api.logger.warn(`${TAG} failed to write summary/memory: ${err}`);
+  }
+
+  // Post approval comment (with summary excerpt if available)
   const criteriaList = verdict.criteria.map((c) => `- ${c}`).join("\n");
+  const summaryExcerpt = summary ? `\n\n**Summary:**\n${summary.slice(0, 2000)}` : "";
   await linearApi.createComment(
     dispatch.issueId,
-    `## Audit Passed\n\n**Criteria verified:**\n${criteriaList}\n\n**Tests:** ${verdict.testResults || "N/A"}\n\n---\n*Attempt ${dispatch.attempt + 1} — audit passed.*`,
+    `## Audit Passed\n\n**Criteria verified:**\n${criteriaList}\n\n**Tests:** ${verdict.testResults || "N/A"}${summaryExcerpt}\n\n---\n*Attempt ${dispatch.attempt + 1} — audit passed. Artifacts: \`${dispatch.worktreePath}/.claw/\`*`,
   ).catch((err) => api.logger.error(`${TAG} failed to post audit pass comment: ${err}`));
 
   api.logger.info(`${TAG} audit PASSED — dispatch completed (attempt ${dispatch.attempt})`);
@@ -458,8 +499,13 @@ async function handleAuditFail(
   const maxAttempts = (pluginConfig?.maxReworkAttempts as number) ?? 2;
   const nextAttempt = dispatch.attempt + 1;
 
+  // Save audit verdict to .claw/ (both escalation and rework paths)
+  try { saveAuditVerdict(dispatch.worktreePath, dispatch.attempt, verdict); } catch {}
+
   if (nextAttempt > maxAttempts) {
     // Escalate — too many failures
+    try { updateManifest(dispatch.worktreePath, { status: "stuck", attempts: nextAttempt }); } catch {}
+
     try {
       await transitionDispatch(
         dispatch.issueIdentifier,
@@ -476,10 +522,20 @@ async function handleAuditFail(
       throw err;
     }
 
+    // Write summary + memory for stuck dispatches too
+    try {
+      const summary = buildSummaryFromArtifacts(dispatch.worktreePath);
+      if (summary) {
+        writeSummary(dispatch.worktreePath, summary);
+        const wsDir = resolveOrchestratorWorkspace(api, pluginConfig);
+        writeDispatchMemory(dispatch.issueIdentifier, summary, wsDir);
+      }
+    } catch {}
+
     const gapsList = verdict.gaps.map((g) => `- ${g}`).join("\n");
     await linearApi.createComment(
       dispatch.issueId,
-      `## Audit Failed — Escalating\n\n**Attempt ${nextAttempt} of ${maxAttempts + 1}**\n\n**Gaps:**\n${gapsList}\n\n**Tests:** ${verdict.testResults || "N/A"}\n\n---\n*Max rework attempts reached. Needs human review.*`,
+      `## Audit Failed — Escalating\n\n**Attempt ${nextAttempt} of ${maxAttempts + 1}**\n\n**Gaps:**\n${gapsList}\n\n**Tests:** ${verdict.testResults || "N/A"}\n\n---\n*Max rework attempts reached. Needs human review. Artifacts: \`${dispatch.worktreePath}/.claw/\`*`,
     ).catch((err) => api.logger.error(`${TAG} failed to post escalation comment: ${err}`));
 
     api.logger.warn(`${TAG} audit FAILED ${nextAttempt}x — escalating to human`);
@@ -608,6 +664,7 @@ export async function spawnWorker(
 
   api.logger.info(`${TAG} spawning worker agent session=${workerSessionId} (attempt ${dispatch.attempt})`);
 
+  const workerStartTime = Date.now();
   const result = await runAgent({
     api,
     agentId: (pluginConfig?.defaultAgentId as string) ?? "default",
@@ -616,6 +673,19 @@ export async function spawnWorker(
     timeoutMs: (pluginConfig?.codexTimeoutMs as number) ?? 10 * 60_000,
   });
 
+  // Save worker output to .claw/
+  const workerElapsed = Date.now() - workerStartTime;
+  try { saveWorkerOutput(dispatch.worktreePath, dispatch.attempt, result.output); } catch {}
+  try {
+    appendLog(dispatch.worktreePath, {
+      ts: new Date().toISOString(), phase: "worker", attempt: dispatch.attempt,
+      agent: (pluginConfig?.defaultAgentId as string) ?? "default",
+      prompt: workerPrompt.task.slice(0, 200),
+      outputPreview: result.output.slice(0, 500),
+      success: result.success, durationMs: workerElapsed,
+    });
+  } catch {}
+
   // runAgent returns inline — trigger audit directly.
   // Re-read dispatch state since it may have changed during worker run.
   const freshState = await readDispatchState(configPath);

package/src/webhook.ts

@@ -9,6 +9,7 @@ import { readDispatchState, getActiveDispatch, registerDispatch, updateDispatchS
 import { createDiscordNotifier, createNoopNotifier, type NotifyFn } from "./notify.js";
 import { assessTier } from "./tier-assess.js";
 import { createWorktree, prepareWorkspace } from "./codex-worktree.js";
+import { ensureClawDir, writeManifest } from "./artifacts.js";
 
 // ── Agent profiles (loaded from config, no hardcoded names) ───────
 interface AgentProfile {
@@ -187,12 +188,18 @@ export async function handleLinearWebhook(
       .map((c: any) => `  - **${c.user?.name ?? "Unknown"}**: ${c.body?.slice(0, 200)}`)
       .join("\n");
 
+    const notifIssueRef = enrichedIssue?.identifier ?? issue.id;
     const message = [
-      `IMPORTANT: You are responding to a Linear issue notification. Your ENTIRE text output will be automatically posted as a comment on the issue. Do NOT attempt to post to Linear yourself — no tools, no CLI, no API calls. Just write your response as plain text/markdown.`,
+      `You are an orchestrator responding to a Linear issue notification. Your text output will be automatically posted as a comment on the issue (do NOT post a comment yourself — the handler does it).`,
       ``,
-      `You were mentioned/assigned in a Linear issue. Respond naturally and helpfully.`,
+      `**Tool access:**`,
+      `- \`linearis\` CLI: READ ONLY. You can read issues (\`linearis issues read ${notifIssueRef}\`), 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.`,
       ``,
-      `## Issue: ${enrichedIssue?.identifier ?? issue.id} — ${enrichedIssue?.title ?? issue.title ?? "(untitled)"}`,
+      `**Your role:** Dispatcher. For work requests, use \`code_run\`. You do NOT update issue status — the audit system handles lifecycle.`,
+      ``,
+      `## Issue: ${notifIssueRef} — ${enrichedIssue?.title ?? issue.title ?? "(untitled)"}`,
       `**Status:** ${enrichedIssue?.state?.name ?? "Unknown"} | **Assignee:** ${enrichedIssue?.assignee?.name ?? "Unassigned"}`,
       ``,
       `**Description:**`,
@@ -200,7 +207,7 @@ export async function handleLinearWebhook(
       commentSummary ? `\n**Recent comments:**\n${commentSummary}` : "",
       comment?.body ? `\n**Triggering comment:**\n> ${comment.body}` : "",
       ``,
-      `Respond concisely. If there's a task, explain what you'll do and do it.`,
+      `Respond concisely. For work requests, dispatch via \`code_run\` and summarize the result.`,
     ].filter(Boolean).join("\n");
 
     // Dispatch agent with session lifecycle (non-blocking)
@@ -363,11 +370,19 @@ export async function handleLinearWebhook(
       .map((c: any) => `**${c.user?.name ?? c.actorName ?? "User"}**: ${(c.body ?? "").slice(0, 300)}`)
       .join("\n\n");
 
+    const issueRef = enrichedIssue?.identifier ?? issue.identifier ?? issue.id;
     const message = [
-      `You are an AI agent responding in a Linear issue session. Your text output will be posted as activities visible to the user.`,
-      `You have access to tools including \`code_run\` for coding tasks, \`spawn_agent\`/\`ask_agent\` for delegation, and standard tools (exec, read, edit, write, web_search, etc.). To manage Linear issues (update status, close, assign, comment, etc.) use the \`linearis\` CLI via exec — e.g. \`linearis issues update API-123 --status done\` to close an issue, \`linearis issues update API-123 --status "In Progress"\` to change status, \`linearis issues list\` to list issues. Run \`linearis usage\` for full command reference.`,
+      `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.`,
+      ``,
+      `**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.`,
       ``,
-      `## Issue: ${enrichedIssue?.identifier ?? issue.identifier ?? issue.id} — ${enrichedIssue?.title ?? issue.title ?? "(untitled)"}`,
+      `## Issue: ${issueRef} — ${enrichedIssue?.title ?? issue.title ?? "(untitled)"}`,
       `**Status:** ${enrichedIssue?.state?.name ?? "Unknown"} | **Assignee:** ${enrichedIssue?.assignee?.name ?? "Unassigned"}`,
       ``,
       `**Description:**`,
@@ -375,7 +390,7 @@ export async function handleLinearWebhook(
       commentContext ? `\n**Conversation:**\n${commentContext}` : "",
       userMessage ? `\n**Latest message:**\n> ${userMessage}` : "",
       ``,
-      `Respond to the user's request. If they ask you to write code or make changes, use the \`code_run\` tool. Be concise and action-oriented.`,
+      `Respond to the user's request. For work requests, dispatch via \`code_run\` and summarize the result. Be concise and action-oriented.`,
     ].filter(Boolean).join("\n");
 
     // Run agent directly (non-blocking)
@@ -543,11 +558,19 @@ export async function handleLinearWebhook(
         .map((c: any) => `**${c.user?.name ?? "User"}**: ${(c.body ?? "").slice(0, 300)}`)
         .join("\n\n");
 
+      const followUpIssueRef = enrichedIssue?.identifier ?? issue.identifier ?? issue.id;
       const message = [
-        `You are an AI agent responding in a Linear issue session. Your text output will be posted as activities visible to the user.`,
-        `You have access to tools including \`code_run\` for coding tasks, \`spawn_agent\`/\`ask_agent\` for delegation, and standard tools (exec, read, edit, write, web_search, etc.). To manage Linear issues (update status, close, assign, comment, etc.) use the \`linearis\` CLI via exec — e.g. \`linearis issues update API-123 --status done\` to close an issue, \`linearis issues update API-123 --status "In Progress"\` to change status, \`linearis issues list\` to list issues. Run \`linearis usage\` for full command reference.`,
+        `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.`,
+        ``,
+        `**Your role:** Dispatcher. For work requests, use \`code_run\`. You do NOT update issue status — the audit system handles lifecycle.`,
         ``,
-        `## Issue: ${enrichedIssue?.identifier ?? issue.identifier ?? issue.id} — ${enrichedIssue?.title ?? issue.title ?? "(untitled)"}`,
+        `## Issue: ${followUpIssueRef} — ${enrichedIssue?.title ?? issue.title ?? "(untitled)"}`,
         `**Status:** ${enrichedIssue?.state?.name ?? "Unknown"} | **Assignee:** ${enrichedIssue?.assignee?.name ?? "Unassigned"}`,
         ``,
         `**Description:**`,
@@ -555,7 +578,7 @@ 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. Be concise and action-oriented.`,
+        `Respond to the user's follow-up. For work requests, dispatch via \`code_run\`. Be concise and action-oriented.`,
       ].filter(Boolean).join("\n");
 
       setActiveSession({
@@ -683,6 +706,14 @@ export async function handleLinearWebhook(
 
     api.logger.info(`Comment mention: @${mentionedAgent} on ${issue.identifier ?? issue.id} by ${commentor}`);
 
+    // Guard: skip if an agent run is already active for this issue
+    // (prevents dual-dispatch when both Comment.create and AgentSessionEvent fire)
+    if (activeRuns.has(issue.id)) {
+      api.logger.info(`Comment mention: agent already running for ${issue.identifier ?? issue.id} — skipping`);
+      return true;
+    }
+    activeRuns.add(issue.id);
+
     // React with eyes to acknowledge the comment
     if (comment?.id) {
       linearApi.createReaction(comment.id, "eyes").catch(() => {});
@@ -712,9 +743,14 @@ export async function handleLinearWebhook(
     const assignee = enrichedIssue.assignee?.name ?? "Unassigned";
 
     const taskMessage = [
-      `IMPORTANT: You are responding to a Linear issue comment. Your ENTIRE text output will be automatically posted as a comment on the issue. Do NOT attempt to post to Linear yourself — no tools, no CLI, no API calls. Just write your response as plain text/markdown.`,
+      `You are an orchestrator responding to a Linear issue 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 ${enrichedIssue.identifier ?? "API-XXX"}\`), 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.`,
+      `- Standard tools: exec, read, edit, write, web_search, etc.`,
       ``,
-      `You were mentioned by name. Respond naturally and helpfully as a team member. Be concise, markdown-friendly. Do NOT use JSON or structured 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.`,
       ``,
       `**Issue:** ${enrichedIssue.identifier ?? enrichedIssue.id} — ${enrichedIssue.title ?? "(untitled)"}`,
       `**Status:** ${state} | **Priority:** ${priority} | **Assignee:** ${assignee} | **Labels:** ${labels}`,
@@ -725,7 +761,7 @@ export async function handleLinearWebhook(
       `**${commentor} wrote:**`,
       `> ${commentBody}`,
       ``,
-      `Respond to their message. Be concise and direct. If they're asking you to do work, explain what you'll do and do it.`,
+      `Respond to their message. Be concise and direct. For work requests, dispatch via \`code_run\` and summarize the result.`,
     ].filter(Boolean).join("\n");
 
     // Dispatch to agent with full session lifecycle (non-blocking)
@@ -814,6 +850,7 @@ export async function handleLinearWebhook(
         }
       } finally {
         clearActiveSession(issue.id);
+        activeRuns.delete(issue.id);
       }
     })();
 
@@ -1214,11 +1251,32 @@ async function handleDispatch(
     api.logger.warn(`@dispatch: could not create agent session: ${err}`);
   }
 
+  // 6b. Initialize .claw/ artifact directory
+  try {
+    ensureClawDir(worktree.path);
+    writeManifest(worktree.path, {
+      issueIdentifier: identifier,
+      issueTitle: enrichedIssue.title ?? "(untitled)",
+      issueId: issue.id,
+      tier: assessment.tier,
+      model: assessment.model,
+      dispatchedAt: new Date().toISOString(),
+      worktreePath: worktree.path,
+      branch: worktree.branch,
+      attempts: 0,
+      status: "dispatched",
+      plugin: "openclaw-linear",
+    });
+  } catch (err) {
+    api.logger.warn(`@dispatch: .claw/ init failed: ${err}`);
+  }
+
   // 7. Register dispatch in persistent state
   const now = new Date().toISOString();
   await registerDispatch(identifier, {
     issueId: issue.id,
     issueIdentifier: identifier,
+    issueTitle: enrichedIssue.title ?? "(untitled)",
     worktreePath: worktree.path,
     branch: worktree.branch,
     tier: assessment.tier,