leopold-driver 0.1.1 → 0.1.3

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

@@ -0,0 +1,48 @@
+---
+name: leopold-watch
+version: 0.1.0
+description: "Launch a local live web dashboard to watch the current project's Leopold run — status, cost meters (context/subagents/forks), event feed, decisions, and a Stop button. Local-only (127.0.0.1), zero dependencies."
+allowed-tools:
+  - Bash
+triggers:
+  - leopold watch
+  - watch the run
+  - open the dashboard
+---
+
+# /leopold-watch
+
+Start the local live dashboard for this project's Leopold run and give the user the URL.
+It only **reads** `.leopold/` (state, plan, decisions, events) and serves on loopback;
+nothing leaves the machine. The one action it offers is a Stop button, which touches
+`.leopold/STOP` — the same kill switch as `/leopold-stop`.
+
+Run this (idempotent — if it is already up, just report the URL):
+
+```bash
+WATCH="$HOME/.claude/leopold/scripts/leopold-watch.py"; [ -f "$WATCH" ] || WATCH="scripts/leopold-watch.py"
+PORT="${LEOPOLD_WATCH_PORT:-4179}"
+if curl -sf "http://127.0.0.1:$PORT/api/state" >/dev/null 2>&1; then
+  echo "Dashboard already running -> http://127.0.0.1:$PORT"
+else
+  nohup python3 "$WATCH" --project "$(pwd)" --port "$PORT" >/tmp/leopold-watch.log 2>&1 &
+  sleep 1
+  if curl -sf "http://127.0.0.1:$PORT/api/state" >/dev/null 2>&1; then
+    echo "Dashboard started -> http://127.0.0.1:$PORT  (pid $!)"
+  else
+    echo "Failed to start; last log lines:"; tail -3 /tmp/leopold-watch.log
+  fi
+fi
+```
+
+Then tell the user, briefly:
+
+- Open **http://127.0.0.1:4179** (or the port shown) in a browser to watch the run live:
+  run status, cost meters (context MB, subagents, forks, iterations, failures vs their
+  budgets), the live event feed, the decisions log, and a **Stop** button.
+- It shows real data only while a run is active (`/leopold-run`); otherwise it says
+  "no active run" and updates the moment one starts.
+- To stop the dashboard itself: `pkill -f leopold-watch.py`. It also runs via `make watch`
+  or, from the npm package, `npx leopold-driver watch`.
+
+Do not do anything else. Start it, report the URL, stop.

package/assets/templates/CHARTER.md

@@ -0,0 +1,32 @@
+# Charter
+
+> This is the decider. The run consults it on every fork so it chooses the way
+> you would. Be concrete; concrete rules resolve real decisions, vague ones do
+> not. This is the part of Leopold that "becomes you."
+
+## What I optimize for
+> Ranked. Example: 1) shipping working software, 2) simplicity, 3) speed.
+1. ...
+
+## Technology and style preferences
+> Languages, frameworks, patterns you favor or avoid.
+- Prefer: ...
+- Avoid: ...
+
+## Always
+> Things the run should always do.
+- ...
+
+## Never
+> Hard lines the run must never cross.
+- ...
+
+## Tie-breakers
+> When principles conflict, how do you choose? Example: "When robustness and
+> speed conflict on user-facing paths, robustness wins; on internal tooling,
+> speed wins."
+- ...
+
+## Examples of decisions I would make
+> 2-4 worked examples. These calibrate the run better than abstract rules.
+- Situation: ... -> I would: ... because ...

package/assets/templates/DECISIONS.md

@@ -0,0 +1,15 @@
+# Decisions
+
+> Append-only audit trail of decisions the run made on your behalf, newest last.
+> Each non-mechanical decision is one block. The Reversal line is your escape
+> hatch: it tells you how to undo a call you disagree with.
+
+<!-- Example:
+## D1 — Cache layer for the MVP            (turn 3, 2026-06-17T15:00:00Z)
+Fork:        in-memory cache vs Redis
+Class:       reversible
+Charter:     "no new infrastructure for the MVP"
+Decision:    in-memory map with a TTL
+Why:         charter rule + principle 5 (explicit over clever)
+Reversal:    swap the cache module for a Redis client; interface is unchanged
+-->

package/assets/templates/GUARDRAILS.md

@@ -0,0 +1,38 @@
+# Guardrails
+
+> The autonomy boundary for this run. Defaults are the recommended posture.
+
+## Action classes
+- Autonomous: reversible work in the repo (edit, build, lint, test, stage).
+- Gated (locked): git commit, git push, PR create/merge, publish, deploy.
+- Forbidden: rm -rf outside scratch, edits outside the project root, editing
+  this file / the hooks / Claude Code settings.
+
+## Git posture
+> Default: LOCKED. The run stages and reports; the human commits and pushes.
+> To allow commits this session: `touch .leopold/ALLOW_GIT` (push stays locked).
+- Commit: locked
+- Push / PR / publish: locked
+
+## Stop conditions
+- max_iterations: 50
+- max_failures: 3            # consecutive failures of the same kind
+- max_no_progress: 6         # turns with the open PLAN set unchanged -> loop, stop
+- max_subagents: 8           # total Task/subagent spawns per run; past it the guard
+                             # denies more (each subagent re-loads the full context =
+                             # the #1 cost multiplier). Raise only if you must.
+- max_forks: 0               # forks clone the WHOLE session context (the leak) — forbidden
+                             # by default; raise only if a sub-task needs the full convo
+- max_context_mb: 5          # stop when the transcript passes this; a long run re-bills
+                             # its growing context every turn. Resume with a fresh run.
+- token/time budget: none    # set if you want a hard ceiling
+
+## On finish
+- on_finish: keep            # keep | archive
+> keep: brief, DECISIONS, and events stay in place. archive: on a clean finish,
+> DECISIONS.md and events.jsonl move to .leopold/runs/<timestamp>/. Either way,
+> the kill switch and git opt-in tokens are always cleared when a run stops.
+
+## Kill switch
+- `/leopold-stop` (clean) or `touch .leopold/STOP` (blunt). Takes effect at the
+  next turn boundary; nothing is interrupted mid-turn.

package/assets/templates/MISSION.md

@@ -0,0 +1,22 @@
+# Mission
+
+> What we are building and why. The autonomous run executes this; it does not
+> invent it. Fill every section. Delete the guidance quotes when done.
+
+## Problem
+> What hurts today, and why it matters now.
+
+## Goal
+> The outcome we want. One or two sentences.
+
+## Non-goals
+> What we are deliberately NOT doing this run. This prevents scope creep.
+- ...
+
+## Definition of done
+> Concrete, checkable. How we will know the mission succeeded.
+- [ ] ...
+
+## Constraints
+> Stack, deadlines, things that must not change, environments.
+- ...

package/assets/templates/PLAN.md

@@ -0,0 +1,9 @@
+# Plan
+
+> Ordered, checkbox backlog. Each item should be independently completable and
+> verifiable. The run takes the next unchecked item each turn and marks it [x]
+> when done. Order by dependency, then by value. Keep items small.
+
+- [ ] First item
+- [ ] Second item
+- [ ] Third item

package/dist/guard.js

@@ -1,16 +1,57 @@
 // The git lock, in driver form. Used as the worker's canUseTool callback so the
 // same policy as the in-session hook holds when the worker runs under the SDK.
-// It only adds denials; it never loosens anything.
+// It only adds denials; it never loosens anything. Detection mirrors the hardened
+// bash guard (hooks/guard-irreversible.sh) and is covered by test/guard.test.ts.
 import fs from "node:fs";
 import path from "node:path";
-const DESTRUCTIVE_RM = /rm\s+-[a-z]*(rf|fr)/i;
-const DESTRUCTIVE_GIT = /git\s+(reset\s+--hard|clean\s+-[a-z]*f|branch\s+-D)/;
-const FORCE_PUSH = /git\s+push\s+.*(--force|--force-with-lease|-f(\s|$))/;
-const GIT_COMMIT = /git\s+(-[^\s]+\s+)*commit/;
-const GIT_PUSH = /git\s+push/;
-const GH_PR = /gh\s+(pr\s+(create|merge)|release\s+create)/;
-const PUBLISH = /(npm|pnpm|yarn)\s+publish|cargo\s+publish|twine\s+upload|pip\s+.*upload/;
-const PROTECTED_PATH = /(GUARDRAILS\.md|settings\.json|settings\.local\.json|leopold\/hooks\/)/;
+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)/;
+// 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",
+]);
+/** Collapse whitespace so tab/space evasion does not change matching. */
+function norm(s) {
+    return s.replace(/[\t\n]+/g, " ").replace(/ +/g, " ").trim();
+}
+/** Resolve the git subcommand, skipping global options + their values, by basename. */
+export function gitSubcommand(cmd) {
+    const toks = norm(cmd).split(" ");
+    let i = toks.findIndex((t) => t.split("/").pop() === "git");
+    if (i === -1)
+        return "";
+    i += 1;
+    while (i < toks.length) {
+        const t = toks[i];
+        if (GIT_VALUE_OPTS.has(t)) {
+            i += 2;
+            continue;
+        }
+        if (t.startsWith("-")) {
+            i += 1;
+            continue;
+        }
+        return t;
+    }
+    return "";
+}
+/** Recursive AND forced rm, in any spelling (--recursive --force, -r -f, -rf, /bin/rm -rf). */
+export function isRecursiveForceRm(cmd) {
+    const c = norm(cmd);
+    if (!/(^|[^\w-])rm(\s|$)/i.test(c))
+        return false;
+    const recursive = /(--recursive|(^|\s)-[a-z]*r)/i.test(c);
+    const force = /(--force|(^|\s)-[a-z]*f)/i.test(c);
+    return recursive && force;
+}
+/** find ... -delete or find ... -exec rm. */
+export function isFindDelete(cmd) {
+    const c = norm(cmd);
+    if (!/(^|[^\w-])find(\s|$)/i.test(c))
+        return false;
+    return /\s-delete(\s|$)/i.test(c) || /-exec\s+rm(\s|$)/i.test(c);
+}
 function hasToken(leoDir, name) {
     return fs.existsSync(path.join(leoDir, name));
 }
@@ -21,26 +62,44 @@ export function makeGuard(leoDir, onBlock) {
             return { behavior: "deny", message };
         };
         if (toolName === "Bash") {
-            const cmd = String(input.command ?? "");
-            if (DESTRUCTIVE_RM.test(cmd))
-                return deny("Leopold guard: 'rm -rf' style deletion is forbidden in autonomous mode.");
-            if (DESTRUCTIVE_GIT.test(cmd))
-                return deny("Leopold guard: destructive git op (reset --hard / clean -f / branch -D) is forbidden.");
-            if (FORCE_PUSH.test(cmd))
-                return deny("Leopold guard: force-push is forbidden in autonomous mode.");
-            if (GIT_COMMIT.test(cmd) && !hasToken(leoDir, "ALLOW_GIT"))
-                return deny("Leopold guard: git commit is locked. Stage and report; the user commits. (touch .leopold/ALLOW_GIT to allow commits this run.)");
-            if (GIT_PUSH.test(cmd) && !hasToken(leoDir, "ALLOW_PUSH"))
-                return deny("Leopold guard: git push is locked. Report readiness instead.");
-            if (GH_PR.test(cmd) && !hasToken(leoDir, "ALLOW_PUSH"))
+            const c = norm(String(input.command ?? ""));
+            if (isRecursiveForceRm(c))
+                return deny("Leopold guard: recursive+forced rm is forbidden in autonomous mode.");
+            if (isFindDelete(c))
+                return deny("Leopold guard: 'find -delete' / 'find -exec rm' is forbidden in autonomous mode.");
+            switch (gitSubcommand(c)) {
+                case "reset":
+                    if (/(^|\s)--hard(\s|$)/.test(c))
+                        return deny("Leopold guard: 'git reset --hard' is forbidden in autonomous mode.");
+                    break;
+                case "clean":
+                    if (/(--force|(^|\s)-[a-z]*f)/i.test(c))
+                        return deny("Leopold guard: 'git clean -f' is forbidden in autonomous mode.");
+                    break;
+                case "branch":
+                    if (/(^|\s)-D(\s|$)/.test(c))
+                        return deny("Leopold guard: 'git branch -D' is forbidden in autonomous mode.");
+                    break;
+                case "push":
+                    if (/(--force|--force-with-lease|(^|\s)-f(\s|$))/.test(c))
+                        return deny("Leopold guard: force-push is forbidden in autonomous mode.");
+                    if (!hasToken(leoDir, "ALLOW_PUSH"))
+                        return deny("Leopold guard: git push is locked. Report readiness instead.");
+                    break;
+                case "commit":
+                    if (!hasToken(leoDir, "ALLOW_GIT"))
+                        return deny("Leopold guard: git commit is locked. Stage and report; the user commits. (touch .leopold/ALLOW_GIT to allow commits this run.)");
+                    break;
+            }
+            if (GH_PR.test(c) && !hasToken(leoDir, "ALLOW_PUSH"))
                 return deny("Leopold guard: opening or merging PRs and creating releases is locked.");
-            if (PUBLISH.test(cmd) && !hasToken(leoDir, "ALLOW_PUBLISH"))
+            if (PUBLISH.test(c) && !hasToken(leoDir, "ALLOW_PUBLISH"))
                 return deny("Leopold guard: publishing packages is locked in autonomous mode.");
         }
         if (toolName === "Edit" || toolName === "Write" || toolName === "MultiEdit" || toolName === "NotebookEdit") {
             const p = String(input.file_path ?? input.path ?? "");
             if (PROTECTED_PATH.test(p))
-                return deny("Leopold guard: editing guardrails, settings, or hooks is forbidden in autonomous mode.");
+                return deny("Leopold guard: editing guardrails, settings, hooks, or run state is forbidden in autonomous mode.");
         }
         return { behavior: "allow", updatedInput: input };
     };

package/dist/harness.js

@@ -0,0 +1,71 @@
+// Harness commands for the leopold-driver CLI: install / menu / watch / extensions /
+// doctor / update. They run the bundled harness assets (skills, hooks, installer,
+// extensions) that `npm run build` vendors into ../assets, so everything works from the
+// npm package alone — no repo clone, no `make`.
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Locate the vendored harness root (assets/ in the package, or the repo root in dev). */
+export function assetRoot() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const bundled = join(here, "..", "assets");
+    if (existsSync(join(bundled, "install.sh")))
+        return bundled;
+    let dir = here; // dev: walk up to the repo root (has install.sh + skills/)
+    for (let i = 0; i < 6; i++) {
+        if (existsSync(join(dir, "install.sh")) && existsSync(join(dir, "skills")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return bundled;
+}
+function run(cmd, args) {
+    const r = spawnSync(cmd, args, { stdio: "inherit" });
+    if (r.error) {
+        const e = r.error;
+        const hint = e.code === "ENOENT" ? ` (is "${cmd}" installed and on PATH?)` : "";
+        console.error(`leopold-driver: could not run ${cmd}${hint}: ${e.message}`);
+        return 1;
+    }
+    return r.status ?? 0;
+}
+export function runInstall(args) {
+    return run("bash", [join(assetRoot(), "install.sh"), ...args]);
+}
+export function runMenu() {
+    return run("bash", [join(assetRoot(), "scripts", "leopold-menu.sh")]);
+}
+export function runWatch(args) {
+    const script = join(assetRoot(), "scripts", "leopold-watch.py");
+    if (!existsSync(script)) {
+        console.error("leopold-driver watch: dashboard script (leopold-watch.py) not found.");
+        return 1;
+    }
+    const py = process.env.LEOPOLD_PYTHON ?? "python3";
+    return run(py, [script, "--project", process.cwd(), ...args]);
+}
+export function runExt(name, args) {
+    const mgr = join(assetRoot(), "extensions", name, "manage.sh");
+    if (!existsSync(mgr)) {
+        console.error(`leopold-driver: unknown extension "${name}". Try: serena, gstack, ovmem.`);
+        return 2;
+    }
+    return run("bash", [mgr, ...(args.length ? args : ["status"])]);
+}
+export function runDoctor() {
+    const extDir = join(assetRoot(), "extensions");
+    let rc = 0;
+    for (const name of existsSync(extDir) ? readdirSync(extDir) : []) {
+        if (!existsSync(join(extDir, name, "manage.sh")))
+            continue;
+        process.stdout.write(`\n[${name}]\n`);
+        const r = run("bash", [join(extDir, name, "manage.sh"), "doctor"]);
+        if (r !== 0)
+            rc = r;
+    }
+    return rc;
+}

package/dist/index.js

@@ -1,31 +1,61 @@
 #!/usr/bin/env node
-// leopold-driver: the external conductor. Reads the .leopold brief from the cwd
-// and orchestrates Claude Code workers through the plan, git locked.
+// leopold-driver: Leopold from npm. Install + manage the harness, conduct runs, and
+// watch — without cloning the repo or running `make`. The harness assets are bundled
+// into the package at build time; subcommands run them.
 import { runDriver } from "./loop.js";
-const arg = process.argv[2] ?? "run";
-if (arg === "--help" || arg === "-h" || arg === "help") {
-    process.stdout.write(`leopold-driver - conduct Claude Code through the .leopold brief.
+import { runInstall, runMenu, runWatch, runExt, runDoctor } from "./harness.js";
+const sub = process.argv[2];
+const rest = process.argv.slice(3);
+function help() {
+    process.stdout.write(`leopold-driver — Leopold from npm. Manage the harness, conduct runs, watch.
 
 Usage:
-  leopold-driver [run] [--dry-run]
+  leopold-driver install [--with-gstack]   install skills + hooks into ~/.claude
+  leopold-driver menu                       toolchain manager (serena / gstack / ovmem)
+  leopold-driver watch [--port N]           live dashboard (http://127.0.0.1:4179)
+  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)
 
-Reads .leopold/ (MISSION, CHARTER, GUARDRAILS, PLAN) from the current project.
+Most commands run the bundled harness — no repo clone, no make. 'watch' needs Python 3.
+Newer version: npm i -g leopold-driver@latest.
 
-Auth:
-  Uses your existing Claude Code login (your subscription) for BOTH the worker
-  and the conductor. No API key needed. ANTHROPIC_API_KEY is only required in a
-  headless environment that has no Claude Code auth configured.
-
-Env:
-  LEOPOLD_CONDUCTOR_MODEL      conductor model (default: your Claude Code default)
-  LEOPOLD_WORKER_MODEL         worker model (default: your Claude Code default)
-  LEOPOLD_MAX_TURNS_PER_ITEM   max worker turns per item (default: 40)
-  LEOPOLD_WEBHOOK              optional URL for JSON POST notifications
+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
 `);
-    process.exit(0);
 }
-runDriver(process.cwd(), process.argv.slice(2)).catch((err) => {
-    const msg = err instanceof Error ? err.message : String(err);
-    console.error("leopold-driver error:", msg);
-    process.exit(1);
-});
+function conduct() {
+    runDriver(process.cwd(), process.argv.slice(2)).catch((err) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error("leopold-driver error:", msg);
+        process.exit(1);
+    });
+}
+switch (sub) {
+    case "install":
+    case "update":
+        process.exit(runInstall(rest));
+    case "menu":
+        process.exit(runMenu());
+    case "watch":
+    case "watch-web":
+        process.exit(runWatch(rest));
+    case "serena":
+    case "gstack":
+    case "ovmem":
+        process.exit(runExt(sub, rest));
+    case "doctor":
+        process.exit(runDoctor());
+    case "--help":
+    case "-h":
+    case "help":
+        help();
+        process.exit(0);
+    default:
+        if (sub && sub !== "run" && !sub.startsWith("-")) {
+            console.error(`leopold-driver: unknown command "${sub}". Try: leopold-driver --help`);
+            process.exit(2);
+        }
+        conduct();
+}

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "leopold-driver",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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": {
-    "leopold-driver": "dist/index.js"
+    "leopold-driver": "dist/index.js",
+    "leopold": "dist/index.js"
   },
   "main": "dist/index.js",
   "files": [
     "dist",
+    "assets",
     "README.md"
   ],
   "engines": {
@@ -33,8 +35,9 @@
     "anthropic"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "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",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
     "prepublishOnly": "npm run build"