leopold-driver 0.5.0 → 0.7.0

package/assets/VERSION

@@ -1 +1 @@
-0.5.0
+0.7.0

package/assets/extensions/gstack/extension.json

@@ -4,5 +4,6 @@
   "summary": "Garry Tan's planning + QA skill suite that Leopold conducts (/spec, /autoplan, /plan-*-review).",
   "homepage": "https://github.com/garrytan/gstack",
   "license": "MIT",
-  "order": 20
+  "order": 20,
+  "capabilities": ["filesystem.home", "network"]
 }

package/assets/extensions/leopold/extension.json

@@ -4,5 +4,6 @@
   "summary": "The autonomous orchestration harness itself (skills + Stop/PreToolUse hooks).",
   "homepage": "https://github.com/Jonhvmp/leopold",
   "license": "MIT",
-  "order": 10
+  "order": 10,
+  "capabilities": ["settings.write", "filesystem.home"]
 }

package/assets/extensions/ovmem/extension.json

@@ -5,6 +5,7 @@
   "homepage": "https://github.com/Jonhvmp/leopold",
   "license": "MIT",
   "order": 30,
+  "capabilities": ["network", "settings.write", "filesystem.home", "package.install", "process.spawn"],
   "dashboard": {
     "label": "Memory",
     "module": "~/.claude/ovmem/dashboard.py",

package/assets/extensions/serena/extension.json

@@ -4,5 +4,6 @@
   "summary": "LSP-backed code intelligence (MCP). Symbol-level retrieval + editing instead of grep/whole-file reads — sharper edits, far fewer tokens. Mandatory for quality.",
   "homepage": "https://github.com/oraios/serena",
   "license": "MIT",
-  "order": 15
+  "order": 15,
+  "capabilities": ["mcp.register", "settings.write", "package.install", "network"]
 }

package/assets/hooks/guard-irreversible.sh

@@ -112,6 +112,10 @@ case "$tool" in
     # normalize: newlines/tabs -> space, collapse runs (defeats whitespace/tab evasion).
     norm="$(printf '%s' "$cmd" | tr '\n\t' '  ' | tr -s ' ')"
 
+    # secret vault / master key are off-limits to the worker (secrets arrive as env vars)
+    matches "$norm" 'secrets\.(key|env)' && \
+      deny "Leopold guard: touching the secret vault/key via shell is forbidden. Secrets are pre-loaded as environment variables."
+
     # Opt-in deny-by-default (LEOPOLD_PARANOID=1): only a small allowlist of
     # read/build/test/lint commands passes; everything else is denied. Best-effort
     # (it keys off the first command word), kept off by default in favor of the
@@ -149,8 +153,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."
@@ -178,6 +188,7 @@ case "$tool" in
       */GUARDRAILS.md)             deny "Leopold guard: GUARDRAILS.md is immutable during an autonomous run." ;;
       */settings.json|*/settings.local.json) deny "Leopold guard: editing Claude Code settings is forbidden in autonomous mode." ;;
       */leopold/hooks/*|*/.leopold/state.json) deny "Leopold guard: the guardrail hooks and run state are immutable during an autonomous run." ;;
+      */secrets.key|*/.leopold/secrets.env) deny "Leopold guard: the secret vault and master key are off-limits. Secrets are pre-loaded as env vars." ;;
     esac
     ;;
 esac

package/assets/scripts/leopold-menu.sh

@@ -47,6 +47,25 @@ ext_installed() { bash "$1/manage.sh" detect >/dev/null 2>&1; }
 ext_status()    { bash "$1/manage.sh" status 2>/dev/null || true; }
 ext_run()       { bash "$1/manage.sh" "$2"; }
 
+ext_caps() { # extension.json -> space-separated capabilities (empty if none)
+  if command -v jq >/dev/null 2>&1; then
+    jq -r '(.capabilities // []) | join(" ")' "$1" 2>/dev/null
+  elif command -v python3 >/dev/null 2>&1; then
+    python3 -c "import json,sys;print(' '.join(json.load(open(sys.argv[1])).get('capabilities',[])))" "$1" 2>/dev/null
+  fi
+}
+
+# Show an extension's declared capabilities and require explicit consent before
+# install/update grants them. No declaration -> nothing to gate, proceed.
+ext_consent() { # dir -> 0 if the user consents
+  local caps; caps="$(ext_caps "$1/extension.json")"
+  [ -n "$caps" ] || return 0
+  printf "\n  %sThis extension requests:%s %s%s%s\n" "$C_BOLD" "$C_RESET" "$C_YELLOW" "$caps" "$C_RESET"
+  printf "  Install/update grants these. Proceed? [y/N] "
+  local a; read -r a || a=""
+  case "$a" in [yY]*) return 0 ;; *) echo "  cancelled."; return 1 ;; esac
+}
+
 pause() { printf "\n%spress Enter to continue%s " "$C_DIM" "$C_RESET"; read -r _ || true; }
 
 # ---- screens ----------------------------------------------------------------
@@ -90,6 +109,8 @@ component_menu() {
     ext_installed "$d" && st="installed${C_RESET} ${C_DIM}($(ext_status "$d"))"
     printf "  %s%s%s\n  status: %s%s\n\n" "$C_BOLD" "$title" "$C_RESET" "$C_GREEN" "$st"
     printf "  %s%s%s\n\n" "$C_DIM" "$(_jget "$d/extension.json" summary)" "$C_RESET"
+    local caps; caps="$(ext_caps "$d/extension.json")"
+    [ -n "$caps" ] && printf "  %scapabilities:%s %s\n\n" "$C_DIM" "$C_RESET" "$caps"
     local has_dash=""; [ -n "$(_jget "$d/extension.json" dashboard)" ] && has_dash=1
     if [ -n "$has_dash" ]; then
       printf "   1) Install    2) Update    3) Remove    4) Doctor    w) Watch    b) Back\n\n"
@@ -98,8 +119,8 @@ component_menu() {
     fi
     printf "select: "; read -r a || a="b"
     case "$a" in
-      1) ext_run "$d" install || echo "${C_YELLOW}install returned non-zero${C_RESET}"; pause ;;
-      2) ext_run "$d" update  || echo "${C_YELLOW}update returned non-zero${C_RESET}";  pause ;;
+      1) ext_consent "$d" && { ext_run "$d" install || echo "${C_YELLOW}install returned non-zero${C_RESET}"; }; pause ;;
+      2) ext_consent "$d" && { ext_run "$d" update  || echo "${C_YELLOW}update returned non-zero${C_RESET}"; }; pause ;;
       3) ext_run "$d" remove  || echo "${C_YELLOW}remove returned non-zero${C_RESET}";  pause ;;
       4) ext_run "$d" doctor  || true; pause ;;
       w|W) [ -n "$has_dash" ] && { ext_run "$d" watch || true; }; pause ;;

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/budget.js

@@ -0,0 +1,16 @@
+// USD budget hard-stop for the SDK driver. The Claude Code CLI already reports
+// `total_cost_usd` per session, so we never need a model price map: accumulate the
+// real cost per item and stop the run when it crosses the cap. Two checks, like
+// paperclip's evaluateCostEvent + getInvocationBlock: preventive (before an item)
+// and reactive (after each item's cost lands).
+/** Parse a budget value (CLI flag / env) into a positive USD number, or undefined. */
+export function parseBudgetUsd(raw) {
+    if (raw === undefined || raw === "")
+        return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+/** True when spend has reached or passed the cap. A missing cap never trips. */
+export function overBudget(spentUsd, capUsd) {
+    return capUsd !== undefined && spentUsd >= capUsd;
+}

package/dist/config.js

@@ -1,6 +1,7 @@
 // Load the brief and run state from .leopold/, and the driver config from env.
 import fs from "node:fs";
 import path from "node:path";
+import { parseBudgetUsd } from "./budget.js";
 export function findLeoDir(cwd) {
     let dir = path.resolve(cwd);
     for (;;) {
@@ -43,12 +44,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"));
@@ -63,6 +76,11 @@ export function clearRunTokens(leoDir) {
         catch { /* ignore */ }
     }
 }
+/** Read `--flag value` from argv (the value is the next token). */
+function flagValue(argv, name) {
+    const i = argv.indexOf(name);
+    return i >= 0 && i + 1 < argv.length ? argv[i + 1] : undefined;
+}
 export function loadConfig(argv) {
     return {
         conductorModel: process.env.LEOPOLD_CONDUCTOR_MODEL || undefined,
@@ -70,5 +88,7 @@ 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",
+        budgetUsd: parseBudgetUsd(flagValue(argv, "--budget-usd") ?? process.env.LEOPOLD_BUDGET_USD),
     };
 }

package/dist/guard.js

@@ -6,7 +6,10 @@ import fs from "node:fs";
 import path from "node:path";
 const GH_PR = /(^|[^\w-])gh(\s.*)?\s(pr\s+(create|merge)|release\s+create)/i;
 const PUBLISH = /(npm|pnpm|yarn)\s+publish|cargo\s+publish|twine\s+upload|pip\s+.*upload/i;
-const PROTECTED_PATH = /(GUARDRAILS\.md|settings\.json|settings\.local\.json|leopold\/hooks\/|\.leopold\/state\.json)/;
+const PROTECTED_PATH = /(GUARDRAILS\.md|settings\.json|settings\.local\.json|leopold\/hooks\/|\.leopold\/state\.json|secrets\.key|secrets\.env)/;
+// The secret vault (.leopold/secrets.env) and master key (~/.claude/leopold/secrets.key)
+// are off-limits to the worker — secrets reach it only as $NAME env vars.
+const SECRET_FILE = /secrets\.key|secrets\.env/;
 // git global options that consume the following token as their value.
 const GIT_VALUE_OPTS = new Set([
     "-c", "-C", "--git-dir", "--work-tree", "--namespace", "--exec-path", "--config-env",
@@ -61,8 +64,15 @@ export function makeGuard(leoDir, onBlock) {
             onBlock(toolName, message);
             return { behavior: "deny", message };
         };
+        if (toolName === "Read") {
+            const p = String(input.file_path ?? "");
+            if (SECRET_FILE.test(p))
+                return deny("Leopold guard: reading the secret vault or master key is forbidden. Secrets are pre-loaded as $NAME env vars.");
+        }
         if (toolName === "Bash") {
             const c = norm(String(input.command ?? ""));
+            if (SECRET_FILE.test(c))
+                return deny("Leopold guard: touching the secret vault/key via shell is forbidden. Secrets are pre-loaded as $NAME env vars.");
             if (isRecursiveForceRm(c))
                 return deny("Leopold guard: recursive+forced rm is forbidden in autonomous mode.");
             if (isFindDelete(c))

package/dist/index.js

@@ -4,6 +4,7 @@
 // into the package at build time; subcommands run them.
 import { runDriver } from "./loop.js";
 import { runInstall, runMenu, runWatch, runExt, runDoctor } from "./harness.js";
+import { runSecrets } from "./secrets.js";
 const sub = process.argv[2];
 const rest = process.argv.slice(3);
 function help() {
@@ -16,13 +17,17 @@ Usage:
   leopold-driver serena [install|doctor]    manage an extension (also: gstack, ovmem)
   leopold-driver doctor                     run every extension's doctor
   leopold-driver update                     reinstall from this package
-  leopold-driver run [--dry-run]            conduct the .leopold run (the SDK driver)
+  leopold-driver run [--worktree] [--budget-usd N] [--dry-run]
+                                            conduct the .leopold run (the SDK driver)
+  leopold-driver secrets set|list [NAME]    manage the run's encrypted secret vault
 
 Most commands run the bundled harness — no repo clone, no make. 'watch' needs Python 3.
 Newer version: npm i -g leopold-driver@latest.
 
 Conducting a run uses your existing Claude Code login (ANTHROPIC_API_KEY only in headless).
-Env: LEOPOLD_CONDUCTOR_MODEL, LEOPOLD_WORKER_MODEL, LEOPOLD_MAX_TURNS_PER_ITEM, LEOPOLD_WEBHOOK
+--worktree isolates the run in a git worktree; --budget-usd stops it at a USD cap.
+Env: LEOPOLD_CONDUCTOR_MODEL, LEOPOLD_WORKER_MODEL, LEOPOLD_MAX_TURNS_PER_ITEM, LEOPOLD_WEBHOOK,
+     LEOPOLD_WORKTREE, LEOPOLD_BUDGET_USD
 `);
 }
 function conduct() {
@@ -47,6 +52,8 @@ switch (sub) {
         process.exit(runExt(sub, rest));
     case "doctor":
         process.exit(runDoctor());
+    case "secrets":
+        process.exit(runSecrets(rest));
     case "--help":
     case "-h":
     case "help":

package/dist/loop.js

@@ -1,11 +1,15 @@
 // 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";
+import { overBudget } from "./budget.js";
 export async function runDriver(cwd, argv) {
     const cfg = loadConfig(argv);
     const brief = loadBrief(cwd);
@@ -16,9 +20,30 @@ 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);
+    state.budget_usd = cfg.budgetUsd;
+    state.spent_usd = 0;
+    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, budget_usd: cfg.budgetUsd ?? 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 +51,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)) {
@@ -33,6 +60,11 @@ export async function runDriver(cwd, argv) {
             await notify(brief.leoDir, cfg.webhookUrl, "Leopold stopped", "Kill switch hit.");
             return;
         }
+        if (overBudget(state.spent_usd ?? 0, cfg.budgetUsd)) {
+            stop("budget_exceeded");
+            await notify(brief.leoDir, cfg.webhookUrl, "Leopold stopped", `Budget reached: $${(state.spent_usd ?? 0).toFixed(2)} of $${cfg.budgetUsd?.toFixed(2)}. Work so far is staged for your review.`);
+            return;
+        }
         if (state.iteration >= state.max_iterations) {
             stop("iteration_budget");
             await notify(brief.leoDir, cfg.webhookUrl, "Leopold stopped", "Iteration budget reached.");
@@ -63,6 +95,10 @@ export async function runDriver(cwd, argv) {
             item,
             workerPrompt,
             onBlock: (tool, reason) => logEvent(brief.leoDir, { event: "guard_block", tool, reason }),
+            onCost: (usd) => {
+                state.spent_usd = (state.spent_usd ?? 0) + usd;
+                logEvent(brief.leoDir, { event: "cost", item, usd, spent_usd: state.spent_usd });
+            },
             onTurn: async (status) => {
                 logEvent(brief.leoDir, { event: "worker_turn", kind: status.kind, item: status.item || item });
                 const verdict = await decide(cfg, brief, status, recent.slice(-5).join("\n"));

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/secrets.js

@@ -0,0 +1,142 @@
+// Encrypted secret vault for a run. Secrets the work needs are injected into the
+// worker as environment variables (resolved at run time), so they reach the worker's
+// Bash tool as $NAME but never land in the prompt/transcript the model sees.
+//
+// At rest: AES-256-GCM. The 32-byte master key lives at ~/.claude/leopold/secrets.key
+// (mode 0600, generated on demand); the vault is .leopold/secrets.env (the encrypted
+// blob). Mirrors paperclip's local-encrypted-provider, file edition — no DB.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { findLeoDir } from "./config.js";
+const ALGO = "aes-256-gcm";
+const NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export function keyPath() {
+    const base = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
+    return path.join(base, "leopold", "secrets.key");
+}
+export function vaultPath(leoDir) {
+    return path.join(leoDir, "secrets.env");
+}
+/** Paths the guard must protect from the worker (the vault and the master key). */
+export function secretFilePaths(leoDir) {
+    return [vaultPath(leoDir), keyPath()];
+}
+function loadOrCreateKey() {
+    const kp = keyPath();
+    if (fs.existsSync(kp))
+        return Buffer.from(fs.readFileSync(kp, "utf8").trim(), "base64");
+    const key = crypto.randomBytes(32);
+    fs.mkdirSync(path.dirname(kp), { recursive: true });
+    fs.writeFileSync(kp, key.toString("base64"), { mode: 0o600 });
+    try {
+        fs.chmodSync(kp, 0o600);
+    }
+    catch { /* best effort on platforms without chmod */ }
+    return key;
+}
+function encrypt(key, plaintext) {
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv(ALGO, key, iv);
+    const data = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    return JSON.stringify({
+        v: 1, iv: iv.toString("base64"),
+        tag: cipher.getAuthTag().toString("base64"), data: data.toString("base64"),
+    });
+}
+function decrypt(key, blob) {
+    const o = JSON.parse(blob);
+    const decipher = crypto.createDecipheriv(ALGO, key, Buffer.from(o.iv, "base64"));
+    decipher.setAuthTag(Buffer.from(o.tag, "base64"));
+    return Buffer.concat([decipher.update(Buffer.from(o.data, "base64")), decipher.final()]).toString("utf8");
+}
+function readVault(leoDir) {
+    const vp = vaultPath(leoDir);
+    if (!fs.existsSync(vp))
+        return {};
+    try {
+        return JSON.parse(decrypt(loadOrCreateKey(), fs.readFileSync(vp, "utf8")));
+    }
+    catch {
+        return {}; // wrong/rotated key or corrupt vault — fail closed (no secrets)
+    }
+}
+function writeVault(leoDir, secrets) {
+    fs.writeFileSync(vaultPath(leoDir), encrypt(loadOrCreateKey(), JSON.stringify(secrets)), { mode: 0o600 });
+}
+export function isValidName(name) {
+    return NAME_RE.test(name);
+}
+export function setSecret(leoDir, name, value) {
+    if (!isValidName(name))
+        throw new Error(`invalid secret name: ${name}`);
+    const s = readVault(leoDir);
+    s[name] = value;
+    writeVault(leoDir, s);
+}
+/** Decrypt the vault to {NAME: value} for env injection. */
+export function loadSecrets(leoDir) {
+    return readVault(leoDir);
+}
+/** Set the run's secrets into process.env for the duration of one item; returns a
+ *  restore() that puts the previous environment back (so secrets don't outlive the item). */
+export function applySecretsEnv(leoDir) {
+    const secrets = loadSecrets(leoDir);
+    const prev = [];
+    for (const [k, v] of Object.entries(secrets)) {
+        prev.push([k, process.env[k]]);
+        process.env[k] = v;
+    }
+    return {
+        restore() {
+            for (const [k, p] of prev) {
+                if (p === undefined)
+                    delete process.env[k];
+                else
+                    process.env[k] = p;
+            }
+        },
+    };
+}
+export function listSecretNames(leoDir) {
+    return Object.keys(readVault(leoDir)).sort();
+}
+/** `leopold-driver secrets set NAME | list` — the value for `set` is read from
+ *  stdin so it never appears in shell history. */
+export function runSecrets(argv) {
+    const sub = argv[0];
+    let leoDir;
+    try {
+        leoDir = findLeoDir(process.cwd());
+    }
+    catch {
+        console.error("leopold-driver secrets: no .leopold/ here. Run /leopold-brief first.");
+        return 1;
+    }
+    if (sub === "list") {
+        const names = listSecretNames(leoDir);
+        process.stdout.write(names.length ? names.join("\n") + "\n" : "(no secrets)\n");
+        return 0;
+    }
+    if (sub === "set") {
+        const name = argv[1];
+        if (!name || !isValidName(name)) {
+            console.error("usage: leopold-driver secrets set NAME   (NAME = a valid env var name)");
+            return 2;
+        }
+        let value;
+        try {
+            value = fs.readFileSync(0, "utf8").replace(/\r?\n$/, ""); // stdin, strip one trailing newline
+        }
+        catch {
+            console.error("could not read the secret value from stdin");
+            return 1;
+        }
+        setSecret(leoDir, name, value);
+        console.log(`secret '${name}' stored (encrypted) in .leopold/secrets.env`);
+        return 0;
+    }
+    console.error("usage: leopold-driver secrets set NAME | list");
+    return 2;
+}

package/dist/worker.js

@@ -8,10 +8,12 @@ import { query } from "@anthropic-ai/claude-agent-sdk";
 import { InputChannel } from "./channel.js";
 import { parseStatus, isTurnComplete } from "./protocol.js";
 import { makeGuard } from "./guard.js";
+import { applySecretsEnv } from "./secrets.js";
 const WORKER_APPEND = `You are a Leopold worker, conducted by an autonomous orchestrator. No human is watching live. Rules for this session:
 - Do NOT ask the human anything. Decide reversible or charter-clear calls yourself and keep going.
 - Spawned mode: if you invoke gstack skills, auto-pick the recommended option; never prompt.
 - git commit/push/publish are LOCKED by a guard. Never attempt them. Stage with "git add" and report instead.
+- Secrets you may need are pre-loaded as environment variables; use them as $NAME, and never ask for, echo, or print their values.
 - Close EVERY turn with a fenced status block, then stop and wait for the conductor's reply:
 
 \`\`\`leopold-status
@@ -29,10 +31,15 @@ export async function runItem(opts) {
     const channel = new InputChannel();
     channel.push(workerPrompt);
     const guard = makeGuard(brief.leoDir, onBlock);
+    // Inject the run's secrets as env vars for this item: they reach the worker's Bash
+    // tool as $NAME but never enter the prompt. Restored after the loop (runs are
+    // sequential, so there is no env overlap between items).
+    const { restore: restoreSecrets } = applySecretsEnv(brief.leoDir);
     const q = query({
         prompt: channel,
         options: {
-            cwd: brief.root,
+            cwd: brief.worktreeRoot ?? brief.root,
+            env: { ...process.env },
             maxTurns: cfg.maxTurnsPerItem,
             permissionMode: "default",
             canUseTool: guard,
@@ -61,6 +68,10 @@ export async function runItem(opts) {
             }
         }
         else if (msg.type === "result") {
+            // The CLI reports the item's real cost here — accumulate it for the budget.
+            const cost = msg.total_cost_usd;
+            if (typeof cost === "number" && Number.isFinite(cost))
+                opts.onCost?.(cost);
             // Session ended (channel closed, or the worker stopped on its own). Flush
             // whatever we have so the conductor can make a final call.
             if (turnText.trim()) {
@@ -72,4 +83,5 @@ export async function runItem(opts) {
             break;
         }
     }
+    restoreSecrets();
 }

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.7.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 test/budget.test.ts test/secrets.test.ts",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
     "prepublishOnly": "npm run build"