@caseyharalson/orrery 0.13.1 → 0.14.0

package/lib/cli/commands/resume.js

@@ -93,6 +93,7 @@ module.exports = function registerResumeCommand(program) {
 
       let planFile;
       let plan;
+      let hasWorktree = false;
 
       if (options.plan) {
         // Resolve plan path (same pattern as status.js)
@@ -134,7 +135,7 @@ module.exports = function registerResumeCommand(program) {
           ".worktrees",
           `plan-${planId}`
         );
-        const hasWorktree = require("fs").existsSync(worktreePath);
+        hasWorktree = fs.existsSync(worktreePath);
 
         if (!hasWorktree) {
           // Verify current branch matches plan's work_branch
@@ -258,17 +259,21 @@ module.exports = function registerResumeCommand(program) {
         console.log(`  ${colorize("pending", "yellow")} ${step.id}`);
       }
 
-      // 7. Commit the plan file changes
-      const planName = planFileName.replace(/\.ya?ml$/, "");
-      const commitMessage = `chore: unblock steps in ${planName}`;
-      const commitHash = commit(commitMessage, [planFile], process.cwd());
+      // 7. Commit the plan file changes (only when not using a worktree,
+      //    since the plan file lives in the main repo's .agent-work/, not
+      //    inside the worktree's git tree)
+      if (!hasWorktree) {
+        const planName = planFileName.replace(/\.ya?ml$/, "");
+        const commitMessage = `chore: unblock steps in ${planName}`;
+        const commitHash = commit(commitMessage, [planFile], process.cwd());
 
-      if (commitHash) {
-        console.log(
-          `\nCommitted: ${commitMessage} (${commitHash.slice(0, 7)})`
-        );
-      } else {
-        console.log("\n(no changes to commit)");
+        if (commitHash) {
+          console.log(
+            `\nCommitted: ${commitMessage} (${commitHash.slice(0, 7)})`
+          );
+        } else {
+          console.log("\n(no changes to commit)");
+        }
       }
 
       // 8. Resume orchestration

package/lib/cli/commands/stop.js

@@ -0,0 +1,146 @@
+const path = require("path");
+
+const { derivePlanId } = require("../../utils/git");
+const {
+  getLockStatus,
+  listPlanLocks,
+  readLock,
+  isOrreryProcess
+} = require("../../utils/lock");
+const { requestStop, clearStopSignal } = require("../../utils/stop-signal");
+
+function supportsColor() {
+  return Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+}
+
+function colorize(text, color) {
+  if (!supportsColor()) return text;
+  const colors = {
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    red: "\x1b[31m",
+    reset: "\x1b[0m"
+  };
+  return `${colors[color] || ""}${text}${colors.reset}`;
+}
+
+/**
+ * Send SIGTERM to a process after verifying it's an orrery process.
+ * @param {number} pid - Process ID
+ * @param {string} label - Label for log messages
+ * @returns {boolean} - Whether the signal was sent
+ */
+function killProcess(pid, label) {
+  if (!isOrreryProcess(pid)) {
+    console.log(
+      `  ${colorize("skipped", "yellow")} ${label} — PID ${pid} is not an orrery process`
+    );
+    return false;
+  }
+
+  try {
+    process.kill(pid, "SIGTERM");
+    console.log(
+      `  ${colorize("stopped", "green")} ${label} (PID ${pid}, sent SIGTERM)`
+    );
+    return true;
+  } catch (err) {
+    if (err.code === "ESRCH") {
+      console.log(
+        `  ${colorize("skipped", "yellow")} ${label} — PID ${pid} already exited`
+      );
+    } else {
+      console.log(`  ${colorize("failed", "red")} ${label} — ${err.message}`);
+    }
+    return false;
+  }
+}
+
+module.exports = function registerStopCommand(program) {
+  program
+    .command("stop")
+    .description("Stop running orchestrations")
+    .option("--plan <file>", "Stop a specific plan by name or file")
+    .option(
+      "--graceful",
+      "Finish current step(s) then stop (instead of immediate SIGTERM)"
+    )
+    .action((options) => {
+      const graceful = options.graceful || false;
+
+      if (options.plan) {
+        // Stop a specific plan
+        const planBasename = path.basename(options.plan);
+        const planId = derivePlanId(planBasename);
+
+        const lock = readLock(planId);
+        if (!lock) {
+          console.log(`No active execution found for plan "${planId}".`);
+          return;
+        }
+
+        const status = getLockStatus(planId);
+        if (status.stale) {
+          console.log(
+            `Lock for plan "${planId}" is stale (PID ${lock.pid} no longer running).`
+          );
+          return;
+        }
+
+        if (!status.locked) {
+          console.log(`No active execution found for plan "${planId}".`);
+          return;
+        }
+
+        if (graceful) {
+          requestStop(planId);
+          console.log(
+            `Graceful stop requested for plan "${planId}" — will stop after current step(s) finish.`
+          );
+        } else {
+          killProcess(lock.pid, `plan "${planId}"`);
+          clearStopSignal(planId);
+        }
+        return;
+      }
+
+      // Stop all running plans
+      const planLocks = listPlanLocks();
+      const activeLocks = planLocks.filter((l) => l.active);
+
+      // Also check global lock
+      const globalStatus = getLockStatus();
+      const globalLock = globalStatus.locked ? readLock() : null;
+
+      if (activeLocks.length === 0 && !globalLock) {
+        console.log("No active orchestrations found.");
+        return;
+      }
+
+      if (graceful) {
+        // Write signal files for all active plans + global
+        if (globalLock) {
+          requestStop();
+          console.log(
+            "Graceful stop requested for global execution — will stop after current step(s) finish."
+          );
+        }
+        for (const pl of activeLocks) {
+          requestStop(pl.planId);
+          console.log(
+            `Graceful stop requested for plan "${pl.planId}" — will stop after current step(s) finish.`
+          );
+        }
+      } else {
+        // Immediate stop via SIGTERM
+        if (globalLock) {
+          killProcess(globalLock.pid, "global execution");
+          clearStopSignal();
+        }
+        for (const pl of activeLocks) {
+          killProcess(pl.pid, `plan "${pl.planId}"`);
+          clearStopSignal(pl.planId);
+        }
+      }
+    });
+};

package/lib/cli/index.js

@@ -7,6 +7,7 @@ const registerInstallDevcontainer = require("./commands/install-devcontainer");
 const registerOrchestrate = require("./commands/orchestrate");
 const registerStatus = require("./commands/status");
 const registerResume = require("./commands/resume");
+const registerStop = require("./commands/stop");
 const registerValidatePlan = require("./commands/validate-plan");
 const registerIngestPlan = require("./commands/ingest-plan");
 const registerManual = require("./commands/manual");
@@ -34,6 +35,7 @@ function buildProgram() {
   registerOrchestrate(program);
   registerStatus(program);
   registerResume(program);
+  registerStop(program);
   registerValidatePlan(program);
   registerIngestPlan(program);
   registerManual(program);

package/lib/orchestration/index.js

@@ -77,6 +77,7 @@ const {
 
 const { ProgressTracker } = require("./progress-tracker");
 const { acquireLock, releaseLock } = require("../utils/lock");
+const { isStopRequested, clearStopSignal } = require("../utils/stop-signal");
 
 const REPO_ROOT = process.cwd();
 
@@ -333,8 +334,9 @@ async function orchestrate(options = {}) {
       return;
     }
 
-    // Clean up lock on signals
+    // Clean up lock and stop signals on signals
     const cleanupLock = () => {
+      clearStopSignal();
       releaseLock();
       process.exit();
     };
@@ -519,6 +521,8 @@ async function resumeInWorktree(
   }
 
   const cleanupLock = () => {
+    clearStopSignal(planId);
+    clearStopSignal();
     releaseLock(planId);
     process.exit();
   };
@@ -921,8 +925,10 @@ async function processPlanInWorktree(normalizedOptions) {
     return;
   }
 
-  // Clean up per-plan lock on signals
+  // Clean up per-plan lock and stop signals on signals
   const cleanupLock = () => {
+    clearStopSignal(planId);
+    clearStopSignal();
     releaseLock(planId);
     process.exit();
   };
@@ -1341,7 +1347,16 @@ async function processPlan(
   }
 
   // Main execution loop
+  const loopPlanId = derivePlanId(path.basename(planFile));
   while (!plan.isComplete()) {
+    // Check for graceful stop signal
+    if (isStopRequested(loopPlanId) || isStopRequested()) {
+      console.log("\nStop signal received — stopping after current step(s).");
+      clearStopSignal(loopPlanId);
+      clearStopSignal();
+      break;
+    }
+
     // Get steps ready to execute
     const readySteps = getReadySteps(plan);
 

package/lib/utils/stop-signal.js

@@ -0,0 +1,51 @@
+const fs = require("fs");
+const path = require("path");
+
+const { getWorkDir } = require("./paths");
+
+/**
+ * Get the path to the stop signal file.
+ * @param {string} [planId] - Optional plan ID for per-plan signals
+ * @returns {string} - Path to the signal file
+ */
+function getStopSignalPath(planId) {
+  const fileName = planId ? `stop-${planId}.signal` : "stop.signal";
+  return path.join(getWorkDir(), fileName);
+}
+
+/**
+ * Write a stop signal file to request graceful stop.
+ * @param {string} [planId] - Optional plan ID for per-plan signals
+ */
+function requestStop(planId) {
+  const signalPath = getStopSignalPath(planId);
+  fs.writeFileSync(signalPath, new Date().toISOString() + "\n");
+}
+
+/**
+ * Check if a stop signal has been requested.
+ * @param {string} [planId] - Optional plan ID for per-plan signals
+ * @returns {boolean}
+ */
+function isStopRequested(planId) {
+  return fs.existsSync(getStopSignalPath(planId));
+}
+
+/**
+ * Remove the stop signal file.
+ * @param {string} [planId] - Optional plan ID for per-plan signals
+ */
+function clearStopSignal(planId) {
+  try {
+    fs.unlinkSync(getStopSignalPath(planId));
+  } catch {
+    // Ignore if file doesn't exist
+  }
+}
+
+module.exports = {
+  getStopSignalPath,
+  requestStop,
+  isStopRequested,
+  clearStopSignal
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caseyharalson/orrery",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "Workflow planning and orchestration CLI for AI agents",
   "license": "MIT",
   "author": "Casey Haralson",