@calltelemetry/openclaw-linear 0.4.0 → 0.5.0

package/src/codex-worktree.ts

@@ -1,11 +1,16 @@
 import { execFileSync } from "node:child_process";
-import { existsSync, statSync, readdirSync } from "node:fs";
+import { existsSync, statSync, readdirSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
 
 const DEFAULT_BASE_REPO = "/home/claw/ai-workspace";
+const DEFAULT_WORKTREE_BASE_DIR = path.join(homedir(), ".openclaw", "worktrees");
 
 export interface WorktreeInfo {
   path: string;
   branch: string;
+  /** True if the worktree already existed and was resumed, not freshly created. */
+  resumed: boolean;
 }
 
 export interface WorktreeStatus {
@@ -14,6 +19,19 @@ export interface WorktreeStatus {
   lastCommit: string | null;
 }
 
+export interface WorktreeOptions {
+  /** Base git repo to create worktrees from. Default: /home/claw/ai-workspace */
+  baseRepo?: string;
+  /** Directory under which worktrees are created. Default: ~/.openclaw/worktrees */
+  baseDir?: string;
+}
+
+function resolveBaseDir(baseDir?: string): string {
+  if (!baseDir) return DEFAULT_WORKTREE_BASE_DIR;
+  if (baseDir.startsWith("~/")) return baseDir.replace("~", homedir());
+  return baseDir;
+}
+
 function git(args: string[], cwd: string): string {
   return execFileSync("git", args, {
     cwd,
@@ -22,42 +40,89 @@ function git(args: string[], cwd: string): string {
   }).trim();
 }
 
+function gitLong(args: string[], cwd: string, timeout = 120_000): string {
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    timeout,
+  }).trim();
+}
+
 /**
- * Create a git worktree for isolated Codex work.
+ * Create a git worktree for isolated work on a Linear issue.
+ *
+ * Path: {baseDir}/{issueIdentifier}/ — deterministic, persistent.
  * Branch: codex/{issueIdentifier}
- * Path: /tmp/codex-{issueIdentifier}-{timestamp}
+ *
+ * Idempotent: if the worktree already exists, returns it without recreating.
+ * If the branch exists but the worktree is gone, recreates the worktree from
+ * the existing branch (resume scenario).
  */
 export function createWorktree(
   issueIdentifier: string,
-  baseRepo?: string,
+  opts?: WorktreeOptions,
 ): WorktreeInfo {
-  const repo = baseRepo ?? DEFAULT_BASE_REPO;
+  const repo = opts?.baseRepo ?? DEFAULT_BASE_REPO;
+  const baseDir = resolveBaseDir(opts?.baseDir);
+
   if (!existsSync(repo)) {
     throw new Error(`Base repo not found: ${repo}`);
   }
 
+  // Ensure base directory exists
+  if (!existsSync(baseDir)) {
+    mkdirSync(baseDir, { recursive: true });
+  }
+
   const branch = `codex/${issueIdentifier}`;
-  const ts = Date.now();
-  const worktreePath = `/tmp/codex-${issueIdentifier}-${ts}`;
+  const worktreePath = path.join(baseDir, issueIdentifier);
 
-  // Ensure we're on a clean base — fetch latest
+  // Fetch latest from origin (best effort) — do this early so both
+  // resume and fresh paths have up-to-date refs.
   try {
     git(["fetch", "origin"], repo);
   } catch {
     // Offline or no remote — continue with local state
   }
 
-  // Delete stale branch if it exists (from a previous run)
-  try {
-    git(["branch", "-D", branch], repo);
-  } catch {
-    // Branch doesn't exist — fine
+  // Idempotent: if worktree already exists, return it
+  if (existsSync(worktreePath)) {
+    try {
+      // Verify it's a valid git worktree
+      git(["rev-parse", "--git-dir"], worktreePath);
+      return { path: worktreePath, branch, resumed: true };
+    } catch {
+      // Directory exists but isn't a valid worktree — remove and recreate
+      try {
+        git(["worktree", "remove", "--force", worktreePath], repo);
+      } catch { /* best effort */ }
+    }
   }
 
-  // Create worktree with new branch off HEAD
+  // Check if branch already exists (resume scenario)
+  const branchExists = branchExistsInRepo(branch, repo);
+
+  if (branchExists) {
+    // Recreate worktree from existing branch — preserves previous work
+    git(["worktree", "add", worktreePath, branch], repo);
+    return { path: worktreePath, branch, resumed: true };
+  }
+
+  // Fresh start: new branch off HEAD
   git(["worktree", "add", "-b", branch, worktreePath], repo);
+  return { path: worktreePath, branch, resumed: false };
+}
 
-  return { path: worktreePath, branch };
+/**
+ * Check if a branch exists in the repo.
+ */
+function branchExistsInRepo(branch: string, repo: string): boolean {
+  try {
+    const result = git(["branch", "--list", branch], repo);
+    return result.trim().length > 0;
+  } catch {
+    return false;
+  }
 }
 
 /**
@@ -117,19 +182,13 @@ export function removeWorktree(
   }
 
   if (opts?.deleteBranch) {
-    // Extract branch name from the worktree path convention
+    // Extract issue identifier from worktree path to find matching branch
+    const dirName = path.basename(worktreePath);
+    const branch = `codex/${dirName}`;
     try {
-      const branches = git(["branch", "--list", "codex/*"], repo);
-      // Only delete if it looks like a codex branch
-      for (const b of branches.split("\n")) {
-        const name = b.trim().replace(/^\* /, "");
-        if (name && worktreePath.includes(name.replace("codex/", ""))) {
-          git(["branch", "-D", name], repo);
-          break;
-        }
-      }
+      git(["branch", "-D", branch], repo);
     } catch {
-      // Best effort
+      // Branch doesn't exist or already deleted
     }
   }
 }
@@ -175,23 +234,23 @@ export function createPullRequest(
 export interface WorktreeEntry {
   path: string;
   branch: string;
+  issueIdentifier: string;
   ageMs: number;
   hasChanges: boolean;
 }
 
 /**
- * List all codex worktrees under /tmp.
+ * List all worktrees in the configured base directory.
  */
-export function listWorktrees(baseRepo?: string): WorktreeEntry[] {
-  const repo = baseRepo ?? DEFAULT_BASE_REPO;
+export function listWorktrees(opts?: WorktreeOptions): WorktreeEntry[] {
+  const baseDir = resolveBaseDir(opts?.baseDir);
   const entries: WorktreeEntry[] = [];
 
-  // Find /tmp/codex-* directories
+  if (!existsSync(baseDir)) return [];
+
   let dirs: string[];
   try {
-    dirs = readdirSync("/tmp")
-      .filter((d) => d.startsWith("codex-"))
-      .map((d) => `/tmp/${d}`);
+    dirs = readdirSync(baseDir).map((d) => path.join(baseDir, d));
   } catch {
     return [];
   }
@@ -202,6 +261,13 @@ export function listWorktrees(baseRepo?: string): WorktreeEntry[] {
       const stat = statSync(dir);
       if (!stat.isDirectory()) continue;
 
+      // Verify it's a git worktree
+      try {
+        git(["rev-parse", "--git-dir"], dir);
+      } catch {
+        continue; // Not a git worktree
+      }
+
       let branch = "unknown";
       try {
         branch = git(["rev-parse", "--abbrev-ref", "HEAD"], dir);
@@ -216,6 +282,7 @@ export function listWorktrees(baseRepo?: string): WorktreeEntry[] {
       entries.push({
         path: dir,
         branch,
+        issueIdentifier: path.basename(dir),
         ageMs: Date.now() - stat.mtimeMs,
         hasChanges,
       });
@@ -227,16 +294,75 @@ export function listWorktrees(baseRepo?: string): WorktreeEntry[] {
   return entries.sort((a, b) => b.ageMs - a.ageMs);
 }
 
+export interface PrepareResult {
+  pulled: boolean;
+  pullOutput?: string;
+  submodulesInitialized: boolean;
+  submoduleOutput?: string;
+  errors: string[];
+}
+
+/**
+ * Prepare a worktree for a code run:
+ *   1. Pull latest from origin for the issue branch (fast-forward only)
+ *   2. Initialize and update all git submodules recursively
+ *
+ * Safe to call on every run — idempotent. Failures are non-fatal;
+ * the code run proceeds even if pull or submodule init fails.
+ */
+export function prepareWorkspace(worktreePath: string, branch: string): PrepareResult {
+  const errors: string[] = [];
+  let pulled = false;
+  let pullOutput: string | undefined;
+  let submodulesInitialized = false;
+  let submoduleOutput: string | undefined;
+
+  // 1. Pull latest from origin (ff-only to avoid merge conflicts)
+  try {
+    // Check if remote branch exists before pulling
+    const remoteBranch = `origin/${branch}`;
+    try {
+      git(["rev-parse", "--verify", remoteBranch], worktreePath);
+      // Remote branch exists — pull latest
+      pullOutput = git(["pull", "--ff-only", "origin", branch], worktreePath);
+      pulled = true;
+    } catch {
+      // Remote branch doesn't exist yet (fresh issue branch) — nothing to pull
+      pullOutput = "remote branch not found, skipping pull";
+    }
+  } catch (err) {
+    const msg = `pull failed: ${err}`;
+    errors.push(msg);
+    pullOutput = msg;
+  }
+
+  // 2. Initialize and update all submodules recursively
+  try {
+    submoduleOutput = gitLong(
+      ["submodule", "update", "--init", "--recursive"],
+      worktreePath,
+      120_000, // submodule clone can take a while
+    );
+    submodulesInitialized = true;
+  } catch (err) {
+    const msg = `submodule init failed: ${err}`;
+    errors.push(msg);
+    submoduleOutput = msg;
+  }
+
+  return { pulled, pullOutput, submodulesInitialized, submoduleOutput, errors };
+}
+
 /**
- * Remove codex worktrees older than maxAgeMs.
+ * Remove worktrees older than maxAgeMs.
  * Returns list of removed paths.
  */
 export function pruneStaleWorktrees(
   maxAgeMs: number = 24 * 60 * 60_000,
-  opts?: { baseRepo?: string; dryRun?: boolean },
+  opts?: WorktreeOptions & { dryRun?: boolean },
 ): { removed: string[]; skipped: string[]; errors: string[] } {
+  const worktrees = listWorktrees(opts);
   const repo = opts?.baseRepo ?? DEFAULT_BASE_REPO;
-  const worktrees = listWorktrees(repo);
   const removed: string[] = [];
   const skipped: string[] = [];
   const errors: string[] = [];

package/src/dispatch-service.ts

@@ -0,0 +1,161 @@
+/**
+ * dispatch-service.ts — Background service for dispatch health monitoring.
+ *
+ * Registered via api.registerService(). Runs on a 5-minute interval.
+ * Zero LLM tokens — all logic is deterministic code.
+ *
+ * Responsibilities:
+ * - Hydrate active sessions from dispatch-state.json on startup
+ * - Detect stale dispatches (active >2h with no progress)
+ * - Verify worktree health for active dispatches
+ * - Prune completed dispatches older than 7 days
+ */
+import { existsSync } from "node:fs";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { hydrateFromDispatchState } from "./active-session.js";
+import {
+  readDispatchState,
+  listStaleDispatches,
+  listRecoverableDispatches,
+  transitionDispatch,
+  TransitionError,
+  removeActiveDispatch,
+  pruneCompleted,
+} from "./dispatch-state.js";
+import { getWorktreeStatus } from "./codex-worktree.js";
+
+const INTERVAL_MS = 5 * 60_000; // 5 minutes
+const STALE_THRESHOLD_MS = 2 * 60 * 60_000; // 2 hours
+const COMPLETED_MAX_AGE_MS = 7 * 24 * 60 * 60_000; // 7 days
+
+type ServiceContext = {
+  logger: { info(msg: string): void; warn(msg: string): void; error(msg: string): void };
+};
+
+export function createDispatchService(api: OpenClawPluginApi) {
+  let intervalId: ReturnType<typeof setInterval> | null = null;
+
+  const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
+  const statePath = pluginConfig?.dispatchStatePath as string | undefined;
+
+  return {
+    id: "linear-dispatch-monitor",
+
+    start: async (ctx: ServiceContext) => {
+      // Hydrate active sessions on startup
+      try {
+        const restored = await hydrateFromDispatchState(statePath);
+        if (restored > 0) {
+          ctx.logger.info(`linear-dispatch: hydrated ${restored} active session(s) from dispatch state`);
+        }
+      } catch (err) {
+        ctx.logger.warn(`linear-dispatch: hydration failed: ${err}`);
+      }
+
+      // Recovery scan: find dispatches stuck in "working" with a workerSessionKey
+      // but no auditSessionKey (worker completed but audit wasn't triggered before crash)
+      try {
+        const state = await readDispatchState(statePath);
+        const recoverable = listRecoverableDispatches(state);
+        for (const d of recoverable) {
+          ctx.logger.warn(
+            `linear-dispatch: recoverable dispatch ${d.issueIdentifier} ` +
+            `(status: ${d.status}, attempt: ${d.attempt}, workerKey: ${d.workerSessionKey}, auditKey: ${d.auditSessionKey ?? "none"})`,
+          );
+          // Mark as stuck for manual review — automated recovery requires
+          // re-triggering audit which needs the full HookContext (Linear API, notifier).
+          // The dispatch monitor logs a warning; operator can re-dispatch.
+        }
+        if (recoverable.length > 0) {
+          ctx.logger.warn(`linear-dispatch: ${recoverable.length} dispatch(es) need recovery — consider re-dispatching`);
+        }
+      } catch (err) {
+        ctx.logger.warn(`linear-dispatch: recovery scan failed: ${err}`);
+      }
+
+      ctx.logger.info(`linear-dispatch: service started (interval: ${INTERVAL_MS / 1000}s)`);
+
+      intervalId = setInterval(() => runTick(ctx), INTERVAL_MS);
+    },
+
+    stop: async (ctx: ServiceContext) => {
+      if (intervalId) {
+        clearInterval(intervalId);
+        intervalId = null;
+        ctx.logger.info("linear-dispatch: service stopped");
+      }
+    },
+  };
+
+  async function runTick(ctx: ServiceContext): Promise<void> {
+    try {
+      const state = await readDispatchState(statePath);
+      const activeCount = Object.keys(state.dispatches.active).length;
+
+      // Skip tick if nothing to do
+      if (activeCount === 0 && Object.keys(state.dispatches.completed).length === 0) return;
+
+      // 1. Stale dispatch detection — transition truly stale dispatches to "stuck"
+      const stale = listStaleDispatches(state, STALE_THRESHOLD_MS);
+      for (const dispatch of stale) {
+        // Skip terminal states
+        if (dispatch.status === "done" || dispatch.status === "failed" || dispatch.status === "stuck") {
+          continue;
+        }
+
+        // Check if worktree still exists and has progress
+        if (existsSync(dispatch.worktreePath)) {
+          const status = getWorktreeStatus(dispatch.worktreePath);
+          if (status.hasUncommitted || status.lastCommit) {
+            // Worktree has activity — not truly stale, just slow
+            continue;
+          }
+        }
+
+        ctx.logger.warn(
+          `linear-dispatch: stale dispatch ${dispatch.issueIdentifier} ` +
+          `(dispatched ${dispatch.dispatchedAt}, status: ${dispatch.status}) — transitioning to stuck`,
+        );
+
+        // Try to transition to stuck
+        try {
+          await transitionDispatch(
+            dispatch.issueIdentifier,
+            dispatch.status,
+            "stuck",
+            { stuckReason: `stale_${Math.round((Date.now() - new Date(dispatch.dispatchedAt).getTime()) / 3_600_000)}h` },
+            statePath,
+          );
+          ctx.logger.info(`linear-dispatch: ${dispatch.issueIdentifier} marked as stuck`);
+        } catch (err) {
+          if (err instanceof TransitionError) {
+            ctx.logger.info(`linear-dispatch: CAS failed for stale transition: ${(err as TransitionError).message}`);
+          } else {
+            ctx.logger.error(`linear-dispatch: stale transition error: ${err}`);
+          }
+        }
+      }
+
+      // 2. Worktree health — verify active dispatches have valid worktrees
+      for (const [id, dispatch] of Object.entries(state.dispatches.active)) {
+        if (!existsSync(dispatch.worktreePath)) {
+          ctx.logger.warn(
+            `linear-dispatch: worktree missing for ${id} at ${dispatch.worktreePath}`
+          );
+        }
+      }
+
+      // 3. Prune old completed entries
+      const pruned = await pruneCompleted(COMPLETED_MAX_AGE_MS, statePath);
+      if (pruned > 0) {
+        ctx.logger.info(`linear-dispatch: pruned ${pruned} old completed dispatch(es)`);
+      }
+
+      if (activeCount > 0) {
+        ctx.logger.info(`linear-dispatch: tick — ${activeCount} active, ${stale.length} stale`);
+      }
+    } catch (err) {
+      ctx.logger.error(`linear-dispatch: tick failed: ${err}`);
+    }
+  }
+}