leopold-driver 0.5.0 → 0.6.0

package/assets/VERSION

@@ -1 +1 @@
-0.5.0
+0.6.0

package/assets/hooks/guard-irreversible.sh

@@ -149,8 +149,14 @@ case "$tool" in
                 deny "Leopold guard: 'git reset --hard' is forbidden in autonomous mode." ;;
       clean)  matches "$norm" '(--force|(^|[[:space:]])-[a-z]*f)' && \
                 deny "Leopold guard: 'git clean -f' is forbidden in autonomous mode." ;;
-      branch) matches "$norm" '(^|[[:space:]])-D([[:space:]]|$)' && \
-                deny "Leopold guard: 'git branch -D' is forbidden in autonomous mode." ;;
+      branch)
+        if matches "$norm" '(^|[[:space:]])-D([[:space:]]|$)'; then
+          # Exception: Leopold's own throwaway run-worktree branches are deletable
+          # (cleanup of `leopold/run-*`); every other forced branch delete stays denied.
+          matches "$norm" 'leopold/run-' || \
+            deny "Leopold guard: 'git branch -D' is forbidden in autonomous mode."
+        fi ;;
+      worktree) : ;;  # allowed: Leopold isolates a run in a dedicated git worktree
       push)
         matches "$norm" '(--force|--force-with-lease|(^|[[:space:]])-f([[:space:]]|$))' && \
           deny "Leopold guard: force-push is forbidden in autonomous mode."

package/assets/skills/leopold-run/SKILL.md

@@ -65,8 +65,11 @@ in **parallel**, use a separate git worktree (one run per worktree):
 
     git worktree add ../<proj>-leopold-2 && cd ../<proj>-leopold-2
 
-Otherwise wait for the other run, or `/leopold-stop` it first. A run idle for
-over 10 minutes is treated as stale and may be taken over.
+The SDK driver automates this: `leopold-driver run --worktree` isolates the run in
+its own `leopold/run-<id>` worktree and, on the next start, reaps an orphaned prior
+run (a dead process that left `active:true`) and prunes its leftover worktree.
+Otherwise wait for the other run, or `/leopold-stop` it first. A run idle for over
+10 minutes is treated as stale and may be taken over.
 
 ## Step 1 — Activate the run
 

package/dist/config.js

@@ -43,12 +43,24 @@ export function initState(brief) {
         consecutive_failures: 0,
         max_failures: intFrom(brief.guardrails, "max_failures", 3),
         started_at: new Date().toISOString(),
+        orchestrator_pid: process.pid,
     };
     writeState(brief.leoDir, state);
     return state;
 }
+/** Persist run state by MERGING over what's already on disk. The bash skill and
+ *  Stop-hook write fields the driver's RunState doesn't model (session_id,
+ *  max_subagents, …); a full overwrite would drop them (and they'd drop ours).
+ *  Read-merge-write keeps both writers' fields intact. */
 export function writeState(leoDir, state) {
-    fs.writeFileSync(path.join(leoDir, "state.json"), JSON.stringify(state, null, 2));
+    const p = path.join(leoDir, "state.json");
+    let onDisk = {};
+    try {
+        if (fs.existsSync(p))
+            onDisk = JSON.parse(fs.readFileSync(p, "utf8"));
+    }
+    catch { /* corrupt/absent — fall back to a clean write */ }
+    fs.writeFileSync(p, JSON.stringify({ ...onDisk, ...state }, null, 2));
 }
 export function killSwitch(leoDir) {
     return fs.existsSync(path.join(leoDir, "STOP"));
@@ -70,5 +82,6 @@ export function loadConfig(argv) {
         maxTurnsPerItem: parseInt(process.env.LEOPOLD_MAX_TURNS_PER_ITEM ?? "40", 10),
         webhookUrl: process.env.LEOPOLD_WEBHOOK || undefined,
         dryRun: argv.includes("--dry-run"),
+        worktree: argv.includes("--worktree") || process.env.LEOPOLD_WORKTREE === "1",
     };
 }

package/dist/loop.js

@@ -1,11 +1,14 @@
 // The orchestration loop: the conductor burns down the plan, one fresh worker
 // per item, deciding from the charter, with git locked, until the plan is done
 // or a stop condition fires. It notifies the human on completion or escalation.
+import { randomUUID } from "node:crypto";
 import { loadBrief, initState, writeState, killSwitch, loadConfig, clearRunTokens } from "./config.js";
 import { runItem } from "./worker.js";
 import { decide } from "./conductor.js";
 import { logEvent, logDecision, markItemDone, openItems, nextOpenItem } from "./log.js";
 import { notify } from "./notify.js";
+import { createWorktree, cleanupWorktree } from "./worktree.js";
+import { reapOrphan } from "./reaper.js";
 export async function runDriver(cwd, argv) {
     const cfg = loadConfig(argv);
     const brief = loadBrief(cwd);
@@ -16,9 +19,25 @@ export async function runDriver(cwd, argv) {
         console.log("Next item: " + (nextOpenItem(brief.planPath) ?? "(none)"));
         return;
     }
+    // Preflight: reap a prior run that crashed leaving state.active === true.
+    reapOrphan(brief.root, brief.leoDir);
+    // Optional isolation: run inside a dedicated git worktree (the worker's cwd).
+    let worktree = null;
+    if (cfg.worktree) {
+        worktree = createWorktree(brief.root, brief.leoDir, randomUUID().slice(0, 8));
+        if (worktree) {
+            brief.worktreeRoot = worktree.path;
+            console.log(`Isolated in worktree: ${worktree.path}  (branch ${worktree.branch})`);
+        }
+    }
     const state = initState(brief);
+    if (worktree) {
+        state.worktree_path = worktree.path;
+        state.worktree_branch = worktree.branch;
+        writeState(brief.leoDir, state);
+    }
     const recent = [];
-    logEvent(brief.leoDir, { event: "run_start", conductor: cfg.conductorModel });
+    logEvent(brief.leoDir, { event: "run_start", conductor: cfg.conductorModel, worktree: worktree?.path ?? null });
     console.log(`Leopold is conducting "${brief.root}". Git is locked. touch .leopold/STOP to halt.\n`);
     const stop = (reason) => {
         state.active = false;
@@ -26,6 +45,8 @@ export async function runDriver(cwd, argv) {
         writeState(brief.leoDir, state);
         clearRunTokens(brief.leoDir);
         logEvent(brief.leoDir, { event: "stop", reason });
+        if (worktree)
+            cleanupWorktree(brief.root, worktree, brief.leoDir);
     };
     for (;;) {
         if (killSwitch(brief.leoDir)) {

package/dist/reaper.js

@@ -0,0 +1,59 @@
+// Orphan reaper: detect a prior run that crashed leaving state.active === true,
+// using a PID-liveness probe (the file's "active" flag is not proof of life).
+// Ported from paperclip's isZombieRun/reapOrphanedRuns, file-state edition.
+import fs from "node:fs";
+import path from "node:path";
+import { logEvent } from "./log.js";
+import { clearRunTokens } from "./config.js";
+import { cleanupWorktree } from "./worktree.js";
+/** True if a process with this pid is alive. `process.kill(pid, 0)` sends no
+ *  signal: it throws ESRCH if the pid is dead, EPERM if it's alive but not ours. */
+export function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === "EPERM";
+    }
+}
+/** Best-effort preflight before a new run starts: if the previous run is still
+ *  flagged active but its orchestrator pid is dead, declare it orphaned — flip
+ *  inactive, log, clean its (clean) worktree, and clear stale run tokens.
+ *
+ *  Conservative on purpose: we only reap when there IS a pid AND it is dead.
+ *  An active state with no pid (e.g. a live in-session /leopold-run, which does
+ *  not persist orchestrator_pid) is left untouched — never clobber a live run. */
+export function reapOrphan(repoRoot, leoDir) {
+    const p = path.join(leoDir, "state.json");
+    if (!fs.existsSync(p))
+        return;
+    let prev;
+    try {
+        prev = JSON.parse(fs.readFileSync(p, "utf8"));
+    }
+    catch {
+        return;
+    }
+    if (prev.active !== true)
+        return;
+    const pid = typeof prev.orchestrator_pid === "number" ? prev.orchestrator_pid : undefined;
+    if (pid === undefined || isProcessAlive(pid))
+        return;
+    prev.active = false;
+    prev.stopped_reason = "reaped_orphan";
+    try {
+        fs.writeFileSync(p, JSON.stringify(prev, null, 2));
+    }
+    catch { /* ignore */ }
+    logEvent(leoDir, {
+        event: "run_reaped",
+        prior_pid: pid,
+        prior_started: prev.started_at ?? null,
+    });
+    const wtPath = typeof prev.worktree_path === "string" ? prev.worktree_path : undefined;
+    const wtBranch = typeof prev.worktree_branch === "string" ? prev.worktree_branch : undefined;
+    if (wtPath && wtBranch)
+        cleanupWorktree(repoRoot, { path: wtPath, branch: wtBranch }, leoDir);
+    clearRunTokens(leoDir);
+}

package/dist/worker.js

@@ -32,7 +32,7 @@ export async function runItem(opts) {
     const q = query({
         prompt: channel,
         options: {
-            cwd: brief.root,
+            cwd: brief.worktreeRoot ?? brief.root,
             maxTurns: cfg.maxTurnsPerItem,
             permissionMode: "default",
             canUseTool: guard,

package/dist/worktree.js

@@ -0,0 +1,87 @@
+// Git worktree isolation for a run (Path A / SDK driver). The orchestrator runs
+// git directly here — NOT through the worker's Bash tool — so the worker's git
+// lock is unaffected (the lock constrains the worker, not the orchestrator).
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { logEvent } from "./log.js";
+function git(cwd, args) {
+    return execFileSync("git", args, {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+}
+export function isGitRepo(dir) {
+    try {
+        return git(dir, ["rev-parse", "--is-inside-work-tree"]) === "true";
+    }
+    catch {
+        return false;
+    }
+}
+/** A worktree is "dirty" if it has staged, unstaged, or untracked changes.
+ *  Git is locked, so a run stages (git add) but never commits — dirty means
+ *  "there is work here the user should review", which we never destroy. */
+export function isDirty(worktreePath) {
+    try {
+        return git(worktreePath, ["status", "--porcelain"]).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Provision an isolated worktree on a throwaway branch `leopold/run-<id>`,
+ *  as a sibling of the repo (matches the manual flow in docs/guardrails.md).
+ *  Returns null if the project is not a git repo — caller falls back to root. */
+export function createWorktree(repoRoot, leoDir, runId) {
+    if (!isGitRepo(repoRoot)) {
+        logEvent(leoDir, { event: "worktree_skipped", reason: "not_a_git_repo" });
+        return null;
+    }
+    const branch = `leopold/run-${runId}`;
+    // sibling of the repo, one level (matches `../<proj>-leopold-2` in the docs)
+    const dir = path.join(path.dirname(repoRoot), `${path.basename(repoRoot)}-leopold-${runId}`);
+    try {
+        git(repoRoot, ["worktree", "add", "-b", branch, dir, "HEAD"]);
+        logEvent(leoDir, { event: "worktree_created", path: dir, branch });
+        return { path: dir, branch };
+    }
+    catch (e) {
+        logEvent(leoDir, { event: "worktree_create_failed", error: String(e.message ?? e) });
+        return null;
+    }
+}
+/** Remove a run's worktree — but ONLY if it's clean. A worktree with work is
+ *  preserved (and logged) for the user to review/merge, since git is locked and
+ *  the run never committed. A clean worktree (or one already gone) is pruned. */
+export function cleanupWorktree(repoRoot, wt, leoDir) {
+    if (!fs.existsSync(wt.path)) {
+        try {
+            git(repoRoot, ["worktree", "prune"]);
+        }
+        catch { /* ignore */ }
+        try {
+            git(repoRoot, ["branch", "-D", wt.branch]);
+        }
+        catch { /* ignore */ }
+        return;
+    }
+    if (isDirty(wt.path)) {
+        logEvent(leoDir, {
+            event: "worktree_preserved",
+            path: wt.path,
+            branch: wt.branch,
+            reason: "uncommitted_changes",
+        });
+        return;
+    }
+    try {
+        git(repoRoot, ["worktree", "remove", "--force", wt.path]);
+        git(repoRoot, ["branch", "-D", wt.branch]);
+        logEvent(leoDir, { event: "worktree_removed", path: wt.path, branch: wt.branch });
+    }
+    catch (e) {
+        logEvent(leoDir, { event: "worktree_remove_failed", path: wt.path, error: String(e.message ?? e) });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "leopold-driver",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Leopold SDK driver: a persistent conductor that orchestrates fresh Claude Code workers per task, decides from your charter, and notifies you. Uses your Claude Code auth. Git stays locked.",
   "type": "module",
   "bin": {
@@ -37,7 +37,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json && node scripts/copy-runtime.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "node --experimental-strip-types --test test/protocol.test.ts test/guard.test.ts",
+    "test": "node --import tsx --test test/protocol.test.ts test/guard.test.ts test/worktree.test.ts test/reaper.test.ts",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
     "prepublishOnly": "npm run build"