@calltelemetry/openclaw-linear 0.7.1 → 0.8.0

package/src/pipeline/e2e-planning.test.ts

@@ -0,0 +1,455 @@
+/**
+ * E2E planning pipeline tests.
+ *
+ * Exercises the real planning lifecycle: initiatePlanningSession → handlePlannerTurn
+ * → runPlanAudit → onApproved → DAG dispatch cascade.
+ *
+ * Mocked: runAgent, LinearAgentApi. Real: planning-state.ts, planner.ts,
+ * planner-tools.ts (auditPlan, buildPlanSnapshot), dag-dispatch.ts.
+ */
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+// ---------------------------------------------------------------------------
+// Mocks — external boundaries only
+// ---------------------------------------------------------------------------
+
+const { runAgentMock } = vi.hoisted(() => ({
+  runAgentMock: vi.fn().mockResolvedValue({ success: true, output: "Mock planner response" }),
+}));
+
+vi.mock("../agent/agent.js", () => ({
+  runAgent: runAgentMock,
+}));
+
+vi.mock("../api/linear-api.js", () => ({}));
+vi.mock("openclaw/plugin-sdk", () => ({}));
+vi.mock("../infra/observability.js", () => ({
+  emitDiagnostic: vi.fn(),
+}));
+
+// ---------------------------------------------------------------------------
+// Imports (AFTER mocks)
+// ---------------------------------------------------------------------------
+
+import { initiatePlanningSession, handlePlannerTurn, runPlanAudit } from "./planner.js";
+import { readPlanningState, type PlanningSession } from "./planning-state.js";
+import { writeProjectDispatch, readProjectDispatch, onProjectIssueCompleted, onProjectIssueStuck, type ProjectDispatchState } from "./dag-dispatch.js";
+import { createMockLinearApi, tmpStatePath } from "../__test__/helpers.js";
+import { makeProjectIssue } from "../__test__/fixtures/linear-responses.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function createCtx(configPath: string, overrides?: Record<string, unknown>) {
+  const linearApi = createMockLinearApi();
+  return {
+    ctx: {
+      api: {
+        logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },
+        pluginConfig: { planningStatePath: configPath, ...overrides },
+      } as any,
+      linearApi: linearApi as any,
+      pluginConfig: { planningStatePath: configPath, ...overrides },
+    },
+    linearApi,
+  };
+}
+
+function createSession(configPath: string, overrides?: Partial<PlanningSession>): PlanningSession {
+  return {
+    projectId: "proj-1",
+    projectName: "Test Project",
+    rootIssueId: "issue-1",
+    rootIdentifier: "PROJ-1",
+    teamId: "team-1",
+    status: "interviewing",
+    startedAt: new Date().toISOString(),
+    turnCount: 0,
+    ...overrides,
+  };
+}
+
+/** Build a set of project issues that will pass auditPlan (description ≥ 50 chars, estimate, priority). */
+function makePassingIssues() {
+  return [
+    makeProjectIssue("PROJ-2", {
+      title: "Implement search API",
+      description: "Build the search API endpoint with filtering and pagination support for the frontend.",
+      estimate: 3,
+      priority: 2,
+      labels: ["Epic"],
+    }),
+    makeProjectIssue("PROJ-3", {
+      title: "Build search results page",
+      description: "Create a search results page component that displays results from the search API endpoint.",
+      estimate: 2,
+      priority: 2,
+      parentIdentifier: "PROJ-2",
+    }),
+    makeProjectIssue("PROJ-4", {
+      title: "Add search autocomplete",
+      description: "Implement autocomplete suggestions in the search input using the search API typeahead endpoint.",
+      estimate: 1,
+      priority: 3,
+      parentIdentifier: "PROJ-2",
+    }),
+  ];
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("E2E planning pipeline", () => {
+  let configPath: string;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    configPath = tmpStatePath("claw-e2e-plan-");
+    runAgentMock.mockResolvedValue({ success: true, output: "Mock planner response" });
+  });
+
+  // =========================================================================
+  // Test 1: Full lifecycle — initiate → interview → approve
+  // =========================================================================
+  it("full lifecycle: initiate → interview turns → finalize → approved", async () => {
+    const { ctx, linearApi } = createCtx(configPath);
+
+    const rootIssue = { id: "issue-1", identifier: "PROJ-1", title: "Root Issue", team: { id: "team-1" } };
+
+    // Mock getProject and getTeamStates for initiation
+    linearApi.getProject.mockResolvedValue({
+      id: "proj-1",
+      name: "Test Project",
+      teams: { nodes: [{ id: "team-1", name: "Team" }] },
+    });
+    linearApi.getTeamStates.mockResolvedValue([
+      { id: "st-1", name: "Backlog", type: "backlog" },
+    ]);
+
+    // Step 1: Initiate planning session
+    await initiatePlanningSession(ctx, "proj-1", rootIssue);
+
+    // Verify welcome comment posted
+    expect(linearApi.createComment).toHaveBeenCalledWith(
+      "issue-1",
+      expect.stringContaining("planning mode"),
+    );
+
+    // Verify session registered
+    let state = await readPlanningState(configPath);
+    expect(state.sessions["proj-1"]).toBeDefined();
+    expect(state.sessions["proj-1"].status).toBe("interviewing");
+    expect(state.sessions["proj-1"].turnCount).toBe(0);
+
+    // Step 2: Interview turn 1
+    const session = createSession(configPath);
+
+    // Mock getProjectIssues and getIssueDetails for interview
+    linearApi.getProjectIssues.mockResolvedValue([]);
+    linearApi.getIssueDetails.mockResolvedValue({
+      id: "issue-1",
+      identifier: "PROJ-1",
+      title: "Root Issue",
+      comments: { nodes: [] },
+      project: { id: "proj-1" },
+      team: { id: "team-1" },
+    });
+
+    await handlePlannerTurn(ctx, session, {
+      issueId: "issue-1",
+      commentBody: "Build a search API and results page",
+      commentorName: "User",
+    });
+
+    // Verify runAgent called for interview
+    expect(runAgentMock).toHaveBeenCalledTimes(1);
+
+    // Verify agent response posted as comment
+    expect(linearApi.createComment).toHaveBeenCalledWith("issue-1", "Mock planner response");
+
+    // Verify turnCount incremented
+    state = await readPlanningState(configPath);
+    expect(state.sessions["proj-1"].turnCount).toBe(1);
+
+    // Step 3: Interview turn 2
+    vi.clearAllMocks();
+    runAgentMock.mockResolvedValue({ success: true, output: "Great, plan updated." });
+
+    const session2 = { ...session, turnCount: 1 };
+    await handlePlannerTurn(ctx, session2, {
+      issueId: "issue-1",
+      commentBody: "Add autocomplete too",
+      commentorName: "User",
+    });
+
+    expect(runAgentMock).toHaveBeenCalledTimes(1);
+    state = await readPlanningState(configPath);
+    expect(state.sessions["proj-1"].turnCount).toBe(2);
+
+    // Step 4: Finalize — with passing issues in the project
+    vi.clearAllMocks();
+    linearApi.getProjectIssues.mockResolvedValue(makePassingIssues());
+
+    const session3 = { ...session, turnCount: 2 };
+    const onApproved = vi.fn();
+
+    await handlePlannerTurn(ctx, session3, {
+      issueId: "issue-1",
+      commentBody: "finalize plan",
+      commentorName: "User",
+    }, { onApproved });
+
+    // Verify "Plan Approved" comment
+    expect(linearApi.createComment).toHaveBeenCalledWith(
+      "issue-1",
+      expect.stringContaining("Plan Approved"),
+    );
+
+    // Verify session ended as approved
+    state = await readPlanningState(configPath);
+    expect(state.sessions["proj-1"].status).toBe("approved");
+
+    // Verify onApproved callback fired
+    expect(onApproved).toHaveBeenCalledWith("proj-1");
+  });
+
+  // =========================================================================
+  // Test 2: Audit fail → re-plan → pass
+  // =========================================================================
+  it("audit fail → fix issues → re-finalize → approved", async () => {
+    const { ctx, linearApi } = createCtx(configPath);
+    const session = createSession(configPath);
+
+    // Register session so updatePlanningSession/endPlanningSession can find it
+    const { registerPlanningSession } = await import("./planning-state.js");
+    await registerPlanningSession("proj-1", session, configPath);
+
+    linearApi.getIssueDetails.mockResolvedValue({
+      id: "issue-1",
+      identifier: "PROJ-1",
+      title: "Root Issue",
+      comments: { nodes: [] },
+    });
+
+    // First finalize — with issues that fail audit (missing descriptions/estimates)
+    linearApi.getProjectIssues.mockResolvedValue([
+      makeProjectIssue("PROJ-2", {
+        title: "Bad issue",
+        description: "short", // <50 chars → audit fails
+      }),
+    ]);
+
+    await runPlanAudit(ctx, session);
+
+    // Verify "Plan Audit Failed" comment
+    expect(linearApi.createComment).toHaveBeenCalledWith(
+      "issue-1",
+      expect.stringContaining("Plan Audit Failed"),
+    );
+
+    // Session should still be interviewing (NOT approved)
+    let state = await readPlanningState(configPath);
+    expect(state.sessions["proj-1"].status).toBe("interviewing");
+
+    // Second finalize — with proper issues
+    vi.clearAllMocks();
+    linearApi.getProjectIssues.mockResolvedValue(makePassingIssues());
+
+    const onApproved = vi.fn();
+    await runPlanAudit(ctx, session, { onApproved });
+
+    // Now should be approved
+    expect(linearApi.createComment).toHaveBeenCalledWith(
+      "issue-1",
+      expect.stringContaining("Plan Approved"),
+    );
+
+    state = await readPlanningState(configPath);
+    expect(state.sessions["proj-1"].status).toBe("approved");
+    expect(onApproved).toHaveBeenCalledWith("proj-1");
+  });
+
+  // =========================================================================
+  // Test 3: Abandon
+  // =========================================================================
+  it("abandon: cancel planning ends session", async () => {
+    const { ctx, linearApi } = createCtx(configPath);
+    const session = createSession(configPath);
+
+    // Register session so endPlanningSession can find it
+    const { registerPlanningSession } = await import("./planning-state.js");
+    await registerPlanningSession("proj-1", session, configPath);
+
+    await handlePlannerTurn(ctx, session, {
+      issueId: "issue-1",
+      commentBody: "cancel planning",
+      commentorName: "User",
+    });
+
+    // Verify abandonment comment
+    expect(linearApi.createComment).toHaveBeenCalledWith(
+      "issue-1",
+      expect.stringContaining("Planning mode ended"),
+    );
+
+    // Session ended as abandoned
+    const state = await readPlanningState(configPath);
+    expect(state.sessions["proj-1"].status).toBe("abandoned");
+  });
+
+  // =========================================================================
+  // Test 4: onApproved fires
+  // =========================================================================
+  it("onApproved callback fires with projectId on approval", async () => {
+    const { ctx, linearApi } = createCtx(configPath);
+    const session = createSession(configPath);
+
+    // Register session so endPlanningSession can update it
+    const { registerPlanningSession } = await import("./planning-state.js");
+    await registerPlanningSession("proj-1", session, configPath);
+
+    linearApi.getProjectIssues.mockResolvedValue(makePassingIssues());
+
+    const onApproved = vi.fn();
+    await runPlanAudit(ctx, session, { onApproved });
+
+    expect(onApproved).toHaveBeenCalledTimes(1);
+    expect(onApproved).toHaveBeenCalledWith("proj-1");
+  });
+
+  // =========================================================================
+  // Test 5: DAG cascade — full chain
+  // =========================================================================
+  it("DAG cascade: complete issues in sequence, project completes", async () => {
+    const dagConfigPath = tmpStatePath("claw-e2e-dag-");
+    const notifyCalls: Array<[string, unknown]> = [];
+    const hookCtx = {
+      api: {
+        logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },
+      } as any,
+      linearApi: {} as any,
+      notify: vi.fn(async (kind: string, payload: unknown) => {
+        notifyCalls.push([kind, payload]);
+      }),
+      pluginConfig: {},
+      configPath: dagConfigPath,
+    };
+
+    // Set up 3-issue project: A → B → C
+    const projectDispatch: ProjectDispatchState = {
+      projectId: "proj-1",
+      projectName: "Test Project",
+      rootIdentifier: "PROJ-1",
+      status: "dispatching",
+      startedAt: new Date().toISOString(),
+      maxConcurrent: 3,
+      issues: {
+        "PROJ-A": {
+          identifier: "PROJ-A",
+          issueId: "id-a",
+          dependsOn: [],
+          unblocks: ["PROJ-B"],
+          dispatchStatus: "dispatched",
+        },
+        "PROJ-B": {
+          identifier: "PROJ-B",
+          issueId: "id-b",
+          dependsOn: ["PROJ-A"],
+          unblocks: ["PROJ-C"],
+          dispatchStatus: "pending",
+        },
+        "PROJ-C": {
+          identifier: "PROJ-C",
+          issueId: "id-c",
+          dependsOn: ["PROJ-B"],
+          unblocks: [],
+          dispatchStatus: "pending",
+        },
+      },
+    };
+    await writeProjectDispatch(projectDispatch, dagConfigPath);
+
+    // Complete A → B becomes ready
+    await onProjectIssueCompleted(hookCtx, "proj-1", "PROJ-A");
+
+    let state = await readProjectDispatch("proj-1", dagConfigPath);
+    expect(state!.issues["PROJ-A"].dispatchStatus).toBe("done");
+    expect(state!.issues["PROJ-B"].dispatchStatus).toBe("dispatched");
+    expect(state!.issues["PROJ-C"].dispatchStatus).toBe("pending");
+    expect(state!.status).toBe("dispatching");
+
+    // Complete B → C becomes ready
+    await onProjectIssueCompleted(hookCtx, "proj-1", "PROJ-B");
+
+    state = await readProjectDispatch("proj-1", dagConfigPath);
+    expect(state!.issues["PROJ-B"].dispatchStatus).toBe("done");
+    expect(state!.issues["PROJ-C"].dispatchStatus).toBe("dispatched");
+    expect(state!.status).toBe("dispatching");
+
+    // Complete C → project complete
+    await onProjectIssueCompleted(hookCtx, "proj-1", "PROJ-C");
+
+    state = await readProjectDispatch("proj-1", dagConfigPath);
+    expect(state!.issues["PROJ-C"].dispatchStatus).toBe("done");
+    expect(state!.status).toBe("completed");
+
+    // Verify notifications
+    const progressNotifications = notifyCalls.filter(([k]) => k === "project_progress");
+    const completeNotifications = notifyCalls.filter(([k]) => k === "project_complete");
+    expect(progressNotifications.length).toBe(2); // after A, after B
+    expect(completeNotifications.length).toBe(1); // after C
+  });
+
+  // =========================================================================
+  // Test 6: DAG stuck
+  // =========================================================================
+  it("DAG stuck: stuck issue blocks dependent, project stuck", async () => {
+    const dagConfigPath = tmpStatePath("claw-e2e-dag-stuck-");
+    const hookCtx = {
+      api: {
+        logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },
+      } as any,
+      linearApi: {} as any,
+      notify: vi.fn().mockResolvedValue(undefined),
+      pluginConfig: {},
+      configPath: dagConfigPath,
+    };
+
+    // 2-issue project: A → B
+    const projectDispatch: ProjectDispatchState = {
+      projectId: "proj-1",
+      projectName: "Test Project",
+      rootIdentifier: "PROJ-1",
+      status: "dispatching",
+      startedAt: new Date().toISOString(),
+      maxConcurrent: 3,
+      issues: {
+        "PROJ-A": {
+          identifier: "PROJ-A",
+          issueId: "id-a",
+          dependsOn: [],
+          unblocks: ["PROJ-B"],
+          dispatchStatus: "dispatched",
+        },
+        "PROJ-B": {
+          identifier: "PROJ-B",
+          issueId: "id-b",
+          dependsOn: ["PROJ-A"],
+          unblocks: [],
+          dispatchStatus: "pending",
+        },
+      },
+    };
+    await writeProjectDispatch(projectDispatch, dagConfigPath);
+
+    // A gets stuck
+    await onProjectIssueStuck(hookCtx, "proj-1", "PROJ-A");
+
+    const state = await readProjectDispatch("proj-1", dagConfigPath);
+    expect(state!.issues["PROJ-A"].dispatchStatus).toBe("stuck");
+    expect(state!.issues["PROJ-B"].dispatchStatus).toBe("pending"); // still blocked
+    expect(state!.status).toBe("stuck"); // project stuck — no progress possible
+  });
+});

package/src/pipeline/pipeline.test.ts

@@ -223,4 +223,73 @@ describe("loadPrompts", () => {
     expect(first).not.toBe(second);
     expect(first).toEqual(second);
   });
+
+  it("merges global overlay with defaults (section-level shallow merge)", () => {
+    // Use promptsPath in pluginConfig to load custom YAML from a temp file
+    const { writeFileSync, mkdtempSync } = require("node:fs");
+    const { join } = require("node:path");
+    const { tmpdir } = require("node:os");
+    const dir = mkdtempSync(join(tmpdir(), "claw-prompt-"));
+    const yamlPath = join(dir, "prompts.yaml");
+    writeFileSync(yamlPath, "worker:\n  system: custom worker system\n");
+
+    clearPromptCache();
+    const prompts = loadPrompts({ promptsPath: yamlPath });
+    // Worker system should be overridden
+    expect(prompts.worker.system).toBe("custom worker system");
+    // Worker task should still be default
+    expect(prompts.worker.task).toContain("{{identifier}}");
+    // Audit should be completely default
+    expect(prompts.audit.system).toContain("auditor");
+    clearPromptCache();
+  });
+
+  it("merges per-project overlay on top of global (three layers)", () => {
+    const { writeFileSync, mkdtempSync, mkdirSync } = require("node:fs");
+    const { join } = require("node:path");
+    const { tmpdir } = require("node:os");
+
+    // Layer 2: global override via promptsPath
+    const globalDir = mkdtempSync(join(tmpdir(), "claw-prompt-global-"));
+    const globalYaml = join(globalDir, "prompts.yaml");
+    writeFileSync(globalYaml, "worker:\n  system: global system\n");
+
+    // Layer 3: per-project override in worktree/.claw/prompts.yaml
+    const worktreeDir = mkdtempSync(join(tmpdir(), "claw-prompt-wt-"));
+    mkdirSync(join(worktreeDir, ".claw"), { recursive: true });
+    writeFileSync(join(worktreeDir, ".claw", "prompts.yaml"), "audit:\n  system: project auditor\n");
+
+    clearPromptCache();
+    const prompts = loadPrompts({ promptsPath: globalYaml }, worktreeDir);
+    // Layer 2: global override
+    expect(prompts.worker.system).toBe("global system");
+    // Layer 3: per-project override
+    expect(prompts.audit.system).toBe("project auditor");
+    // Layer 1: defaults retained where not overridden
+    expect(prompts.rework.addendum).toContain("PREVIOUS AUDIT FAILED");
+    clearPromptCache();
+  });
+
+  it("clearPromptCache clears both global and project caches", () => {
+    const { writeFileSync, mkdtempSync, mkdirSync } = require("node:fs");
+    const { join } = require("node:path");
+    const { tmpdir } = require("node:os");
+
+    // Per-project YAML only (no global — uses defaults for global)
+    const worktreeDir = mkdtempSync(join(tmpdir(), "claw-prompt-cache-"));
+    mkdirSync(join(worktreeDir, ".claw"), { recursive: true });
+    writeFileSync(join(worktreeDir, ".claw", "prompts.yaml"), "worker:\n  system: cached project\n");
+
+    clearPromptCache();
+    const first = loadPrompts(undefined, worktreeDir);
+    expect(first.worker.system).toBe("cached project");
+    // Same ref from cache
+    expect(loadPrompts(undefined, worktreeDir)).toBe(first);
+    // Clear both caches
+    clearPromptCache();
+    const second = loadPrompts(undefined, worktreeDir);
+    expect(second).not.toBe(first);
+    expect(second.worker.system).toBe("cached project");
+    clearPromptCache();
+  });
 });

package/src/pipeline/pipeline.ts

@@ -60,15 +60,15 @@ interface PromptTemplates {
 
 const DEFAULT_PROMPTS: PromptTemplates = {
   worker: {
-    system: "You are implementing a Linear issue. Post an implementation summary as a Linear comment when done. DO NOT mark the issue as Done.",
-    task: "Implement issue {{identifier}}: {{title}}\n\nIssue body:\n{{description}}\n\nWorktree: {{worktreePath}}",
+    system: "You are a coding worker implementing a Linear issue. Your ONLY job is to write code and return a text summary. Do NOT attempt to update, close, comment on, or modify the Linear issue. Do NOT mark the issue as Done.",
+    task: "Implement issue {{identifier}}: {{title}}\n\nIssue body:\n{{description}}\n\nWorktree: {{worktreePath}}\n\nImplement the solution, run tests, commit your work, and return a text summary.",
   },
   audit: {
     system: "You are an independent auditor. The Linear issue body is the SOURCE OF TRUTH. Worker comments are secondary evidence.",
     task: 'Audit issue {{identifier}}: {{title}}\n\nIssue body:\n{{description}}\n\nWorktree: {{worktreePath}}\n\nReturn JSON verdict: {"pass": true/false, "criteria": [...], "gaps": [...], "testResults": "..."}',
   },
   rework: {
-    addendum: "PREVIOUS AUDIT FAILED (attempt {{attempt}}). Gaps:\n{{gaps}}\n\nAddress these specific issues.",
+    addendum: "PREVIOUS AUDIT FAILED (attempt {{attempt}}). Gaps:\n{{gaps}}\n\nAddress these specific issues. Preserve correct code from prior attempts.",
   },
 };
 
@@ -88,12 +88,11 @@ function mergePromptLayers(base: PromptTemplates, overlay: Partial<PromptTemplat
 }
 
 /**
- * Load global prompts (layers 1+2: hardcoded defaults + global promptsPath override).
- * Cached after first load.
+ * Load and parse the raw prompts YAML file (global promptsPath or sidecar).
+ * Returns the parsed object, or null if no file found.
+ * Shared by both pipeline and planner prompt loaders.
  */
-function loadGlobalPrompts(pluginConfig?: Record<string, unknown>): PromptTemplates {
-  if (_cachedGlobalPrompts) return _cachedGlobalPrompts;
-
+export function loadRawPromptYaml(pluginConfig?: Record<string, unknown>): Record<string, any> | null {
   try {
     const customPath = pluginConfig?.promptsPath as string | undefined;
     let raw: string;
@@ -108,9 +107,23 @@ function loadGlobalPrompts(pluginConfig?: Record<string, unknown>): PromptTempla
       raw = readFileSync(join(pluginRoot, "prompts.yaml"), "utf-8");
     }
 
-    const parsed = parseYaml(raw) as Partial<PromptTemplates>;
-    _cachedGlobalPrompts = mergePromptLayers(DEFAULT_PROMPTS, parsed);
+    return parseYaml(raw) as Record<string, any>;
   } catch {
+    return null;
+  }
+}
+
+/**
+ * Load global prompts (layers 1+2: hardcoded defaults + global promptsPath override).
+ * Cached after first load.
+ */
+function loadGlobalPrompts(pluginConfig?: Record<string, unknown>): PromptTemplates {
+  if (_cachedGlobalPrompts) return _cachedGlobalPrompts;
+
+  const parsed = loadRawPromptYaml(pluginConfig);
+  if (parsed) {
+    _cachedGlobalPrompts = mergePromptLayers(DEFAULT_PROMPTS, parsed as Partial<PromptTemplates>);
+  } else {
     _cachedGlobalPrompts = DEFAULT_PROMPTS;
   }
 
@@ -188,7 +201,7 @@ export function buildWorkerTask(
     worktreePath,
     tier: "",
     attempt: String(opts?.attempt ?? 0),
-    gaps: opts?.gaps?.join("\n- ") ?? "",
+    gaps: opts?.gaps?.length ? "- " + opts.gaps.join("\n- ") : "",
   };
 
   let task = renderTemplate(prompts.worker.task, vars);
@@ -332,7 +345,12 @@ export async function triggerAudit(
   };
 
   // Build audit prompt from YAML templates
-  const auditPrompt = buildAuditTask(issue, dispatch.worktreePath, pluginConfig);
+  // For multi-repo dispatches, render worktreePath as a list of repo→path mappings
+  const effectiveAuditPath = dispatch.worktrees
+    ? dispatch.worktrees.map(w => `${w.repoName}: ${w.path}`).join("\n")
+    : dispatch.worktreePath;
+
+  const auditPrompt = buildAuditTask(issue, effectiveAuditPath, pluginConfig);
 
   // Set Linear label
   await linearApi.emitActivity(dispatch.agentSessionId ?? "", {
@@ -444,6 +462,11 @@ export async function processVerdict(
   const verdict = parseVerdict(auditOutput);
   if (!verdict) {
     api.logger.warn(`${TAG} could not parse audit verdict from output (${auditOutput.length} chars)`);
+    // Post comment so user knows what happened
+    await linearApi.createComment(
+      dispatch.issueId,
+      `## Audit Inconclusive\n\nThe auditor's response couldn't be parsed as a verdict. **Retrying automatically** — this usually resolves itself.\n\n**If it keeps happening:** \`openclaw openclaw-linear prompts validate\`\n\n**Status:** Retrying audit now. No action needed.`,
+    ).catch((err) => api.logger.error(`${TAG} failed to post inconclusive comment: ${err}`));
     // Treat unparseable verdict as failure
     await handleAuditFail(hookCtx, dispatch, {
       pass: false,
@@ -527,7 +550,7 @@ async function handleAuditPass(
   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"}${summaryExcerpt}\n\n---\n*Attempt ${dispatch.attempt + 1} — audit passed. Artifacts: \`${dispatch.worktreePath}/.claw/\`*`,
+    `## Done\n\nThis issue has been implemented and verified.\n\n**What was checked:**\n${criteriaList}\n\n**Test results:** ${verdict.testResults || "N/A"}${summaryExcerpt}\n\n---\n*Completed on attempt ${dispatch.attempt + 1}.*\n\n**Next steps:**\n- Review the code: \`cd ${dispatch.worktreePath}\`\n- View artifacts: \`ls ${dispatch.worktreePath}/.claw/\`\n- Create a PR from the worktree branch if one wasn't opened automatically`,
   ).catch((err) => api.logger.error(`${TAG} failed to post audit pass comment: ${err}`));
 
   api.logger.info(`${TAG} audit PASSED — dispatch completed (attempt ${dispatch.attempt})`);
@@ -603,7 +626,7 @@ async function handleAuditFail(
     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. Artifacts: \`${dispatch.worktreePath}/.claw/\`*`,
+      `## Needs Your Help\n\nAll ${nextAttempt} attempts failed. The agent couldn't resolve these issues on its own.\n\n**What went wrong:**\n${gapsList}\n\n**Test results:** ${verdict.testResults || "N/A"}\n\n---\n\n**What you can do:**\n1. **Clarify requirements** — update the issue body with more detail, then re-assign to try again\n2. **Fix it manually** — the agent's work is in the worktree: \`cd ${dispatch.worktreePath}\`\n3. **Force retry** — \`/dispatch retry ${dispatch.issueIdentifier}\`\n4. **View logs** — worker output: \`.claw/worker-*.md\`, audit verdicts: \`.claw/audit-*.json\``,
     ).catch((err) => api.logger.error(`${TAG} failed to post escalation comment: ${err}`));
 
     api.logger.warn(`${TAG} audit FAILED ${nextAttempt}x — escalating to human`);
@@ -647,7 +670,7 @@ async function handleAuditFail(
   const gapsList = verdict.gaps.map((g) => `- ${g}`).join("\n");
   await linearApi.createComment(
     dispatch.issueId,
-    `## Audit Failed — Rework\n\n**Attempt ${nextAttempt} of ${maxAttempts + 1}**\n\n**Gaps:**\n${gapsList}\n\n**Tests:** ${verdict.testResults || "N/A"}\n\n---\n*Reworking: addressing gaps above.*`,
+    `## Needs More Work\n\nThe audit found gaps. **Retrying now** — the worker gets the feedback below as context.\n\n**Attempt ${nextAttempt} of ${maxAttempts + 1}** — ${maxAttempts + 1 - nextAttempt > 0 ? `${maxAttempts + 1 - nextAttempt} more ${maxAttempts + 1 - nextAttempt === 1 ? "retry" : "retries"} if this fails too` : "this is the last attempt"}.\n\n**What needs fixing:**\n${gapsList}\n\n**Test results:** ${verdict.testResults || "N/A"}\n\n**Status:** Worker is restarting with the gaps above as context. No action needed unless all retries fail.`,
   ).catch((err) => api.logger.error(`${TAG} failed to post rework comment: ${err}`));
 
   api.logger.info(`${TAG} audit FAILED — rework attempt ${nextAttempt}/${maxAttempts + 1}`);
@@ -716,7 +739,12 @@ export async function spawnWorker(
   };
 
   // Build worker prompt from YAML templates
-  const workerPrompt = buildWorkerTask(issue, dispatch.worktreePath, {
+  // For multi-repo dispatches, render worktreePath as a list of repo→path mappings
+  const effectiveWorkerPath = dispatch.worktrees
+    ? dispatch.worktrees.map(w => `${w.repoName}: ${w.path}`).join("\n")
+    : dispatch.worktreePath;
+
+  const workerPrompt = buildWorkerTask(issue, effectiveWorkerPath, {
     attempt: dispatch.attempt,
     gaps: opts?.gaps,
     pluginConfig,
@@ -798,8 +826,9 @@ export async function spawnWorker(
 
     await linearApi.createComment(
       dispatch.issueId,
-      `## Watchdog Kill\n\nAgent killed by inactivity watchdog (no I/O for ${thresholdSec}s). ` +
-      `Automatic retry also failed.\n\n---\n*Needs human review. Artifacts: \`${dispatch.worktreePath}/.claw/\`*`,
+      `## Agent Timed Out\n\nThe agent stopped responding for over ${thresholdSec}s. It was automatically restarted, but the retry also timed out.\n\n` +
+      `**What you can do:**\n1. **Try again** — re-assign this issue or \`/dispatch retry ${dispatch.issueIdentifier}\`\n2. **Break it down** — if it keeps timing out, split into smaller issues\n3. **Increase timeout** — set \`inactivitySec\` higher in your agent profile\n\n` +
+      `**Logs:** \`${dispatch.worktreePath}/.claw/log.jsonl\` (look for \`"phase": "watchdog"\`)\n\n**Current status:** Stuck — waiting for you.`,
     ).catch(() => {});
 
     await hookCtx.notify("watchdog_kill", {