@neriros/ralphy 2.7.2 → 2.7.4

package/README.md

@@ -83,7 +83,7 @@ What it does on each tick:
 2. Dedupes against `.ralph/agent-state.json` (already processed) plus any in-flight workers
 3. For each new issue: fetches existing comments, scaffolds `openspec/changes/<id-slug>/{proposal.md,tasks.md,design.md}` (with the comments embedded so the worker sees prior discussion), then spawns `ralph task --name <id-slug>` up to the concurrency cap
 4. Posts a "🤖 started" comment on the Linear issue and (optionally) moves it to `inProgressStatus`
-5. On worker exit, posts a success/failure comment and (on success) moves the issue to `doneStatus`
+5. On worker exit, posts a success/failure comment and (on success) moves the issue to `doneStatus` and/or applies `doneLabel`
 
 Defaults are written to `ralphy.config.json` on first run; CLI flags override config values per invocation.
 
@@ -102,11 +102,24 @@ Defaults are written to `ralphy.config.json` on first run; CLI flags override co
     "labels": ["ralph", "automation"],
     "inProgressStatus": "In Progress",
     "doneStatus": "In Review",
+    "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
@@ -138,6 +151,7 @@ Failed workers (non-zero exit) are not marked processed, so they'll be retried o
 | `--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        |
 
 ## 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,7 @@ 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>)",
   "",
   "  --help, -h              Show this help message",
   "",
@@ -56187,7 +56188,8 @@ async function parseArgs(argv) {
     linearStatus: [],
     linearLabel: [],
     pollInterval: 60,
-    concurrency: 1
+    concurrency: 1,
+    worktree: false
   };
   let expectModel = false;
   let expectModelFlag = false;
@@ -56378,6 +56380,9 @@ async function parseArgs(argv) {
       case "--concurrency":
         expectConcurrency = true;
         break;
+      case "--worktree":
+        result2.worktree = true;
+        break;
       default:
         if (VALID_MODES.has(arg)) {
           result2.mode = arg;
@@ -56445,7 +56450,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";
@@ -69685,6 +69690,26 @@ async function updateIssueState(apiKey, issueId, stateId) {
     stateId
   });
 }
+async function fetchIssueLabels(apiKey, teamKey) {
+  const query = `query Labels($team: String!) {
+    issueLabels(filter: { team: { key: { eq: $team } } }, first: 250) {
+      nodes { id name }
+    }
+  }`;
+  const data = await linearRequest(apiKey, query, {
+    team: teamKey
+  });
+  return data.issueLabels.nodes;
+}
+async function addLabelToIssue(apiKey, issueId, labelId) {
+  const mutation = `mutation AddLabel($id: String!, $labelId: String!) {
+    issueAddLabel(id: $id, labelId: $labelId) { success }
+  }`;
+  await linearRequest(apiKey, mutation, {
+    id: issueId,
+    labelId
+  });
+}
 
 // apps/cli/src/agent/state.ts
 import { join as join10 } from "path";
@@ -69781,6 +69806,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({
@@ -69790,6 +69819,7 @@ var RalphyConfigSchema = exports_external.object({
     labels: exports_external.union([exports_external.array(exports_external.string()), exports_external.string()]).transform((v) => typeof v === "string" ? [v] : v).default([]),
     inProgressStatus: exports_external.string().optional(),
     doneStatus: exports_external.string().optional(),
+    doneLabel: exports_external.string().optional(),
     postComments: exports_external.boolean().default(true)
   }).default({ statuses: [], labels: [], postComments: true })
 }).default({
@@ -69959,6 +69989,27 @@ class AgentCoordinator {
     if (ok && this.opts.doneStatus) {
       await this.moveIssue(issue, this.opts.doneStatus);
     }
+    if (ok && this.opts.doneLabel) {
+      await this.tagIssue(issue, this.opts.doneLabel);
+    }
+  }
+  async tagIssue(issue, labelName) {
+    const updater = this.deps.updater;
+    if (!updater.resolveLabelId || !updater.addLabel) {
+      this.deps.onLog(`! Linear updater does not support labels (cannot tag ${issue.identifier} with '${labelName}')`, "yellow");
+      return;
+    }
+    try {
+      const labelId = await updater.resolveLabelId(issue, labelName);
+      if (!labelId) {
+        this.deps.onLog(`! Linear label '${labelName}' not found for ${issue.identifier}`, "yellow");
+        return;
+      }
+      await updater.addLabel(issue, labelId);
+      this.deps.onLog(`  \u2192 ${issue.identifier} tagged with '${labelName}'`, "gray");
+    } catch (err) {
+      this.deps.onLog(`! Linear label add failed for ${issue.identifier}: ${err.message}`, "red");
+    }
   }
   async moveIssue(issue, stateName) {
     const updater = this.deps.updater;
@@ -69984,8 +70035,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;
@@ -70022,7 +70120,26 @@ function AgentMode({ args, projectRoot, statesDir, tasksDir }) {
         labels: args.linearLabel.length ? args.linearLabel : cfg.linear.labels
       };
       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) => {
@@ -70032,7 +70149,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 = [
@@ -70050,14 +70187,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),
@@ -70075,6 +70233,17 @@ function AgentMode({ args, projectRoot, statesDir, tasksDir }) {
               stateCache.set(team, map2);
             }
             return map2.get(stateName.toLowerCase()) ?? null;
+          },
+          addLabel: (issue, labelId) => addLabelToIssue(apiKey, issue.id, labelId),
+          resolveLabelId: async (issue, labelName) => {
+            const team = teamKeyOf(issue);
+            let map2 = labelCache.get(team);
+            if (!map2) {
+              const labels = await fetchIssueLabels(apiKey, team);
+              map2 = new Map(labels.map((l) => [l.name.toLowerCase(), l.id]));
+              labelCache.set(team, map2);
+            }
+            return map2.get(labelName.toLowerCase()) ?? null;
           }
         }
       }, {
@@ -70082,6 +70251,7 @@ function AgentMode({ args, projectRoot, statesDir, tasksDir }) {
         filter: filter2,
         inProgressStatus: cfg.linear.inProgressStatus,
         doneStatus: cfg.linear.doneStatus,
+        doneLabel: cfg.linear.doneLabel,
         postComments: cfg.linear.postComments
       });
       coordRef.current = coord2;
@@ -70163,11 +70333,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"];
@@ -70193,7 +70363,7 @@ class OpenSpecChangeStore {
     }
   }
   getChangeDirectory(name) {
-    return join13("openspec", "changes", name);
+    return join15("openspec", "changes", name);
   }
   async listChanges() {
     const result2 = runOpenspec(["list", "--json"]);
@@ -70207,7 +70377,7 @@ class OpenSpecChangeStore {
         }
       } catch {}
     }
-    const changesDir = join13("openspec", "changes");
+    const changesDir = join15("openspec", "changes");
     if (!await Bun.file(changesDir).exists())
       return [];
     try {
@@ -70218,18 +70388,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}
@@ -70240,7 +70410,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();
@@ -70321,8 +70491,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);
@@ -70379,7 +70549,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, "..");
   }
@@ -70414,11 +70584,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"],
@@ -70426,13 +70596,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.2",
+  "version": "2.7.4",
   "description": "An iterative AI task execution framework. Orchestrates multi-phase autonomous work using Claude or Codex engines.",
   "keywords": [
     "agent",