astrocode-workflow 0.3.2 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astrocode-workflow",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/astro/workflow-runner.ts

@@ -0,0 +1,36 @@
+// src/astro/workflow-runner.ts
+import { acquireRepoLock } from "../state/repo-lock";
+import { workflowRepoLock } from "../state/workflow-repo-lock";
+
+/**
+ * This is the only place you should hold the repo lock.
+ * Everything that mutates the repo (tool calls, steps) runs inside this scope.
+ *
+ * Replace the internals with your actual astro/opencode driver loop.
+ */
+export async function runAstroWorkflow(opts: {
+  lockPath: string;
+  repoRoot: string;
+  sessionId: string;
+  owner?: string;
+
+  // Hook in your existing workflow engine
+  proceedOneStep: () => Promise<{ done: boolean }>;
+}): Promise<void> {
+  await workflowRepoLock(
+    { acquireRepoLock },
+    {
+      lockPath: opts.lockPath,
+      repoRoot: opts.repoRoot,
+      sessionId: opts.sessionId,
+      owner: opts.owner,
+      fn: async () => {
+        // ✅ Lock is held ONCE for the entire run. Tool calls can "rattle through".
+        while (true) {
+          const { done } = await opts.proceedOneStep();
+          if (done) return;
+        }
+      },
+    }
+  );
+}

package/src/state/repo-lock.ts

@@ -1,13 +1,37 @@
 // src/state/repo-lock.ts
 import fs from "node:fs";
 import path from "node:path";
+import crypto from "node:crypto";
+
+const LOCK_VERSION = 2;
+
+// Process-stable identifier for this Node process instance.
+const PROCESS_INSTANCE_ID = crypto.randomUUID();
+
+// Hard guardrails against garbage/corruption.
+const MAX_LOCK_BYTES = 64 * 1024; // 64KB; lock file should be tiny.
+
+// How many times we’ll attempt "atomic-ish replace" before giving up.
+const ATOMIC_REPLACE_RETRIES = 3;
 
 type LockFile = {
+  v: number;
+
   pid: number;
   created_at: string;
   updated_at: string;
   repo_root: string;
+
+  // Identifies the running process instance (process-stable).
+  instance_id: string;
+
+  // Logical session owner (propagated by opencode).
   session_id?: string;
+
+  // Fencing token: changes every successful acquire.
+  // Prevents ABA release deleting someone else’s lock.
+  lease_id: string;
+
   owner?: string; // optional human-readable owner
 };
 
@@ -19,117 +43,534 @@ function sleep(ms: number) {
   return new Promise((r) => setTimeout(r, ms));
 }
 
+/**
+ * PID existence check:
+ * - EPERM => process exists but we can't signal it (treat as alive)
+ * - ESRCH => process does not exist (dead)
+ */
 function isPidAlive(pid: number): boolean {
   try {
-    // Signal 0 checks existence without killing.
     (process as any).kill(pid, 0);
     return true;
+  } catch (err: any) {
+    const code = err?.code;
+    if (code === "EPERM") return true;
+    if (code === "ESRCH") return false;
+    // Unknown: conservative = don't evict.
+    return true;
+  }
+}
+
+function parseISOToMs(iso: string): number | null {
+  const t = Date.parse(iso);
+  if (Number.isNaN(t)) return null;
+  return t;
+}
+
+function isStaleByAge(existing: LockFile, staleMs: number): boolean {
+  const updatedMs = parseISOToMs(existing.updated_at);
+  if (updatedMs === null) return true;
+  return Date.now() - updatedMs > staleMs;
+}
+
+function safeUnlink(p: string) {
+  try {
+    fs.unlinkSync(p);
   } catch {
-    return false;
+    // ignore
   }
 }
 
+/**
+ * Reads & validates lock file defensively.
+ * Supports both v2 JSON format and legacy PID-only format for compatibility.
+ * Returns null on any parse/validation failure.
+ */
 function readLock(lockPath: string): LockFile | null {
   try {
-    const raw = fs.readFileSync(lockPath, "utf8");
-    const parsed = JSON.parse(raw) as LockFile;
-    if (!parsed || typeof parsed.pid !== "number") return null;
-    return parsed;
+    const st = fs.statSync(lockPath);
+    if (!st.isFile()) return null;
+    if (st.size <= 0 || st.size > MAX_LOCK_BYTES) return null;
+
+    const raw = fs.readFileSync(lockPath, "utf8").trim();
+
+    // Try v2 JSON first
+    try {
+      const parsed = JSON.parse(raw) as LockFile;
+      if (parsed && typeof parsed === "object" && parsed.v === LOCK_VERSION) {
+        if (typeof parsed.pid !== "number") return null;
+        if (typeof parsed.created_at !== "string") return null;
+        if (typeof parsed.updated_at !== "string") return null;
+        if (typeof parsed.repo_root !== "string") return null;
+        if (typeof parsed.instance_id !== "string") return null;
+        if (typeof parsed.lease_id !== "string") return null;
+
+        if (parsed.session_id !== undefined && typeof parsed.session_id !== "string") return null;
+        if (parsed.owner !== undefined && typeof parsed.owner !== "string") return null;
+
+        return parsed;
+      }
+    } catch {
+      // Not JSON, try legacy format
+    }
+
+    // Legacy format: just PID as number string
+    const legacyPid = parseInt(raw, 10);
+    if (Number.isNaN(legacyPid) || legacyPid <= 0) return null;
+
+    // Convert legacy to v2 format
+    const now = nowISO();
+    const leaseId = crypto.randomUUID();
+    return {
+      v: LOCK_VERSION,
+      pid: legacyPid,
+      created_at: now, // Approximate
+      updated_at: now,
+      repo_root: "", // Unknown, will be filled by caller
+      instance_id: PROCESS_INSTANCE_ID, // Assume same instance
+      session_id: undefined,
+      lease_id: leaseId,
+      owner: "legacy-lock",
+    };
   } catch {
     return null;
   }
 }
 
-function writeLock(lockPath: string, lock: LockFile) {
-  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
-  fs.writeFileSync(lockPath, JSON.stringify(lock, null, 2));
+/**
+ * Best-effort directory fsync:
+ * Helps durability on crash for some filesystems (mostly POSIX).
+ * On platforms where opening a directory fails, we ignore.
+ */
+function fsyncDirBestEffort(dirPath: string) {
+  try {
+    const fd = fs.openSync(dirPath, "r");
+    try {
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    // ignore (not portable)
+  }
+}
+
+/**
+ * "Atomic-ish" replace:
+ * - Write temp file
+ * - Try rename over target (POSIX generally atomic)
+ * - Windows can fail if target exists/locked; fallback to unlink+rename (not atomic, but best-effort)
+ * - Best-effort directory fsync after rename
+ */
+function writeLockAtomicish(lockPath: string, lock: LockFile) {
+  const dir = path.dirname(lockPath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const tmp = `${lockPath}.${(process as any).pid}.${Date.now()}.${crypto.randomUUID()}.tmp`;
+  const body = JSON.stringify(lock); // compact JSON to reduce IO
+
+  fs.writeFileSync(tmp, body, "utf8");
+
+  let lastErr: any = null;
+  for (let i = 0; i < ATOMIC_REPLACE_RETRIES; i++) {
+    try {
+      fs.renameSync(tmp, lockPath);
+      fsyncDirBestEffort(dir);
+      return;
+    } catch (err: any) {
+      lastErr = err;
+      const code = err?.code;
+
+      // Common Windows-ish cases where rename over existing fails.
+      if (code === "EEXIST" || code === "EPERM" || code === "ENOTEMPTY") {
+        safeUnlink(lockPath);
+        continue;
+      }
+
+      // If tmp vanished somehow, stop.
+      if (code === "ENOENT") break;
+
+      continue;
+    }
+  }
+
+  safeUnlink(tmp);
+  if (lastErr) throw lastErr;
+  throw new Error(`Failed to replace lock file: ${lockPath}`);
 }
 
-function safeUnlink(lockPath: string) {
+/**
+ * Atomic "create if not exists" using exclusive open.
+ */
+function tryCreateExclusiveFile(filePath: string, contentsUtf8: string): boolean {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+
   try {
-    fs.unlinkSync(lockPath);
-  } catch {
-    // ignore
+    const fd = fs.openSync(filePath, "wx");
+    try {
+      fs.writeFileSync(fd, contentsUtf8, "utf8");
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    fsyncDirBestEffort(path.dirname(filePath));
+    return true;
+  } catch (err: any) {
+    if (err?.code === "EEXIST") return false;
+    throw err;
   }
 }
 
+function tryCreateRepoLockExclusive(lockPath: string, lock: LockFile): boolean {
+  return tryCreateExclusiveFile(lockPath, JSON.stringify(lock));
+}
+
+/**
+ * In-process lock cache:
+ * Prevents repeated acquire/release cycles during tool-call storms.
+ */
+type CachedHandle = {
+  key: string;
+  lockPath: string;
+  sessionId?: string;
+  leaseId: string;
+  refCount: number;
+  heartbeatStop: () => void;
+  releaseOnce: () => void;
+};
+
+const ACTIVE_LOCKS = new Map<string, CachedHandle>();
+
+function cacheKey(lockPath: string, sessionId?: string): string {
+  return `${lockPath}::${sessionId ?? ""}`;
+}
+
+/**
+ * Heartbeat loop:
+ * - setTimeout (not setInterval) to avoid backlog drift under load
+ * - Minimizes writes by enforcing minWriteMs
+ * - ABA-safe: only refreshes if lock matches our lease_id and process identity
+ * - Avoids unnecessary writes if lock already has a recent updated_at
+ */
+function startHeartbeat(opts: {
+  lockPath: string;
+  repoRoot: string;
+  sessionId?: string;
+  owner?: string;
+  leaseId: string;
+  heartbeatMs: number;
+  minWriteMs: number;
+}): () => void {
+  let stopped = false;
+  let lastWriteAt = 0;
+  let timer: NodeJS.Timeout | null = null;
+
+  const tick = () => {
+    if (stopped) return;
+
+    const now = Date.now();
+    const shouldAttempt = now - lastWriteAt >= opts.minWriteMs;
+
+    if (shouldAttempt) {
+      const existing = readLock(opts.lockPath);
+
+      if (
+        existing &&
+        existing.lease_id === opts.leaseId &&
+        existing.pid === (process as any).pid &&
+        existing.instance_id === PROCESS_INSTANCE_ID
+      ) {
+        const updatedMs = parseISOToMs(existing.updated_at);
+        const isFresh = updatedMs !== null && now - updatedMs < opts.minWriteMs;
+
+        if (!isFresh) {
+          writeLockAtomicish(opts.lockPath, {
+            ...existing,
+            updated_at: nowISO(),
+            repo_root: opts.repoRoot,
+            session_id: opts.sessionId ?? existing.session_id,
+            owner: opts.owner ?? existing.owner,
+          });
+          lastWriteAt = now;
+        } else {
+          lastWriteAt = now;
+        }
+      }
+    }
+
+    timer = setTimeout(tick, opts.heartbeatMs);
+    (timer as any).unref?.();
+  };
+
+  tick();
+
+  return () => {
+    stopped = true;
+    if (timer) clearTimeout(timer);
+  };
+}
+
+/**
+ * Shutdown cleanup:
+ * Best-effort release on normal termination signals.
+ */
+let EXIT_HOOK_INSTALLED = false;
+function installExitHookOnce() {
+  if (EXIT_HOOK_INSTALLED) return;
+  EXIT_HOOK_INSTALLED = true;
+
+  const cleanup = () => {
+    for (const [key, h] of ACTIVE_LOCKS.entries()) {
+      try {
+        ACTIVE_LOCKS.delete(key);
+        h.heartbeatStop();
+        h.releaseOnce();
+      } catch {
+        // ignore
+      }
+    }
+  };
+
+  (process as any).once("exit", cleanup);
+  (process as any).once("SIGINT", () => {
+    cleanup();
+    (process as any).exit(130);
+  });
+  (process as any).once("SIGTERM", () => {
+    cleanup();
+    (process as any).exit(143);
+  });
+}
+
 /**
  * Acquire a repo-scoped lock with:
- * - Re-entrant behavior for SAME PID (your own process can call tools repeatedly)
- * - Stale lock eviction for dead PIDs
- * - Best-effort contention retry
+ * - ✅ process-local caching + refcount (efficient repeated tool calls)
+ * - ✅ heartbeat lease + stale recovery
+ * - ✅ atomic create (`wx`) + portable replace fallback
+ * - ✅ dead PID eviction + stale eviction
+ * - ✅ no live takeover (even same session) to avoid concurrency stomps
+ * - ✅ ABA-safe release via lease_id fencing
+ * - ✅ exponential backoff + jitter to reduce FS churn
  */
 export async function acquireRepoLock(opts: {
   lockPath: string;
   repoRoot: string;
   sessionId?: string;
   owner?: string;
-  retryMs?: number;      // default 2000
-  pollMs?: number;       // default 100
+
+  retryMs?: number;      // default 8000
+  pollMs?: number;       // default 20
+  pollMaxMs?: number;    // default 250
+  staleMs?: number;      // default 2 minutes
+  heartbeatMs?: number;  // default 200
+  minWriteMs?: number;   // default 800
 }): Promise<{ release: () => void }> {
+  installExitHookOnce();
+
   const { lockPath, repoRoot, sessionId, owner } = opts;
-  const retryMs = opts.retryMs ?? 2000;
-  const pollMs = opts.pollMs ?? 100;
 
-  const myPid = (process as any).pid;
+  const retryMs = opts.retryMs ?? 8000;
+  const pollBaseMs = opts.pollMs ?? 20;
+  const pollMaxMs = opts.pollMaxMs ?? 250;
+
+  const heartbeatMs = opts.heartbeatMs ?? 200;
+  const minWriteMs = opts.minWriteMs ?? 800;
+
+  // Ensure stale is comfortably above minWriteMs to prevent false-stale under load.
+  const staleMs = Math.max(opts.staleMs ?? 2 * 60 * 1000, minWriteMs * 8);
+
+  // ✅ Fast path: reuse cached handle in the same process/session.
+  const key = cacheKey(lockPath, sessionId);
+  const cached = ACTIVE_LOCKS.get(key);
+  if (cached) {
+    cached.refCount += 1;
+    return {
+      release: () => {
+        cached.refCount -= 1;
+        if (cached.refCount <= 0) {
+          ACTIVE_LOCKS.delete(key);
+          cached.heartbeatStop();
+          cached.releaseOnce();
+        }
+      },
+    };
+  }
+
+  const myPid = ((process as any).pid as number);
   const startedAt = Date.now();
+  let pollMs = pollBaseMs;
 
   while (true) {
     const existing = readLock(lockPath);
 
-    // No lock -> take it.
+    // No lock (or unreadable/invalid) -> try create.
     if (!existing) {
       const now = nowISO();
-      writeLock(lockPath, {
+      const leaseId = crypto.randomUUID();
+
+      const candidate: LockFile = {
+        v: LOCK_VERSION,
         pid: myPid,
         created_at: now,
         updated_at: now,
         repo_root: repoRoot,
+        instance_id: PROCESS_INSTANCE_ID,
         session_id: sessionId,
+        lease_id: leaseId,
         owner,
-      });
+      };
 
-      // Verify we actually own it (race safety)
-      const verify = readLock(lockPath);
-      if (verify && verify.pid === myPid) {
-        return {
-          release: () => {
-            const cur = readLock(lockPath);
-            // Only the owner PID removes the lock.
-            if (cur && cur.pid === myPid) safeUnlink(lockPath);
-          },
+      const created = tryCreateRepoLockExclusive(lockPath, candidate);
+      if (created) {
+        const heartbeatStop = startHeartbeat({
+          lockPath,
+          repoRoot,
+          sessionId,
+          owner,
+          leaseId,
+          heartbeatMs,
+          minWriteMs,
+        });
+
+        const releaseOnce = () => {
+          const cur = readLock(lockPath);
+          if (!cur) return;
+
+          // ABA-safe
+          if (cur.lease_id !== leaseId) return;
+
+          // Strict identity: only exact process instance can delete.
+          if (cur.pid !== myPid) return;
+          if (cur.instance_id !== PROCESS_INSTANCE_ID) return;
+
+          safeUnlink(lockPath);
+          fsyncDirBestEffort(path.dirname(lockPath));
         };
-      }
 
-      // Race lost; retry.
-    } else {
-      // Re-entrant: SAME PID owns lock -> refresh timestamp and proceed.
-      if (existing.pid === myPid) {
-        const now = nowISO();
-        writeLock(lockPath, { ...existing, updated_at: now, session_id: sessionId ?? existing.session_id, owner: owner ?? existing.owner });
+        const handle: CachedHandle = {
+          key,
+          lockPath,
+          sessionId,
+          leaseId,
+          refCount: 1,
+          heartbeatStop,
+          releaseOnce,
+        };
+        ACTIVE_LOCKS.set(key, handle);
+
         return {
           release: () => {
-            const cur = readLock(lockPath);
-            if (cur && cur.pid === myPid) safeUnlink(lockPath);
+            const h = ACTIVE_LOCKS.get(key);
+            if (!h) return;
+            h.refCount -= 1;
+            if (h.refCount <= 0) {
+              ACTIVE_LOCKS.delete(key);
+              h.heartbeatStop();
+              h.releaseOnce();
+            }
           },
         };
       }
 
-      // Another PID: if dead -> evict stale lock
-      if (!isPidAlive(existing.pid)) {
+      // Race lost; reset backoff and loop.
+      pollMs = pollBaseMs;
+      continue;
+    }
+
+    // Re-entrant by SAME PROCESS IDENTITY (pid+instance), or legacy lock with same PID.
+    if (existing.pid === myPid && (existing.instance_id === PROCESS_INSTANCE_ID || existing.owner === "legacy-lock")) {
+      const leaseId = crypto.randomUUID();
+
+      writeLockAtomicish(lockPath, {
+        ...existing,
+        v: LOCK_VERSION,
+        updated_at: nowISO(),
+        repo_root: repoRoot,
+        instance_id: PROCESS_INSTANCE_ID, // Upgrade legacy
+        session_id: sessionId ?? existing.session_id,
+        owner: owner ?? existing.owner,
+        lease_id: leaseId,
+      });
+
+      const heartbeatStop = startHeartbeat({
+        lockPath,
+        repoRoot,
+        sessionId: sessionId ?? existing.session_id,
+        owner: owner ?? existing.owner,
+        leaseId,
+        heartbeatMs,
+        minWriteMs,
+      });
+
+      const releaseOnce = () => {
+        const cur = readLock(lockPath);
+        if (!cur) return;
+        if (cur.lease_id !== leaseId) return;
+        if (cur.pid !== myPid) return;
+        if (cur.instance_id !== PROCESS_INSTANCE_ID) return;
         safeUnlink(lockPath);
-        // loop back and acquire
-      } else {
-        // Alive and not us -> wait bounded
-        if (Date.now() - startedAt > retryMs) {
-          throw new Error(
-            `Astrocode lock is already held (${lockPath}). pid=${existing.pid} (alive). ` +
-            `Close other opencode processes or wait.`
-          );
-        }
-        await sleep(pollMs);
-      }
+        fsyncDirBestEffort(path.dirname(lockPath));
+      };
+
+      const handle: CachedHandle = {
+        key,
+        lockPath,
+        sessionId,
+        leaseId,
+        refCount: 1,
+        heartbeatStop,
+        releaseOnce,
+      };
+      ACTIVE_LOCKS.set(key, handle);
+
+      return {
+        release: () => {
+          const h = ACTIVE_LOCKS.get(key);
+          if (!h) return;
+          h.refCount -= 1;
+          if (h.refCount <= 0) {
+            ACTIVE_LOCKS.delete(key);
+            h.heartbeatStop();
+            h.releaseOnce();
+          }
+        },
+      };
     }
+
+    // 🚫 No live takeover (even same session).
+    // We only evict dead/stale locks.
+
+    const pidAlive = isPidAlive(existing.pid);
+    const staleByAge = isStaleByAge(existing, staleMs);
+
+    if (!pidAlive || staleByAge) {
+      safeUnlink(lockPath);
+      fsyncDirBestEffort(path.dirname(lockPath));
+      pollMs = pollBaseMs;
+      continue;
+    }
+
+    // Alive and not us -> bounded wait with exponential backoff + jitter.
+    if (Date.now() - startedAt > retryMs) {
+      const ownerBits = [
+        `pid=${existing.pid}`,
+        existing.session_id ? `session=${existing.session_id}` : null,
+        existing.owner ? `owner=${existing.owner}` : null,
+        `updated_at=${existing.updated_at}`,
+        sessionId && existing.session_id === sessionId ? `(same-session waiting)` : null,
+      ]
+        .filter(Boolean)
+        .join(" ");
+
+      throw new Error(
+        `Astrocode lock is already held (${lockPath}). ${ownerBits}. ` +
+          `Close other opencode processes or wait.`
+      );
+    }
+
+    const jitter = Math.floor(Math.random() * Math.min(12, pollMs));
+    await sleep(pollMs + jitter);
+    pollMs = Math.min(pollMaxMs, Math.floor(pollMs * 1.35));
   }
 }
 

package/src/state/workflow-repo-lock.ts

@@ -0,0 +1,74 @@
+// src/state/workflow-repo-lock.ts
+import type { acquireRepoLock } from "./repo-lock";
+
+type RepoLockAcquire = typeof acquireRepoLock;
+
+type Held = {
+  release: () => void;
+  depth: number;
+};
+
+const HELD_BY_KEY = new Map<string, Held>();
+
+function key(lockPath: string, sessionId?: string) {
+  return `${lockPath}::${sessionId ?? ""}`;
+}
+
+/**
+ * Acquire ONCE per workflow/session in this process.
+ * Nested calls reuse the same held lock (no reacquire, no churn).
+ */
+export async function workflowRepoLock<T>(
+  deps: { acquireRepoLock: RepoLockAcquire },
+  opts: {
+    lockPath: string;
+    repoRoot: string;
+    sessionId?: string;
+    owner?: string;
+    fn: () => Promise<T>;
+  }
+): Promise<T> {
+  const k = key(opts.lockPath, opts.sessionId);
+  const existing = HELD_BY_KEY.get(k);
+
+  if (existing) {
+    existing.depth += 1;
+    try {
+      return await opts.fn();
+    } finally {
+      existing.depth -= 1;
+      if (existing.depth <= 0) {
+        HELD_BY_KEY.delete(k);
+        existing.release();
+      }
+    }
+  }
+
+  // IMPORTANT: this is tuned for "hold for whole workflow".
+  const handle = await deps.acquireRepoLock({
+    lockPath: opts.lockPath,
+    repoRoot: opts.repoRoot,
+    sessionId: opts.sessionId,
+    owner: opts.owner,
+
+    retryMs: 30_000,
+    staleMs: 2 * 60_000,
+    heartbeatMs: 200,
+    minWriteMs: 800,
+    pollMs: 20,
+    pollMaxMs: 250,
+  });
+
+  const held: Held = { release: handle.release, depth: 1 };
+  HELD_BY_KEY.set(k, held);
+
+  try {
+    return await opts.fn();
+  } finally {
+    held.depth -= 1;
+    if (held.depth <= 0) {
+      HELD_BY_KEY.delete(k);
+      held.release();
+    }
+  }
+}

package/src/tools/init.ts

@@ -7,7 +7,7 @@ import { ensureSchema, openSqlite, configurePragmas } from "../state/db";
 import { getAstroPaths, ensureAstroDirs } from "../shared/paths";
 import { nowISO } from "../shared/time";
 import { sha256Hex } from "../shared/hash";
-import { withRepoLock } from "../state/repo-lock";
+
 
 type RuntimeState = {
   db: SqliteDb | null;
@@ -30,15 +30,6 @@ export function createAstroInitTool(opts: { ctx: any; config: AstrocodeConfig; r
     },
     execute: async ({ ensure_spec, spec_placeholder }) => {
       const repoRoot = ctx.directory as string;
-      const lockPath = path.join(repoRoot, ".astro", "astro.lock");
-      const sessionId = (ctx as any).sessionID as string | undefined;
-
-      return withRepoLock({
-        lockPath,
-        repoRoot,
-        sessionId,
-        owner: "astro_init",
-        fn: async () => {
           const paths = getAstroPaths(repoRoot, config.db.path);
           ensureAstroDirs(paths);
 
@@ -116,16 +107,14 @@ export function createAstroInitTool(opts: { ctx: any; config: AstrocodeConfig; r
             ? `Next: run /astro-status. (DB recovered in-process.)`
             : `Next: restart the agent/runtime if Astrocode is still in Limited Mode, then run /astro-status.`,
         ].join("\n");
-          } finally {
-            // Only close if this tool opened it AND we did not publish it for ongoing use.
-            if (!hadDbAlready && !publishedToRuntime && db && typeof db.close === "function") {
-              try {
-                db.close();
-              } catch {}
-            }
-          }
-        },
-      });
+      } finally {
+        // Only close if this tool opened it AND we did not publish it for ongoing use.
+        if (!hadDbAlready && !publishedToRuntime && db && typeof db.close === "function") {
+          try {
+            db.close();
+          } catch {}
+        }
+      }
     },
   });
 }

package/src/tools/repair.ts

@@ -1,12 +1,11 @@
 import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool";
-import path from "node:path";
 import type { AstrocodeConfig } from "../config/schema";
 import type { SqliteDb } from "../state/db";
 import { withTx } from "../state/db";
 import { repairState, formatRepairReport } from "../workflow/repair";
 import { putArtifact } from "../workflow/artifacts";
 import { nowISO } from "../shared/time";
-import { withRepoLock } from "../state/repo-lock";
+
 
 export function createAstroRepairTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
   const { ctx, config, db } = opts;
@@ -18,27 +17,16 @@ export function createAstroRepairTool(opts: { ctx: any; config: AstrocodeConfig;
     },
     execute: async ({ write_report_artifact }) => {
       const repoRoot = ctx.directory as string;
-      const lockPath = path.join(repoRoot, ".astro", "astro.lock");
-      const sessionId = (ctx as any).sessionID as string | undefined;
-
-      return withRepoLock({
-        lockPath,
-        repoRoot,
-        sessionId,
-        owner: "astro_repair",
-        fn: async () => {
-          const report = withTx(db, () => repairState(db, config));
-          const md = formatRepairReport(report);
+      const report = withTx(db, () => repairState(db, config));
+      const md = formatRepairReport(report);
 
-          if (write_report_artifact) {
-            const rel = `.astro/repair/repair_${nowISO().replace(/[:.]/g, "-")}.md`;
-            const a = putArtifact({ repoRoot, db, run_id: null, stage_key: null, type: "log", rel_path: rel, content: md, meta: { kind: "repair" } });
-            return md + `\n\nReport saved: ${rel} (artifact=${a.artifact_id})`;
-          }
+      if (write_report_artifact) {
+        const rel = `.astro/repair/repair_${nowISO().replace(/[:.]/g, "-")}.md`;
+        const a = putArtifact({ repoRoot, db, run_id: null, stage_key: null, type: "log", rel_path: rel, content: md, meta: { kind: "repair" } });
+        return md + `\n\nReport saved: ${rel} (artifact=${a.artifact_id})`;
+      }
 
-          return md;
-        },
-      });
+      return md;
     },
   });
 }

package/src/tools/stage.ts

@@ -13,7 +13,7 @@ import { getAstroPaths, ensureAstroDirs, toPosix } from "../shared/paths";
 import { failRun, getActiveRun, getStageRuns, startStage, completeRun } from "../workflow/state-machine";
 import { newEventId, newId } from "../state/ids";
 import { insertStory } from "../workflow/story-helpers";
-import { withRepoLock } from "../state/repo-lock";
+
 
 function nextStageKey(pipeline: StageKey[], current: StageKey): StageKey | null {
   const i = pipeline.indexOf(current);
@@ -129,15 +129,6 @@ export function createAstroStageCompleteTool(opts: { ctx: any; config: Astrocode
     },
     execute: async ({ run_id, stage_key, output_text, allow_new_stories, relation_reason }) => {
       const repoRoot = ctx.directory as string;
-      const lockPath = path.join(repoRoot, ".astro", "astro.lock");
-      const sessionId = (ctx as any).sessionID as string | undefined;
-
-      return withRepoLock({
-        lockPath,
-        repoRoot,
-        sessionId,
-        owner: "astro_stage_complete",
-        fn: async () => {
       const paths = getAstroPaths(repoRoot, config.db.path);
       ensureAstroDirs(paths);
 
@@ -401,8 +392,6 @@ Ensure JSON has required fields (stage_key, status) and valid syntax.`;
       lines.push(context);
 
       return lines.join("\n").trim();
-        },
-      });
     },
   });
 }

package/src/tools/status.ts

@@ -1,9 +1,8 @@
 import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool";
-import path from "node:path";
 import type { AstrocodeConfig } from "../config/schema";
 import type { SqliteDb } from "../state/db";
 import { decideNextAction, getActiveRun, getStageRuns, getStory } from "../workflow/state-machine";
-import { withRepoLock } from "../state/repo-lock";
+
 
 function statusIcon(status: string): string {
   switch (status) {
@@ -57,17 +56,7 @@ export function createAstroStatusTool(opts: { ctx: any; config: AstrocodeConfig;
         ].join("\n");
       }
 
-      const repoRoot = ctx.directory as string;
-      const lockPath = path.join(repoRoot, ".astro", "astro.lock");
-      const sessionId = (ctx as any).sessionID as string | undefined;
-
-      return withRepoLock({
-        lockPath,
-        repoRoot,
-        sessionId,
-        owner: "astro_status",
-        fn: async () => {
-          try {
+      try {
         const active = getActiveRun(db);
 
         const lines: string[] = [];
@@ -141,9 +130,7 @@ export function createAstroStatusTool(opts: { ctx: any; config: AstrocodeConfig;
           `⛔ Database error.`,
           `Error: ${msg}`,
         ].join("\n");
-          }
-        },
-      });
+      }
     },
   });
 }

package/src/tools/story.ts

@@ -1,5 +1,4 @@
 import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool";
-import path from "node:path";
 import type { AstrocodeConfig } from "../config/schema";
 import type { SqliteDb } from "../state/db";
 import { withTx } from "../state/db";
@@ -7,11 +6,11 @@ import { nowISO } from "../shared/time";
 import type { StoryState } from "../state/types";
 
 import { insertStory } from "../workflow/story-helpers";
-import { withRepoLock } from "../state/repo-lock";
+
 
 
 export function createAstroStoryQueueTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
-  const { ctx, db } = opts;
+  const { db } = opts;
 
   return tool({
     description: "Create a queued story (ticket) in Astrocode. Returns story_key.",
@@ -22,30 +21,18 @@ export function createAstroStoryQueueTool(opts: { ctx: any; config: AstrocodeCon
       priority: tool.schema.number().int().default(0),
     },
     execute: async ({ title, body_md, epic_key, priority }) => {
-      const repoRoot = ctx.directory as string;
-      const lockPath = path.join(repoRoot, ".astro", "astro.lock");
-      const sessionId = (ctx as any).sessionID as string | undefined;
-
-      return withRepoLock({
-        lockPath,
-        repoRoot,
-        sessionId,
-        owner: "astro_story_queue",
-        fn: async () => {
-          const story_key = withTx(db, () => {
-            const key = insertStory(db, { title, body_md, epic_key: epic_key ?? null, priority: priority ?? 0, state: 'queued' });
-            return key;
-          });
-
-          return `✅ Queued story ${story_key}: ${title}`;
-        },
+      const story_key = withTx(db, () => {
+        const key = insertStory(db, { title, body_md, epic_key: epic_key ?? null, priority: priority ?? 0, state: 'queued' });
+        return key;
       });
+
+      return `✅ Queued story ${story_key}: ${title}`;
     },
   });
 }
 
 export function createAstroStoryApproveTool(opts: { ctx: any; config: AstrocodeConfig; db: SqliteDb }): ToolDefinition {
-  const { ctx, db } = opts;
+  const { db } = opts;
 
   return tool({
     description: "Approve a story so it becomes eligible to run.",
@@ -53,26 +40,14 @@ export function createAstroStoryApproveTool(opts: { ctx: any; config: AstrocodeC
       story_key: tool.schema.string().min(1),
     },
     execute: async ({ story_key }) => {
-      const repoRoot = ctx.directory as string;
-      const lockPath = path.join(repoRoot, ".astro", "astro.lock");
-      const sessionId = (ctx as any).sessionID as string | undefined;
-
-      return withRepoLock({
-        lockPath,
-        repoRoot,
-        sessionId,
-        owner: "astro_story_approve",
-        fn: async () => {
-          const now = nowISO();
-          const row = db.prepare("SELECT story_key, state, title FROM stories WHERE story_key=?").get(story_key) as any;
-          if (!row) throw new Error(`Story not found: ${story_key}`);
-
-          if (row.state === "approved") return `ℹ️ Story ${story_key} already approved.`;
-
-          db.prepare("UPDATE stories SET state='approved', approved_at=?, updated_at=? WHERE story_key=?").run(now, now, story_key);
-          return `✅ Approved story ${story_key}: ${row.title}`;
-        },
-      });
+      const now = nowISO();
+      const row = db.prepare("SELECT story_key, state, title FROM stories WHERE story_key=?").get(story_key) as any;
+      if (!row) throw new Error(`Story not found: ${story_key}`);
+
+      if (row.state === "approved") return `ℹ️ Story ${story_key} already approved.`;
+
+      db.prepare("UPDATE stories SET state='approved', approved_at=?, updated_at=? WHERE story_key=?").run(now, now, story_key);
+      return `✅ Approved story ${story_key}: ${row.title}`;
     },
   });
 }

package/src/tools/workflow.ts

@@ -20,11 +20,12 @@ import { buildStageDirective, directiveHash } from "../workflow/directives";
 import { injectChatPrompt } from "../ui/inject";
 import { nowISO } from "../shared/time";
 import { newEventId } from "../state/ids";
-import { withRepoLock } from "../state/repo-lock";
+
 import { debug } from "../shared/log";
 import { createToastManager } from "../ui/toasts";
 import type { AgentConfig } from "@opencode-ai/sdk";
 import { acquireRepoLock } from "../state/repo-lock";
+import { workflowRepoLock } from "../state/workflow-repo-lock";
 
 // Agent name mapping for case-sensitive resolution
 export const STAGE_TO_AGENT_MAP: Record<string, string> = {
@@ -191,12 +192,14 @@ export function createAstroWorkflowProceedTool(opts: { ctx: any; config: Astroco
       const lockPath = path.join(repoRoot, ".astro", "astro.lock");
       const sessionId = (ctx as any).sessionID as string | undefined;
 
-      return withRepoLock({
-        lockPath,
-        repoRoot,
-        sessionId,
-        owner: "astro_workflow_proceed",
-        fn: async () => {
+      return workflowRepoLock(
+        { acquireRepoLock },
+        {
+          lockPath,
+          repoRoot,
+          sessionId,
+          owner: "astro_workflow_proceed",
+          fn: async () => {
         const steps = Math.min(max_steps, config.workflow.loop_max_steps_hard_cap);
 
       const actions: string[] = [];
@@ -420,8 +423,8 @@ export function createAstroWorkflowProceedTool(opts: { ctx: any; config: Astroco
       }
 
       return lines.join("\n").trim();
-        },
-      });
+          },
+        });
     },
   });
 }