@calltelemetry/openclaw-linear 0.7.0 → 0.8.0

package/src/infra/commands.test.ts

@@ -0,0 +1,276 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// ---------------------------------------------------------------------------
+// Mocks
+// ---------------------------------------------------------------------------
+
+vi.mock("../pipeline/dispatch-state.js", () => ({
+  readDispatchState: vi.fn(),
+  getActiveDispatch: vi.fn(),
+  listActiveDispatches: vi.fn(),
+  removeActiveDispatch: vi.fn(),
+  transitionDispatch: vi.fn(),
+  TransitionError: class TransitionError extends Error {
+    constructor(
+      public dispatchId: string,
+      public fromStatus: string,
+      public toStatus: string,
+      public actualStatus: string,
+    ) {
+      super(
+        `CAS transition failed for ${dispatchId}: ` +
+        `expected ${fromStatus} → ${toStatus}, but current status is ${actualStatus}`,
+      );
+      this.name = "TransitionError";
+    }
+  },
+  registerDispatch: vi.fn(),
+}));
+
+import { registerDispatchCommands } from "./commands.js";
+import {
+  readDispatchState,
+  getActiveDispatch,
+  listActiveDispatches,
+  removeActiveDispatch,
+  transitionDispatch,
+  registerDispatch,
+} from "../pipeline/dispatch-state.js";
+import type { DispatchState, ActiveDispatch } from "../pipeline/dispatch-state.js";
+
+const mockReadDispatchState = readDispatchState as ReturnType<typeof vi.fn>;
+const mockGetActiveDispatch = getActiveDispatch as ReturnType<typeof vi.fn>;
+const mockListActiveDispatches = listActiveDispatches as ReturnType<typeof vi.fn>;
+const mockRemoveActiveDispatch = removeActiveDispatch as ReturnType<typeof vi.fn>;
+const mockTransitionDispatch = transitionDispatch as ReturnType<typeof vi.fn>;
+const mockRegisterDispatch = registerDispatch as ReturnType<typeof vi.fn>;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function emptyState(): DispatchState {
+  return {
+    dispatches: { active: {}, completed: {} },
+    sessionMap: {},
+    processedEvents: [],
+  };
+}
+
+function makeActive(overrides?: Partial<ActiveDispatch>): ActiveDispatch {
+  return {
+    issueId: "uuid-1",
+    issueIdentifier: "CT-100",
+    worktreePath: "/tmp/wt/CT-100",
+    branch: "codex/CT-100",
+    tier: "junior",
+    model: "test-model",
+    status: "dispatched",
+    dispatchedAt: new Date("2026-02-18T10:00:00Z").toISOString(),
+    attempt: 0,
+    ...overrides,
+  };
+}
+
+/** Capture the registered command handler from the mock api */
+function captureHandler() {
+  let handler: (ctx: any) => Promise<any>;
+  const api = {
+    pluginConfig: undefined,
+    registerCommand: vi.fn((cmd: any) => {
+      handler = cmd.handler;
+    }),
+    logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+  };
+  registerDispatchCommands(api as any);
+  return { api, handler: handler! };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("registerDispatchCommands", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("registers the /dispatch command", () => {
+    const { api } = captureHandler();
+    expect(api.registerCommand).toHaveBeenCalledOnce();
+    const cmd = api.registerCommand.mock.calls[0][0];
+    expect(cmd.name).toBe("dispatch");
+    expect(cmd.acceptsArgs).toBe(true);
+  });
+
+  it("dispatch list shows active dispatches with age/tier/status", async () => {
+    const d = makeActive({
+      issueIdentifier: "CT-100",
+      tier: "senior",
+      status: "working",
+      attempt: 1,
+    });
+    const state = emptyState();
+    state.dispatches.active["CT-100"] = d;
+
+    mockReadDispatchState.mockResolvedValue(state);
+    mockListActiveDispatches.mockReturnValue([d]);
+
+    const { handler } = captureHandler();
+    const result = await handler({ args: "list" });
+
+    expect(result.text).toContain("Active Dispatches (1)");
+    expect(result.text).toContain("CT-100");
+    expect(result.text).toContain("working");
+    expect(result.text).toContain("senior");
+    expect(result.text).toContain("attempt 1");
+    // Should contain age in minutes (a number followed by 'm')
+    expect(result.text).toMatch(/\d+m/);
+  });
+
+  it("dispatch list with no active dispatches shows 'No active dispatches'", async () => {
+    mockReadDispatchState.mockResolvedValue(emptyState());
+    mockListActiveDispatches.mockReturnValue([]);
+
+    const { handler } = captureHandler();
+    const result = await handler({ args: "list" });
+
+    expect(result.text).toBe("No active dispatches.");
+  });
+
+  it("dispatch status shows details for active dispatch", async () => {
+    const d = makeActive({
+      issueIdentifier: "CT-100",
+      issueTitle: "Fix the login bug",
+      tier: "medior",
+      status: "auditing",
+      attempt: 2,
+    });
+    const state = emptyState();
+    state.dispatches.active["CT-100"] = d;
+
+    mockReadDispatchState.mockResolvedValue(state);
+    mockGetActiveDispatch.mockReturnValue(d);
+
+    const { handler } = captureHandler();
+    const result = await handler({ args: "status CT-100" });
+
+    expect(result.text).toContain("CT-100");
+    expect(result.text).toContain("Fix the login bug");
+    expect(result.text).toContain("auditing");
+    expect(result.text).toContain("medior");
+    expect(result.text).toContain("Attempt: 2");
+  });
+
+  it("dispatch status shows 'not found' for missing identifier", async () => {
+    const state = emptyState();
+    mockReadDispatchState.mockResolvedValue(state);
+    mockGetActiveDispatch.mockReturnValue(null);
+
+    const { handler } = captureHandler();
+    const result = await handler({ args: "status CT-999" });
+
+    expect(result.text).toContain("No dispatch found for CT-999");
+  });
+
+  it("dispatch retry on stuck dispatch transitions to dispatched", async () => {
+    const d = makeActive({
+      issueIdentifier: "CT-100",
+      status: "stuck",
+      stuckReason: "timed out",
+    });
+    const state = emptyState();
+    state.dispatches.active["CT-100"] = d;
+
+    mockReadDispatchState.mockResolvedValue(state);
+    mockGetActiveDispatch.mockReturnValue(d);
+    mockRemoveActiveDispatch.mockResolvedValue(undefined);
+    mockRegisterDispatch.mockResolvedValue(undefined);
+
+    const { handler } = captureHandler();
+    const result = await handler({ args: "retry CT-100" });
+
+    expect(mockRemoveActiveDispatch).toHaveBeenCalledWith("CT-100", undefined);
+    expect(mockRegisterDispatch).toHaveBeenCalledWith(
+      "CT-100",
+      expect.objectContaining({ status: "dispatched", stuckReason: undefined }),
+      undefined,
+    );
+    expect(result.text).toContain("CT-100");
+    expect(result.text).toContain("reset to dispatched");
+  });
+
+  it("dispatch retry on working dispatch returns error", async () => {
+    const d = makeActive({ issueIdentifier: "CT-100", status: "working" });
+    const state = emptyState();
+    state.dispatches.active["CT-100"] = d;
+
+    mockReadDispatchState.mockResolvedValue(state);
+    mockGetActiveDispatch.mockReturnValue(d);
+
+    const { handler } = captureHandler();
+    const result = await handler({ args: "retry CT-100" });
+
+    expect(result.text).toContain("Cannot retry CT-100");
+    expect(result.text).toContain("working");
+    expect(result.text).toContain("must be stuck");
+  });
+
+  it("dispatch escalate sets dispatch to stuck with reason", async () => {
+    const d = makeActive({ issueIdentifier: "CT-100", status: "working" });
+    const state = emptyState();
+    state.dispatches.active["CT-100"] = d;
+
+    mockReadDispatchState.mockResolvedValue(state);
+    mockGetActiveDispatch.mockReturnValue(d);
+    mockTransitionDispatch.mockResolvedValue({ ...d, status: "stuck", stuckReason: "agent looping" });
+
+    const { handler } = captureHandler();
+    const result = await handler({ args: "escalate CT-100 agent looping" });
+
+    expect(mockTransitionDispatch).toHaveBeenCalledWith(
+      "CT-100",
+      "working",
+      "stuck",
+      { stuckReason: "agent looping" },
+      undefined,
+    );
+    expect(result.text).toContain("CT-100");
+    expect(result.text).toContain("escalated to stuck");
+    expect(result.text).toContain("agent looping");
+  });
+
+  it("dispatch escalate without reason uses default", async () => {
+    const d = makeActive({ issueIdentifier: "CT-100", status: "dispatched" });
+    const state = emptyState();
+    state.dispatches.active["CT-100"] = d;
+
+    mockReadDispatchState.mockResolvedValue(state);
+    mockGetActiveDispatch.mockReturnValue(d);
+    mockTransitionDispatch.mockResolvedValue({ ...d, status: "stuck", stuckReason: "manual escalation" });
+
+    const { handler } = captureHandler();
+    const result = await handler({ args: "escalate CT-100" });
+
+    expect(mockTransitionDispatch).toHaveBeenCalledWith(
+      "CT-100",
+      "dispatched",
+      "stuck",
+      { stuckReason: "manual escalation" },
+      undefined,
+    );
+    expect(result.text).toContain("escalated to stuck");
+    expect(result.text).toContain("manual escalation");
+  });
+
+  it("help/unknown subcommand shows available commands", async () => {
+    const { handler } = captureHandler();
+    const result = await handler({ args: "help" });
+
+    expect(result.text).toContain("Dispatch Commands");
+    expect(result.text).toContain("/dispatch list");
+    expect(result.text).toContain("/dispatch status");
+    expect(result.text).toContain("/dispatch retry");
+    expect(result.text).toContain("/dispatch escalate");
+  });
+});

package/src/infra/commands.ts

@@ -0,0 +1,156 @@
+/**
+ * commands.ts — Zero-LLM slash commands for dispatch operations.
+ *
+ * Registered via api.registerCommand(). These commands bypass the AI agent
+ * entirely — they read/write dispatch state directly and return formatted text.
+ */
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import {
+  readDispatchState,
+  getActiveDispatch,
+  listActiveDispatches,
+  removeActiveDispatch,
+  transitionDispatch,
+  TransitionError,
+  registerDispatch,
+  type ActiveDispatch,
+} from "../pipeline/dispatch-state.js";
+
+export function registerDispatchCommands(api: OpenClawPluginApi): void {
+  const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
+  const statePath = pluginConfig?.dispatchStatePath as string | undefined;
+
+  api.registerCommand({
+    name: "dispatch",
+    description: "Manage dispatches: list, status <id>, retry <id>, escalate <id>",
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      const args = (ctx.args ?? "").trim().split(/\s+/);
+      const sub = args[0]?.toLowerCase();
+      const id = args[1];
+
+      if (!sub || sub === "list") {
+        return await handleList(statePath);
+      }
+      if (sub === "status" && id) {
+        return await handleStatus(id, statePath);
+      }
+      if (sub === "retry" && id) {
+        return await handleRetry(id, statePath, api);
+      }
+      if (sub === "escalate" && id) {
+        const reason = args.slice(2).join(" ") || "manual escalation";
+        return await handleEscalate(id, reason, statePath, api);
+      }
+
+      return {
+        text: [
+          "**Dispatch Commands:**",
+          "`/dispatch list` — show active dispatches",
+          "`/dispatch status <id>` — phase/attempt details",
+          "`/dispatch retry <id>` — reset stuck → dispatched",
+          "`/dispatch escalate <id> [reason]` — force to stuck",
+        ].join("\n"),
+      };
+    },
+  });
+}
+
+async function handleList(statePath?: string) {
+  const state = await readDispatchState(statePath);
+  const active = listActiveDispatches(state);
+
+  if (active.length === 0) {
+    return { text: "No active dispatches." };
+  }
+
+  const lines = active.map((d) => {
+    const age = Math.round((Date.now() - new Date(d.dispatchedAt).getTime()) / 60_000);
+    return `**${d.issueIdentifier}** — ${d.status} (${d.tier}, attempt ${d.attempt}, ${age}m)`;
+  });
+
+  return { text: `**Active Dispatches (${active.length})**\n${lines.join("\n")}` };
+}
+
+async function handleStatus(id: string, statePath?: string) {
+  const state = await readDispatchState(statePath);
+  const d = getActiveDispatch(state, id);
+
+  if (!d) {
+    const completed = state.dispatches.completed[id];
+    if (completed) {
+      return {
+        text: `**${id}** — completed (${completed.status}, ${completed.tier}, ${completed.totalAttempts ?? 0} attempts)`,
+      };
+    }
+    return { text: `No dispatch found for ${id}.` };
+  }
+
+  const age = Math.round((Date.now() - new Date(d.dispatchedAt).getTime()) / 60_000);
+  const lines = [
+    `**${d.issueIdentifier}** — ${d.issueTitle ?? d.issueIdentifier}`,
+    `Status: ${d.status} | Tier: ${d.tier} | Attempt: ${d.attempt}`,
+    `Age: ${age}m | Worktree: \`${d.worktreePath}\``,
+    d.stuckReason ? `Stuck reason: ${d.stuckReason}` : "",
+    d.agentSessionId ? `Session: ${d.agentSessionId}` : "",
+  ].filter(Boolean);
+
+  return { text: lines.join("\n") };
+}
+
+async function handleRetry(id: string, statePath: string | undefined, api: OpenClawPluginApi) {
+  const state = await readDispatchState(statePath);
+  const d = getActiveDispatch(state, id);
+
+  if (!d) {
+    return { text: `No active dispatch found for ${id}.` };
+  }
+
+  if (d.status !== "stuck") {
+    return { text: `Cannot retry ${id} — status is ${d.status} (must be stuck).` };
+  }
+
+  // Remove and re-register with reset status
+  await removeActiveDispatch(id, statePath);
+  const retryDispatch: ActiveDispatch = {
+    ...d,
+    status: "dispatched",
+    stuckReason: undefined,
+    workerSessionKey: undefined,
+    auditSessionKey: undefined,
+    dispatchedAt: new Date().toISOString(),
+  };
+  await registerDispatch(id, retryDispatch, statePath);
+
+  api.logger.info(`/dispatch retry: ${id} reset from stuck → dispatched`);
+  return { text: `**${id}** reset to dispatched. Will be picked up by next dispatch cycle.` };
+}
+
+async function handleEscalate(
+  id: string,
+  reason: string,
+  statePath: string | undefined,
+  api: OpenClawPluginApi,
+) {
+  const state = await readDispatchState(statePath);
+  const d = getActiveDispatch(state, id);
+
+  if (!d) {
+    return { text: `No active dispatch found for ${id}.` };
+  }
+
+  if (d.status === "stuck" || d.status === "done" || d.status === "failed") {
+    return { text: `Cannot escalate ${id} — already in terminal state: ${d.status}.` };
+  }
+
+  try {
+    await transitionDispatch(id, d.status, "stuck", { stuckReason: reason }, statePath);
+    api.logger.info(`/dispatch escalate: ${id} → stuck (${reason})`);
+    return { text: `**${id}** escalated to stuck: ${reason}` };
+  } catch (err) {
+    if (err instanceof TransitionError) {
+      return { text: `CAS conflict: ${err.message}` };
+    }
+    return { text: `Error: ${String(err)}` };
+  }
+}

package/src/infra/doctor.test.ts

@@ -382,6 +382,25 @@ describe("formatReport", () => {
     expect(output).toContain("1 passed");
     expect(output).toContain("1 warning");
   });
+
+  it("shows fix guidance for warnings and errors", () => {
+    const report = {
+      sections: [
+        {
+          name: "Auth",
+          checks: [
+            { label: "Token expired", severity: "warn" as const, fix: "Run: openclaw openclaw-linear auth" },
+            { label: "All good", severity: "pass" as const, fix: "Should not appear" },
+          ],
+        },
+      ],
+      summary: { passed: 1, warnings: 1, errors: 0 },
+    };
+
+    const output = formatReport(report);
+    expect(output).toContain("→ Run: openclaw openclaw-linear auth");
+    expect(output).not.toContain("Should not appear");
+  });
 });
 
 describe("formatReportJson", () => {

package/src/infra/doctor.ts

@@ -25,6 +25,8 @@ export interface CheckResult {
   severity: CheckSeverity;
   detail?: string;
   fixable?: boolean;
+  /** User-facing guidance on how to resolve the issue */
+  fix?: string;
 }
 
 export interface CheckSection {
@@ -66,12 +68,12 @@ function pass(label: string, detail?: string): CheckResult {
   return { label, severity: "pass", detail };
 }
 
-function warn(label: string, detail?: string, fixable = false): CheckResult {
-  return { label, severity: "warn", detail, fixable: fixable || undefined };
+function warn(label: string, detail?: string, opts?: { fixable?: boolean; fix?: string }): CheckResult {
+  return { label, severity: "warn", detail, fixable: opts?.fixable || undefined, fix: opts?.fix };
 }
 
-function fail(label: string, detail?: string): CheckResult {
-  return { label, severity: "fail", detail };
+function fail(label: string, detail?: string, fix?: string): CheckResult {
+  return { label, severity: "fail", detail, fix };
 }
 
 function resolveDispatchStatePath(pluginConfig?: Record<string, unknown>): string {
@@ -126,7 +128,7 @@ export async function checkAuth(pluginConfig?: Record<string, unknown>): Promise
   if (tokenInfo.accessToken) {
     checks.push(pass(`Access token found (source: ${tokenInfo.source})`));
   } else {
-    checks.push(fail("No access token found", "Run: openclaw openclaw-linear auth"));
+    checks.push(fail("No access token found", undefined, "Run: openclaw openclaw-linear auth"));
     // Can't check further without token
     return { checks, ctx };
   }
@@ -135,12 +137,12 @@ export async function checkAuth(pluginConfig?: Record<string, unknown>): Promise
   if (tokenInfo.expiresAt) {
     const remaining = tokenInfo.expiresAt - Date.now();
     if (remaining <= 0) {
-      checks.push(warn("Token expired", "Restart gateway to trigger auto-refresh"));
+      checks.push(warn("Token expired", undefined, { fix: "Run: openclaw openclaw-linear auth" }));
     } else {
       const hours = Math.floor(remaining / 3_600_000);
       const mins = Math.floor((remaining % 3_600_000) / 60_000);
       if (remaining < 3_600_000) {
-        checks.push(warn(`Token expires soon (${mins}m remaining)`));
+        checks.push(warn(`Token expires soon (${mins}m remaining)`, undefined, { fix: "Restart the gateway to trigger auto-refresh, or run: openclaw openclaw-linear auth" }));
       } else {
         checks.push(pass(`Token not expired (${hours}h ${mins}m remaining)`));
       }
@@ -190,8 +192,8 @@ export async function checkAuth(pluginConfig?: Record<string, unknown>): Promise
     } else {
       checks.push(warn(
         `auth-profiles.json permissions (${mode.toString(8)}, expected 600)`,
-        "Run: chmod 600 ~/.openclaw/auth-profiles.json",
-        true,
+        undefined,
+        { fixable: true, fix: "Run: chmod 600 ~/.openclaw/auth-profiles.json" },
       ));
     }
   } catch {
@@ -246,7 +248,7 @@ export function checkAgentConfig(pluginConfig?: Record<string, unknown>): CheckR
 
   const agentCount = Object.keys(profiles).length;
   if (agentCount === 0) {
-    checks.push(fail("agent-profiles.json has no agents"));
+    checks.push(fail("agent-profiles.json has no agents", undefined, "Add at least one agent to ~/.openclaw/agent-profiles.json"));
     return checks;
   }
   checks.push(pass(`agent-profiles.json loaded (${agentCount} agent${agentCount > 1 ? "s" : ""})`));
@@ -256,7 +258,7 @@ export function checkAgentConfig(pluginConfig?: Record<string, unknown>): CheckR
   if (defaultEntry) {
     checks.push(pass(`Default agent: ${defaultEntry[0]}`));
   } else {
-    checks.push(warn("No agent has isDefault: true"));
+    checks.push(warn("No agent has isDefault: true", undefined, { fix: "Add \"isDefault\": true to one agent in ~/.openclaw/agent-profiles.json" }));
   }
 
   // Required fields
@@ -270,7 +272,7 @@ export function checkAgentConfig(pluginConfig?: Record<string, unknown>): CheckR
   if (missing.length === 0) {
     checks.push(pass("All agents have required fields"));
   } else {
-    checks.push(fail(`Agent field issues: ${missing.join("; ")}`));
+    checks.push(fail(`Agent field issues: ${missing.join("; ")}`, undefined, "Each agent needs at least a \"label\" and \"mentionAliases\" array in agent-profiles.json"));
   }
 
   // defaultAgentId match
@@ -321,7 +323,7 @@ export function checkCodingTools(): CheckResult[] {
   if (hasConfig) {
     checks.push(pass(`coding-tools.json loaded (default: ${config.codingTool ?? "claude"})`));
   } else {
-    checks.push(warn("coding-tools.json not found or empty (using defaults)"));
+    checks.push(warn("coding-tools.json not found or empty (using defaults)", undefined, { fix: "Create coding-tools.json in the plugin root — see README for format" }));
   }
 
   // Validate default backend
@@ -355,7 +357,7 @@ export function checkCodingTools(): CheckResult[] {
         accessSync(bin, constants.X_OK);
         checks.push(pass(`${name}: installed (version check skipped)`));
       } catch {
-        checks.push(warn(`${name}: not found at ${bin}`));
+        checks.push(warn(`${name}: not found at ${bin}`, undefined, { fix: `Install ${name} or check that it's in your PATH` }));
       }
     }
   }
@@ -402,8 +404,8 @@ export async function checkFilesAndDirs(pluginConfig?: Record<string, unknown>,
         } else {
           checks.push(warn(
             `Stale lock file (${Math.round(lockAge / 1000)}s old)`,
-            "Use --fix to remove",
-            true,
+            undefined,
+            { fixable: true, fix: "Run: openclaw openclaw-linear doctor --fix to remove" },
           ));
         }
       } else {
@@ -440,10 +442,10 @@ export async function checkFilesAndDirs(pluginConfig?: Record<string, unknown>,
       });
       checks.push(pass("Base repo is valid git repo"));
     } catch {
-      checks.push(fail(`Base repo is not a git repo: ${baseRepo}`));
+      checks.push(fail(`Base repo is not a git repo: ${baseRepo}`, undefined, "Run: git init in the base repo directory, or set codexBaseRepo to a different path"));
     }
   } else {
-    checks.push(fail(`Base repo does not exist: ${baseRepo}`));
+    checks.push(fail(`Base repo does not exist: ${baseRepo}`, undefined, "Set codexBaseRepo in plugin config to your git repository path"));
   }
 
   // Prompts
@@ -482,7 +484,7 @@ export async function checkFilesAndDirs(pluginConfig?: Record<string, unknown>,
     if (errors.length === 0) {
       checks.push(pass(`Prompts valid (${sectionCount}/5 sections, ${varCount}/4 variables)`));
     } else {
-      checks.push(fail(`Prompt issues: ${errors.join("; ")}`));
+      checks.push(fail(`Prompt issues: ${errors.join("; ")}`, undefined, "Run: openclaw openclaw-linear prompts validate for details"));
     }
   } catch (err) {
     checks.push(fail(
@@ -526,7 +528,7 @@ export async function checkConnectivity(pluginConfig?: Record<string, unknown>,
         checks.push(fail(`Linear API: unreachable (${err instanceof Error ? err.message : String(err)})`));
       }
     } else {
-      checks.push(fail("Linear API: no token available"));
+      checks.push(fail("Linear API: no token available", undefined, "Run: openclaw openclaw-linear auth"));
     }
   }
 
@@ -602,7 +604,7 @@ export async function checkDispatchHealth(pluginConfig?: Record<string, unknown>
     checks.push(pass("No stale dispatches"));
   } else {
     const ids = stale.map((d) => d.issueIdentifier).join(", ");
-    checks.push(warn(`${stale.length} stale dispatch${stale.length > 1 ? "es" : ""}: ${ids}`));
+    checks.push(warn(`${stale.length} stale dispatch${stale.length > 1 ? "es" : ""}: ${ids}`, undefined, { fix: "Re-assign the issue to retry, or run: openclaw openclaw-linear doctor --fix to clean up" }));
   }
 
   // Orphaned worktrees
@@ -639,8 +641,8 @@ export async function checkDispatchHealth(pluginConfig?: Record<string, unknown>
     } else {
       checks.push(warn(
         `${old.length} completed dispatch${old.length > 1 ? "es" : ""} older than 7 days`,
-        "Use --fix to prune",
-        true,
+        undefined,
+        { fixable: true, fix: "Run: openclaw openclaw-linear doctor --fix to clean up old entries" },
       ));
     }
   }
@@ -737,6 +739,9 @@ export function formatReport(report: DoctorReport): string {
     lines.push(section.name);
     for (const check of section.checks) {
       lines.push(`  ${icon(check.severity)} ${check.label}`);
+      if (check.fix && check.severity !== "pass") {
+        lines.push(`    → ${check.fix}`);
+      }
     }
   }
 

package/src/infra/file-lock.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { acquireLock, releaseLock } from "./file-lock.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+
+const tmpDir = os.tmpdir();
+const testState = path.join(tmpDir, `file-lock-test-${process.pid}.json`);
+const lockFile = testState + ".lock";
+
+afterEach(async () => {
+  try { await fs.unlink(lockFile); } catch {}
+  try { await fs.unlink(testState); } catch {}
+});
+
+describe("acquireLock / releaseLock", () => {
+  it("creates and removes a lock file", async () => {
+    await acquireLock(testState);
+    const stat = await fs.stat(lockFile);
+    expect(stat.isFile()).toBe(true);
+
+    await releaseLock(testState);
+    await expect(fs.stat(lockFile)).rejects.toThrow();
+  });
+
+  it("blocks concurrent acquires until released", async () => {
+    await acquireLock(testState);
+
+    let secondAcquired = false;
+    const secondLock = acquireLock(testState).then(() => {
+      secondAcquired = true;
+    });
+
+    // Give the second acquire a moment to spin
+    await new Promise((r) => setTimeout(r, 120));
+    expect(secondAcquired).toBe(false);
+
+    await releaseLock(testState);
+    await secondLock;
+    expect(secondAcquired).toBe(true);
+
+    await releaseLock(testState);
+  });
+
+  it("releaseLock is safe to call when no lock exists", async () => {
+    await expect(releaseLock(testState)).resolves.toBeUndefined();
+  });
+
+  it("recovers from stale lock", async () => {
+    // Write a lock file with an old timestamp (> 30s ago)
+    await fs.writeFile(lockFile, String(Date.now() - 60_000), { flag: "w" });
+
+    // Should succeed by detecting stale lock
+    await acquireLock(testState);
+    const content = await fs.readFile(lockFile, "utf-8");
+    const lockTime = Number(content);
+    expect(Date.now() - lockTime).toBeLessThan(5000);
+
+    await releaseLock(testState);
+  });
+});