@caseyharalson/orrery 0.11.0 → 0.13.0

package/lib/orchestration/index.js

@@ -13,6 +13,7 @@
  * - When complete, a PR is created and orchestrator returns to source branch
  */
 
+const { execSync } = require("child_process");
 const fs = require("fs");
 const path = require("path");
 const YAML = require("yaml");
@@ -49,8 +50,10 @@ const {
   commit,
   createPullRequest,
   deriveBranchName,
+  derivePlanId,
   hasUncommittedChanges,
   addWorktree,
+  addWorktreeExistingBranch,
   removeWorktree,
   getCommitRange,
   cherryPick,
@@ -62,7 +65,8 @@ const config = require("./config");
 const {
   getPlansDir,
   getCompletedDir,
-  getReportsDir
+  getReportsDir,
+  isWorkDirExternal
 } = require("../utils/paths");
 
 const {
@@ -72,6 +76,7 @@ const {
 } = require("./condensed-plan");
 
 const { ProgressTracker } = require("./progress-tracker");
+const { acquireLock, releaseLock } = require("../utils/lock");
 
 const REPO_ROOT = process.cwd();
 
@@ -262,7 +267,8 @@ async function orchestrate(options = {}) {
     verbose: Boolean(options.verbose),
     resume: Boolean(options.resume),
     review: options.review,
-    parallel: options.parallel
+    parallel: options.parallel,
+    onComplete: options.onComplete || null
   };
 
   config.logging.streamOutput = normalizedOptions.verbose;
@@ -277,140 +283,377 @@ async function orchestrate(options = {}) {
     );
   }
 
-  console.log("=== Plan Orchestrator Starting ===\n");
+  // Per-plan worktree mode: when --plan is specified without --resume,
+  // use per-plan lock and worktree isolation for concurrent execution
+  if (
+    normalizedOptions.plan &&
+    !normalizedOptions.resume &&
+    !normalizedOptions.dryRun
+  ) {
+    await processPlanInWorktree(normalizedOptions);
+    return;
+  }
 
-  const plansDir = getPlansDir();
-  const completedDir = getCompletedDir();
-  const reportsDir = getReportsDir();
+  // Per-plan worktree resume: when --plan + --resume, check for existing worktree
+  if (
+    normalizedOptions.plan &&
+    normalizedOptions.resume &&
+    !normalizedOptions.dryRun
+  ) {
+    const plansDir = getPlansDir();
+    const resolved = resolvePlanFile(normalizedOptions.plan, plansDir);
+    if (resolved) {
+      const planId = derivePlanId(path.basename(resolved));
+      const worktreePath = path.join(REPO_ROOT, ".worktrees", `plan-${planId}`);
+      if (fs.existsSync(worktreePath)) {
+        const plan = loadPlan(resolved);
+        const completedDir = getCompletedDir();
+        const reportsDir = getReportsDir();
+        await resumeInWorktree(
+          resolved,
+          plan,
+          planId,
+          worktreePath,
+          completedDir,
+          reportsDir,
+          normalizedOptions.onComplete
+        );
+        return;
+      }
+    }
+    // No worktree found — fall through to existing global-lock resume path
+  }
 
-  // Record the source branch we're starting from
-  const sourceBranch = getCurrentBranch(REPO_ROOT);
-  console.log(`Source branch: ${sourceBranch}\n`);
+  // Acquire global execution lock (skip for dry-run)
+  if (!normalizedOptions.dryRun) {
+    const lockResult = acquireLock();
+    if (!lockResult.acquired) {
+      console.error(`Cannot start: ${lockResult.reason}`);
+      process.exitCode = 1;
+      return;
+    }
 
-  // Check for uncommitted changes
-  if (hasUncommittedChanges(REPO_ROOT)) {
-    console.error(
-      "Error: Uncommitted changes detected. Please commit or stash before running orchestrator."
-    );
-    process.exit(1);
+    // Clean up lock on signals
+    const cleanupLock = () => {
+      releaseLock();
+      process.exit();
+    };
+    process.on("SIGINT", cleanupLock);
+    process.on("SIGTERM", cleanupLock);
   }
 
-  // Resume mode: find and continue the plan for the current branch
-  if (normalizedOptions.resume) {
-    await handleResumeMode(plansDir, completedDir, reportsDir, sourceBranch);
-    return;
-  }
+  try {
+    console.log("=== Plan Orchestrator Starting ===\n");
 
-  // Get list of completed plan filenames (to exclude)
-  const completedNames = getCompletedPlanNames(completedDir);
+    const plansDir = getPlansDir();
+    const completedDir = getCompletedDir();
+    const reportsDir = getReportsDir();
 
-  let planFiles = [];
-  let allPlanFiles = [];
+    // Get list of completed plan filenames (to exclude)
+    const completedNames = getCompletedPlanNames(completedDir);
 
-  if (normalizedOptions.plan) {
-    const resolvedPlanFile = resolvePlanFile(normalizedOptions.plan, plansDir);
-    if (!resolvedPlanFile) {
-      console.error(`Plan file not found: ${normalizedOptions.plan}`);
-      process.exit(1);
+    let planFiles = [];
+    let allPlanFiles = [];
+
+    if (normalizedOptions.plan) {
+      const resolvedPlanFile = resolvePlanFile(
+        normalizedOptions.plan,
+        plansDir
+      );
+      if (!resolvedPlanFile) {
+        console.error(`Plan file not found: ${normalizedOptions.plan}`);
+        process.exit(1);
+      }
+      if (completedNames.has(path.basename(resolvedPlanFile))) {
+        console.log(
+          `Plan already completed: ${path.basename(resolvedPlanFile)}`
+        );
+        return;
+      }
+      allPlanFiles = [resolvedPlanFile];
+    } else {
+      // Scan for active plans
+      allPlanFiles = getPlanFiles(plansDir).filter(
+        (f) => !completedNames.has(path.basename(f))
+      );
+    }
+
+    // Filter out plans that are already dispatched (have work_branch set)
+    const dispatchedPlans = [];
+
+    for (const planFile of allPlanFiles) {
+      const plan = loadPlan(planFile);
+      if (plan.metadata.work_branch) {
+        dispatchedPlans.push({
+          file: path.basename(planFile),
+          workBranch: plan.metadata.work_branch
+        });
+      } else {
+        planFiles.push(planFile);
+      }
+    }
+
+    if (dispatchedPlans.length > 0) {
+      console.log(
+        `Skipping ${dispatchedPlans.length} already-dispatched plan(s):`
+      );
+      for (const dp of dispatchedPlans) {
+        console.log(`  - ${dp.file} (work branch: ${dp.workBranch})`);
+      }
+      console.log();
+    }
+
+    if (planFiles.length === 0) {
+      console.log(
+        `No new plans to process in ${path.relative(process.cwd(), plansDir)}/`
+      );
+      console.log(
+        "Create a plan file without work_branch metadata to get started."
+      );
+      return;
     }
-    if (completedNames.has(path.basename(resolvedPlanFile))) {
-      console.log(`Plan already completed: ${path.basename(resolvedPlanFile)}`);
+
+    if (normalizedOptions.dryRun) {
+      logDryRunSummary(planFiles);
       return;
     }
-    allPlanFiles = [resolvedPlanFile];
-  } else {
-    // Scan for active plans
-    allPlanFiles = getPlanFiles(plansDir).filter(
-      (f) => !completedNames.has(path.basename(f))
-    );
-  }
 
-  // Filter out plans that are already dispatched (have work_branch set)
-  const dispatchedPlans = [];
+    // Record the source branch we're starting from
+    const sourceBranch = getCurrentBranch(REPO_ROOT);
+    console.log(`Source branch: ${sourceBranch}\n`);
 
-  for (const planFile of allPlanFiles) {
-    const plan = loadPlan(planFile);
-    if (plan.metadata.work_branch) {
-      dispatchedPlans.push({
-        file: path.basename(planFile),
-        workBranch: plan.metadata.work_branch
-      });
-    } else {
-      planFiles.push(planFile);
+    // Check for uncommitted changes
+    if (hasUncommittedChanges(REPO_ROOT)) {
+      console.error(
+        "Error: Uncommitted changes detected. Please commit or stash before running orchestrator."
+      );
+      process.exit(1);
     }
-  }
 
-  if (dispatchedPlans.length > 0) {
-    console.log(
-      `Skipping ${dispatchedPlans.length} already-dispatched plan(s):`
-    );
-    for (const dp of dispatchedPlans) {
-      console.log(`  - ${dp.file} (work branch: ${dp.workBranch})`);
+    // Resume mode: find and continue the plan for the current branch
+    if (normalizedOptions.resume) {
+      await handleResumeMode(
+        plansDir,
+        completedDir,
+        reportsDir,
+        sourceBranch,
+        normalizedOptions.plan,
+        normalizedOptions.onComplete
+      );
+      return;
+    }
+
+    console.log(`Found ${planFiles.length} plan(s) to process:\n`);
+    for (const pf of planFiles) {
+      console.log(`  - ${path.basename(pf)}`);
     }
     console.log();
-  }
 
-  if (planFiles.length === 0) {
-    console.log(
-      `No new plans to process in ${path.relative(process.cwd(), plansDir)}/`
-    );
-    console.log(
-      "Create a plan file without work_branch metadata to get started."
-    );
-    return;
+    // Process each plan (one at a time, with branch switching)
+    for (const planFile of planFiles) {
+      const result = await processPlanWithBranching(
+        planFile,
+        sourceBranch,
+        completedDir,
+        reportsDir,
+        parallelEnabled,
+        normalizedOptions.onComplete
+      );
+
+      if (result.isComplete && result.isSuccessful) {
+        // Plan completed successfully - return to source branch for next plan
+        const currentBranch = getCurrentBranch(REPO_ROOT);
+        if (currentBranch !== sourceBranch) {
+          console.log(`\nReturning to source branch: ${sourceBranch}`);
+          checkoutBranch(sourceBranch, REPO_ROOT);
+        }
+      } else {
+        // Plan is blocked - stay on work branch and stop processing
+        console.log(`\nPlan "${path.basename(planFile)}" is blocked.`);
+        console.log(`Staying on work branch: ${result.workBranch}`);
+        console.log("\nTo continue:");
+        console.log("  1. Fix the blocked steps (orrery status)");
+        console.log("  2. Run 'orrery resume' to unblock and continue");
+
+        // List remaining unprocessed plans
+        const remaining = planFiles.slice(planFiles.indexOf(planFile) + 1);
+        if (remaining.length > 0) {
+          console.log(`\nSkipped ${remaining.length} remaining plan(s).`);
+        }
+        break; // Stop processing
+      }
+    }
+
+    console.log("\n=== Orchestrator Complete ===");
+  } finally {
+    if (!normalizedOptions.dryRun) releaseLock();
   }
+}
 
-  if (normalizedOptions.dryRun) {
-    logDryRunSummary(planFiles);
+/**
+ * Resume a plan inside its existing worktree.
+ * @param {string} planFile - Resolved plan file path
+ * @param {Object} plan - Loaded plan object
+ * @param {string} planId - Plan ID for locking
+ * @param {string} worktreePath - Path to existing worktree
+ * @param {string} completedDir - Directory for completed plans
+ * @param {string} reportsDir - Directory for reports
+ */
+async function resumeInWorktree(
+  planFile,
+  plan,
+  planId,
+  worktreePath,
+  completedDir,
+  reportsDir,
+  onComplete
+) {
+  const planFileName = path.basename(planFile);
+
+  // Acquire per-plan lock
+  const lockResult = acquireLock(planId, { worktreePath });
+  if (!lockResult.acquired) {
+    console.error(`Cannot resume plan "${planId}": ${lockResult.reason}`);
+    process.exitCode = 1;
     return;
   }
 
-  console.log(`Found ${planFiles.length} plan(s) to process:\n`);
-  for (const pf of planFiles) {
-    console.log(`  - ${path.basename(pf)}`);
-  }
-  console.log();
+  const cleanupLock = () => {
+    releaseLock(planId);
+    process.exit();
+  };
+  process.on("SIGINT", cleanupLock);
+  process.on("SIGTERM", cleanupLock);
 
-  // Process each plan (one at a time, with branch switching)
-  for (const planFile of planFiles) {
-    await processPlanWithBranching(
-      planFile,
-      sourceBranch,
-      completedDir,
-      reportsDir,
-      parallelEnabled
+  try {
+    process.env.ORRERY_REPO_ROOT = REPO_ROOT;
+
+    console.log(`Found plan: ${planFileName}`);
+
+    if (plan.isComplete()) {
+      console.log("\nPlan is already complete (no pending steps).");
+      return;
+    }
+
+    const pendingSteps = plan.steps.filter((s) => s.status === "pending");
+    const inProgressSteps = plan.steps.filter(
+      (s) => s.status === "in_progress"
     );
+    console.log(`Pending steps: ${pendingSteps.length}`);
+    if (inProgressSteps.length > 0) {
+      console.log(
+        `In-progress steps (will be retried): ${inProgressSteps.length}`
+      );
+      for (const step of inProgressSteps) {
+        step.status = "pending";
+      }
+      savePlan(plan);
+    }
 
-    // Reload plan to check final state
-    const plan = loadPlan(planFile);
+    console.log("\nResuming plan execution in worktree...\n");
+
+    const parallelEnabled = resolveParallelEnabled(undefined);
+    if (parallelEnabled) {
+      config.concurrency.maxParallel = resolveParallelMax();
+      console.log(
+        `Parallel mode enabled (max ${config.concurrency.maxParallel} concurrent agents)`
+      );
+    }
+
+    const ctx = { workingDir: worktreePath, mainRepoRoot: REPO_ROOT };
+    await processPlan(planFile, completedDir, reportsDir, parallelEnabled, ctx);
+
+    // Reload and check final state
+    plan = loadPlan(planFile);
     const isComplete = plan.isComplete();
-    const isSuccessful = plan.isSuccessful();
 
-    if (isComplete && isSuccessful) {
-      // Plan completed successfully - return to source branch for next plan
-      const currentBranch = getCurrentBranch(REPO_ROOT);
-      if (currentBranch !== sourceBranch) {
-        console.log(`\nReturning to source branch: ${sourceBranch}`);
-        checkoutBranch(sourceBranch, REPO_ROOT);
+    if (isComplete) {
+      archivePlan(planFile, plan, completedDir);
+
+      const workCommit = commit(
+        `chore: complete plan ${planFileName}`,
+        [],
+        worktreePath
+      );
+      if (workCommit) {
+        console.log(`Committed plan completion (${workCommit.slice(0, 7)})`);
       }
-    } else {
-      // Plan is blocked - stay on work branch and stop processing
-      console.log(`\nPlan "${path.basename(planFile)}" is blocked.`);
-      console.log(`Staying on work branch: ${plan.metadata.work_branch}`);
-      console.log("\nTo continue:");
-      console.log("  1. Fix the blocked steps (orrery status)");
-      console.log("  2. Run 'orrery resume' to unblock and continue");
 
-      // List remaining unprocessed plans
-      const remaining = planFiles.slice(planFiles.indexOf(planFile) + 1);
-      if (remaining.length > 0) {
-        console.log(`\nSkipped ${remaining.length} remaining plan(s).`);
+      const sourceBranch = plan.metadata.source_branch || "main";
+      const prTitle = `Plan: ${planFileName.replace(/\.ya?ml$/, "").replace(/^\d{4}-\d{2}-\d{2}-/, "")}`;
+      const prBody = generatePRBody(plan);
+      const prInfo = createPullRequest(
+        prTitle,
+        prBody,
+        sourceBranch,
+        worktreePath
+      );
+      logPullRequestInfo(prInfo);
+
+      const isSuccessful = plan.isSuccessful();
+      runOnCompleteHook(
+        onComplete,
+        {
+          planName: planFileName,
+          planFile,
+          outcome: isSuccessful ? "success" : "partial",
+          workBranch: plan.metadata.work_branch || "",
+          sourceBranch,
+          prUrl: prInfo.url || "",
+          stepsTotal: plan.steps.length,
+          stepsCompleted: plan.steps.filter((s) => s.status === "complete")
+            .length,
+          stepsBlocked: plan.steps.filter((s) => s.status === "blocked").length
+        },
+        worktreePath
+      );
+
+      // Clean up worktree on success
+      try {
+        removeWorktree(worktreePath, REPO_ROOT);
+        console.log(`Cleaned up worktree: ${worktreePath}`);
+      } catch (err) {
+        console.error(`Failed to clean up worktree: ${err.message}`);
+      }
+    } else {
+      const progressCommit = commit(
+        `wip: progress on plan ${planFileName}`,
+        [],
+        worktreePath
+      );
+      if (progressCommit) {
+        console.log(
+          `Committed work-in-progress (${progressCommit.slice(0, 7)})`
+        );
       }
-      break; // Stop processing
+
+      runOnCompleteHook(
+        onComplete,
+        {
+          planName: planFileName,
+          planFile,
+          outcome: "incomplete",
+          workBranch: plan.metadata.work_branch || "",
+          sourceBranch: plan.metadata.source_branch || "main",
+          prUrl: "",
+          stepsTotal: plan.steps.length,
+          stepsCompleted: plan.steps.filter((s) => s.status === "complete")
+            .length,
+          stepsBlocked: plan.steps.filter((s) => s.status === "blocked").length
+        },
+        worktreePath
+      );
+
+      console.log(
+        "\nPlan still has pending steps. Run --resume again to continue."
+      );
     }
-  }
 
-  console.log("\n=== Orchestrator Complete ===");
+    console.log("\n=== Resume Complete ===");
+  } finally {
+    delete process.env.ORRERY_REPO_ROOT;
+    releaseLock(planId);
+  }
 }
 
 /**
@@ -420,36 +663,93 @@ async function handleResumeMode(
   plansDir,
   completedDir,
   reportsDir,
-  currentBranch
+  currentBranch,
+  planFileArg,
+  onComplete
 ) {
   console.log("=== Resume Mode ===\n");
-  console.log(`Looking for plan with work_branch: ${currentBranch}\n`);
 
-  // Get all plan files (including dispatched ones)
-  const completedNames = getCompletedPlanNames(completedDir);
-  const allPlanFiles = getPlanFiles(plansDir).filter(
-    (f) => !completedNames.has(path.basename(f))
-  );
-
-  // Find plan matching current branch
   let matchingPlanFile = null;
   let matchingPlan = null;
 
-  for (const planFile of allPlanFiles) {
-    const plan = loadPlan(planFile);
-    if (plan.metadata.work_branch === currentBranch) {
-      matchingPlanFile = planFile;
-      matchingPlan = plan;
-      break;
+  if (planFileArg) {
+    // Resolve the plan file from argument
+    const resolved = resolvePlanFile(planFileArg, plansDir);
+    if (!resolved) {
+      console.error(`Plan file not found: ${planFileArg}`);
+      process.exit(1);
     }
-  }
 
-  if (!matchingPlanFile) {
-    console.error(`No plan found with work_branch matching "${currentBranch}"`);
-    console.log("\nTo resume a plan:");
-    console.log("  1. git checkout <work-branch>");
-    console.log("  2. orrery exec --resume");
-    process.exit(1);
+    matchingPlan = loadPlan(resolved);
+    matchingPlanFile = resolved;
+
+    // Validate work_branch
+    if (!matchingPlan.metadata.work_branch) {
+      console.error("Plan has no work_branch — it hasn't been dispatched yet.");
+      console.log(
+        "\nUse 'orrery exec --plan <file>' to dispatch the plan first."
+      );
+      process.exit(1);
+    }
+
+    // Check for existing worktree for this plan
+    const planId = derivePlanId(path.basename(resolved));
+    const worktreePath = path.join(REPO_ROOT, ".worktrees", `plan-${planId}`);
+    if (fs.existsSync(worktreePath)) {
+      // Resume in worktree mode
+      console.log(`Found existing worktree: ${worktreePath}`);
+      console.log(`Using specified plan: ${path.basename(resolved)}\n`);
+      await resumeInWorktree(
+        resolved,
+        matchingPlan,
+        planId,
+        worktreePath,
+        completedDir,
+        reportsDir,
+        onComplete
+      );
+      return;
+    }
+
+    if (matchingPlan.metadata.work_branch !== currentBranch) {
+      console.error(
+        `Plan expects branch '${matchingPlan.metadata.work_branch}' but you are on '${currentBranch}'.`
+      );
+      console.log(`\nRun: git checkout ${matchingPlan.metadata.work_branch}`);
+      process.exit(1);
+    }
+
+    console.log(`Using specified plan: ${path.basename(resolved)}\n`);
+  } else {
+    console.log(`Looking for plan with work_branch: ${currentBranch}\n`);
+
+    // Get all plan files (including dispatched ones)
+    const completedNames = getCompletedPlanNames(completedDir);
+    const allPlanFiles = getPlanFiles(plansDir).filter(
+      (f) => !completedNames.has(path.basename(f))
+    );
+
+    // Find plan matching current branch
+    for (const planFile of allPlanFiles) {
+      const plan = loadPlan(planFile);
+      if (plan.metadata.work_branch === currentBranch) {
+        matchingPlanFile = planFile;
+        matchingPlan = plan;
+        break;
+      }
+    }
+
+    if (!matchingPlanFile) {
+      console.error(
+        `No plan found with work_branch matching "${currentBranch}"`
+      );
+      console.log("\nTo resume a plan:");
+      console.log("  1. git checkout <work-branch>");
+      console.log("  2. orrery exec --resume");
+      console.log("\nOr specify a plan directly:");
+      console.log("  orrery exec --resume --plan <file>");
+      process.exit(1);
+    }
   }
 
   const planFileName = path.basename(matchingPlanFile);
@@ -518,6 +818,26 @@ async function handleResumeMode(
     const prBody = generatePRBody(matchingPlan);
     const prInfo = createPullRequest(prTitle, prBody, sourceBranch, REPO_ROOT);
     logPullRequestInfo(prInfo);
+
+    const isSuccessful = matchingPlan.isSuccessful();
+    runOnCompleteHook(
+      onComplete,
+      {
+        planName: planFileName,
+        planFile: matchingPlanFile,
+        outcome: isSuccessful ? "success" : "partial",
+        workBranch: matchingPlan.metadata.work_branch || currentBranch,
+        sourceBranch,
+        prUrl: prInfo.url || "",
+        stepsTotal: matchingPlan.steps.length,
+        stepsCompleted: matchingPlan.steps.filter(
+          (s) => s.status === "complete"
+        ).length,
+        stepsBlocked: matchingPlan.steps.filter((s) => s.status === "blocked")
+          .length
+      },
+      REPO_ROOT
+    );
   } else {
     const progressCommit = commit(
       `wip: progress on plan ${planFileName}`,
@@ -527,6 +847,26 @@ async function handleResumeMode(
     if (progressCommit) {
       console.log(`Committed work-in-progress (${progressCommit.slice(0, 7)})`);
     }
+
+    runOnCompleteHook(
+      onComplete,
+      {
+        planName: planFileName,
+        planFile: matchingPlanFile,
+        outcome: "incomplete",
+        workBranch: matchingPlan.metadata.work_branch || currentBranch,
+        sourceBranch: matchingPlan.metadata.source_branch || "main",
+        prUrl: "",
+        stepsTotal: matchingPlan.steps.length,
+        stepsCompleted: matchingPlan.steps.filter(
+          (s) => s.status === "complete"
+        ).length,
+        stepsBlocked: matchingPlan.steps.filter((s) => s.status === "blocked")
+          .length
+      },
+      REPO_ROOT
+    );
+
     console.log(
       "\nPlan still has pending steps. Run --resume again to continue."
     );
@@ -535,6 +875,235 @@ async function handleResumeMode(
   console.log("\n=== Resume Complete ===");
 }
 
+/**
+ * Process a single plan in an isolated git worktree.
+ * Uses per-plan locking to allow concurrent execution of multiple plans.
+ * @param {Object} normalizedOptions - Normalized orchestration options
+ */
+async function processPlanInWorktree(normalizedOptions) {
+  const plansDir = getPlansDir();
+  const completedDir = getCompletedDir();
+  const reportsDir = getReportsDir();
+
+  // Handle parallel mode configuration
+  const parallelEnabled = resolveParallelEnabled(normalizedOptions.parallel);
+  if (parallelEnabled) {
+    config.concurrency.maxParallel = resolveParallelMax();
+  }
+
+  // Resolve the plan file
+  const resolvedPlanFile = resolvePlanFile(normalizedOptions.plan, plansDir);
+  if (!resolvedPlanFile) {
+    console.error(`Plan file not found: ${normalizedOptions.plan}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const completedNames = getCompletedPlanNames(completedDir);
+  const planFileName = path.basename(resolvedPlanFile);
+  if (completedNames.has(planFileName)) {
+    console.log(`Plan already completed: ${planFileName}`);
+    return;
+  }
+
+  // Derive plan ID and work branch
+  const planId = derivePlanId(planFileName);
+  const workBranch = deriveBranchName(planFileName);
+
+  // Acquire per-plan lock
+  const worktreesDir = path.join(REPO_ROOT, ".worktrees");
+  const worktreePath = path.join(worktreesDir, `plan-${planId}`);
+
+  const lockResult = acquireLock(planId, { worktreePath });
+  if (!lockResult.acquired) {
+    console.error(`Cannot start plan "${planId}": ${lockResult.reason}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // Clean up per-plan lock on signals
+  const cleanupLock = () => {
+    releaseLock(planId);
+    process.exit();
+  };
+  process.on("SIGINT", cleanupLock);
+  process.on("SIGTERM", cleanupLock);
+
+  try {
+    console.log("=== Plan Orchestrator Starting (worktree mode) ===\n");
+    console.log(`Plan: ${planFileName}`);
+    console.log(`Plan ID: ${planId}`);
+    console.log(`Work branch: ${workBranch}`);
+
+    // Set ORRERY_REPO_ROOT so path resolution works from inside the worktree
+    process.env.ORRERY_REPO_ROOT = REPO_ROOT;
+
+    const sourceBranch = getCurrentBranch(REPO_ROOT);
+    console.log(`Source branch: ${sourceBranch}\n`);
+
+    // Check for uncommitted changes in the main repo
+    if (hasUncommittedChanges(REPO_ROOT)) {
+      console.error(
+        "Error: Uncommitted changes detected. Please commit or stash before running orchestrator."
+      );
+      process.exitCode = 1;
+      return;
+    }
+
+    // Update plan metadata (in the plan file, not committed to source branch)
+    let plan = loadPlan(resolvedPlanFile);
+    plan.metadata.source_branch = sourceBranch;
+    plan.metadata.work_branch = workBranch;
+    savePlan(plan);
+
+    // Create work branch if needed
+    if (!branchExists(workBranch, REPO_ROOT)) {
+      console.log(`Creating work branch: ${workBranch}`);
+      createBranch(workBranch, REPO_ROOT);
+      // Switch back to source branch — the worktree will use the work branch
+      checkoutBranch(sourceBranch, REPO_ROOT);
+    }
+
+    // Create or reuse plan worktree
+    if (!fs.existsSync(worktreesDir)) {
+      fs.mkdirSync(worktreesDir, { recursive: true });
+    }
+
+    if (fs.existsSync(worktreePath)) {
+      console.log(`Reusing existing worktree: ${worktreePath}`);
+    } else {
+      console.log(`Creating worktree: ${worktreePath}`);
+      addWorktreeExistingBranch(worktreePath, workBranch, REPO_ROOT);
+    }
+
+    // Build execution context
+    const ctx = { workingDir: worktreePath, mainRepoRoot: REPO_ROOT };
+
+    if (parallelEnabled) {
+      console.log(
+        `Parallel mode enabled (max ${config.concurrency.maxParallel} concurrent agents)`
+      );
+    }
+
+    console.log(`\nWorking directory: ${worktreePath}\n`);
+
+    // Process the plan inside the worktree
+    await processPlan(
+      resolvedPlanFile,
+      completedDir,
+      reportsDir,
+      parallelEnabled,
+      ctx
+    );
+
+    // Reload and check final state
+    plan = loadPlan(resolvedPlanFile);
+    const isComplete = plan.isComplete();
+
+    if (isComplete) {
+      const isSuccessful = plan.isSuccessful();
+
+      // Archive the plan
+      archivePlan(resolvedPlanFile, plan, completedDir);
+
+      // Commit all work branch changes (inside worktree)
+      const workCommit = commit(
+        `chore: complete plan ${planFileName}`,
+        [],
+        worktreePath
+      );
+      if (workCommit) {
+        console.log(`Committed plan completion (${workCommit.slice(0, 7)})`);
+      }
+
+      // Generate PR info
+      const prTitle = `Plan: ${planFileName.replace(/\.ya?ml$/, "").replace(/^\d{4}-\d{2}-\d{2}-/, "")}`;
+      const prBody = generatePRBody(plan);
+      const prInfo = createPullRequest(
+        prTitle,
+        prBody,
+        sourceBranch,
+        worktreePath
+      );
+      logPullRequestInfo(prInfo);
+
+      // Run on-complete hook before worktree cleanup
+      runOnCompleteHook(
+        normalizedOptions.onComplete,
+        {
+          planName: planFileName,
+          planFile: resolvedPlanFile,
+          outcome: isSuccessful ? "success" : "partial",
+          workBranch,
+          sourceBranch,
+          prUrl: prInfo.url || "",
+          stepsTotal: plan.steps.length,
+          stepsCompleted: plan.steps.filter((s) => s.status === "complete")
+            .length,
+          stepsBlocked: plan.steps.filter((s) => s.status === "blocked").length
+        },
+        worktreePath
+      );
+
+      // Clean up worktree on success
+      try {
+        removeWorktree(worktreePath, REPO_ROOT);
+        console.log(`Cleaned up worktree: ${worktreePath}`);
+      } catch (err) {
+        console.error(`Failed to clean up worktree: ${err.message}`);
+      }
+
+      if (isSuccessful) {
+        console.log("\n=== Plan Complete (success) ===");
+      } else {
+        console.log("\n=== Plan Complete (partial — some steps blocked) ===");
+      }
+    } else {
+      // Plan not complete — commit WIP and preserve worktree
+      const progressCommit = commit(
+        `wip: progress on plan ${planFileName}`,
+        [],
+        worktreePath
+      );
+      if (progressCommit) {
+        console.log(
+          `Committed work-in-progress (${progressCommit.slice(0, 7)})`
+        );
+      }
+
+      runOnCompleteHook(
+        normalizedOptions.onComplete,
+        {
+          planName: planFileName,
+          planFile: resolvedPlanFile,
+          outcome: "incomplete",
+          workBranch,
+          sourceBranch,
+          prUrl: "",
+          stepsTotal: plan.steps.length,
+          stepsCompleted: plan.steps.filter((s) => s.status === "complete")
+            .length,
+          stepsBlocked: plan.steps.filter((s) => s.status === "blocked").length
+        },
+        worktreePath
+      );
+
+      console.log(
+        "\nPlan not complete. Worktree preserved for later continuation."
+      );
+      console.log(`Worktree: ${worktreePath}`);
+      console.log("\nTo continue:");
+      console.log("  1. Fix the blocked steps (orrery status)");
+      console.log(
+        `  2. Run 'orrery resume --plan ${normalizedOptions.plan}' to continue`
+      );
+    }
+  } finally {
+    delete process.env.ORRERY_REPO_ROOT;
+    releaseLock(planId);
+  }
+}
+
 /**
  * Process a single plan with branch management
  * @param {string} planFile - Path to the plan file
@@ -542,13 +1111,15 @@ async function handleResumeMode(
  * @param {string} completedDir - Directory for completed plans
  * @param {string} reportsDir - Directory for reports
  * @param {boolean} parallelEnabled - Whether parallel execution with worktrees is enabled
+ * @returns {Promise<{isComplete: boolean, isSuccessful: boolean, workBranch: string}>}
  */
 async function processPlanWithBranching(
   planFile,
   sourceBranch,
   completedDir,
   reportsDir,
-  parallelEnabled = false
+  parallelEnabled = false,
+  onComplete = null
 ) {
   const planFileName = path.basename(planFile);
   console.log(`\n--- Processing: ${planFileName} ---\n`);
@@ -563,16 +1134,18 @@ async function processPlanWithBranching(
   plan.metadata.work_branch = workBranch;
   savePlan(plan);
 
-  // Commit the metadata update on source branch
-  const metadataCommit = commit(
-    `chore: dispatch plan ${planFileName} to ${workBranch}`,
-    [planFile],
-    REPO_ROOT
-  );
-  if (metadataCommit) {
-    console.log(
-      `Marked plan as dispatched on ${sourceBranch} (${metadataCommit.slice(0, 7)})`
+  // Commit the metadata update on source branch (only if work dir is inside repo)
+  if (!isWorkDirExternal()) {
+    const metadataCommit = commit(
+      `chore: dispatch plan ${planFileName} to ${workBranch}`,
+      [planFile],
+      REPO_ROOT
     );
+    if (metadataCommit) {
+      console.log(
+        `Marked plan as dispatched on ${sourceBranch} (${metadataCommit.slice(0, 7)})`
+      );
+    }
   }
 
   // Step 3: Create and switch to work branch
@@ -592,6 +1165,8 @@ async function processPlanWithBranching(
   const isComplete = plan.isComplete();
 
   if (isComplete) {
+    const isSuccessful = plan.isSuccessful();
+
     // Step 6: Archive the plan (on work branch)
     archivePlan(planFile, plan, completedDir);
 
@@ -610,6 +1185,25 @@ async function processPlanWithBranching(
     const prBody = generatePRBody(plan);
     const prInfo = createPullRequest(prTitle, prBody, sourceBranch, REPO_ROOT);
     logPullRequestInfo(prInfo);
+
+    runOnCompleteHook(
+      onComplete,
+      {
+        planName: planFileName,
+        planFile,
+        outcome: isSuccessful ? "success" : "partial",
+        workBranch,
+        sourceBranch,
+        prUrl: prInfo.url || "",
+        stepsTotal: plan.steps.length,
+        stepsCompleted: plan.steps.filter((s) => s.status === "complete")
+          .length,
+        stepsBlocked: plan.steps.filter((s) => s.status === "blocked").length
+      },
+      REPO_ROOT
+    );
+
+    return { isComplete: true, isSuccessful, workBranch };
   } else {
     // Plan not complete (still has pending steps or was interrupted)
     // Commit any progress made
@@ -621,9 +1215,29 @@ async function processPlanWithBranching(
     if (progressCommit) {
       console.log(`Committed work-in-progress (${progressCommit.slice(0, 7)})`);
     }
+
+    runOnCompleteHook(
+      onComplete,
+      {
+        planName: planFileName,
+        planFile,
+        outcome: "incomplete",
+        workBranch,
+        sourceBranch,
+        prUrl: "",
+        stepsTotal: plan.steps.length,
+        stepsCompleted: plan.steps.filter((s) => s.status === "complete")
+          .length,
+        stepsBlocked: plan.steps.filter((s) => s.status === "blocked").length
+      },
+      REPO_ROOT
+    );
+
     console.log(
       "\nPlan not complete. Work branch preserved for later continuation."
     );
+
+    return { isComplete: false, isSuccessful: false, workBranch };
   }
 }
 
@@ -696,13 +1310,18 @@ function generatePRBody(plan) {
  * @param {string} completedDir - Directory for completed plans
  * @param {string} reportsDir - Directory for reports
  * @param {boolean} parallelEnabled - Whether parallel execution with worktrees is enabled
+ * @param {{workingDir: string, mainRepoRoot: string}} [ctx] - Execution context for worktree mode
  */
 async function processPlan(
   planFile,
   completedDir,
   reportsDir,
-  parallelEnabled = false
+  parallelEnabled = false,
+  ctx
 ) {
+  if (!ctx) {
+    ctx = { workingDir: REPO_ROOT, mainRepoRoot: REPO_ROOT };
+  }
   let plan = loadPlan(planFile);
   const activeAgents = []; // Array of {handle, stepIds, tempPlanFile, worktreeInfo?}
 
@@ -739,22 +1358,23 @@ async function processPlan(
             tracker
           );
           plan = loadPlan(planFile);
-          await mergeWorktreeCommits(results, REPO_ROOT);
+          await mergeWorktreeCommits(results, ctx.workingDir);
         } else {
           // Serial mode: wait for one
           const { stepIds, parsedResults } = await waitForAgentCompletion(
             planFile,
             activeAgents,
             reportsDir,
-            tracker
+            tracker,
+            ctx
           );
           plan = loadPlan(planFile);
 
-          if (hasUncommittedChanges(REPO_ROOT)) {
+          if (hasUncommittedChanges(ctx.workingDir)) {
             const commitMsg =
               parsedResults[0]?.commitMessage ||
               `feat: complete step(s) ${stepIds.join(", ")}`;
-            const commitSha = commit(commitMsg, [], REPO_ROOT);
+            const commitSha = commit(commitMsg, [], ctx.workingDir);
             if (commitSha) {
               console.log(
                 `Committed: ${commitMsg.split("\n")[0]} (${commitSha.slice(0, 7)})`
@@ -800,7 +1420,8 @@ async function processPlan(
           activeAgents,
           tracker,
           useWorktree,
-          parallel.length > 1 // skipLogging for parallel batches
+          parallel.length > 1, // skipLogging for parallel batches
+          ctx
         );
       }
     }
@@ -813,7 +1434,15 @@ async function processPlan(
       ) {
         break;
       }
-      await startSteps(planFile, [step.id], activeAgents, tracker, false);
+      await startSteps(
+        planFile,
+        [step.id],
+        activeAgents,
+        tracker,
+        false,
+        false,
+        ctx
+      );
     }
 
     // If we started any agents, wait for completion
@@ -832,22 +1461,23 @@ async function processPlan(
           tracker
         );
         plan = loadPlan(planFile);
-        await mergeWorktreeCommits(results, REPO_ROOT);
+        await mergeWorktreeCommits(results, ctx.workingDir);
       } else {
         // Serial execution: wait for one agent at a time
         const { stepIds, parsedResults } = await waitForAgentCompletion(
           planFile,
           activeAgents,
           reportsDir,
-          tracker
+          tracker,
+          ctx
         );
         plan = loadPlan(planFile);
 
-        if (hasUncommittedChanges(REPO_ROOT)) {
+        if (hasUncommittedChanges(ctx.workingDir)) {
           const commitMsg =
             parsedResults[0]?.commitMessage ||
             `feat: complete step(s) ${stepIds.join(", ")}`;
-          const commitSha = commit(commitMsg, [], REPO_ROOT);
+          const commitSha = commit(commitMsg, [], ctx.workingDir);
           if (commitSha) {
             console.log(
               `Committed: ${commitMsg.split("\n")[0]} (${commitSha.slice(0, 7)})`
@@ -869,6 +1499,8 @@ async function processPlan(
  * @param {Object[]} activeAgents - Array of active agent handles
  * @param {ProgressTracker} tracker - Progress tracker instance
  * @param {boolean} useWorktree - Whether to use a git worktree for isolation
+ * @param {boolean} skipLogging - Whether to skip logging step start
+ * @param {{workingDir: string, mainRepoRoot: string}} [ctx] - Execution context
  */
 async function startSteps(
   planFile,
@@ -876,8 +1508,13 @@ async function startSteps(
   activeAgents,
   tracker,
   useWorktree = false,
-  skipLogging = false
+  skipLogging = false,
+  ctx
 ) {
+  if (!ctx) {
+    ctx = { workingDir: REPO_ROOT, mainRepoRoot: REPO_ROOT };
+  }
+
   // Log step start with progress info (unless skipped for parallel batch)
   if (!skipLogging) {
     tracker.logStepStart(stepIds);
@@ -895,13 +1532,15 @@ async function startSteps(
   const condensedPlan = generateCondensedPlan(plan, stepIds);
   const tempPlanFile = writeCondensedPlan(condensedPlan, planFile, stepIds);
 
-  // Determine working directory (worktree or main repo)
-  let workingDir = REPO_ROOT;
+  // Determine working directory (worktree or ctx.workingDir)
+  let workingDir = ctx.workingDir;
   let worktreeInfo = null;
 
   if (useWorktree) {
+    // Step-level worktrees are created relative to the main repo root,
+    // not the plan worktree, to avoid nesting issues
     const branchName = `worktree-${stepIds.join("-")}-${Date.now()}`;
-    const worktreesDir = path.join(REPO_ROOT, ".worktrees");
+    const worktreesDir = path.join(ctx.mainRepoRoot, ".worktrees");
 
     // Ensure .worktrees directory exists
     if (!fs.existsSync(worktreesDir)) {
@@ -911,7 +1550,7 @@ async function startSteps(
     const worktreePath = path.join(worktreesDir, branchName);
 
     try {
-      addWorktree(worktreePath, branchName, "HEAD", REPO_ROOT);
+      addWorktree(worktreePath, branchName, "HEAD", ctx.mainRepoRoot);
       workingDir = worktreePath;
       worktreeInfo = { path: worktreePath, branch: branchName };
       console.log(`Created worktree for ${stepIds.join(",")}: ${worktreePath}`);
@@ -964,14 +1603,19 @@ async function startSteps(
  * @param {Object[]} activeAgents - Array of active agent handles
  * @param {string} reportsDir - Directory for reports
  * @param {ProgressTracker} tracker - Progress tracker instance
+ * @param {{workingDir: string, mainRepoRoot: string}} [ctx] - Execution context
  * @returns {{stepIds: string[], parsedResults: Object[]}} Completed step IDs and parsed results
  */
 async function waitForAgentCompletion(
   planFile,
   activeAgents,
   reportsDir,
-  tracker
+  tracker,
+  ctx
 ) {
+  if (!ctx) {
+    ctx = { workingDir: REPO_ROOT, mainRepoRoot: REPO_ROOT };
+  }
   if (activeAgents.length === 0) return { stepIds: [], parsedResults: [] };
 
   // Wait for any agent to complete
@@ -1036,7 +1680,7 @@ async function waitForAgentCompletion(
             config,
             tempPlanFile,
             [stepId],
-            REPO_ROOT,
+            ctx.workingDir,
             { stepId, timeoutMs: resolveAgentTimeout() }
           );
 
@@ -1091,7 +1735,7 @@ async function waitForAgentCompletion(
             planFile,
             [stepId],
             reviewResult.feedback,
-            REPO_ROOT,
+            ctx.workingDir,
             {
               stepId,
               stepIds: [stepId],
@@ -1318,6 +1962,37 @@ function writeReport(reportsDir, planFile, report) {
   console.log(`Report written: ${fileName}`);
 }
 
+/**
+ * Run the on-complete hook command with plan context as environment variables.
+ * Failures are logged but never thrown.
+ * @param {string} command - Shell command to execute
+ * @param {Object} context - Plan context for environment variables
+ * @param {string} cwd - Working directory to run the command in
+ */
+function runOnCompleteHook(command, context, cwd) {
+  if (!command) return;
+
+  const env = {
+    ...process.env,
+    ORRERY_PLAN_NAME: String(context.planName || ""),
+    ORRERY_PLAN_FILE: String(context.planFile || ""),
+    ORRERY_PLAN_OUTCOME: String(context.outcome || ""),
+    ORRERY_WORK_BRANCH: String(context.workBranch || ""),
+    ORRERY_SOURCE_BRANCH: String(context.sourceBranch || ""),
+    ORRERY_PR_URL: String(context.prUrl || ""),
+    ORRERY_STEPS_TOTAL: String(context.stepsTotal || 0),
+    ORRERY_STEPS_COMPLETED: String(context.stepsCompleted || 0),
+    ORRERY_STEPS_BLOCKED: String(context.stepsBlocked || 0)
+  };
+
+  try {
+    console.log(`\nRunning on-complete hook: ${command}`);
+    execSync(command, { cwd, env, stdio: "inherit", timeout: 60000 });
+  } catch (err) {
+    console.error(`on-complete hook failed: ${err.message}`);
+  }
+}
+
 /**
  * Archive a completed plan
  */
@@ -1345,4 +2020,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { orchestrate };
+module.exports = { orchestrate, runOnCompleteHook };