@neriros/ralphy 2.7.3 → 2.7.5

package/README.md

@@ -105,11 +105,21 @@ Defaults are written to `ralphy.config.json` on first run; CLI flags override co
     "doneLabel": "ralphy-done",
     "postComments": true,
   },
+  "useWorktree": true,
+  "cleanupWorktreeOnSuccess": false,
+  "setupScript": "bun install",
+  "teardownScript": "git status",
 }
 ```
 
 `doneStatus` and `doneLabel` are independent — set either, both, or neither. Use `doneLabel` if your team marks completion via a label rather than a workflow state.
 
+#### Per-task git worktrees
+
+With `--worktree` (or `useWorktree: true` in config) each task runs in an isolated worktree at `.ralph/worktrees/<change-name>` checked out onto a fresh `ralph/<change-name>` branch. The change is scaffolded _inside_ the worktree, and the loop's cwd is the worktree, so concurrent workers can't stomp on each other.
+
+Use `setupScript` (run inside the worktree right after scaffolding) to install dependencies, copy `.env`, etc. Use `teardownScript` (run after the loop exits, before any worktree cleanup) to gather artifacts or roll back local mutations. Both run via `sh -c`; failures are logged but never block the loop. With `cleanupWorktreeOnSuccess: true` the worktree is removed when the worker exits 0 — failed workers always keep their worktree (and branch) for human inspection.
+
 Failed workers (non-zero exit) are not marked processed, so they'll be retried on the next poll. SIGINT/SIGTERM cleanly stops polling and kills active workers. All Linear side effects are best-effort — failures log a warning but never block the task loop.
 
 ## CLI Options
@@ -133,14 +143,18 @@ Failed workers (non-zero exit) are not marked processed, so they'll be retried o
 
 ### Agent mode flags
 
-| Option                   | Description                                  |
-| ------------------------ | -------------------------------------------- |
-| `--linear-team <key>`    | Linear team key (e.g. `ENG`)                 |
-| `--linear-assignee <id>` | Filter by assignee (user id, email, or `me`) |
-| `--linear-status <name>` | Filter by status name (repeatable)           |
-| `--linear-label <name>`  | Filter by label name (repeatable, any-of)    |
-| `--poll-interval <s>`    | Seconds between Linear polls (default: 60)   |
-| `--concurrency <n>`      | Max concurrent task loops (default: 1)       |
+| Option                        | Description                                   |
+| ----------------------------- | --------------------------------------------- |
+| `--linear-team <key>`         | Linear team key (e.g. `ENG`)                  |
+| `--linear-assignee <id>`      | Filter by assignee (user id, email, or `me`)  |
+| `--linear-status <name>`      | Filter by status name (repeatable)            |
+| `--linear-label <name>`       | Filter by label name (repeatable, any-of)     |
+| `--poll-interval <s>`         | Seconds between Linear polls (default: 60)    |
+| `--concurrency <n>`           | Max concurrent task loops (default: 1)        |
+| `--worktree`                  | Run each task in its own git worktree         |
+| `--in-progress-status <name>` | Linear status to set when work starts         |
+| `--done-status <name>`        | Linear status to set on successful completion |
+| `--done-label <name>`         | Linear label to add on successful completion  |
 
 ## OpenSpec Flow
 

package/dist/cli/index.js

@@ -49811,10 +49811,10 @@ var require_axios = __commonJS((exports, module) => {
   } = utils$1;
   var globalFetchAPI = (({
     Request,
-    Response
+    Response: Response2
   }) => ({
     Request,
-    Response
+    Response: Response2
   }))(utils$1.global);
   var {
     ReadableStream: ReadableStream$1,
@@ -49834,11 +49834,11 @@ var require_axios = __commonJS((exports, module) => {
     const {
       fetch: envFetch,
       Request,
-      Response
+      Response: Response2
     } = env3;
     const isFetchSupported = envFetch ? isFunction2(envFetch) : typeof fetch === "function";
     const isRequestSupported = isFunction2(Request);
-    const isResponseSupported = isFunction2(Response);
+    const isResponseSupported = isFunction2(Response2);
     if (!isFetchSupported) {
       return false;
     }
@@ -49860,7 +49860,7 @@ var require_axios = __commonJS((exports, module) => {
       }
       return duplexAccessed && !hasContentType;
     });
-    const supportsResponseStream = isResponseSupported && isReadableStreamSupported && test(() => utils$1.isReadableStream(new Response("").body));
+    const supportsResponseStream = isResponseSupported && isReadableStreamSupported && test(() => utils$1.isReadableStream(new Response2("").body));
     const resolvers = {
       stream: supportsResponseStream && ((res) => res.body)
     };
@@ -49971,7 +49971,7 @@ var require_axios = __commonJS((exports, module) => {
           });
           const responseContentLength = utils$1.toFiniteNumber(response.headers.get("content-length"));
           const [onProgress, flush] = onDownloadProgress && progressEventDecorator(responseContentLength, progressEventReducer(asyncDecorator(onDownloadProgress), true)) || [];
-          response = new Response(trackStream(response.body, DEFAULT_CHUNK_SIZE, onProgress, () => {
+          response = new Response2(trackStream(response.body, DEFAULT_CHUNK_SIZE, onProgress, () => {
             flush && flush();
             unsubscribe && unsubscribe();
           }), options);
@@ -50006,9 +50006,9 @@ var require_axios = __commonJS((exports, module) => {
     const {
       fetch: fetch2,
       Request,
-      Response
+      Response: Response2
     } = env3;
-    const seeds = [Request, Response, fetch2];
+    const seeds = [Request, Response2, fetch2];
     let len = seeds.length, i = len, seed, target, map2 = seedCache;
     while (i--) {
       seed = seeds[i];
@@ -50548,7 +50548,7 @@ var require_axios = __commonJS((exports, module) => {
 });
 
 // apps/cli/src/index.ts
-import { resolve, join as join15, dirname as dirname4 } from "path";
+import { resolve, join as join17, dirname as dirname4 } from "path";
 import { exists, mkdir as mkdir3 } from "fs/promises";
 
 // node_modules/.bun/ink@5.2.1+1f88f629f0141b18/node_modules/ink/build/render.js
@@ -56152,6 +56152,10 @@ var HELP_TEXT = [
   "  --linear-label <name>   Filter by label name (repeatable, any-of)",
   "  --poll-interval <s>     Seconds between Linear polls (default: 60)",
   "  --concurrency <n>       Max concurrent task loops (default: 1)",
+  "  --worktree              Run each task in its own git worktree (.ralph/worktrees/<name>)",
+  "  --in-progress-status <name>  Linear status to set when work starts on an issue",
+  "  --done-status <name>    Linear status to set when work completes successfully",
+  "  --done-label <name>     Linear label to add when work completes successfully",
   "",
   "  --help, -h              Show this help message",
   "",
@@ -56187,7 +56191,11 @@ async function parseArgs(argv) {
     linearStatus: [],
     linearLabel: [],
     pollInterval: 60,
-    concurrency: 1
+    concurrency: 1,
+    worktree: false,
+    inProgressStatus: "",
+    doneStatus: "",
+    doneLabel: ""
   };
   let expectModel = false;
   let expectModelFlag = false;
@@ -56207,6 +56215,9 @@ async function parseArgs(argv) {
   let expectLinearLabel = false;
   let expectPollInterval = false;
   let expectConcurrency = false;
+  let expectInProgressStatus = false;
+  let expectDoneStatus = false;
+  let expectDoneLabel = false;
   for (const arg of argv) {
     if (expectModel) {
       if (VALID_MODELS.has(arg)) {
@@ -56302,6 +56313,21 @@ async function parseArgs(argv) {
       expectConcurrency = false;
       continue;
     }
+    if (expectInProgressStatus) {
+      result2.inProgressStatus = arg;
+      expectInProgressStatus = false;
+      continue;
+    }
+    if (expectDoneStatus) {
+      result2.doneStatus = arg;
+      expectDoneStatus = false;
+      continue;
+    }
+    if (expectDoneLabel) {
+      result2.doneLabel = arg;
+      expectDoneLabel = false;
+      continue;
+    }
     switch (arg) {
       case "--claude":
         if (result2.engineSet && result2.engine !== "claude") {
@@ -56378,6 +56404,18 @@ async function parseArgs(argv) {
       case "--concurrency":
         expectConcurrency = true;
         break;
+      case "--worktree":
+        result2.worktree = true;
+        break;
+      case "--in-progress-status":
+        expectInProgressStatus = true;
+        break;
+      case "--done-status":
+        expectDoneStatus = true;
+        break;
+      case "--done-label":
+        expectDoneLabel = true;
+        break;
       default:
         if (VALID_MODES.has(arg)) {
           result2.mode = arg;
@@ -56445,7 +56483,7 @@ function createDefaultContext() {
 
 // apps/cli/src/components/App.tsx
 var import_react58 = __toESM(require_react(), 1);
-import { join as join14 } from "path";
+import { join as join16 } from "path";
 
 // packages/core/src/state.ts
 import { join as join2 } from "path";
@@ -69801,6 +69839,10 @@ var RalphyConfigSchema = exports_external.object({
   pollIntervalSeconds: exports_external.number().int().positive().default(60),
   maxIterationsPerTask: exports_external.number().int().nonnegative().default(0),
   maxCostUsdPerTask: exports_external.number().nonnegative().default(0),
+  useWorktree: exports_external.boolean().default(false),
+  cleanupWorktreeOnSuccess: exports_external.boolean().default(false),
+  setupScript: exports_external.string().optional(),
+  teardownScript: exports_external.string().optional(),
   engine: exports_external.enum(["claude", "codex"]).default("claude"),
   model: exports_external.enum(["haiku", "sonnet", "opus"]).default("opus"),
   linear: exports_external.object({
@@ -70026,8 +70068,55 @@ class AgentCoordinator {
   }
 }
 
+// apps/cli/src/agent/worktree.ts
+import { join as join13 } from "path";
+function worktreesDir(projectRoot) {
+  return join13(projectRoot, ".ralph", "worktrees");
+}
+function branchForChange(changeName) {
+  return `ralph/${changeName}`;
+}
+async function createWorktree(projectRoot, changeName, runner) {
+  const dir = worktreesDir(projectRoot);
+  const cwd2 = join13(dir, changeName);
+  const branch = branchForChange(changeName);
+  const list = await runner.run(["worktree", "list", "--porcelain"], projectRoot);
+  if (list.stdout.includes(`worktree ${cwd2}
+`)) {
+    return { cwd: cwd2, branch };
+  }
+  let branchExists = true;
+  try {
+    await runner.run(["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`], projectRoot);
+  } catch {
+    branchExists = false;
+  }
+  const cmd = branchExists ? ["worktree", "add", cwd2, branch] : ["worktree", "add", "-b", branch, cwd2];
+  await runner.run(cmd, projectRoot);
+  return { cwd: cwd2, branch };
+}
+async function removeWorktree(projectRoot, cwd2, runner) {
+  await runner.run(["worktree", "remove", "--force", cwd2], projectRoot);
+}
+
 // apps/cli/src/components/AgentMode.tsx
 var jsx_dev_runtime9 = __toESM(require_jsx_dev_runtime(), 1);
+import { join as join14 } from "path";
+var bunGitRunner = {
+  run: async (args, cwd2) => {
+    const proc = Bun.spawn({ cmd: ["git", ...args], cwd: cwd2, stdout: "pipe", stderr: "pipe" });
+    const stdout = await new Response(proc.stdout).text();
+    const stderr = await new Response(proc.stderr).text();
+    const code = await proc.exited;
+    if (code !== 0) {
+      const err = new Error("git command failed");
+      err.stderr = stderr;
+      err.code = code;
+      throw err;
+    }
+    return { stdout, stderr };
+  }
+};
 var lineCounter = 0;
 function nextId() {
   lineCounter += 1;
@@ -70066,6 +70155,24 @@ function AgentMode({ args, projectRoot, statesDir, tasksDir }) {
       const stateCache = new Map;
       const labelCache = new Map;
       const teamKeyOf = (issue) => issue.identifier.split("-")[0];
+      const useWorktree = args.worktree || cfg.useWorktree;
+      const cwdByChange = new Map;
+      async function runScript(label, cmd, cwd2) {
+        appendLog(`  ${label}: ${cmd}`, "gray");
+        const proc = Bun.spawn({
+          cmd: ["sh", "-c", cmd],
+          cwd: cwd2,
+          stdout: "ignore",
+          stderr: "pipe",
+          stdin: "ignore"
+        });
+        const code = await proc.exited;
+        if (code !== 0) {
+          const stderr = await new Response(proc.stderr).text();
+          appendLog(`! ${label} exited code ${code}${stderr ? `: ${stderr.trim().split(`
+`)[0]}` : ""}`, "yellow");
+        }
+      }
       const coord2 = new AgentCoordinator({
         fetchIssues: (f2) => fetchOpenIssues(apiKey, f2),
         scaffold: async (issue) => {
@@ -70075,7 +70182,27 @@ function AgentMode({ args, projectRoot, statesDir, tasksDir }) {
           } catch (err) {
             appendLog(`! Linear comment fetch failed for ${issue.identifier}: ${err.message}`, "yellow");
           }
-          return scaffoldChangeForIssue(tasksDir, statesDir, issue, comments);
+          let workerCwd = projectRoot;
+          let scaffoldTasksDir = tasksDir;
+          let scaffoldStatesDir = statesDir;
+          const probeName = issue.identifier.toLowerCase();
+          if (useWorktree) {
+            try {
+              const wt = await createWorktree(projectRoot, probeName, bunGitRunner);
+              workerCwd = wt.cwd;
+              scaffoldTasksDir = join14(wt.cwd, "openspec", "changes");
+              scaffoldStatesDir = join14(wt.cwd, ".ralph", "tasks");
+              appendLog(`  ${issue.identifier} worktree: ${wt.cwd} (${wt.branch})`, "gray");
+            } catch (err) {
+              appendLog(`! worktree create failed for ${issue.identifier}: ${err.message} \u2014 falling back to project root`, "yellow");
+            }
+          }
+          const changeName = await scaffoldChangeForIssue(scaffoldTasksDir, scaffoldStatesDir, issue, comments);
+          cwdByChange.set(changeName, workerCwd);
+          if (cfg.setupScript) {
+            await runScript("setup", cfg.setupScript, workerCwd);
+          }
+          return changeName;
         },
         spawnWorker: (changeName) => {
           const cmd = [
@@ -70093,14 +70220,35 @@ function AgentMode({ args, projectRoot, statesDir, tasksDir }) {
           const maxCost = args.maxCostUsd || cfg.maxCostUsdPerTask;
           if (maxCost > 0)
             cmd.push("--max-cost", String(maxCost));
+          const cwd2 = cwdByChange.get(changeName) ?? projectRoot;
           const proc = Bun.spawn({
             cmd,
-            cwd: projectRoot,
+            cwd: cwd2,
             stdout: "ignore",
             stderr: "ignore",
             stdin: "ignore"
           });
-          return { exited: proc.exited, kill: () => proc.kill() };
+          const wrapped = proc.exited.then(async (code) => {
+            if (cfg.teardownScript) {
+              try {
+                await runScript("teardown", cfg.teardownScript, cwd2);
+              } catch {}
+            }
+            if (useWorktree && cwd2 !== projectRoot) {
+              const ok = code === 0;
+              if (ok && cfg.cleanupWorktreeOnSuccess) {
+                try {
+                  await removeWorktree(projectRoot, cwd2, bunGitRunner);
+                  appendLog(`  removed worktree ${cwd2}`, "gray");
+                } catch (err) {
+                  appendLog(`! worktree remove failed for ${changeName}: ${err.message}`, "yellow");
+                }
+              }
+            }
+            cwdByChange.delete(changeName);
+            return code;
+          });
+          return { exited: wrapped, kill: () => proc.kill() };
         },
         loadState: () => readAgentState(projectRoot),
         saveState: (s) => writeAgentState(projectRoot, s),
@@ -70134,9 +70282,9 @@ function AgentMode({ args, projectRoot, statesDir, tasksDir }) {
       }, {
         concurrency,
         filter: filter2,
-        inProgressStatus: cfg.linear.inProgressStatus,
-        doneStatus: cfg.linear.doneStatus,
-        doneLabel: cfg.linear.doneLabel,
+        inProgressStatus: args.inProgressStatus || cfg.linear.inProgressStatus,
+        doneStatus: args.doneStatus || cfg.linear.doneStatus,
+        doneLabel: args.doneLabel || cfg.linear.doneLabel,
         postComments: cfg.linear.postComments
       });
       coordRef.current = coord2;
@@ -70218,11 +70366,11 @@ function AgentMode({ args, projectRoot, statesDir, tasksDir }) {
 }
 
 // packages/openspec/src/openspec-change-store.ts
-import { join as join13, dirname as dirname3 } from "path";
+import { join as join15, dirname as dirname3 } from "path";
 import { readdir, mkdir as mkdir2 } from "fs/promises";
 function resolveOpenspecBin() {
   const pkgJsonPath = Bun.resolveSync("@fission-ai/openspec/package.json", import.meta.dir);
-  return join13(dirname3(pkgJsonPath), "bin", "openspec.js");
+  return join15(dirname3(pkgJsonPath), "bin", "openspec.js");
 }
 function runOpenspec(args, options = {}) {
   const stdio = options.inherit ? ["inherit", "inherit", "inherit"] : ["ignore", "pipe", "pipe"];
@@ -70248,7 +70396,7 @@ class OpenSpecChangeStore {
     }
   }
   getChangeDirectory(name) {
-    return join13("openspec", "changes", name);
+    return join15("openspec", "changes", name);
   }
   async listChanges() {
     const result2 = runOpenspec(["list", "--json"]);
@@ -70262,7 +70410,7 @@ class OpenSpecChangeStore {
         }
       } catch {}
     }
-    const changesDir = join13("openspec", "changes");
+    const changesDir = join15("openspec", "changes");
     if (!await Bun.file(changesDir).exists())
       return [];
     try {
@@ -70273,18 +70421,18 @@ class OpenSpecChangeStore {
     }
   }
   async readTaskList(name) {
-    const file = Bun.file(join13("openspec", "changes", name, "tasks.md"));
+    const file = Bun.file(join15("openspec", "changes", name, "tasks.md"));
     if (!await file.exists())
       return "";
     return await file.text();
   }
   async writeTaskList(name, content) {
-    const path = join13("openspec", "changes", name, "tasks.md");
+    const path = join15("openspec", "changes", name, "tasks.md");
     await mkdir2(dirname3(path), { recursive: true });
     await Bun.write(path, content);
   }
   async appendSteering(name, message) {
-    const path = join13("openspec", "changes", name, "steering.md");
+    const path = join15("openspec", "changes", name, "steering.md");
     const file = Bun.file(path);
     const existing = await file.exists() ? await file.text() : null;
     const updated = existing ? `${message}
@@ -70295,7 +70443,7 @@ ${existing.trimStart()}` : `${message}
     await Bun.write(path, updated);
   }
   async readSection(name, artifact, heading) {
-    const file = Bun.file(join13("openspec", "changes", name, artifact));
+    const file = Bun.file(join15("openspec", "changes", name, artifact));
     if (!await file.exists())
       return "";
     const content = await file.text();
@@ -70376,8 +70524,8 @@ function App2({ args, statesDir, tasksDir, projectRoot }) {
           message: "Error: --name is required for status mode"
         }, undefined, false, undefined, this);
       }
-      const stateDir = join14(statesDir, args.name);
-      if (getStorage().read(join14(stateDir, ".ralph-state.json")) === null) {
+      const stateDir = join16(statesDir, args.name);
+      if (getStorage().read(join16(stateDir, ".ralph-state.json")) === null) {
         return /* @__PURE__ */ jsx_dev_runtime10.jsxDEV(ErrorMessage, {
           message: `Error: change '${args.name}' not found`
         }, undefined, false, undefined, this);
@@ -70434,7 +70582,7 @@ if (typeof globalThis.Bun === "undefined") {
 async function findProjectRoot() {
   let dir = process.cwd();
   while (dir !== "/") {
-    if (await exists(join15(dir, "openspec")))
+    if (await exists(join17(dir, "openspec")))
       return dir;
     dir = resolve(dir, "..");
   }
@@ -70469,11 +70617,11 @@ try {
 capture("command_run", { mode: args.mode, engine: args.engine, model: args.model });
 try {
   const projectRoot = await findProjectRoot();
-  const statesDir = join15(projectRoot, ".ralph", "tasks");
-  const tasksDir = join15(projectRoot, "openspec", "changes");
+  const statesDir = join17(projectRoot, ".ralph", "tasks");
+  const tasksDir = join17(projectRoot, "openspec", "changes");
   if (args.mode === "init") {
     await mkdir3(statesDir, { recursive: true });
-    const openspecBin = join15(dirname4(Bun.resolveSync("@fission-ai/openspec/package.json", import.meta.dir)), "bin", "openspec.js");
+    const openspecBin = join17(dirname4(Bun.resolveSync("@fission-ai/openspec/package.json", import.meta.dir)), "bin", "openspec.js");
     Bun.spawnSync({
       cmd: [process.execPath, openspecBin, "init", "--tools", "none", "--force"],
       stdio: ["inherit", "inherit", "inherit"],
@@ -70481,13 +70629,13 @@ try {
     });
   }
   if (args.mode === "task" && args.name) {
-    await mkdir3(join15(statesDir, args.name), { recursive: true });
-    await mkdir3(join15(tasksDir, args.name), { recursive: true });
+    await mkdir3(join17(statesDir, args.name), { recursive: true });
+    await mkdir3(join17(tasksDir, args.name), { recursive: true });
   }
   if (args.mode === "agent") {
     await mkdir3(statesDir, { recursive: true });
     await mkdir3(tasksDir, { recursive: true });
-    await mkdir3(join15(projectRoot, ".ralph"), { recursive: true });
+    await mkdir3(join17(projectRoot, ".ralph"), { recursive: true });
   }
   await runWithContext(createDefaultContext(), async () => {
     const { waitUntilExit } = render_default(import_react59.createElement(App2, { args, statesDir, tasksDir, projectRoot }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neriros/ralphy",
-  "version": "2.7.3",
+  "version": "2.7.5",
   "description": "An iterative AI task execution framework. Orchestrates multi-phase autonomous work using Claude or Codex engines.",
   "keywords": [
     "agent",