@caseyharalson/orrery 0.10.0 → 0.12.0

package/lib/cli/commands/resume.js

@@ -1,8 +1,13 @@
+const fs = require("fs");
 const path = require("path");
 
 const { findPlanForCurrentBranch } = require("../../utils/plan-detect");
-const { updateStepsStatus } = require("../../orchestration/plan-loader");
-const { commit } = require("../../utils/git");
+const {
+  loadPlan,
+  updateStepsStatus
+} = require("../../orchestration/plan-loader");
+const { commit, getCurrentBranch } = require("../../utils/git");
+const { getPlansDir } = require("../../utils/paths");
 const { orchestrate } = require("../../orchestration");
 
 function supportsColor() {
@@ -24,6 +29,7 @@ module.exports = function registerResumeCommand(program) {
   program
     .command("resume")
     .description("Unblock steps and resume orchestration")
+    .option("--plan <file>", "Resume a specific plan file")
     .option("--step <id>", "Unblock a specific step before resuming")
     .option("--all", "Unblock all blocked steps (default behavior)")
     .option(
@@ -31,31 +37,90 @@ module.exports = function registerResumeCommand(program) {
       "Preview what would be unblocked without making changes"
     )
     .action(async (options) => {
-      // 1. Find plan for current branch
-      let match;
-      try {
-        match = findPlanForCurrentBranch();
-      } catch {
-        console.error("Error detecting plan from current branch.");
-        console.log(
-          "Make sure you're on a work branch (e.g., plan/feature-name)."
-        );
-        process.exitCode = 1;
-        return;
-      }
+      let planFile;
+      let plan;
+
+      if (options.plan) {
+        // Resolve plan path (same pattern as status.js)
+        const planArg = options.plan;
+        let resolvedPath;
+        if (path.isAbsolute(planArg)) {
+          resolvedPath = planArg;
+        } else if (planArg.includes(path.sep)) {
+          resolvedPath = path.resolve(process.cwd(), planArg);
+        } else {
+          resolvedPath = path.join(getPlansDir(), planArg);
+        }
 
-      if (!match) {
-        console.error(
-          "Not on a work branch. No plan found for current branch."
-        );
-        console.log("\nTo resume a plan:");
-        console.log("  1. git checkout <work-branch>");
-        console.log("  2. orrery resume");
-        process.exitCode = 1;
-        return;
-      }
+        if (!resolvedPath || !fs.existsSync(resolvedPath)) {
+          console.error(`Plan not found: ${planArg}`);
+          process.exitCode = 1;
+          return;
+        }
+
+        plan = loadPlan(resolvedPath);
+        planFile = resolvedPath;
+
+        // Validate work_branch
+        if (!plan.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.exitCode = 1;
+          return;
+        }
+
+        // Verify current branch matches plan's work_branch
+        let currentBranch;
+        try {
+          currentBranch = getCurrentBranch(process.cwd());
+        } catch {
+          console.error("Error detecting current branch.");
+          process.exitCode = 1;
+          return;
+        }
+
+        if (currentBranch !== plan.metadata.work_branch) {
+          console.error(
+            `Plan expects branch '${plan.metadata.work_branch}' but you are on '${currentBranch}'.`
+          );
+          console.log(`\nRun: git checkout ${plan.metadata.work_branch}`);
+          process.exitCode = 1;
+          return;
+        }
+      } else {
+        // 1. Find plan for current branch (existing behavior)
+        let match;
+        try {
+          match = findPlanForCurrentBranch();
+        } catch {
+          console.error("Error detecting plan from current branch.");
+          console.log(
+            "Make sure you're on a work branch (e.g., plan/feature-name)."
+          );
+          process.exitCode = 1;
+          return;
+        }
 
-      const { planFile, plan } = match;
+        if (!match) {
+          console.error(
+            "Not on a work branch. No plan found for current branch."
+          );
+          console.log("\nTo resume a plan:");
+          console.log("  1. git checkout <work-branch>");
+          console.log("  2. orrery resume");
+          console.log("\nOr specify a plan directly:");
+          console.log("  orrery resume --plan <file>");
+          process.exitCode = 1;
+          return;
+        }
+
+        planFile = match.planFile;
+        plan = match.plan;
+      }
       const planFileName = path.basename(planFile);
       console.log(`(detected plan: ${planFileName})\n`);
 
@@ -72,13 +137,11 @@ module.exports = function registerResumeCommand(program) {
         }
 
         console.log("Resuming orchestration...\n");
-        await orchestrate({ resume: true });
+        await orchestrate({ resume: true, plan: options.plan });
         return;
       }
 
       // 4. Determine which steps to unblock
-      let stepsToUnblock = [];
-
       if (options.step) {
         // Unblock specific step
         const step = blockedSteps.find((s) => s.id === options.step);
@@ -93,12 +156,12 @@ module.exports = function registerResumeCommand(program) {
           process.exitCode = 1;
           return;
         }
-        stepsToUnblock = [step];
-      } else {
-        // Default: unblock all (--all is implicit)
-        stepsToUnblock = blockedSteps;
       }
 
+      const stepsToUnblock = options.step
+        ? [blockedSteps.find((s) => s.id === options.step)]
+        : blockedSteps;
+
       // 5. Dry-run mode: show preview
       if (options.dryRun) {
         console.log("Dry run - would unblock the following steps:\n");
@@ -141,6 +204,6 @@ module.exports = function registerResumeCommand(program) {
 
       // 8. Resume orchestration
       console.log("\nResuming orchestration...\n");
-      await orchestrate({ resume: true });
+      await orchestrate({ resume: true, plan: options.plan });
     });
 };

package/lib/cli/commands/status.js

@@ -4,6 +4,7 @@ const { getPlansDir } = require("../../utils/paths");
 const { getPlanFiles, loadPlan } = require("../../orchestration/plan-loader");
 const { findPlanForCurrentBranch } = require("../../utils/plan-detect");
 const { getCurrentBranch } = require("../../utils/git");
+const { getLockStatus } = require("../../utils/lock");
 
 function supportsColor() {
   return Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
@@ -92,6 +93,18 @@ module.exports = function registerStatusCommand(program) {
     .description("Show orchestration status for plans in the current project")
     .option("--plan <file>", "Show detailed status for a specific plan")
     .action((options) => {
+      // Check for active execution
+      const lock = getLockStatus();
+      if (lock.locked) {
+        console.log(
+          `Execution in progress (PID ${lock.pid}, started ${lock.startedAt})\n`
+        );
+      } else if (lock.stale) {
+        console.log(
+          `Note: Stale lock detected (PID ${lock.pid} no longer running)\n`
+        );
+      }
+
       const plansDir = getPlansDir();
       const planArg = options.plan;
 

package/lib/cli/index.js

@@ -9,6 +9,8 @@ const registerStatus = require("./commands/status");
 const registerResume = require("./commands/resume");
 const registerValidatePlan = require("./commands/validate-plan");
 const registerIngestPlan = require("./commands/ingest-plan");
+const registerManual = require("./commands/manual");
+const registerPlansDir = require("./commands/plans-dir");
 const registerHelp = require("./commands/help");
 
 function getPackageVersion() {
@@ -34,6 +36,8 @@ function buildProgram() {
   registerResume(program);
   registerValidatePlan(program);
   registerIngestPlan(program);
+  registerManual(program);
+  registerPlansDir(program);
   registerHelp(program);
 
   program.on("command:*", (operands) => {

package/lib/orchestration/index.js

@@ -62,7 +62,8 @@ const config = require("./config");
 const {
   getPlansDir,
   getCompletedDir,
-  getReportsDir
+  getReportsDir,
+  isWorkDirExternal
 } = require("../utils/paths");
 
 const {
@@ -72,6 +73,7 @@ const {
 } = require("./condensed-plan");
 
 const { ProgressTracker } = require("./progress-tracker");
+const { acquireLock, releaseLock } = require("../utils/lock");
 
 const REPO_ROOT = process.cwd();
 
@@ -277,140 +279,168 @@ async function orchestrate(options = {}) {
     );
   }
 
-  console.log("=== Plan Orchestrator Starting ===\n");
-
-  const plansDir = getPlansDir();
-  const completedDir = getCompletedDir();
-  const reportsDir = getReportsDir();
-
-  // Record the source branch we're starting from
-  const sourceBranch = getCurrentBranch(REPO_ROOT);
-  console.log(`Source branch: ${sourceBranch}\n`);
+  // Acquire 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))
+      );
     }
-    if (completedNames.has(path.basename(resolvedPlanFile))) {
-      console.log(`Plan already completed: ${path.basename(resolvedPlanFile)}`);
-      return;
+
+    // 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);
+      }
     }
-    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 = [];
+    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();
+    }
 
-  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 (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 (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})`);
+    if (normalizedOptions.dryRun) {
+      logDryRunSummary(planFiles);
+      return;
     }
-    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;
-  }
+    // Record the source branch we're starting from
+    const sourceBranch = getCurrentBranch(REPO_ROOT);
+    console.log(`Source branch: ${sourceBranch}\n`);
 
-  if (normalizedOptions.dryRun) {
-    logDryRunSummary(planFiles);
-    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);
+    }
 
-  console.log(`Found ${planFiles.length} plan(s) to process:\n`);
-  for (const pf of planFiles) {
-    console.log(`  - ${path.basename(pf)}`);
-  }
-  console.log();
+    // Resume mode: find and continue the plan for the current branch
+    if (normalizedOptions.resume) {
+      await handleResumeMode(
+        plansDir,
+        completedDir,
+        reportsDir,
+        sourceBranch,
+        normalizedOptions.plan
+      );
+      return;
+    }
 
-  // Process each plan (one at a time, with branch switching)
-  for (const planFile of planFiles) {
-    await processPlanWithBranching(
-      planFile,
-      sourceBranch,
-      completedDir,
-      reportsDir,
-      parallelEnabled
-    );
+    console.log(`Found ${planFiles.length} plan(s) to process:\n`);
+    for (const pf of planFiles) {
+      console.log(`  - ${path.basename(pf)}`);
+    }
+    console.log();
 
-    // Reload plan to check final state
-    const plan = loadPlan(planFile);
-    const isComplete = plan.isComplete();
-    const isSuccessful = plan.isSuccessful();
+    // Process each plan (one at a time, with branch switching)
+    for (const planFile of planFiles) {
+      const result = await processPlanWithBranching(
+        planFile,
+        sourceBranch,
+        completedDir,
+        reportsDir,
+        parallelEnabled
+      );
 
-    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);
-      }
-    } 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).`);
+      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
       }
-      break; // Stop processing
     }
-  }
 
-  console.log("\n=== Orchestrator Complete ===");
+    console.log("\n=== Orchestrator Complete ===");
+  } finally {
+    if (!normalizedOptions.dryRun) releaseLock();
+  }
 }
 
 /**
@@ -420,36 +450,73 @@ async function handleResumeMode(
   plansDir,
   completedDir,
   reportsDir,
-  currentBranch
+  currentBranch,
+  planFileArg
 ) {
   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);
+    }
+
+    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);
@@ -542,6 +609,7 @@ 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,
@@ -563,16 +631,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 +662,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 +682,8 @@ async function processPlanWithBranching(
     const prBody = generatePRBody(plan);
     const prInfo = createPullRequest(prTitle, prBody, sourceBranch, REPO_ROOT);
     logPullRequestInfo(prInfo);
+
+    return { isComplete: true, isSuccessful, workBranch };
   } else {
     // Plan not complete (still has pending steps or was interrupted)
     // Commit any progress made
@@ -624,6 +698,8 @@ async function processPlanWithBranching(
     console.log(
       "\nPlan not complete. Work branch preserved for later continuation."
     );
+
+    return { isComplete: false, isSuccessful: false, workBranch };
   }
 }