@calltelemetry/openclaw-linear 0.7.0 → 0.7.1

package/src/gateway/dispatch-methods.ts

@@ -0,0 +1,243 @@
+/**
+ * dispatch-methods.ts — Gateway RPC methods for dispatch operations.
+ *
+ * Registers methods on the OpenClaw gateway that allow clients (UI, CLI, other
+ * plugins) to inspect and manage the dispatch pipeline via the standard
+ * gateway request/respond protocol.
+ *
+ * Methods:
+ *   dispatch.list      — List active + completed dispatches (filterable)
+ *   dispatch.get       — Full details for a single dispatch
+ *   dispatch.retry     — Re-dispatch a stuck issue
+ *   dispatch.escalate  — Force a working/auditing dispatch into stuck
+ *   dispatch.cancel    — Remove an active dispatch entirely
+ *   dispatch.stats     — Aggregate counts by status and tier
+ */
+
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import {
+  readDispatchState,
+  getActiveDispatch,
+  listActiveDispatches,
+  transitionDispatch,
+  removeActiveDispatch,
+  registerDispatch,
+  TransitionError,
+  type ActiveDispatch,
+  type DispatchState,
+  type DispatchStatus,
+  type CompletedDispatch,
+} from "../pipeline/dispatch-state.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function ok(data: Record<string, unknown> = {}): Record<string, unknown> {
+  return { ok: true, ...data };
+}
+
+function fail(error: string): Record<string, unknown> {
+  return { ok: false, error };
+}
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+export function registerDispatchMethods(api: OpenClawPluginApi): void {
+  const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
+  const statePath = pluginConfig?.dispatchStatePath as string | undefined;
+
+  // ---- dispatch.list -------------------------------------------------------
+  api.registerGatewayMethod("dispatch.list", async ({ params, respond }) => {
+    try {
+      const statusFilter = params.status as DispatchStatus | undefined;
+      const tierFilter = params.tier as string | undefined;
+
+      const state = await readDispatchState(statePath);
+      let active = listActiveDispatches(state);
+
+      if (statusFilter) {
+        active = active.filter((d) => d.status === statusFilter);
+      }
+      if (tierFilter) {
+        active = active.filter((d) => d.tier === tierFilter);
+      }
+
+      const completed = Object.values(state.dispatches.completed);
+
+      respond(true, ok({ active, completed }));
+    } catch (err: any) {
+      respond(true, fail(err.message ?? String(err)));
+    }
+  });
+
+  // ---- dispatch.get --------------------------------------------------------
+  api.registerGatewayMethod("dispatch.get", async ({ params, respond }) => {
+    try {
+      const identifier = params.identifier as string | undefined;
+      if (!identifier) {
+        respond(true, fail("Missing required param: identifier"));
+        return;
+      }
+
+      const state = await readDispatchState(statePath);
+      const active = getActiveDispatch(state, identifier);
+      if (active) {
+        respond(true, ok({ dispatch: active, source: "active" }));
+        return;
+      }
+
+      const completed = state.dispatches.completed[identifier];
+      if (completed) {
+        respond(true, ok({ dispatch: completed, source: "completed" }));
+        return;
+      }
+
+      respond(true, fail(`No dispatch found for identifier: ${identifier}`));
+    } catch (err: any) {
+      respond(true, fail(err.message ?? String(err)));
+    }
+  });
+
+  // ---- dispatch.retry ------------------------------------------------------
+  // Stuck dispatches are terminal in VALID_TRANSITIONS, so we cannot use
+  // transitionDispatch. Instead, remove the active dispatch and re-register
+  // it with status reset to "dispatched" and an incremented attempt counter.
+  api.registerGatewayMethod("dispatch.retry", async ({ params, respond }) => {
+    try {
+      const identifier = params.identifier as string | undefined;
+      if (!identifier) {
+        respond(true, fail("Missing required param: identifier"));
+        return;
+      }
+
+      const state = await readDispatchState(statePath);
+      const dispatch = getActiveDispatch(state, identifier);
+      if (!dispatch) {
+        respond(true, fail(`No active dispatch for identifier: ${identifier}`));
+        return;
+      }
+
+      if (dispatch.status !== "stuck") {
+        respond(true, fail(`Cannot retry dispatch in status "${dispatch.status}" — only "stuck" dispatches can be retried`));
+        return;
+      }
+
+      // Capture current state, remove, then re-register with reset status
+      const retryDispatch: ActiveDispatch = {
+        ...dispatch,
+        status: "dispatched",
+        attempt: dispatch.attempt + 1,
+        stuckReason: undefined,
+        workerSessionKey: undefined,
+        auditSessionKey: undefined,
+      };
+
+      await removeActiveDispatch(identifier, statePath);
+      await registerDispatch(identifier, retryDispatch, statePath);
+
+      api.logger.info(`dispatch.retry: ${identifier} re-dispatched (attempt ${retryDispatch.attempt})`);
+      respond(true, ok({ dispatch: retryDispatch }));
+    } catch (err: any) {
+      respond(true, fail(err.message ?? String(err)));
+    }
+  });
+
+  // ---- dispatch.escalate ---------------------------------------------------
+  api.registerGatewayMethod("dispatch.escalate", async ({ params, respond }) => {
+    try {
+      const identifier = params.identifier as string | undefined;
+      if (!identifier) {
+        respond(true, fail("Missing required param: identifier"));
+        return;
+      }
+
+      const reason = (params.reason as string) || "Manually escalated via gateway";
+
+      const state = await readDispatchState(statePath);
+      const dispatch = getActiveDispatch(state, identifier);
+      if (!dispatch) {
+        respond(true, fail(`No active dispatch for identifier: ${identifier}`));
+        return;
+      }
+
+      if (dispatch.status !== "working" && dispatch.status !== "auditing") {
+        respond(true, fail(`Cannot escalate dispatch in status "${dispatch.status}" — only "working" or "auditing" dispatches can be escalated`));
+        return;
+      }
+
+      const updated = await transitionDispatch(
+        identifier,
+        dispatch.status,
+        "stuck",
+        { stuckReason: reason },
+        statePath,
+      );
+
+      api.logger.info(`dispatch.escalate: ${identifier} escalated to stuck (was ${dispatch.status}, reason: ${reason})`);
+      respond(true, ok({ dispatch: updated }));
+    } catch (err: any) {
+      if (err instanceof TransitionError) {
+        respond(true, fail(`Transition conflict: ${err.message}`));
+        return;
+      }
+      respond(true, fail(err.message ?? String(err)));
+    }
+  });
+
+  // ---- dispatch.cancel -----------------------------------------------------
+  api.registerGatewayMethod("dispatch.cancel", async ({ params, respond }) => {
+    try {
+      const identifier = params.identifier as string | undefined;
+      if (!identifier) {
+        respond(true, fail("Missing required param: identifier"));
+        return;
+      }
+
+      const state = await readDispatchState(statePath);
+      const dispatch = getActiveDispatch(state, identifier);
+      if (!dispatch) {
+        respond(true, fail(`No active dispatch for identifier: ${identifier}`));
+        return;
+      }
+
+      await removeActiveDispatch(identifier, statePath);
+
+      api.logger.info(`dispatch.cancel: ${identifier} removed (was ${dispatch.status})`);
+      respond(true, ok({ cancelled: identifier, previousStatus: dispatch.status }));
+    } catch (err: any) {
+      respond(true, fail(err.message ?? String(err)));
+    }
+  });
+
+  // ---- dispatch.stats ------------------------------------------------------
+  api.registerGatewayMethod("dispatch.stats", async ({ params, respond }) => {
+    try {
+      const state = await readDispatchState(statePath);
+      const active = listActiveDispatches(state);
+
+      const byStatus: Record<string, number> = {};
+      const byTier: Record<string, number> = {};
+
+      for (const d of active) {
+        byStatus[d.status] = (byStatus[d.status] ?? 0) + 1;
+        byTier[d.tier] = (byTier[d.tier] ?? 0) + 1;
+      }
+
+      const completedCount = Object.keys(state.dispatches.completed).length;
+
+      respond(true, ok({
+        activeCount: active.length,
+        completedCount,
+        byStatus,
+        byTier,
+      }));
+    } catch (err: any) {
+      respond(true, fail(err.message ?? String(err)));
+    }
+  });
+
+  api.logger.info("Dispatch gateway methods registered (dispatch.list, dispatch.get, dispatch.retry, dispatch.escalate, dispatch.cancel, dispatch.stats)");
+}

package/src/infra/cli.ts

@@ -5,8 +5,7 @@ import type { Command } from "commander";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { createInterface } from "node:readline";
 import { exec } from "node:child_process";
-import { readFileSync, writeFileSync } from "node:fs";
-import { readFileSync as readFileSyncFs, existsSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { resolveLinearToken, AUTH_PROFILES_PATH, LINEAR_GRAPHQL_URL } from "../api/linear-api.js";
@@ -258,33 +257,21 @@ export function registerCli(program: Command, api: OpenClawPluginApi): void {
 
   prompts
     .command("show")
-    .description("Print current prompts.yaml content")
-    .action(async () => {
+    .description("Print resolved prompts (global or per-project)")
+    .option("--worktree <path>", "Show merged prompts for a specific worktree")
+    .action(async (opts: { worktree?: string }) => {
       const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
-      const customPath = pluginConfig?.promptsPath as string | undefined;
+      clearPromptCache();
+      const loaded = loadPrompts(pluginConfig, opts.worktree);
 
-      let resolvedPath: string;
-      if (customPath) {
-        resolvedPath = customPath.startsWith("~")
-          ? customPath.replace("~", process.env.HOME ?? "")
-          : customPath;
+      if (opts.worktree) {
+        console.log(`\nResolved prompts for worktree: ${opts.worktree}\n`);
       } else {
-        const pluginRoot = join(dirname(fileURLToPath(import.meta.url)), "../..");
-        resolvedPath = join(pluginRoot, "prompts.yaml");
+        console.log(`\nGlobal resolved prompts\n`);
       }
 
-      console.log(`\nPrompts file: ${resolvedPath}\n`);
-
-      try {
-        const content = readFileSyncFs(resolvedPath, "utf-8");
-        console.log(content);
-      } catch {
-        console.log("(file not found — using built-in defaults)\n");
-        // Show the loaded defaults
-        clearPromptCache();
-        const loaded = loadPrompts(pluginConfig);
-        console.log(JSON.stringify(loaded, null, 2));
-      }
+      console.log(JSON.stringify(loaded, null, 2));
+      console.log();
     });
 
   prompts
@@ -310,13 +297,14 @@ export function registerCli(program: Command, api: OpenClawPluginApi): void {
 
   prompts
     .command("validate")
-    .description("Validate prompts.yaml structure")
-    .action(async () => {
+    .description("Validate prompts.yaml structure (global or per-project)")
+    .option("--worktree <path>", "Validate merged prompts for a specific worktree")
+    .action(async (opts: { worktree?: string }) => {
       const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
       clearPromptCache();
 
       try {
-        const loaded = loadPrompts(pluginConfig);
+        const loaded = loadPrompts(pluginConfig, opts.worktree);
         const errors: string[] = [];
 
         if (!loaded.worker?.system) errors.push("Missing worker.system");
@@ -336,13 +324,14 @@ export function registerCli(program: Command, api: OpenClawPluginApi): void {
           }
         }
 
+        const label = opts.worktree ? `worktree ${opts.worktree}` : "global";
         if (errors.length > 0) {
-          console.log("\nValidation FAILED:\n");
+          console.log(`\nValidation FAILED (${label}):\n`);
           for (const e of errors) console.log(`  - ${e}`);
           console.log();
           process.exitCode = 1;
         } else {
-          console.log("\nValidation PASSED — all sections and template variables present.\n");
+          console.log(`\nValidation PASSED (${label}) — all sections and template variables present.\n`);
         }
       } catch (err) {
         console.error(`\nFailed to load prompts: ${err}\n`);
@@ -350,6 +339,85 @@ export function registerCli(program: Command, api: OpenClawPluginApi): void {
       }
     });
 
+  prompts
+    .command("init")
+    .description("Scaffold per-project .claw/prompts.yaml in a worktree")
+    .argument("<worktree-path>", "Path to the worktree")
+    .action(async (worktreePath: string) => {
+      const { mkdirSync, writeFileSync: writeFS } = await import("node:fs");
+      const clawDir = join(worktreePath, ".claw");
+      const promptsFile = join(clawDir, "prompts.yaml");
+
+      if (existsSync(promptsFile)) {
+        console.log(`\n  ${promptsFile} already exists.\n`);
+        return;
+      }
+
+      mkdirSync(clawDir, { recursive: true });
+      writeFS(promptsFile, [
+        "# Per-project prompt overrides for Linear Agent pipeline.",
+        "# Only include sections/fields you want to override.",
+        "# Unspecified fields inherit from the global prompts.yaml.",
+        "#",
+        "# Available sections: worker, audit, rework",
+        "# Template variables: {{identifier}}, {{title}}, {{description}}, {{worktreePath}}, {{tier}}, {{attempt}}, {{gaps}}",
+        "",
+        "# worker:",
+        "#   system: \"Custom system prompt for workers in this project.\"",
+        "#   task: \"Implement issue {{identifier}}: {{title}}\\n\\n{{description}}\\n\\nWorktree: {{worktreePath}}\"",
+        "",
+        "# audit:",
+        "#   system: \"Custom audit system prompt for this project.\"",
+        "",
+        "# rework:",
+        "#   addendum: \"Custom rework addendum for this project.\"",
+        "",
+      ].join("\n"), "utf-8");
+
+      console.log(`\n  Created: ${promptsFile}`);
+      console.log(`  Edit this file to customize prompts for this worktree.\n`);
+    });
+
+  prompts
+    .command("diff")
+    .description("Show differences between global and per-project prompts")
+    .argument("<worktree-path>", "Path to the worktree")
+    .action(async (worktreePath: string) => {
+      const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
+      clearPromptCache();
+
+      const global = loadPrompts(pluginConfig);
+      const merged = loadPrompts(pluginConfig, worktreePath);
+
+      const projectFile = join(worktreePath, ".claw", "prompts.yaml");
+      if (!existsSync(projectFile)) {
+        console.log(`\n  No per-project prompts at ${projectFile}`);
+        console.log(`  Run 'openclaw openclaw-linear prompts init ${worktreePath}' to create one.\n`);
+        return;
+      }
+
+      console.log(`\nPrompt diff: global vs ${worktreePath}\n`);
+
+      let hasDiffs = false;
+      for (const section of ["worker", "audit", "rework"] as const) {
+        const globalSection = global[section] as Record<string, string>;
+        const mergedSection = merged[section] as Record<string, string>;
+        for (const [key, val] of Object.entries(mergedSection)) {
+          if (globalSection[key] !== val) {
+            hasDiffs = true;
+            console.log(`  ${section}.${key}:`);
+            console.log(`    global:  ${globalSection[key]?.slice(0, 100)}...`);
+            console.log(`    project: ${val.slice(0, 100)}...`);
+            console.log();
+          }
+        }
+      }
+
+      if (!hasDiffs) {
+        console.log("  No differences — per-project prompts match global.\n");
+      }
+    });
+
   // --- openclaw openclaw-linear notify ---
   const notifyCmd = linear
     .command("notify")

package/src/infra/codex-worktree.ts

@@ -3,6 +3,7 @@ import { existsSync, statSync, readdirSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
 import { ensureGitignore } from "../pipeline/artifacts.js";
+import type { RepoConfig } from "./multi-repo.js";
 
 const DEFAULT_BASE_REPO = "/home/claw/ai-workspace";
 const DEFAULT_WORKTREE_BASE_DIR = path.join(homedir(), ".openclaw", "worktrees");
@@ -117,6 +118,88 @@ export function createWorktree(
   return { path: worktreePath, branch, resumed: false };
 }
 
+export interface MultiWorktreeResult {
+  /** Parent directory containing all repo worktrees for this issue. */
+  parentPath: string;
+  worktrees: Array<{
+    repoName: string;
+    path: string;
+    branch: string;
+    resumed: boolean;
+  }>;
+}
+
+/**
+ * Create worktrees for multiple repos.
+ *
+ * Layout: {baseDir}/{issueIdentifier}/{repoName}/
+ * Branch: codex/{issueIdentifier} (same branch name in each repo)
+ *
+ * Each individual repo worktree follows the same idempotent/resume logic
+ * as createWorktree: if the worktree or branch already exists, it resumes.
+ */
+export function createMultiWorktree(
+  identifier: string,
+  repos: RepoConfig[],
+  opts?: { baseDir?: string },
+): MultiWorktreeResult {
+  const baseDir = resolveBaseDir(opts?.baseDir);
+  const parentPath = path.join(baseDir, identifier);
+
+  // Ensure parent directory exists
+  if (!existsSync(parentPath)) {
+    mkdirSync(parentPath, { recursive: true });
+  }
+
+  const branch = `codex/${identifier}`;
+  const worktrees: MultiWorktreeResult["worktrees"] = [];
+
+  for (const repo of repos) {
+    if (!existsSync(repo.path)) {
+      throw new Error(`Repo not found: ${repo.name} at ${repo.path}`);
+    }
+
+    const worktreePath = path.join(parentPath, repo.name);
+
+    // Fetch latest from origin (best effort)
+    try {
+      git(["fetch", "origin"], repo.path);
+    } catch {
+      // Offline or no remote — continue with local state
+    }
+
+    // Idempotent: if worktree already exists, resume it
+    if (existsSync(worktreePath)) {
+      try {
+        git(["rev-parse", "--git-dir"], worktreePath);
+        ensureGitignore(worktreePath);
+        worktrees.push({ repoName: repo.name, path: worktreePath, branch, resumed: true });
+        continue;
+      } catch {
+        // Directory exists but isn't a valid worktree — remove and recreate
+        try {
+          git(["worktree", "remove", "--force", worktreePath], repo.path);
+        } catch { /* best effort */ }
+      }
+    }
+
+    // Check if branch already exists (resume scenario)
+    const exists = branchExistsInRepo(branch, repo.path);
+
+    if (exists) {
+      git(["worktree", "add", worktreePath, branch], repo.path);
+      ensureGitignore(worktreePath);
+      worktrees.push({ repoName: repo.name, path: worktreePath, branch, resumed: true });
+    } else {
+      git(["worktree", "add", "-b", branch, worktreePath], repo.path);
+      ensureGitignore(worktreePath);
+      worktrees.push({ repoName: repo.name, path: worktreePath, branch, resumed: false });
+    }
+  }
+
+  return { parentPath, worktrees };
+}
+
 /**
  * Check if a branch exists in the repo.
  */

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)}` };
+  }
+}