@caseyharalson/orrery 0.12.0 → 0.13.1

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,
@@ -264,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;
@@ -279,7 +283,48 @@ async function orchestrate(options = {}) {
     );
   }
 
-  // Acquire execution lock (skip for dry-run)
+  // 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;
+  }
+
+  // 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
+  }
+
+  // Acquire global execution lock (skip for dry-run)
   if (!normalizedOptions.dryRun) {
     const lockResult = acquireLock();
     if (!lockResult.acquired) {
@@ -392,7 +437,8 @@ async function orchestrate(options = {}) {
         completedDir,
         reportsDir,
         sourceBranch,
-        normalizedOptions.plan
+        normalizedOptions.plan,
+        normalizedOptions.onComplete
       );
       return;
     }
@@ -410,7 +456,8 @@ async function orchestrate(options = {}) {
         sourceBranch,
         completedDir,
         reportsDir,
-        parallelEnabled
+        parallelEnabled,
+        normalizedOptions.onComplete
       );
 
       if (result.isComplete && result.isSuccessful) {
@@ -443,6 +490,172 @@ async function orchestrate(options = {}) {
   }
 }
 
+/**
+ * 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;
+  }
+
+  const cleanupLock = () => {
+    releaseLock(planId);
+    process.exit();
+  };
+  process.on("SIGINT", cleanupLock);
+  process.on("SIGTERM", cleanupLock);
+
+  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);
+    }
+
+    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();
+
+    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)})`);
+      }
+
+      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)})`
+        );
+      }
+
+      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=== Resume Complete ===");
+  } finally {
+    delete process.env.ORRERY_REPO_ROOT;
+    releaseLock(planId);
+  }
+}
+
 /**
  * Handle resume mode: find and continue plan for current branch
  */
@@ -451,7 +664,8 @@ async function handleResumeMode(
   completedDir,
   reportsDir,
   currentBranch,
-  planFileArg
+  planFileArg,
+  onComplete
 ) {
   console.log("=== Resume Mode ===\n");
 
@@ -478,6 +692,25 @@ async function handleResumeMode(
       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}'.`
@@ -585,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}`,
@@ -594,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."
     );
@@ -602,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
@@ -616,7 +1118,8 @@ async function processPlanWithBranching(
   sourceBranch,
   completedDir,
   reportsDir,
-  parallelEnabled = false
+  parallelEnabled = false,
+  onComplete = null
 ) {
   const planFileName = path.basename(planFile);
   console.log(`\n--- Processing: ${planFileName} ---\n`);
@@ -683,6 +1186,23 @@ async function processPlanWithBranching(
     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)
@@ -695,6 +1215,24 @@ 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."
     );
@@ -772,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?}
 
@@ -815,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)})`
@@ -876,7 +1420,8 @@ async function processPlan(
           activeAgents,
           tracker,
           useWorktree,
-          parallel.length > 1 // skipLogging for parallel batches
+          parallel.length > 1, // skipLogging for parallel batches
+          ctx
         );
       }
     }
@@ -889,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
@@ -908,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)})`
@@ -945,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,
@@ -952,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);
@@ -971,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)) {
@@ -987,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}`);
@@ -1040,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
@@ -1112,7 +1680,7 @@ async function waitForAgentCompletion(
             config,
             tempPlanFile,
             [stepId],
-            REPO_ROOT,
+            ctx.workingDir,
             { stepId, timeoutMs: resolveAgentTimeout() }
           );
 
@@ -1167,7 +1735,7 @@ async function waitForAgentCompletion(
             planFile,
             [stepId],
             reviewResult.feedback,
-            REPO_ROOT,
+            ctx.workingDir,
             {
               stepId,
               stepIds: [stepId],
@@ -1394,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
  */
@@ -1421,4 +2020,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { orchestrate };
+module.exports = { orchestrate, runOnCompleteHook };