@caseyharalson/orrery 0.11.0 → 0.12.0

package/HELP.md

@@ -71,20 +71,25 @@ each step.
 
 ```
 Options:
-  --plan <file>  Process only a specific plan file
-  --dry-run      Show what would be executed without running agents
-  --verbose      Show detailed agent output
-  --resume       Resume orchestration on the current work branch
-  --review       Enable code review loop after each step
-  --parallel     Enable parallel execution with git worktrees for isolation
+  --plan <file>   Process only a specific plan file
+  --dry-run       Show what would be executed without running agents
+  --verbose       Show detailed agent output
+  --resume        Resume orchestration on the current work branch
+  --review        Enable code review loop after each step
+  --parallel      Enable parallel execution with git worktrees for isolation
+  --background    Run orchestration as a detached background process
 ```
 
+Only one `exec`/`resume` can run at a time per project. A lock file
+(`exec.lock`) prevents concurrent runs and is automatically cleaned up.
+
 Example:
 
 ```bash
 orrery exec
 orrery exec --plan my-feature.yaml --review
 orrery exec --parallel --verbose
+orrery exec --background
 ```
 
 #### `orrery resume`
@@ -94,15 +99,21 @@ work branch, resets blocked steps to pending, commits, and resumes.
 
 ```
 Options:
-  --step <id>  Unblock a specific step before resuming
-  --all        Unblock all blocked steps (default behavior)
-  --dry-run    Preview what would be unblocked without making changes
+  --plan <file>  Resume a specific plan file (skips branch auto-detection)
+  --step <id>    Unblock a specific step before resuming
+  --all          Unblock all blocked steps (default behavior)
+  --dry-run      Preview what would be unblocked without making changes
 ```
 
+When `--plan` is provided, the plan's `work_branch` must match the current
+branch. If the plan hasn't been dispatched yet (no `work_branch`), use
+`orrery exec --plan` first.
+
 Example:
 
 ```bash
 orrery resume
+orrery resume --plan my-feature.yaml
 orrery resume --step step-2
 orrery resume --dry-run
 ```
@@ -112,7 +123,8 @@ orrery resume --dry-run
 #### `orrery status`
 
 Show orchestration status for plans in the current project. Auto-detects the
-plan when on a work branch.
+plan when on a work branch. Also shows whether an orchestration process is
+currently running (via lock file detection) or if a stale lock exists.
 
 ```
 Options:
@@ -250,6 +262,19 @@ The review agent inspects changes after each step. If issues are found, an edit
 agent applies fixes and verification re-runs, repeating until approval or the
 max iteration limit is reached (default: 3).
 
+### Background Execution
+
+Run orchestration as a detached background process:
+
+```bash
+orrery exec --background
+orrery exec --plan my-feature.yaml --background
+```
+
+The process runs detached and logs output to `<work-dir>/exec.log`. Use
+`orrery status` to check progress. A lock file prevents starting a second
+execution while one is already running.
+
 ### Parallel Execution
 
 Run independent steps concurrently using git worktrees for isolation:
@@ -371,8 +396,14 @@ Orrery maintains state in `.agent-work/` (configurable via `ORRERY_WORK_DIR`):
   plans/        Active plan files (new and in-progress)
   reports/      Step-level execution logs and outcomes
   completed/    Successfully executed plans (archived)
+  exec.lock     Lock file when orchestration is running
+  exec.log      Output log for background execution
 ```
 
+When `ORRERY_WORK_DIR` is set, Orrery automatically scopes to a project
+subdirectory (`<project-name>-<hash>`) so multiple projects can share the same
+work directory without plan conflicts.
+
 ---
 
 ## Environment Variables
@@ -385,7 +416,7 @@ Orrery maintains state in `.agent-work/` (configurable via `ORRERY_WORK_DIR`):
 | `ORRERY_PARALLEL_MAX`          | Maximum concurrent parallel agents                   | `3`                   |
 | `ORRERY_REVIEW_ENABLED`        | Enable the review loop                               | `false`               |
 | `ORRERY_REVIEW_MAX_ITERATIONS` | Maximum review-edit loop iterations                  | `3`                   |
-| `ORRERY_WORK_DIR`              | Override the work directory path                     | `.agent-work`         |
+| `ORRERY_WORK_DIR`              | Override the work directory path (project-scoped)    | `.agent-work`         |
 
 ---
 

package/README.md

@@ -88,6 +88,7 @@ For power users, Orrery offers additional capabilities:
 - **External Plan Creation** - Import plans from other tools or LLMs
 - **Review Loop** - Iterative code review after each step with automatic fixes
 - **Parallel Execution** - Run independent steps concurrently with git worktree isolation
+- **Background Execution** - Run orchestration as a detached process and poll status
 - **Handling Blocked Plans** - Recovery workflows when steps cannot complete
 
 See [Advanced Workflows](docs/advanced-workflows.md) for details.
@@ -120,17 +121,18 @@ The Orchestrator (`orrery exec`) is the engine that drives the process. It loads
 
 ## Command Reference
 
-| Command              | Description                                                                                                   |
-| :------------------- | :------------------------------------------------------------------------------------------------------------ |
-| `orrery`             | Command reference.                                                                                            |
-| `orrery init`        | Initialize Orrery: install skills to detected agents.                                                         |
-| `orrery manual`      | Show the full CLI reference manual.                                                                           |
-| `orrery orchestrate` | Executes the active plan. Use `--review` for review loop, `--parallel` for parallel execution. Alias: `exec`. |
-| `orrery status`      | Shows the progress of current plans.                                                                          |
+| Command              | Description                                                                                                                                     |
+| :------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `orrery`             | Command reference.                                                                                                                              |
+| `orrery init`        | Initialize Orrery: install skills to detected agents.                                                                                           |
+| `orrery manual`      | Show the full CLI reference manual.                                                                                                             |
+| `orrery orchestrate` | Executes the active plan. Use `--review` for review loop, `--parallel` for parallel execution, `--background` for detached mode. Alias: `exec`. |
+| `orrery resume`      | Unblock steps and resume orchestration. Use `--plan` to target a specific plan.                                                                 |
+| `orrery status`      | Shows the progress of current plans and active execution status.                                                                                |
 
 ## Directory Structure
 
-Orrery maintains its state in the `.agent-work/` directory (configurable via `ORRERY_WORK_DIR`).
+Orrery maintains its state in the `.agent-work/` directory (configurable via `ORRERY_WORK_DIR`). When `ORRERY_WORK_DIR` is set, each project gets an isolated subdirectory so multiple projects can share the same work directory.
 
 - `.agent-work/plans/`: **Active Plans.** New and in-progress plan files.
 - `.agent-work/reports/`: **Reports.** Step-level execution logs and outcomes.

package/agent/skills/discovery/SKILL.md

@@ -191,7 +191,15 @@ Use the schema defined in `./schemas/plan-schema.yaml`.
 
 **Output Location:**
 
-- Directory: `.agent-work/plans/`
+First, determine the plans directory by running:
+
+```bash
+orrery plans-dir
+```
+
+This prints the resolved plans directory (respects `ORRERY_WORK_DIR` when set).
+
+- Directory: the path returned by `orrery plans-dir`
 - Filename: `<date>-<plan-name>.yaml`
 - Date format: YYYY-MM-DD (e.g., `2026-01-11`)
 - Plan name: kebab-case description of the task (e.g., `fix-clone-agent-skills`)
@@ -215,7 +223,7 @@ Plans are automatically validated via the PostToolUse hook when written.
 For manual validation, run:
 
 ```bash
-orrery validate-plan .agent-work/plans/<plan>.yaml
+orrery validate-plan <plans-dir>/<plan>.yaml
 ```
 
 This catches common YAML issues like unquoted colons and normalizes formatting.
@@ -405,11 +413,11 @@ Discovery is complete when:
 When the plan is complete and validated, output the plan file path and present the user with their next options:
 
 ```
-Plan created: .agent-work/plans/<date>-<plan-name>.yaml
+Plan created: <plans-dir>/<date>-<plan-name>.yaml
 
 Next steps:
-- /refine-plan .agent-work/plans/<plan-file> — Analyze and improve the plan before execution
-- /simulate-plan .agent-work/plans/<plan-file> — Explore the plan through dialogue, ask "what if" questions
+- /refine-plan <plans-dir>/<plan-file> — Analyze and improve the plan before execution
+- /simulate-plan <plans-dir>/<plan-file> — Explore the plan through dialogue, ask "what if" questions
 - orrery exec — (Command run from the terminal) Execute the plan with the orrery orchestrator
 ```
 

package/agent/skills/orrery-execute/SKILL.md

@@ -39,7 +39,7 @@ These guidelines override generic examples in this skill. For example, if a guid
 
 ### Git State
 
-The orchestrator modifies `.agent-work/` files before you start (marking steps `in_progress`, creating temp files). This is expected. **Ignore changes in `.agent-work/`** when checking git status - these are orchestrator bookkeeping files, not unexpected changes.
+The orchestrator modifies plan and work directory files before you start (marking steps `in_progress`, creating temp files). This is expected. **Ignore changes in the orchestrator work directory** (e.g., `.agent-work/` or the path from `orrery plans-dir`) when checking git status - these are orchestrator bookkeeping files, not unexpected changes.
 
 ### Step 1: Read the Plan
 

package/agent/skills/refine-plan/SKILL.md

@@ -3,7 +3,8 @@ name: refine-plan
 description: >
   Analyze and improve an existing plan file. Reviews plan structure, dependencies,
   context quality, and acceptance criteria, then implements improvements directly.
-  Requires a plan file argument (e.g., /refine-plan .agent-work/plans/my-plan.yaml).
+  Requires a plan file argument (e.g., /refine-plan my-plan.yaml).
+  Run `orrery plans-dir` to find the plans directory.
 hooks:
   PostToolUse:
     - matcher: "Write"
@@ -273,7 +274,7 @@ Ready for execution.
 ## Example Dialogue
 
 ```
-User: /refine-plan .agent-work/plans/analytics-dashboard.yaml
+User: /refine-plan analytics-dashboard.yaml
 
 Agent: I've loaded the analytics dashboard plan. It has 6 steps delivering
 two outcomes. Let me analyze it for improvements.

package/agent/skills/simulate-plan/SKILL.md

@@ -2,7 +2,8 @@
 name: simulate-plan
 description: >
   Explore a plan through conversational dialogue before committing to execution.
-  Requires a plan file argument (e.g., /simulate-plan .agent-work/plans/my-plan.yaml, /simulate-plan my-plan).
+  Requires a plan file argument (e.g., /simulate-plan my-plan.yaml, /simulate-plan my-plan).
+  Run `orrery plans-dir` to find the plans directory.
   Ask "what if" questions, trace dependencies, and build intuition about what you're building.
 ---
 
@@ -164,7 +165,7 @@ Only discuss what's in the plan. If asked about implementation details not cover
 ## Example Dialogue
 
 ```
-User: /simulate .agent-work/plans/analytics-dashboard.yaml
+User: /simulate-plan analytics-dashboard.yaml
 
 Agent: I've loaded the analytics dashboard plan. It has 6 steps delivering
 two outcomes: "Users can see usage trends" and "Admins can export reports."

package/lib/cli/commands/orchestrate.js

@@ -1,4 +1,9 @@
+const { spawn } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
 const { orchestrate } = require("../../orchestration");
+const { getWorkDir } = require("../../utils/paths");
 
 module.exports = function registerOrchestrateCommand(program) {
   program
@@ -14,7 +19,54 @@ module.exports = function registerOrchestrateCommand(program) {
       "--parallel",
       "Enable parallel execution with git worktrees for isolation"
     )
+    .option(
+      "--background",
+      "Run orchestration as a detached background process"
+    )
     .action(async (options) => {
+      // Background mode: re-spawn as detached process
+      if (options.background) {
+        if (options.dryRun) {
+          console.log(
+            "Note: --background with --dry-run runs in foreground.\n"
+          );
+          // Fall through to normal execution
+        } else {
+          const args = [];
+          if (options.plan) args.push("--plan", options.plan);
+          if (options.verbose) args.push("--verbose");
+          if (options.resume) args.push("--resume");
+          if (options.review) args.push("--review");
+          if (options.parallel) args.push("--parallel");
+
+          const logFile = path.join(getWorkDir(), "exec.log");
+          const logFd = fs.openSync(logFile, "a");
+
+          const binPath = path.join(
+            __dirname,
+            "..",
+            "..",
+            "..",
+            "bin",
+            "orrery.js"
+          );
+          const child = spawn(process.execPath, [binPath, "exec", ...args], {
+            detached: true,
+            stdio: ["ignore", logFd, logFd],
+            cwd: process.cwd(),
+            env: process.env
+          });
+
+          child.unref();
+          fs.closeSync(logFd);
+
+          console.log(`Background execution started (PID ${child.pid})`);
+          console.log(`Log file: ${logFile}`);
+          console.log("\nUse 'orrery status' to check progress.");
+          return;
+        }
+      }
+
       try {
         await orchestrate({
           plan: options.plan,

package/lib/cli/commands/plans-dir.js

@@ -0,0 +1,10 @@
+const { getPlansDir } = require("../../utils/paths");
+
+module.exports = function registerPlansDirCommand(program) {
+  program
+    .command("plans-dir")
+    .description("Print the resolved plans directory path")
+    .action(() => {
+      console.log(getPlansDir());
+    });
+};

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

@@ -10,6 +10,7 @@ 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() {
@@ -36,6 +37,7 @@ function buildProgram() {
   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 };
   }
 }
 

package/lib/utils/git.js

@@ -22,7 +22,9 @@ function git(command, cwd) {
   } catch (error) {
     // Return stderr if available, otherwise throw
     if (error.stderr) {
-      throw new Error(`git ${command} failed: ${error.stderr.trim()}`);
+      throw new Error(`git ${command} failed: ${error.stderr.trim()}`, {
+        cause: error
+      });
     }
     throw error;
   }
@@ -34,7 +36,12 @@ function git(command, cwd) {
  * @returns {string} - Current branch name
  */
 function getCurrentBranch(cwd) {
-  return git("rev-parse --abbrev-ref HEAD", cwd);
+  try {
+    return git("rev-parse --abbrev-ref HEAD", cwd);
+  } catch {
+    // Unborn branch (no commits yet) — symbolic-ref still works
+    return git("symbolic-ref --short HEAD", cwd);
+  }
 }
 
 /**

package/lib/utils/lock.js

@@ -0,0 +1,170 @@
+const { execSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+const { getWorkDir } = require("./paths");
+
+const LOCK_FILE = "exec.lock";
+
+function getLockPath() {
+  return path.join(getWorkDir(), LOCK_FILE);
+}
+
+/**
+ * Check if a process with the given PID is running.
+ * @param {number} pid - Process ID
+ * @returns {boolean}
+ */
+function isProcessRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a PID belongs to an orrery process.
+ * @param {number} pid - Process ID
+ * @returns {boolean}
+ */
+function isOrreryProcess(pid) {
+  try {
+    // Linux: read /proc/<pid>/cmdline (null-separated args)
+    const cmdlinePath = `/proc/${pid}/cmdline`;
+    if (fs.existsSync(cmdlinePath)) {
+      const raw = fs.readFileSync(cmdlinePath, "utf8");
+      const args = raw.split("\0").filter(Boolean);
+      // Check if any argument ends with the orrery binary (bin/orrery.js or bin/orrery)
+      return args.some(
+        (arg) => arg.endsWith("bin/orrery.js") || arg.endsWith("bin/orrery")
+      );
+    }
+
+    // macOS/other: use ps
+    const args = execSync(`ps -p ${pid} -o args=`, {
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim();
+    return args.includes("bin/orrery.js") || args.includes("bin/orrery ");
+  } catch {
+    // Cannot determine — treat as stale (safe default)
+    return false;
+  }
+}
+
+/**
+ * Read and parse the lock file.
+ * @returns {{pid: number, startedAt: string, command: string}|null}
+ */
+function readLock() {
+  const lockPath = getLockPath();
+  try {
+    const content = fs.readFileSync(lockPath, "utf8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Attempt to acquire the execution lock.
+ * @returns {{acquired: boolean, reason?: string, pid?: number}}
+ */
+function acquireLock() {
+  const lockPath = getLockPath();
+  const lockData = {
+    pid: process.pid,
+    startedAt: new Date().toISOString(),
+    command: process.argv.slice(2).join(" ")
+  };
+
+  // Check for existing lock
+  const existing = readLock();
+  if (existing) {
+    const running = isProcessRunning(existing.pid);
+    if (running && isOrreryProcess(existing.pid)) {
+      return {
+        acquired: false,
+        reason: `Another orrery process is running (PID ${existing.pid}, started ${existing.startedAt})`,
+        pid: existing.pid
+      };
+    }
+
+    // Stale lock — remove it
+    try {
+      fs.unlinkSync(lockPath);
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+
+  // Atomic create
+  try {
+    fs.writeFileSync(lockPath, JSON.stringify(lockData, null, 2) + "\n", {
+      flag: "wx"
+    });
+    return { acquired: true };
+  } catch (err) {
+    if (err.code === "EEXIST") {
+      // Race condition — another process acquired between check and write
+      const raceWinner = readLock();
+      return {
+        acquired: false,
+        reason: `Another orrery process just started (PID ${raceWinner?.pid || "unknown"})`,
+        pid: raceWinner?.pid
+      };
+    }
+    return {
+      acquired: false,
+      reason: `Failed to create lock file: ${err.message}`
+    };
+  }
+}
+
+/**
+ * Release the execution lock (only if owned by current process).
+ */
+function releaseLock() {
+  const lockPath = getLockPath();
+  const existing = readLock();
+
+  if (existing && existing.pid === process.pid) {
+    try {
+      fs.unlinkSync(lockPath);
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+}
+
+/**
+ * Get the current lock status (read-only).
+ * @returns {{locked: boolean, pid?: number, startedAt?: string, stale: boolean}}
+ */
+function getLockStatus() {
+  const existing = readLock();
+
+  if (!existing) {
+    return { locked: false, stale: false };
+  }
+
+  const running = isProcessRunning(existing.pid);
+  const isOrrery = running && isOrreryProcess(existing.pid);
+
+  return {
+    locked: isOrrery,
+    pid: existing.pid,
+    startedAt: existing.startedAt,
+    stale: !isOrrery
+  };
+}
+
+module.exports = {
+  acquireLock,
+  releaseLock,
+  getLockStatus,
+  isProcessRunning,
+  isOrreryProcess
+};

package/lib/utils/paths.js

@@ -1,3 +1,4 @@
+const crypto = require("crypto");
 const fs = require("fs");
 const path = require("path");
 
@@ -10,10 +11,28 @@ function ensureDir(dirPath) {
   return dirPath;
 }
 
+/**
+ * Generate a deterministic project identifier from the current working directory.
+ * Format: <sanitized-basename>-<hash8>
+ * @returns {string} - Project identifier
+ */
+function getProjectId() {
+  const cwd = path.resolve(process.cwd());
+  const basename = path.basename(cwd) || "root";
+  const sanitized = basename.replace(/[^a-zA-Z0-9._-]/g, "_");
+  const hash = crypto
+    .createHash("sha256")
+    .update(cwd)
+    .digest("hex")
+    .slice(0, 8);
+  return `${sanitized}-${hash}`;
+}
+
 function getWorkDir() {
   const envDir = process.env[WORK_DIR_ENV];
   if (envDir && envDir.trim()) {
-    return ensureDir(envDir.trim());
+    const projectScoped = path.join(envDir.trim(), getProjectId());
+    return ensureDir(projectScoped);
   }
   return ensureDir(path.join(process.cwd(), ".agent-work"));
 }
@@ -34,10 +53,18 @@ function getTempDir() {
   return ensureDir(path.join(getWorkDir(), "temp"));
 }
 
+function isWorkDirExternal() {
+  const workDir = path.resolve(getWorkDir());
+  const cwd = path.resolve(process.cwd());
+  return !workDir.startsWith(cwd + path.sep) && workDir !== cwd;
+}
+
 module.exports = {
   getWorkDir,
   getPlansDir,
   getCompletedDir,
   getReportsDir,
-  getTempDir
+  getTempDir,
+  getProjectId,
+  isWorkDirExternal
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caseyharalson/orrery",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Workflow planning and orchestration CLI for AI agents",
   "license": "MIT",
   "author": "Casey Haralson",
@@ -52,7 +52,8 @@
     "yaml": "^2.8.2"
   },
   "devDependencies": {
-    "eslint": "^9.39.2",
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.0.1",
     "eslint-config-prettier": "^10.1.8",
     "prettier": "^3.8.1"
   }