astrocode-workflow 0.3.3 → 0.3.5

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.3",
+  "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();

package/src/state/repo-lock.ts

@@ -83,6 +83,7 @@ function safeUnlink(p: string) {
 
 /**
  * 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 {
@@ -91,23 +92,46 @@ function readLock(lockPath: string): LockFile | null {
     if (!st.isFile()) return null;
     if (st.size <= 0 || st.size > MAX_LOCK_BYTES) return null;
 
-    const raw = fs.readFileSync(lockPath, "utf8");
-    const parsed = JSON.parse(raw) as LockFile;
+    const raw = fs.readFileSync(lockPath, "utf8").trim();
 
-    if (!parsed) return null;
-    if (parsed.v !== LOCK_VERSION) return null;
-
-    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;
+    // 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
+    }
 
-    if (parsed.session_id !== undefined && typeof parsed.session_id !== "string") return null;
-    if (parsed.owner !== undefined && typeof parsed.owner !== "string") return null;
+    // Legacy format: just PID as number string
+    const legacyPid = parseInt(raw, 10);
+    if (Number.isNaN(legacyPid) || legacyPid <= 0) return null;
 
-    return parsed;
+    // 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;
   }
@@ -453,8 +477,8 @@ export async function acquireRepoLock(opts: {
       continue;
     }
 
-    // Re-entrant by SAME PROCESS IDENTITY (pid+instance).
-    if (existing.pid === myPid && existing.instance_id === PROCESS_INSTANCE_ID) {
+    // 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, {
@@ -462,6 +486,7 @@ export async function acquireRepoLock(opts: {
         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,