@caseyharalson/orrery 0.13.0 → 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/agent-invoker.js

@@ -251,14 +251,28 @@ function createDefaultResult(stepId, exitCode, stderr) {
 }
 
 /**
- * Check if an error condition should trigger failover to another agent
+ * Check if agent stdout contains valid structured output (indicating a
+ * legitimate task-level result rather than an infrastructure failure).
+ * @param {string} stdout - Raw stdout from agent
+ * @returns {boolean}
+ */
+function hasValidAgentOutput(stdout) {
+  if (!stdout) return false;
+  const results = parseAgentResults(stdout);
+  return results.length > 0;
+}
+
+/**
+ * Check if an error condition should trigger failover to another agent.
+ * Failover triggers on any non-zero exit unless the agent produced valid
+ * structured output (indicating a legitimate task-level failure, not an
+ * infrastructure issue).
  * @param {Object} result - Process result with exitCode, stdout, stderr
  * @param {Error} spawnError - Error from spawn (if any)
  * @param {boolean} timedOut - Whether the process timed out
- * @param {Object} errorPatterns - Regex patterns for error detection
  * @returns {{shouldFailover: boolean, reason: string}}
  */
-function shouldTriggerFailover(result, spawnError, timedOut, errorPatterns) {
+function shouldTriggerFailover(result, spawnError, timedOut) {
   // 1. Spawn failures (command not found, ENOENT)
   if (spawnError) {
     if (spawnError.code === "ENOENT") {
@@ -272,23 +286,12 @@ function shouldTriggerFailover(result, spawnError, timedOut, errorPatterns) {
     return { shouldFailover: true, reason: "timeout" };
   }
 
-  // 3. Non-zero exit with error patterns in stderr (but NOT legitimate blocked)
+  // 3. Non-zero exit — failover unless agent produced valid structured output
   if (result && result.exitCode !== 0) {
-    const stderr = result.stderr || "";
-
-    // Check API error patterns
-    for (const pattern of errorPatterns.apiError || []) {
-      if (pattern.test(stderr)) {
-        return { shouldFailover: true, reason: "api_error" };
-      }
-    }
-
-    // Check token limit patterns
-    for (const pattern of errorPatterns.tokenLimit || []) {
-      if (pattern.test(stderr)) {
-        return { shouldFailover: true, reason: "token_limit" };
-      }
+    if (hasValidAgentOutput(result.stdout)) {
+      return { shouldFailover: false, reason: null };
     }
+    return { shouldFailover: true, reason: "agent_error" };
   }
 
   return { shouldFailover: false, reason: null };
@@ -513,8 +516,7 @@ function invokeAgentWithFailover(
         const { shouldFailover, reason } = shouldTriggerFailover(
           result,
           null,
-          result.timedOut,
-          failoverConfig.errorPatterns || {}
+          result.timedOut
         );
 
         if (shouldFailover && i < availableAgents.length - 1) {
@@ -535,8 +537,7 @@ function invokeAgentWithFailover(
         const { shouldFailover, reason } = shouldTriggerFailover(
           null,
           spawnError,
-          false,
-          failoverConfig.errorPatterns || {}
+          false
         );
 
         if (shouldFailover && i < availableAgents.length - 1) {
@@ -595,6 +596,7 @@ module.exports = {
   invokeAgentWithFailover,
   parseAgentResults,
   createDefaultResult,
+  shouldTriggerFailover,
   waitForAll,
   waitForAny
 };

package/lib/orchestration/config.js

@@ -146,30 +146,7 @@ module.exports = {
 
     // Timeout in milliseconds before trying next agent (15 minutes)
     // Can be overridden via ORRERY_AGENT_TIMEOUT environment variable
-    timeoutMs: 900000,
-
-    // Patterns to detect failover-triggering errors from stderr
-    errorPatterns: {
-      // API/connection errors
-      apiError: [
-        /API error/i,
-        /connection refused/i,
-        /ECONNRESET/i,
-        /ETIMEDOUT/i,
-        /network error/i,
-        /rate limit/i,
-        /429/,
-        /502/,
-        /503/
-      ],
-      // Token/context limit errors
-      tokenLimit: [
-        /token limit/i,
-        /context.*(limit|length|exceeded)/i,
-        /maximum.*tokens/i,
-        /too long/i
-      ]
-    }
+    timeoutMs: 900000
   },
 
   // Concurrency control

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.0",
+  "version": "0.14.0",
   "description": "Workflow planning and orchestration CLI for AI agents",
   "license": "MIT",
   "author": "Casey Haralson",