astrocode-workflow 0.3.4 → 0.3.5

package/dist/src/astro/workflow-runner.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 declare function runAstroWorkflow(opts: {
+    lockPath: string;
+    repoRoot: string;
+    sessionId: string;
+    owner?: string;
+    proceedOneStep: () => Promise<{
+        done: boolean;
+    }>;
+}): Promise<void>;

package/dist/src/astro/workflow-runner.js

@@ -0,0 +1,25 @@
+// 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) {
+    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/dist/src/hooks/inject-provider.d.ts

@@ -4,6 +4,10 @@ type ChatMessageInput = {
     sessionID: string;
     agent: string;
 };
+type ToolExecuteAfterInput = {
+    tool: string;
+    sessionID?: string;
+};
 type RuntimeState = {
     db: SqliteDb | null;
     limitedMode: boolean;
@@ -18,5 +22,6 @@ export declare function createInjectProvider(opts: {
     runtime: RuntimeState;
 }): {
     onChatMessage(input: ChatMessageInput): Promise<void>;
+    onToolAfter(input: ToolExecuteAfterInput): Promise<void>;
 };
 export {};

package/dist/src/hooks/inject-provider.js

@@ -116,5 +116,15 @@ export function createInjectProvider(opts) {
             // Inject eligible injects before processing the user's message
             await injectEligibleInjects(input.sessionID);
         },
+        async onToolAfter(input) {
+            if (!config.inject?.enabled)
+                return;
+            // Extract sessionID (same pattern as continuation enforcer)
+            const sessionId = input.sessionID ?? ctx.sessionID;
+            if (!sessionId)
+                return;
+            // Inject eligible injects after tool execution
+            await injectEligibleInjects(sessionId);
+        },
     };
 }

package/dist/src/index.js

@@ -9,7 +9,6 @@ import { createInjectProvider } from "./hooks/inject-provider";
 import { createToastManager } from "./ui/toasts";
 import { createAstroAgents } from "./agents/registry";
 import { info, warn } from "./shared/log";
-import { acquireRepoLock } from "./state/repo-lock";
 // Safe config cloning with structuredClone preference (fallback for older Node versions)
 // CONTRACT: Config is guaranteed JSON-serializable (enforced by loadAstrocodeConfig validation)
 const cloneConfig = (v) => {
@@ -38,9 +37,12 @@ const Astrocode = async (ctx) => {
         throw new Error("Astrocode requires ctx.directory to be a string repo root.");
     }
     const repoRoot = ctx.directory;
-    // Acquire exclusive repo lock to prevent multiple processes from corrupting the database
-    const lockPath = `${repoRoot}/.astro/astro.lock`;
-    const repoLock = acquireRepoLock(lockPath);
+    // NOTE: Repo locking is handled at the workflow level via workflowRepoLock.
+    // The workflow tool correctly acquires and holds the lock for the entire workflow execution.
+    // Plugin-level locking is unnecessary and architecturally incorrect since:
+    // - The lock would be held for the entire session lifecycle (too long)
+    // - Individual tools are designed to be called within workflow context where lock is held
+    // - Workflow-level locking with refcounting prevents lock churn during tool execution
     // Always load config first - this provides defaults even in limited mode
     let pluginConfig;
     try {
@@ -258,6 +260,10 @@ const Astrocode = async (ctx) => {
             return { args: nextArgs };
         },
         "tool.execute.after": async (input, output) => {
+            // Inject eligible injects after tool execution (not just on chat messages)
+            if (injectProvider && hookEnabled("inject-provider")) {
+                await injectProvider.onToolAfter(input);
+            }
             // Truncate huge tool outputs to artifacts
             if (truncatorHook && hookEnabled("tool-output-truncator")) {
                 await truncatorHook(input, output ?? null);
@@ -284,8 +290,7 @@ const Astrocode = async (ctx) => {
         },
         // Best-effort cleanup
         close: async () => {
-            // Release repo lock first (important for process termination)
-            repoLock.release();
+            // Close database connection
             if (db && typeof db.close === "function") {
                 try {
                     db.close();

package/dist/src/state/repo-lock.d.ts

@@ -1,3 +1,34 @@
-export declare function acquireRepoLock(lockPath: string): {
+/**
+ * Acquire a repo-scoped lock with:
+ * - ✅ 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 declare function acquireRepoLock(opts: {
+    lockPath: string;
+    repoRoot: string;
+    sessionId?: string;
+    owner?: string;
+    retryMs?: number;
+    pollMs?: number;
+    pollMaxMs?: number;
+    staleMs?: number;
+    heartbeatMs?: number;
+    minWriteMs?: number;
+}): Promise<{
     release: () => void;
-};
+}>;
+/**
+ * Helper wrapper: always releases lock.
+ */
+export declare function withRepoLock<T>(opts: {
+    lockPath: string;
+    repoRoot: string;
+    sessionId?: string;
+    owner?: string;
+    fn: () => Promise<T>;
+}): Promise<T>;

package/dist/src/state/repo-lock.js

@@ -1,29 +1,502 @@
 // src/state/repo-lock.ts
 import fs from "node:fs";
 import path from "node:path";
-export function acquireRepoLock(lockPath) {
-    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
-    let fd;
+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;
+function nowISO() {
+    return new Date().toISOString();
+}
+function sleep(ms) {
+    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) {
     try {
-        fd = fs.openSync(lockPath, "wx"); // exclusive create
+        process.kill(pid, 0);
+        return true;
     }
-    catch (e) {
-        const msg = e?.code === "EEXIST"
-            ? `Astrocode lock is already held (${lockPath}). Another opencode process is running in this repo.`
-            : `Failed to acquire lock (${lockPath}): ${e?.message ?? String(e)}`;
-        throw new Error(msg);
+    catch (err) {
+        const code = err?.code;
+        if (code === "EPERM")
+            return true;
+        if (code === "ESRCH")
+            return false;
+        // Unknown: conservative = don't evict.
+        return true;
     }
-    fs.writeFileSync(fd, `${process.pid}\n`, "utf8");
-    return {
-        release: () => {
-            try {
-                fs.closeSync(fd);
+}
+function parseISOToMs(iso) {
+    const t = Date.parse(iso);
+    if (Number.isNaN(t))
+        return null;
+    return t;
+}
+function isStaleByAge(existing, staleMs) {
+    const updatedMs = parseISOToMs(existing.updated_at);
+    if (updatedMs === null)
+        return true;
+    return Date.now() - updatedMs > staleMs;
+}
+function safeUnlink(p) {
+    try {
+        fs.unlinkSync(p);
+    }
+    catch {
+        // 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) {
+    try {
+        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);
+            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;
+    }
+}
+/**
+ * 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) {
+    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, lock) {
+    const dir = path.dirname(lockPath);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmp = `${lockPath}.${process.pid}.${Date.now()}.${crypto.randomUUID()}.tmp`;
+    const body = JSON.stringify(lock); // compact JSON to reduce IO
+    fs.writeFileSync(tmp, body, "utf8");
+    let lastErr = null;
+    for (let i = 0; i < ATOMIC_REPLACE_RETRIES; i++) {
+        try {
+            fs.renameSync(tmp, lockPath);
+            fsyncDirBestEffort(dir);
+            return;
+        }
+        catch (err) {
+            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}`);
+}
+/**
+ * Atomic "create if not exists" using exclusive open.
+ */
+function tryCreateExclusiveFile(filePath, contentsUtf8) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    try {
+        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) {
+        if (err?.code === "EEXIST")
+            return false;
+        throw err;
+    }
+}
+function tryCreateRepoLockExclusive(lockPath, lock) {
+    return tryCreateExclusiveFile(lockPath, JSON.stringify(lock));
+}
+const ACTIVE_LOCKS = new Map();
+function cacheKey(lockPath, sessionId) {
+    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) {
+    let stopped = false;
+    let lastWriteAt = 0;
+    let timer = 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.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;
+                }
             }
-            catch { }
+        }
+        timer = setTimeout(tick, opts.heartbeatMs);
+        timer.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 {
-                fs.unlinkSync(lockPath);
+                ACTIVE_LOCKS.delete(key);
+                h.heartbeatStop();
+                h.releaseOnce();
+            }
+            catch {
+                // ignore
             }
-            catch { }
-        },
+        }
     };
+    process.once("exit", cleanup);
+    process.once("SIGINT", () => {
+        cleanup();
+        process.exit(130);
+    });
+    process.once("SIGTERM", () => {
+        cleanup();
+        process.exit(143);
+    });
+}
+/**
+ * Acquire a repo-scoped lock with:
+ * - ✅ 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) {
+    installExitHookOnce();
+    const { lockPath, repoRoot, sessionId, owner } = opts;
+    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.pid;
+    const startedAt = Date.now();
+    let pollMs = pollBaseMs;
+    while (true) {
+        const existing = readLock(lockPath);
+        // No lock (or unreadable/invalid) -> try create.
+        if (!existing) {
+            const now = nowISO();
+            const leaseId = crypto.randomUUID();
+            const candidate = {
+                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,
+            };
+            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));
+                };
+                const handle = {
+                    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();
+                        }
+                    },
+                };
+            }
+            // 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);
+                fsyncDirBestEffort(path.dirname(lockPath));
+            };
+            const handle = {
+                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));
+    }
+}
+/**
+ * Helper wrapper: always releases lock.
+ */
+export async function withRepoLock(opts) {
+    const handle = await acquireRepoLock({
+        lockPath: opts.lockPath,
+        repoRoot: opts.repoRoot,
+        sessionId: opts.sessionId,
+        owner: opts.owner,
+    });
+    try {
+        return await opts.fn();
+    }
+    finally {
+        handle.release();
+    }
 }

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

@@ -0,0 +1,16 @@
+import type { acquireRepoLock } from "./repo-lock";
+type RepoLockAcquire = typeof acquireRepoLock;
+/**
+ * Acquire ONCE per workflow/session in this process.
+ * Nested calls reuse the same held lock (no reacquire, no churn).
+ */
+export declare function workflowRepoLock<T>(deps: {
+    acquireRepoLock: RepoLockAcquire;
+}, opts: {
+    lockPath: string;
+    repoRoot: string;
+    sessionId?: string;
+    owner?: string;
+    fn: () => Promise<T>;
+}): Promise<T>;
+export {};

package/dist/src/state/workflow-repo-lock.js

@@ -0,0 +1,50 @@
+const HELD_BY_KEY = new Map();
+function key(lockPath, sessionId) {
+    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(deps, opts) {
+    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 = { 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/dist/src/tools/status.js

@@ -31,7 +31,7 @@ function stageIcon(status) {
     }
 }
 export function createAstroStatusTool(opts) {
-    const { config, db } = opts;
+    const { ctx, config, db } = opts;
     return tool({
         description: "Show a compact Astrocode status dashboard: active run/stage, pipeline, story board counts, and next action.",
         args: {

package/dist/src/tools/workflow.js

@@ -1,5 +1,6 @@
 // src/tools/workflow.ts
 import { tool } from "@opencode-ai/plugin/tool";
+import path from "node:path";
 import { withTx } from "../state/db";
 import { buildContextSnapshot } from "../workflow/context";
 import { decideNextAction, createRunForStory, startStage, completeRun, failRun, getActiveRun, EVENT_TYPES, } from "../workflow/state-machine";
@@ -10,6 +11,7 @@ import { newEventId } from "../state/ids";
 import { debug } from "../shared/log";
 import { createToastManager } from "../ui/toasts";
 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 = {
     frame: "Frame",
@@ -156,200 +158,201 @@ export function createAstroWorkflowProceedTool(opts) {
             max_steps: tool.schema.number().int().positive().default(config.workflow.default_max_steps),
         },
         execute: async ({ mode, max_steps }) => {
-            // Acquire repo lock to ensure no concurrent workflow operations
-            const lockPath = `${ctx.directory}/.astro/astro.lock`;
-            const repoLock = acquireRepoLock(lockPath);
-            try {
-                const sessionId = ctx.sessionID;
-                const steps = Math.min(max_steps, config.workflow.loop_max_steps_hard_cap);
-                const actions = [];
-                const warnings = [];
-                const startedAt = nowISO();
-                // Collect UI events emitted inside state-machine functions, then flush AFTER tx.
-                const uiEvents = [];
-                const emit = (e) => uiEvents.push(e);
-                for (let i = 0; i < steps; i++) {
-                    const next = decideNextAction(db, config);
-                    if (next.kind === "idle") {
-                        actions.push("idle: no approved stories");
-                        break;
-                    }
-                    if (next.kind === "start_run") {
-                        // SINGLE tx boundary: caller owns tx, state-machine is pure.
-                        const { run_id } = withTx(db, () => createRunForStory(db, config, next.story_key));
-                        actions.push(`started run ${run_id} for story ${next.story_key}`);
-                        if (mode === "step")
-                            break;
-                        continue;
-                    }
-                    if (next.kind === "complete_run") {
-                        withTx(db, () => completeRun(db, next.run_id, emit));
-                        actions.push(`completed run ${next.run_id}`);
-                        if (mode === "step")
+            const repoRoot = ctx.directory;
+            const lockPath = path.join(repoRoot, ".astro", "astro.lock");
+            const sessionId = ctx.sessionID;
+            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 = [];
+                    const warnings = [];
+                    const startedAt = nowISO();
+                    // Collect UI events emitted inside state-machine functions, then flush AFTER tx.
+                    const uiEvents = [];
+                    const emit = (e) => uiEvents.push(e);
+                    for (let i = 0; i < steps; i++) {
+                        const next = decideNextAction(db, config);
+                        if (next.kind === "idle") {
+                            actions.push("idle: no approved stories");
                             break;
-                        continue;
-                    }
-                    if (next.kind === "failed") {
-                        // Ensure DB state reflects failure in one tx; emit UI event.
-                        withTx(db, () => failRun(db, next.run_id, next.stage_key, next.error_text, emit));
-                        actions.push(`failed: ${next.stage_key} — ${next.error_text}`);
-                        if (mode === "step")
-                            break;
-                        continue;
-                    }
-                    if (next.kind === "delegate_stage") {
-                        const active = getActiveRun(db);
-                        if (!active)
-                            throw new Error("Invariant: delegate_stage but no active run.");
-                        const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(active.run_id);
-                        const story = db.prepare("SELECT * FROM stories WHERE story_key=?").get(run.story_key);
-                        let agentName = resolveAgentName(next.stage_key, config, agents, warnings);
-                        const agentExists = (name) => {
-                            if (agents && agents[name])
-                                return true;
-                            const knownStageAgents = ["Frame", "Plan", "Spec", "Implement", "Review", "Verify", "Close", "General", "Astro", "general"];
-                            if (knownStageAgents.includes(name))
-                                return true;
-                            return false;
-                        };
-                        if (!agentExists(agentName)) {
-                            const originalAgent = agentName;
-                            console.warn(`[Astrocode] Agent ${agentName} not found. Falling back to orchestrator.`);
-                            agentName = config.agents?.orchestrator_name || "Astro";
+                        }
+                        if (next.kind === "start_run") {
+                            // SINGLE tx boundary: caller owns tx, state-machine is pure.
+                            const { run_id } = withTx(db, () => createRunForStory(db, config, next.story_key));
+                            actions.push(`started run ${run_id} for story ${next.story_key}`);
+                            if (mode === "step")
+                                break;
+                            continue;
+                        }
+                        if (next.kind === "complete_run") {
+                            withTx(db, () => completeRun(db, next.run_id, emit));
+                            actions.push(`completed run ${next.run_id}`);
+                            if (mode === "step")
+                                break;
+                            continue;
+                        }
+                        if (next.kind === "failed") {
+                            // Ensure DB state reflects failure in one tx; emit UI event.
+                            withTx(db, () => failRun(db, next.run_id, next.stage_key, next.error_text, emit));
+                            actions.push(`failed: ${next.stage_key} — ${next.error_text}`);
+                            if (mode === "step")
+                                break;
+                            continue;
+                        }
+                        if (next.kind === "delegate_stage") {
+                            const active = getActiveRun(db);
+                            if (!active)
+                                throw new Error("Invariant: delegate_stage but no active run.");
+                            const run = db.prepare("SELECT * FROM runs WHERE run_id=?").get(active.run_id);
+                            const story = db.prepare("SELECT * FROM stories WHERE story_key=?").get(run.story_key);
+                            let agentName = resolveAgentName(next.stage_key, config, agents, warnings);
+                            const agentExists = (name) => {
+                                if (agents && agents[name])
+                                    return true;
+                                const knownStageAgents = ["Frame", "Plan", "Spec", "Implement", "Review", "Verify", "Close", "General", "Astro", "general"];
+                                if (knownStageAgents.includes(name))
+                                    return true;
+                                return false;
+                            };
                             if (!agentExists(agentName)) {
-                                console.warn(`[Astrocode] Orchestrator ${agentName} not available. Falling back to General.`);
-                                agentName = "General";
+                                const originalAgent = agentName;
+                                console.warn(`[Astrocode] Agent ${agentName} not found. Falling back to orchestrator.`);
+                                agentName = config.agents?.orchestrator_name || "Astro";
                                 if (!agentExists(agentName)) {
-                                    throw new Error(`Critical: No agents available for delegation. Primary: ${originalAgent}, Orchestrator: ${config.agents?.orchestrator_name || "Astro"}, General: unavailable`);
+                                    console.warn(`[Astrocode] Orchestrator ${agentName} not available. Falling back to General.`);
+                                    agentName = "General";
+                                    if (!agentExists(agentName)) {
+                                        throw new Error(`Critical: No agents available for delegation. Primary: ${originalAgent}, Orchestrator: ${config.agents?.orchestrator_name || "Astro"}, General: unavailable`);
+                                    }
                                 }
                             }
-                        }
-                        // NOTE: startStage owns its own tx (state-machine.ts).
-                        withTx(db, () => {
-                            startStage(db, active.run_id, next.stage_key, { subagent_type: agentName }, emit);
-                        });
-                        const context = buildContextSnapshot({
-                            db,
-                            config,
-                            run_id: active.run_id,
-                            next_action: `delegate stage ${next.stage_key}`,
-                        });
-                        const stageDirective = buildStageDirective({
-                            config,
-                            stage_key: next.stage_key,
-                            run_id: active.run_id,
-                            story_key: run.story_key,
-                            story_title: story?.title ?? "(missing)",
-                            stage_agent_name: agentName,
-                            stage_goal: stageGoal(next.stage_key, config),
-                            stage_constraints: stageConstraints(next.stage_key, config),
-                            context_snapshot_md: context,
-                        }).body;
-                        const delegatePrompt = buildDelegationPrompt({
-                            stageDirective,
-                            run_id: active.run_id,
-                            stage_key: next.stage_key,
-                            stage_agent_name: agentName,
-                        });
-                        // Record continuation (best-effort; no tx wrapper needed but safe either way)
-                        const h = directiveHash(delegatePrompt);
-                        const now = nowISO();
-                        if (sessionId) {
-                            // This assumes continuations table exists in vNext schema.
-                            db.prepare("INSERT INTO continuations (session_id, run_id, directive_hash, kind, reason, created_at) VALUES (?, ?, ?, 'stage', ?, ?)").run(sessionId, active.run_id, h, `delegate ${next.stage_key}`, now);
-                        }
-                        // Visible injection so user can see state (awaited)
-                        if (sessionId) {
-                            await injectChatPrompt({ ctx, sessionId, text: delegatePrompt, agent: "Astro" });
-                            const continueMessage = [
-                                `[SYSTEM DIRECTIVE: ASTROCODE — AWAIT_STAGE_COMPLETION]`,
-                                ``,
-                                `Stage \`${next.stage_key}\` delegated to \`${agentName}\`.`,
-                                ``,
-                                `When \`${agentName}\` completes, call:`,
-                                `astro_stage_complete(run_id="${active.run_id}", stage_key="${next.stage_key}", output_text="[paste subagent output here]")`,
-                                ``,
-                                `This advances the workflow.`,
-                            ].join("\n");
-                            await injectChatPrompt({ ctx, sessionId, text: continueMessage, agent: "Astro" });
-                        }
-                        actions.push(`delegated stage ${next.stage_key} via ${agentName}`);
-                        // Stop here; subagent needs to run.
-                        break;
-                    }
-                    if (next.kind === "await_stage_completion") {
-                        actions.push(`await stage completion: ${next.stage_key}`);
-                        if (sessionId) {
+                            // NOTE: startStage owns its own tx (state-machine.ts).
+                            withTx(db, () => {
+                                startStage(db, active.run_id, next.stage_key, { subagent_type: agentName }, emit);
+                            });
                             const context = buildContextSnapshot({
                                 db,
                                 config,
-                                run_id: next.run_id,
-                                next_action: `complete stage ${next.stage_key}`,
+                                run_id: active.run_id,
+                                next_action: `delegate stage ${next.stage_key}`,
+                            });
+                            const stageDirective = buildStageDirective({
+                                config,
+                                stage_key: next.stage_key,
+                                run_id: active.run_id,
+                                story_key: run.story_key,
+                                story_title: story?.title ?? "(missing)",
+                                stage_agent_name: agentName,
+                                stage_goal: stageGoal(next.stage_key, config),
+                                stage_constraints: stageConstraints(next.stage_key, config),
+                                context_snapshot_md: context,
+                            }).body;
+                            const delegatePrompt = buildDelegationPrompt({
+                                stageDirective,
+                                run_id: active.run_id,
+                                stage_key: next.stage_key,
+                                stage_agent_name: agentName,
                             });
-                            const prompt = [
-                                `[SYSTEM DIRECTIVE: ASTROCODE — AWAIT_STAGE_OUTPUT]`,
-                                ``,
-                                `Run \`${next.run_id}\` is waiting for stage \`${next.stage_key}\` output.`,
-                                `If you have the subagent output, call astro_stage_complete with output_text=the FULL output.`,
-                                ``,
-                                `Context snapshot:`,
-                                context,
-                            ].join("\n").trim();
-                            const h = directiveHash(prompt);
+                            // Record continuation (best-effort; no tx wrapper needed but safe either way)
+                            const h = directiveHash(delegatePrompt);
                             const now = nowISO();
-                            db.prepare("INSERT INTO continuations (session_id, run_id, directive_hash, kind, reason, created_at) VALUES (?, ?, ?, 'continue', ?, ?)").run(sessionId, next.run_id, h, `await ${next.stage_key}`, now);
-                            await injectChatPrompt({ ctx, sessionId, text: prompt, agent: "Astro" });
+                            if (sessionId) {
+                                // This assumes continuations table exists in vNext schema.
+                                db.prepare("INSERT INTO continuations (session_id, run_id, directive_hash, kind, reason, created_at) VALUES (?, ?, ?, 'stage', ?, ?)").run(sessionId, active.run_id, h, `delegate ${next.stage_key}`, now);
+                            }
+                            // Visible injection so user can see state (awaited)
+                            if (sessionId) {
+                                await injectChatPrompt({ ctx, sessionId, text: delegatePrompt, agent: "Astro" });
+                                const continueMessage = [
+                                    `[SYSTEM DIRECTIVE: ASTROCODE — AWAIT_STAGE_COMPLETION]`,
+                                    ``,
+                                    `Stage \`${next.stage_key}\` delegated to \`${agentName}\`.`,
+                                    ``,
+                                    `When \`${agentName}\` completes, call:`,
+                                    `astro_stage_complete(run_id="${active.run_id}", stage_key="${next.stage_key}", output_text="[paste subagent output here]")`,
+                                    ``,
+                                    `This advances the workflow.`,
+                                ].join("\n");
+                                await injectChatPrompt({ ctx, sessionId, text: continueMessage, agent: "Astro" });
+                            }
+                            actions.push(`delegated stage ${next.stage_key} via ${agentName}`);
+                            // Stop here; subagent needs to run.
+                            break;
                         }
+                        if (next.kind === "await_stage_completion") {
+                            actions.push(`await stage completion: ${next.stage_key}`);
+                            if (sessionId) {
+                                const context = buildContextSnapshot({
+                                    db,
+                                    config,
+                                    run_id: next.run_id,
+                                    next_action: `complete stage ${next.stage_key}`,
+                                });
+                                const prompt = [
+                                    `[SYSTEM DIRECTIVE: ASTROCODE — AWAIT_STAGE_OUTPUT]`,
+                                    ``,
+                                    `Run \`${next.run_id}\` is waiting for stage \`${next.stage_key}\` output.`,
+                                    `If you have the subagent output, call astro_stage_complete with output_text=the FULL output.`,
+                                    ``,
+                                    `Context snapshot:`,
+                                    context,
+                                ].join("\n").trim();
+                                const h = directiveHash(prompt);
+                                const now = nowISO();
+                                db.prepare("INSERT INTO continuations (session_id, run_id, directive_hash, kind, reason, created_at) VALUES (?, ?, ?, 'continue', ?, ?)").run(sessionId, next.run_id, h, `await ${next.stage_key}`, now);
+                                await injectChatPrompt({ ctx, sessionId, text: prompt, agent: "Astro" });
+                            }
+                            break;
+                        }
+                        actions.push(`unhandled next action: ${next.kind}`);
                         break;
                     }
-                    actions.push(`unhandled next action: ${next.kind}`);
-                    break;
-                }
-                // Flush UI events (toast + prompt) AFTER state transitions
-                if (uiEvents.length > 0) {
-                    for (const e of uiEvents) {
-                        const msg = buildUiMessage(e);
-                        if (config.ui.toasts.enabled) {
-                            await toasts.show({
-                                title: msg.title,
-                                message: msg.message,
-                                variant: msg.variant,
-                            });
-                        }
-                        if (ctx?.sessionID) {
-                            await injectChatPrompt({
-                                ctx,
-                                sessionId: ctx.sessionID,
-                                text: msg.chatText,
-                                agent: "Astro",
-                            });
+                    // Flush UI events (toast + prompt) AFTER state transitions
+                    if (uiEvents.length > 0) {
+                        for (const e of uiEvents) {
+                            const msg = buildUiMessage(e);
+                            if (config.ui.toasts.enabled) {
+                                await toasts.show({
+                                    title: msg.title,
+                                    message: msg.message,
+                                    variant: msg.variant,
+                                });
+                            }
+                            if (ctx?.sessionID) {
+                                await injectChatPrompt({
+                                    ctx,
+                                    sessionId: ctx.sessionID,
+                                    text: msg.chatText,
+                                    agent: "Astro",
+                                });
+                            }
                         }
+                        actions.push(`ui: flushed ${uiEvents.length} event(s)`);
+                    }
+                    // Housekeeping event
+                    db.prepare("INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, NULL, NULL, ?, ?, ?)").run(newEventId(), EVENT_TYPES.WORKFLOW_PROCEED, JSON.stringify({ started_at: startedAt, mode, max_steps: steps, actions }), nowISO());
+                    const active = getActiveRun(db);
+                    const lines = [];
+                    lines.push(`# astro_workflow_proceed`);
+                    lines.push(`- mode: ${mode}`);
+                    lines.push(`- steps requested: ${max_steps} (cap=${steps})`);
+                    if (active)
+                        lines.push(`- active run: \`${active.run_id}\` (stage=${active.current_stage_key ?? "?"})`);
+                    lines.push(``, `## Actions`);
+                    for (const a of actions)
+                        lines.push(`- ${a}`);
+                    if (warnings.length > 0) {
+                        lines.push(``, `## Warnings`);
+                        for (const w of warnings)
+                            lines.push(`⚠️ ${w}`);
                     }
-                    actions.push(`ui: flushed ${uiEvents.length} event(s)`);
-                }
-                // Housekeeping event
-                db.prepare("INSERT INTO events (event_id, run_id, stage_key, type, body_json, created_at) VALUES (?, NULL, NULL, ?, ?, ?)").run(newEventId(), EVENT_TYPES.WORKFLOW_PROCEED, JSON.stringify({ started_at: startedAt, mode, max_steps: steps, actions }), nowISO());
-                const active = getActiveRun(db);
-                const lines = [];
-                lines.push(`# astro_workflow_proceed`);
-                lines.push(`- mode: ${mode}`);
-                lines.push(`- steps requested: ${max_steps} (cap=${steps})`);
-                if (active)
-                    lines.push(`- active run: \`${active.run_id}\` (stage=${active.current_stage_key ?? "?"})`);
-                lines.push(``, `## Actions`);
-                for (const a of actions)
-                    lines.push(`- ${a}`);
-                if (warnings.length > 0) {
-                    lines.push(``, `## Warnings`);
-                    for (const w of warnings)
-                        lines.push(`⚠️ ${w}`);
-                }
-                return lines.join("\n").trim();
-            }
-            finally {
-                // Always release the lock
-                repoLock.release();
-            }
+                    return lines.join("\n").trim();
+                },
+            });
         },
     });
 }

package/package.json

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

package/src/hooks/inject-provider.ts

@@ -9,6 +9,11 @@ type ChatMessageInput = {
   agent: string;
 };
 
+type ToolExecuteAfterInput = {
+  tool: string;
+  sessionID?: string;
+};
+
 type RuntimeState = {
   db: SqliteDb | null;
   limitedMode: boolean;
@@ -156,5 +161,16 @@ export function createInjectProvider(opts: {
       // Inject eligible injects before processing the user's message
       await injectEligibleInjects(input.sessionID);
     },
+
+    async onToolAfter(input: ToolExecuteAfterInput) {
+      if (!config.inject?.enabled) return;
+
+      // Extract sessionID (same pattern as continuation enforcer)
+      const sessionId = input.sessionID ?? (ctx as any).sessionID;
+      if (!sessionId) return;
+
+      // Inject eligible injects after tool execution
+      await injectEligibleInjects(sessionId);
+    },
   };
 }

package/src/index.ts

@@ -13,7 +13,6 @@ import { createToastManager, type ToastOptions } from "./ui/toasts";
 import { createAstroAgents } from "./agents/registry";
 import type { AgentConfig } from "@opencode-ai/sdk";
 import { info, warn } from "./shared/log";
-import { acquireRepoLock } from "./state/repo-lock";
 
 // Type definitions for plugin components
 type ConfigHandler = (config: Record<string, any>) => Promise<void>;
@@ -25,6 +24,7 @@ type ContinuationEnforcer = {
 type ToolOutputTruncator = (input: any, output: any | null) => Promise<void>;
 type InjectProvider = {
   onChatMessage: (input: any) => Promise<void>;
+  onToolAfter: (input: any) => Promise<void>;
 };
 type ToastManager = {
   show: (toast: ToastOptions) => Promise<void>;
@@ -59,9 +59,12 @@ const Astrocode: Plugin = async (ctx) => {
   }
   const repoRoot = ctx.directory;
 
-  // Acquire exclusive repo lock to prevent multiple processes from corrupting the database
-  const lockPath = `${repoRoot}/.astro/astro.lock`;
-  const repoLock = acquireRepoLock(lockPath);
+  // NOTE: Repo locking is handled at the workflow level via workflowRepoLock.
+  // The workflow tool correctly acquires and holds the lock for the entire workflow execution.
+  // Plugin-level locking is unnecessary and architecturally incorrect since:
+  // - The lock would be held for the entire session lifecycle (too long)
+  // - Individual tools are designed to be called within workflow context where lock is held
+  // - Workflow-level locking with refcounting prevents lock churn during tool execution
 
   // Always load config first - this provides defaults even in limited mode
   let pluginConfig: AstrocodeConfig;
@@ -299,6 +302,11 @@ const Astrocode: Plugin = async (ctx) => {
     },
 
     "tool.execute.after": async (input: any, output: any) => {
+      // Inject eligible injects after tool execution (not just on chat messages)
+      if (injectProvider && hookEnabled("inject-provider")) {
+        await injectProvider.onToolAfter(input);
+      }
+
       // Truncate huge tool outputs to artifacts
       if (truncatorHook && hookEnabled("tool-output-truncator")) {
         await truncatorHook(input, output ?? null);
@@ -330,9 +338,7 @@ const Astrocode: Plugin = async (ctx) => {
 
     // Best-effort cleanup
     close: async () => {
-      // Release repo lock first (important for process termination)
-      repoLock.release();
-
+      // Close database connection
       if (db && typeof db.close === "function") {
         try {
           db.close();