executant 1.20.0 → 1.21.1

package/README.md

@@ -115,10 +115,43 @@ steps:
       This is pass {{item}} of 5. Review src/runner.ts for untested edge cases.
 ```
 
+## Variables at Runtime
+
+Pass `--var KEY=VALUE` on the command line to override or supply workflow vars without editing the YAML:
+
+```bash
+executant --var env=staging --var region=eu-west-1 deploy.yaml
+```
+
+CLI vars override any same-named vars in the workflow's `vars:` section. Multiple `--var` flags are accepted.
+
 ## Quality Controls
 
 - **`llm_as_judge: true`** — after a step completes, Claude evaluates the output; retries with feedback on FAIL, up to 5×
 - **`self_healing: true`** — on script failure, Claude diagnoses and repairs the command, then re-runs it, up to 5×
+- **`timeout_seconds: N`** — kill the step after N seconds and fail with exit code 3. Works for both script and prompt steps.
+
+```yaml
+steps:
+  - name: install
+    command: npm ci
+    timeout_seconds: 120   # fail if install takes longer than 2 min
+
+  - name: implement
+    prompt: Implement the feature described above.
+    timeout_seconds: 1800  # 30 min ceiling for the Claude step
+```
+
+## Cancellation
+
+Write a `.executant-cancel` file in the **same directory as the workflow YAML** to stop the workflow cleanly **between steps**:
+
+```bash
+executant long-workflow.yaml &
+touch .executant-cancel   # workflow stops at the next step boundary; exits 4
+```
+
+The file is deleted automatically. This is a cooperative, process-safe alternative to SIGTERM — no mid-step git state corruption. The cancel file is always resolved relative to the workflow file, so the location is predictable regardless of which directory you invoked executant from.
 
 ## Interjection
 
@@ -162,9 +195,20 @@ executant workflow.yaml                         # run a workflow
 executant --ci workflow.yaml                    # headless, NDJSON to stdout
 executant --step <name|n> wf.yaml              # run one step by name or index
 executant --from-step <n> wf.yaml              # resume from step n
+executant --var KEY=VALUE wf.yaml              # override a workflow var at runtime
 executant update                                # upgrade to latest version
 ```
 
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | All steps completed successfully |
+| `1` | A step failed at runtime |
+| `2` | YAML or variable validation error |
+| `3` | A step timed out (`timeout_seconds` exceeded) |
+| `4` | Cancelled via `.executant-cancel` file |
+
 ## Development
 
 ```bash

package/dist/index.js

@@ -52,8 +52,8 @@ var init_update = __esm({
 // src/index.ts
 import React3 from "react";
 import { render } from "ink";
-import { readFileSync as readFileSync6 } from "node:fs";
-import { dirname as dirname4, join as join4 } from "node:path";
+import { mkdirSync as mkdirSync4, readFileSync as readFileSync6 } from "node:fs";
+import { dirname as dirname4, join as join5, resolve as resolve3 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // src/load-workflow.ts
@@ -154,7 +154,8 @@ var RawStepSchema = z.lazy(
     forEach: z.union([z.array(z.string()), z.string()]).optional(),
     repeat: z.number().int().positive().optional(),
     context: z.array(z.string()).optional(),
-    steps: z.array(RawStepSchema).min(1).optional()
+    steps: z.array(RawStepSchema).min(1).optional(),
+    timeout_seconds: z.number().positive().optional()
   })
 );
 var RawWorkflowSchema = z.object({
@@ -162,7 +163,7 @@ var RawWorkflowSchema = z.object({
   steps: z.array(RawStepSchema),
   vars: z.record(z.string(), z.string()).optional()
 });
-function loadWorkflow(filePath2) {
+function loadWorkflow(filePath2, cliVars2 = {}) {
   let raw;
   try {
     raw = readFileSync2(filePath2, "utf8");
@@ -179,7 +180,7 @@ function loadWorkflow(filePath2) {
     throw new Error(`Invalid workflow file "${filePath2}":
 ${detail}`);
   }
-  const vars = doc.vars ?? {};
+  const vars = { ...doc.vars ?? {}, ...cliVars2 };
   const seen = /* @__PURE__ */ new Set();
   for (const step of doc.steps) {
     if (seen.has(step.name)) {
@@ -243,6 +244,9 @@ function convertInnerStep(step, vars, name, continueOnError) {
         maxHealingAttempts: step.max_healing_attempts,
         ...step.output && {
           output: resolveOutputFile(step.output, vars, name)
+        },
+        ...step.timeout_seconds !== void 0 && {
+          timeoutSeconds: step.timeout_seconds
         }
       };
     }
@@ -267,7 +271,10 @@ function convertInnerStep(step, vars, name, continueOnError) {
         llmAsJudge: step.llm_as_judge,
         allowedTools: step.allowed_tools,
         model: "sonnet",
-        ...contextFiles.length > 0 && { contextFiles }
+        ...contextFiles.length > 0 && { contextFiles },
+        ...step.timeout_seconds !== void 0 && {
+          timeoutSeconds: step.timeout_seconds
+        }
       };
     }
     default:
@@ -309,14 +316,42 @@ function substituteVars(text, vars, stepName, field) {
 
 // src/runner.ts
 import { exec } from "node:child_process";
-import { mkdirSync, readFileSync as readFileSync3, writeFileSync } from "node:fs";
-import { dirname as dirname2 } from "node:path";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync as readFileSync3,
+  unlinkSync,
+  writeFileSync
+} from "node:fs";
+import { dirname as dirname2, join as join2 } from "node:path";
 import { promisify } from "node:util";
 import { z as z2 } from "zod";
 
 // src/tasks/command.ts
 import { spawn } from "node:child_process";
 
+// src/types.ts
+var InterjectChannel = class {
+  _queue = [];
+  /** Called by the TUI when the user submits an interjection message. */
+  interject(message) {
+    this._queue.push(message);
+  }
+  /** Drains and returns any queued messages (for non-Claude steps to consume). */
+  consumeQueue() {
+    const q = this._queue.slice();
+    this._queue = [];
+    return q;
+  }
+};
+var TimeoutError = class extends Error {
+  exitCode = 3;
+  constructor(stepName, seconds) {
+    super(`Step "${stepName}" timed out after ${seconds}s`);
+    this.name = "TimeoutError";
+  }
+};
+
 // src/tasks/stream.ts
 var AsyncQueue = class {
   buf = [];
@@ -332,8 +367,8 @@ var AsyncQueue = class {
   }
   next() {
     if (this.buf.length > 0) return Promise.resolve(this.buf.shift());
-    return new Promise((resolve3) => {
-      this.waiter = resolve3;
+    return new Promise((resolve4) => {
+      this.waiter = resolve4;
     });
   }
   async *[Symbol.asyncIterator]() {
@@ -369,11 +404,30 @@ async function* mergeStreamsToLines(...streams) {
   yield* q;
 }
 function waitForExit(proc) {
-  return new Promise((resolve3, reject) => {
-    proc.on("close", (code) => resolve3(code ?? 0));
+  return new Promise((resolve4, reject) => {
+    proc.on("close", (code) => resolve4(code ?? 0));
     proc.on("error", reject);
   });
 }
+function startTimeout(proc, taskName, timeoutSeconds) {
+  if (timeoutSeconds == null) return { check: () => {
+  }, cancel: () => {
+  } };
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    try {
+      proc.kill();
+    } catch {
+    }
+  }, timeoutSeconds * 1e3);
+  return {
+    check: () => {
+      if (timedOut) throw new TimeoutError(taskName, timeoutSeconds);
+    },
+    cancel: () => clearTimeout(timer)
+  };
+}
 
 // src/tasks/command.ts
 var CommandError = class extends Error {
@@ -391,12 +445,22 @@ async function* runCommand(task) {
   const proc = spawn("bash", ["-c", task.command], {
     stdio: ["ignore", "pipe", "pipe"]
   });
-  for await (const line of mergeStreamsToLines(proc.stdout, proc.stderr)) {
-    yield { type: "output:text", index: -1, text: line };
-  }
-  const code = await waitForExit(proc);
-  if (code !== 0) {
-    throw new CommandError(code, task.command, `Command "${task.name}" exited with code ${code}`);
+  const timeout = startTimeout(proc, task.name, task.timeoutSeconds);
+  try {
+    for await (const line of mergeStreamsToLines(proc.stdout, proc.stderr)) {
+      yield { type: "output:text", index: -1, text: line };
+    }
+    const code = await waitForExit(proc);
+    timeout.check();
+    if (code !== 0) {
+      throw new CommandError(
+        code,
+        task.command,
+        `Command "${task.name}" exited with code ${code}`
+      );
+    }
+  } finally {
+    timeout.cancel();
   }
 }
 
@@ -458,6 +522,7 @@ async function* runClaude(task) {
   };
   process.once("SIGTERM", cleanup);
   process.once("SIGHUP", cleanup);
+  const timeout = startTimeout(proc, task.name, task.timeoutSeconds);
   const plainLines = [];
   try {
     for await (const line of mergeStreamsToLines(proc.stdout, proc.stderr)) {
@@ -474,8 +539,10 @@ async function* runClaude(task) {
       }
     }
     const code = await waitForExit(proc);
+    timeout.check();
     if (code !== 0) throw buildExitError(code, plainLines);
   } finally {
+    timeout.cancel();
     process.off("SIGTERM", cleanup);
     process.off("SIGHUP", cleanup);
   }
@@ -560,10 +627,28 @@ function shouldSkipStep(stepNumber, name, options2) {
   }
   return options2.fromStep !== void 0 && stepNumber < options2.fromStep[0];
 }
+var LAST_OUTPUT_MAX_LINES = 100;
 async function* runWorkflow(workflow2, options2 = {}, channel2) {
   const workflowStart = Date.now();
+  const cancelFile = join2(
+    options2.workDir ?? process.cwd(),
+    ".executant-cancel"
+  );
   yield { type: "workflow:start", workflow: workflow2 };
+  let lastStepOutput;
   for (const [i, task] of workflow2.tasks.entries()) {
+    if (existsSync(cancelFile)) {
+      try {
+        unlinkSync(cancelFile);
+      } catch {
+      }
+      yield {
+        type: "workflow:cancelled",
+        workflow: workflow2,
+        durationMs: Date.now() - workflowStart
+      };
+      return;
+    }
     const stepNumber = i + 1;
     if (shouldSkipStep(stepNumber, task.name, options2)) {
       yield { type: "step:skip", index: i, name: task.name };
@@ -572,14 +657,20 @@ async function* runWorkflow(workflow2, options2 = {}, channel2) {
     const stepStart = Date.now();
     yield { type: "step:start", index: i, name: task.name };
     const from = options2.fromStep && options2.fromStep[0] === stepNumber ? options2.fromStep.slice(1) : void 0;
+    const lines = [];
     try {
       for await (const event of runStep(task, from, channel2)) {
         if (event.type === "step:iteration" || event.type === "step:inner" || event.type === "output:text" || event.type === "output:tool") {
+          if (event.type === "output:text") {
+            if (lines.length >= LAST_OUTPUT_MAX_LINES) lines.shift();
+            lines.push(event.text);
+          }
           yield { ...event, index: i };
         } else {
           yield event;
         }
       }
+      lastStepOutput = lines.join("\n") || void 0;
       yield {
         type: "step:complete",
         index: i,
@@ -588,14 +679,23 @@ async function* runWorkflow(workflow2, options2 = {}, channel2) {
       };
     } catch (err) {
       const error = normalizeError(err);
-      yield { type: "step:error", index: i, name: task.name, error };
+      const lastOutput = lines.join("\n") || void 0;
+      lastStepOutput = lastOutput;
+      yield {
+        type: "step:error",
+        index: i,
+        name: task.name,
+        error,
+        lastOutput
+      };
       if (!task.continueOnError) throw error;
     }
   }
   yield {
     type: "workflow:complete",
     workflow: workflow2,
-    durationMs: Date.now() - workflowStart
+    durationMs: Date.now() - workflowStart,
+    lastOutput: lastStepOutput
   };
 }
 async function* runStep(task, from, channel2) {
@@ -1058,6 +1158,7 @@ function reducer(state, event) {
     case "workflow:start":
       return { ...state, startTime: Date.now() };
     case "workflow:complete":
+    case "workflow:cancelled":
       return { ...state, endTime: Date.now() };
     case "step:start":
       return updateTask(state, event.index, {
@@ -1454,10 +1555,15 @@ function App({
           if (event.type === "workflow:complete") {
             setTimeout(() => exit(), EXIT_DELAY_MS);
           }
+          if (event.type === "workflow:cancelled") {
+            process.exitCode = 4;
+            setTimeout(() => exit(), EXIT_DELAY_MS);
+          }
         }
       } catch (err) {
         if (!active) return;
         dispatch({ type: "log", level: "error", text: getErrorMessage(err) });
+        process.exitCode = err instanceof TimeoutError ? 3 : 1;
         setTimeout(
           () => exit(err instanceof Error ? err : new Error(getErrorMessage(err))),
           EXIT_DELAY_MS
@@ -1601,8 +1707,8 @@ function App({
 }
 
 // src/plan.ts
-import { existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "node:fs";
-import { join as join2, resolve } from "node:path";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "node:fs";
+import { join as join3, resolve } from "node:path";
 import { dump as dumpYaml } from "js-yaml";
 import { z as z3 } from "zod";
 import { zodToJsonSchema as zodToJsonSchema2 } from "zod-to-json-schema";
@@ -1630,7 +1736,7 @@ function walkUp(startDir, check) {
   while (true) {
     const found = check(dir);
     if (found !== null) return found;
-    const parent = join2(dir, "..");
+    const parent = join3(dir, "..");
     if (resolve(parent) === resolve(dir)) return null;
     dir = parent;
   }
@@ -1638,13 +1744,13 @@ function walkUp(startDir, check) {
 function findGitRoot(startDir) {
   return walkUp(
     startDir,
-    (dir) => existsSync(join2(dir, ".git")) ? dir : null
+    (dir) => existsSync2(join3(dir, ".git")) ? dir : null
   );
 }
 function findProjectRoot(startDir) {
   return walkUp(startDir, (dir) => {
-    const candidate = join2(dir, ".claude", "executant.local", "tasks");
-    return existsSync(candidate) ? candidate : null;
+    const candidate = join3(dir, ".claude", "executant.local", "tasks");
+    return existsSync2(candidate) ? candidate : null;
   });
 }
 function isSimpleRequest(description) {
@@ -1684,7 +1790,7 @@ Examples:
       console.error("Error: -f/--file requires a file path argument");
       process.exit(1);
     }
-    if (!existsSync(filePath2)) {
+    if (!existsSync2(filePath2)) {
       console.error(`Error: File not found: ${filePath2}`);
       process.exit(1);
     }
@@ -1712,14 +1818,14 @@ Examples:
   let taskDir = findProjectRoot(process.cwd());
   if (!taskDir) {
     const base = findGitRoot(process.cwd()) ?? process.cwd();
-    taskDir = join2(base, ".claude", "executant.local", "tasks");
+    taskDir = join3(base, ".claude", "executant.local", "tasks");
     mkdirSync2(taskDir, { recursive: true });
   }
-  const todoDir = join2(taskDir, "todo");
+  const todoDir = join3(taskDir, "todo");
   mkdirSync2(todoDir, { recursive: true });
   const slug = slugify(description);
   const ts = timestamp();
-  const taskFile = join2(todoDir, `${ts}-${slug}.yaml`);
+  const taskFile = join3(todoDir, `${ts}-${slug}.yaml`);
   return { description, taskFile, todoDir, fast };
 }
 async function runPass3Judge(description, workflow2) {
@@ -2037,7 +2143,7 @@ ${PLAN_SYSTEM_RULES}`,
 }
 
 // src/refine.ts
-import { existsSync as existsSync2, readFileSync as readFileSync5 } from "node:fs";
+import { existsSync as existsSync3, readFileSync as readFileSync5 } from "node:fs";
 import { load as loadYaml } from "js-yaml";
 var PLAN_REFINE_PROMPT = loadPrompt("plan-refine");
 var PLAN_SYSTEM_RULES2 = loadPrompt("plan-system-rules");
@@ -2064,7 +2170,7 @@ Examples:
     console.error("Usage: executant refine <task-file> [INSTRUCTIONS]");
     process.exit(1);
   }
-  if (!existsSync2(taskFile)) {
+  if (!existsSync3(taskFile)) {
     console.error(`Error: File not found: ${taskFile}`);
     process.exit(1);
   }
@@ -2089,7 +2195,7 @@ Examples:
       console.error("Error: -f/--file requires a file path argument");
       process.exit(1);
     }
-    if (!existsSync2(filePath2)) {
+    if (!existsSync3(filePath2)) {
       console.error(`Error: File not found: ${filePath2}`);
       process.exit(1);
     }
@@ -2325,13 +2431,13 @@ function PlanApp({ description, events: events2 }) {
 }
 
 // src/logger.ts
-import { appendFileSync, existsSync as existsSync3, mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "node:fs";
-import { dirname as dirname3, join as join3, resolve as resolve2 } from "node:path";
+import { appendFileSync, existsSync as existsSync4, mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { dirname as dirname3, join as join4, resolve as resolve2 } from "node:path";
 function findExecutantLocalDir(startDir) {
   let dir = resolve2(startDir);
   while (true) {
-    const candidate = join3(dir, ".claude", "executant.local");
-    if (existsSync3(candidate)) return candidate;
+    const candidate = join4(dir, ".claude", "executant.local");
+    if (existsSync4(candidate)) return candidate;
     const parent = dirname3(dir);
     if (parent === dir) return null;
     dir = parent;
@@ -2340,7 +2446,7 @@ function findExecutantLocalDir(startDir) {
 function resolveLogDir(workflowFilePath) {
   const startDir = dirname3(resolve2(workflowFilePath));
   const executantLocal = findExecutantLocalDir(startDir);
-  return executantLocal ? join3(executantLocal, "logs") : join3(startDir, "logs");
+  return executantLocal ? join4(executantLocal, "logs") : join4(startDir, "logs");
 }
 var INIT_STATE = {
   logFile: "",
@@ -2353,7 +2459,7 @@ function appendLog(logFile, text) {
 }
 function onWorkflowStart(ctx, s) {
   mkdirSync3(ctx.logDir, { recursive: true });
-  const logFile = join3(ctx.logDir, `${ctx.ts}_${ctx.slug}.log`);
+  const logFile = join4(ctx.logDir, `${ctx.ts}_${ctx.slug}.log`);
   writeFileSync3(
     logFile,
     `# Execution Log
@@ -2450,6 +2556,7 @@ function reduce(ctx, s, event) {
     case "log":
       return onLogMessage(s, event.level, event.text);
     case "workflow:complete":
+    case "workflow:cancelled":
       return onWorkflowComplete(ctx, s);
     default:
       return s;
@@ -2481,25 +2588,10 @@ async function* withLogger(gen, logger2) {
   }
 }
 
-// src/types.ts
-var InterjectChannel = class {
-  _queue = [];
-  /** Called by the TUI when the user submits an interjection message. */
-  interject(message) {
-    this._queue.push(message);
-  }
-  /** Drains and returns any queued messages (for non-Claude steps to consume). */
-  consumeQueue() {
-    const q = this._queue.slice();
-    this._queue = [];
-    return q;
-  }
-};
-
 // src/index.ts
 var CURRENT_VERSION = JSON.parse(
   readFileSync6(
-    join4(dirname4(fileURLToPath2(import.meta.url)), "../package.json"),
+    join5(dirname4(fileURLToPath2(import.meta.url)), "../package.json"),
     "utf-8"
   )
 ).version;
@@ -2558,6 +2650,7 @@ Options:
   --ci                  Headless mode \u2014 print events as NDJSON, no TUI
   --step <name|index>   Run only the named step or step at 1-based index
   --from-step <n>       Resume from step n (e.g. 3, 3.2, 2.5.4.3 \u2014 1-based path)
+  --var KEY=VALUE       Override or supply a workflow var at runtime (repeatable)
   --help, -h            Show this help
 
 Commands:
@@ -2599,6 +2692,18 @@ YAML \u2014 script step fields (type: script | command, or inferred when command
   self_healing      bool    On failure, Claude diagnoses and fixes iteratively
                             up to 5 attempts with accumulated context (default: false)
   max_healing_attempts  int   Override max self-healing retries (default: 5)
+  timeout_seconds   number  Kill the step and fail with exit code 3 after N seconds
+
+Cancellation:
+  Write a .executant-cancel file in the working directory to stop execution
+  cleanly between steps (exit code 4). The file is deleted automatically.
+
+Exit codes:
+  0  All steps completed successfully
+  1  A step failed at runtime
+  2  YAML or variable validation error
+  3  A step timed out (timeout_seconds exceeded)
+  4  Cancelled via .executant-cancel file
 
 YAML \u2014 log step fields (type: log, or inferred when message is present and prompt is absent):
   message           string  Text to emit as a progress marker
@@ -2624,6 +2729,7 @@ Example:
 var ciMode = false;
 var stepFilter;
 var fromStep;
+var cliVars = {};
 var positional = [];
 for (let i = 0; i < rawArgs.length; i++) {
   const a = rawArgs[i];
@@ -2649,6 +2755,18 @@ for (let i = 0; i < rawArgs.length; i++) {
       process.exit(1);
     }
     fromStep = parts;
+  } else if (a === "--var") {
+    if (!rawArgs[i + 1]) {
+      console.error("--var requires a KEY=VALUE argument");
+      process.exit(1);
+    }
+    const pair = rawArgs[++i];
+    const eq = pair.indexOf("=");
+    if (eq <= 0) {
+      console.error(`--var value must be KEY=VALUE, got: ${pair}`);
+      process.exit(1);
+    }
+    cliVars[pair.slice(0, eq)] = pair.slice(eq + 1);
   } else {
     positional.push(a);
   }
@@ -2660,12 +2778,21 @@ if (!filePath) {
 }
 var workflow;
 try {
-  workflow = loadWorkflow(filePath);
+  workflow = loadWorkflow(filePath, cliVars);
 } catch (err) {
   console.error(getErrorMessage(err));
-  process.exit(1);
+  process.exit(2);
 }
-var options = { stepFilter, fromStep };
+var localDir = findExecutantLocalDir(dirname4(resolve3(filePath)));
+if (localDir) {
+  mkdirSync4(join5(localDir, "tasks", "todo"), { recursive: true });
+  mkdirSync4(join5(localDir, "tasks", "done"), { recursive: true });
+}
+var options = {
+  stepFilter,
+  fromStep,
+  workDir: dirname4(resolve3(filePath))
+};
 var channel = new InterjectChannel();
 var rawEvents = runWorkflow(workflow, options, channel);
 var logger = createLogger(resolveLogDir(filePath), workflow.goal);
@@ -2680,11 +2807,17 @@ function errorReplacer(_key, value) {
 if (ciMode) {
   (async () => {
     for await (const event of events) {
-      process.stdout.write(JSON.stringify(event, errorReplacer) + "\n");
+      const line = JSON.stringify(event, errorReplacer) + "\n";
+      if (event.type === "workflow:cancelled") {
+        process.stdout.write(line, () => process.exit(4));
+        return;
+      }
+      process.stdout.write(line);
     }
   })().catch((err) => {
+    const code = err instanceof TimeoutError ? 3 : 1;
     console.error(err);
-    process.exit(1);
+    process.exit(code);
   });
 } else {
   render(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "executant",
-  "version": "1.20.0",
+  "version": "1.21.1",
   "description": "Harness for YAML-defined workflows that enables stepping through Claude sessions and bash commands",
   "repository": {
     "type": "git",