leopold-driver 0.1.0

package/README.md

@@ -0,0 +1,89 @@
+# @leopold/driver
+
+The external conductor. Where the in-session engine (skills + hooks) keeps one
+Claude Code session going, the driver is a persistent process that **conducts
+fresh Claude Code workers**, one per plan item, and holds your mission and
+charter across the whole run. It is the tier that turns Leopold from "a better
+loop" into a real harness you brief and walk away from.
+
+## What it does differently
+
+- **Persistent conductor, fresh workers.** The driver (the "you") remembers the
+  mission, charter, and every decision for the entire run. Each plan item gets a
+  brand-new worker with clean context, so quality does not rot as the run grows.
+  This is the best of both worlds: Ralph's fresh-context-per-task plus a
+  conductor that Ralph does not have.
+- **Real message exchange.** The worker closes each turn with a structured
+  status block. The conductor reads it, decides from your charter, and either
+  pushes a concrete instruction back into the same worker session or ends the
+  item. That is a genuine back-and-forth between two agents, not a blind
+  "continue".
+- **It decides, then notifies.** Reversible or charter-clear forks are decided
+  and logged. Only a genuinely irreversible-and-ambiguous fork stops the run and
+  pings you. You get a notification on completion or escalation, not a screen to
+  babysit.
+- **Git stays locked.** The worker runs under a `canUseTool` guard with the same
+  policy as the in-session hook: commit, push, force-push, `rm -rf`, PR/release,
+  and publish are blocked unless you drop an explicit opt-in token.
+
+## Auth: it uses YOUR Claude Code, not a separate API key
+
+Both the worker and the conductor run through the Claude Agent SDK, which uses
+your existing Claude Code login (your subscription). There is **no separate API
+key and no split billing**. `ANTHROPIC_API_KEY` is only needed in a headless
+environment with no Claude Code auth configured.
+
+## The conductor <-> worker protocol
+
+```
+worker  -> works on the item, closes the turn with:
+           ```leopold-status
+           STATUS: done | needs-decision | blocked
+           ITEM / SUMMARY / DECISION-NEEDED / NEXT / EVIDENCE
+           ```
+driver  -> parses the status, the conductor (your charter as system prompt)
+           returns a verdict: answer | finish | escalate
+           - answer   -> push a concrete instruction into the worker session
+           - finish   -> mark the plan item done, start the next item (fresh worker)
+           - escalate -> notify you, pause the run
+```
+
+## Install and build
+
+```bash
+cd packages/driver
+npm install
+npm run build
+```
+
+## Usage
+
+From any project that already has a `.leopold/` brief (written by `/leopold-brief`),
+and with Claude Code logged in:
+
+```bash
+node /path/to/leopold/packages/driver/dist/index.js          # run
+node /path/to/leopold/packages/driver/dist/index.js --dry-run # load brief, show the plan, do nothing
+```
+
+### Environment
+
+| Var | Default | Purpose |
+|---|---|---|
+| `LEOPOLD_CONDUCTOR_MODEL` | your Claude Code default | the conductor's model |
+| `LEOPOLD_WORKER_MODEL` | your Claude Code default | the worker's model |
+| `LEOPOLD_MAX_TURNS_PER_ITEM` | `40` | worker turn budget per item |
+| `LEOPOLD_WEBHOOK` | none | URL for JSON POST notifications (Slack/Discord/etc.) |
+| `ANTHROPIC_API_KEY` | none | only for headless environments without Claude Code auth |
+
+Stop conditions (plan complete, kill switch via `.leopold/STOP`, repeated
+failures, iteration budget) come from `.leopold/GUARDRAILS.md`, same as the
+in-session engine.
+
+## Status and known limits
+
+Alpha. Verified: compiles against `@anthropic-ai/claude-agent-sdk`, the CLI and
+dry-run work, the status parser and git guard are tested. Not yet built: a
+watchdog for a worker that ends a turn without emitting a status block (today the
+worker is strongly instructed to always emit one), parallel multi-worker waves,
+and the live dashboard. See the repo roadmap.

package/dist/channel.js

@@ -0,0 +1,49 @@
+// A driver-controlled async iterable of worker input messages.
+//
+// The Claude Agent SDK consumes the worker's prompt as an AsyncIterable of user
+// messages (streaming input mode). We drive it by hand: the conductor pushes a
+// reply only after it has read and judged the worker's previous turn, which is
+// what makes the exchange a real back-and-forth instead of a blind loop.
+export class InputChannel {
+    queue = [];
+    waiting = [];
+    closed = false;
+    wrap(text) {
+        return {
+            type: "user",
+            session_id: "",
+            parent_tool_use_id: null,
+            message: { role: "user", content: [{ type: "text", text }] },
+        };
+    }
+    /** Send one user message into the worker session. */
+    push(text) {
+        if (this.closed)
+            return;
+        const msg = this.wrap(text);
+        const w = this.waiting.shift();
+        if (w)
+            w({ value: msg, done: false });
+        else
+            this.queue.push(msg);
+    }
+    /** Signal end of input; the worker session winds down. */
+    close() {
+        this.closed = true;
+        let w;
+        while ((w = this.waiting.shift()))
+            w({ value: undefined, done: true });
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                const queued = this.queue.shift();
+                if (queued)
+                    return Promise.resolve({ value: queued, done: false });
+                if (this.closed)
+                    return Promise.resolve({ value: undefined, done: true });
+                return new Promise((resolve) => this.waiting.push(resolve));
+            },
+        };
+    }
+}

package/dist/conductor.js

@@ -0,0 +1,88 @@
+// The conductor: the persistent "you". It reads a worker's status and decides
+// what to tell it, grounded in the mission and charter.
+//
+// It runs through the SAME Agent SDK as the worker, so it uses your existing
+// Claude Code auth (your subscription). No separate API key, no split billing.
+// It is a one-shot reasoning call with NO tools that returns a JSON verdict.
+import { query } from "@anthropic-ai/claude-agent-sdk";
+function system(brief) {
+    return `You are Leopold, the conductor. You sit in the user's seat and make the calls they would make so a Claude Code worker can keep building without stopping to ask a human. You are NOT the coder; you read the worker's status and decide what to tell it.
+
+Protocol for every worker status:
+- Classify the fork: reversibility (cheap to undo = reversible) and charter clarity (does the charter/mission answer it?).
+- Reversible OR charter-clear -> action "answer": give a crisp, concrete instruction, and fill logTitle/logWhy/reversal so it is auditable.
+- Irreversible AND ambiguous, OR a charter contradiction, OR a sign the mission premise is wrong -> action "escalate"; do NOT guess. Set escalationReason.
+- Worker STATUS done -> action "finish" (item complete, no reply). If evidence looks weak (no tests/build run), instead "answer" telling it to verify first.
+- Worker STATUS blocked -> "answer" with a remediation if the charter/principles make it clear, else "escalate".
+
+When the charter is silent, decide with these ordered principles: completeness, boil-lakes-not-oceans, pragmatic, DRY, explicit-over-clever, bias-toward-action. Keep replies short and actionable. git commit/push/publish are locked; never instruct the worker to commit or push.
+
+Respond with ONLY a single JSON object, no prose, no code fence, shaped exactly:
+{"action":"answer|finish|escalate","classification":"reversible|irreversible|n/a","charterBasis":"...","reply":"...","logTitle":"...","logWhy":"...","reversal":"...","escalationReason":"..."}
+Omit reply for finish/escalate. Omit logTitle for mechanical calls. Omit escalationReason unless escalating.
+
+=== MISSION ===
+${brief.mission}
+
+=== CHARTER (this is how the user decides; follow it) ===
+${brief.charter}`;
+}
+function parseVerdict(text) {
+    let obj = {};
+    const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    const raw = fenced ? fenced[1] : text.match(/\{[\s\S]*\}/)?.[0] ?? "";
+    try {
+        obj = JSON.parse(raw);
+    }
+    catch {
+        obj = {};
+    }
+    return {
+        action: obj.action ?? "escalate",
+        classification: obj.classification ?? "n/a",
+        charterBasis: obj.charterBasis ?? "",
+        reply: obj.reply,
+        logTitle: obj.logTitle,
+        logWhy: obj.logWhy,
+        reversal: obj.reversal,
+        escalationReason: obj.escalationReason ?? "Conductor produced no parseable decision; escalating to the human.",
+    };
+}
+export async function decide(cfg, brief, status, recentDecisions) {
+    const userText = `The worker reported this for item "${status.item}":
+
+STATUS: ${status.kind}
+SUMMARY: ${status.summary}
+DECISION-NEEDED: ${status.decisionNeeded ?? "(none)"}
+NEXT: ${status.next ?? "(none)"}
+EVIDENCE: ${status.evidence ?? "(none)"}
+
+Recent decisions you already made this run (do not contradict them):
+${recentDecisions || "(none yet)"}
+
+Return the JSON verdict now.`;
+    const q = query({
+        prompt: userText,
+        options: {
+            ...(cfg.conductorModel ? { model: cfg.conductorModel } : {}),
+            systemPrompt: system(brief),
+            allowedTools: [],
+            settingSources: [],
+            maxTurns: 1,
+            permissionMode: "default",
+        },
+    });
+    let text = "";
+    for await (const msg of q) {
+        if (msg.type === "assistant") {
+            for (const b of msg.message?.content ?? [])
+                if (b.type === "text" && b.text)
+                    text += b.text;
+        }
+        else if (msg.type === "result") {
+            if (!text && typeof msg.result === "string")
+                text = msg.result;
+        }
+    }
+    return parseVerdict(text);
+}

package/dist/config.js

@@ -0,0 +1,74 @@
+// Load the brief and run state from .leopold/, and the driver config from env.
+import fs from "node:fs";
+import path from "node:path";
+export function findLeoDir(cwd) {
+    let dir = path.resolve(cwd);
+    for (;;) {
+        const leo = path.join(dir, ".leopold");
+        if (fs.existsSync(leo))
+            return leo;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new Error("No .leopold/ found here. Run /leopold-brief first to write the brief.");
+}
+function read(leoDir, name) {
+    const p = path.join(leoDir, name);
+    if (!fs.existsSync(p))
+        throw new Error(`Missing ${name} in .leopold/. Run /leopold-brief first.`);
+    return fs.readFileSync(p, "utf8");
+}
+export function loadBrief(cwd) {
+    const leoDir = findLeoDir(cwd);
+    return {
+        mission: read(leoDir, "MISSION.md"),
+        charter: read(leoDir, "CHARTER.md"),
+        guardrails: read(leoDir, "GUARDRAILS.md"),
+        planPath: path.join(leoDir, "PLAN.md"),
+        root: path.dirname(leoDir),
+        leoDir,
+    };
+}
+function intFrom(text, key, fallback) {
+    const m = text.match(new RegExp(`${key}\\s*:\\s*(\\d+)`, "i"));
+    return m ? parseInt(m[1], 10) : fallback;
+}
+export function initState(brief) {
+    const state = {
+        active: true,
+        iteration: 0,
+        max_iterations: intFrom(brief.guardrails, "max_iterations", 50),
+        consecutive_failures: 0,
+        max_failures: intFrom(brief.guardrails, "max_failures", 3),
+        started_at: new Date().toISOString(),
+    };
+    writeState(brief.leoDir, state);
+    return state;
+}
+export function writeState(leoDir, state) {
+    fs.writeFileSync(path.join(leoDir, "state.json"), JSON.stringify(state, null, 2));
+}
+export function killSwitch(leoDir) {
+    return fs.existsSync(path.join(leoDir, "STOP"));
+}
+/** Safety hygiene on stop: clear the kill switch and per-session git opt-in
+ *  tokens so the next run re-locks git and does not halt on a stale STOP. */
+export function clearRunTokens(leoDir) {
+    for (const t of ["STOP", "ALLOW_GIT", "ALLOW_PUSH", "ALLOW_PUBLISH"]) {
+        try {
+            fs.rmSync(path.join(leoDir, t), { force: true });
+        }
+        catch { /* ignore */ }
+    }
+}
+export function loadConfig(argv) {
+    return {
+        conductorModel: process.env.LEOPOLD_CONDUCTOR_MODEL || undefined,
+        workerModel: process.env.LEOPOLD_WORKER_MODEL || undefined,
+        maxTurnsPerItem: parseInt(process.env.LEOPOLD_MAX_TURNS_PER_ITEM ?? "40", 10),
+        webhookUrl: process.env.LEOPOLD_WEBHOOK || undefined,
+        dryRun: argv.includes("--dry-run"),
+    };
+}

package/dist/guard.js

@@ -0,0 +1,47 @@
+// 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.
+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\/)/;
+function hasToken(leoDir, name) {
+    return fs.existsSync(path.join(leoDir, name));
+}
+export function makeGuard(leoDir, onBlock) {
+    return async function canUseTool(toolName, input) {
+        const deny = (message) => {
+            onBlock(toolName, message);
+            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"))
+                return deny("Leopold guard: opening or merging PRs and creating releases is locked.");
+            if (PUBLISH.test(cmd) && !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 { behavior: "allow", updatedInput: input };
+    };
+}

package/dist/index.js

@@ -0,0 +1,31 @@
+#!/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.
+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.
+
+Usage:
+  leopold-driver [run] [--dry-run]
+
+Reads .leopold/ (MISSION, CHARTER, GUARDRAILS, PLAN) from the current project.
+
+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
+`);
+    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);
+});

package/dist/log.js

@@ -0,0 +1,58 @@
+// Observability: the decision trail (DECISIONS.md), the event stream
+// (events.jsonl), and plan bookkeeping (PLAN.md checkboxes).
+import fs from "node:fs";
+import path from "node:path";
+export function logEvent(leoDir, event) {
+    const line = JSON.stringify({ ts: new Date().toISOString(), ...event });
+    fs.appendFileSync(path.join(leoDir, "events.jsonl"), line + "\n");
+}
+let decisionCounter = 0;
+export function logDecision(leoDir, iteration, status, v) {
+    if (!v.logTitle)
+        return; // mechanical calls are not logged as blocks
+    decisionCounter += 1;
+    const block = [
+        "",
+        `## D${decisionCounter} — ${v.logTitle}   (turn ${iteration}, ${new Date().toISOString()})`,
+        `Fork:        ${status.decisionNeeded ?? status.summary}`,
+        `Class:       ${v.classification}`,
+        `Charter:     ${v.charterBasis}`,
+        `Decision:    ${v.reply ?? "(finish item)"}`,
+        `Why:         ${v.logWhy ?? ""}`,
+        `Reversal:    ${v.reversal ?? ""}`,
+        "",
+    ].join("\n") + "\n";
+    fs.appendFileSync(path.join(leoDir, "DECISIONS.md"), block);
+}
+export function openItems(planPath) {
+    const text = fs.readFileSync(planPath, "utf8");
+    return (text.match(/^[ \t]*- \[ \]/gm) ?? []).length;
+}
+export function nextOpenItem(planPath) {
+    const text = fs.readFileSync(planPath, "utf8");
+    const m = text.match(/^[ \t]*- \[ \] (.*)$/m);
+    return m ? m[1].trim() : null;
+}
+/** Mark the open item whose text matches `itemText` as done; fall back to the
+ *  first open item. Returns the number of open items remaining. */
+export function markItemDone(planPath, itemText) {
+    const lines = fs.readFileSync(planPath, "utf8").split("\n");
+    const needle = itemText.trim().slice(0, 40);
+    let marked = false;
+    for (let i = 0; i < lines.length && !marked; i++) {
+        if (/^[ \t]*- \[ \]/.test(lines[i]) && (needle === "" || lines[i].includes(needle))) {
+            lines[i] = lines[i].replace("- [ ]", "- [x]");
+            marked = true;
+        }
+    }
+    if (!marked) {
+        for (let i = 0; i < lines.length && !marked; i++) {
+            if (/^[ \t]*- \[ \]/.test(lines[i])) {
+                lines[i] = lines[i].replace("- [ ]", "- [x]");
+                marked = true;
+            }
+        }
+    }
+    fs.writeFileSync(planPath, lines.join("\n"));
+    return openItems(planPath);
+}

package/dist/loop.js

@@ -0,0 +1,103 @@
+// 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 { 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";
+export async function runDriver(cwd, argv) {
+    const cfg = loadConfig(argv);
+    const brief = loadBrief(cwd);
+    if (cfg.dryRun) {
+        console.log("DRY RUN — brief loaded, no workers will run.\n");
+        console.log("Mission:\n" + brief.mission.split("\n").slice(0, 10).join("\n"));
+        console.log(`\nOpen plan items: ${openItems(brief.planPath)}`);
+        console.log("Next item: " + (nextOpenItem(brief.planPath) ?? "(none)"));
+        return;
+    }
+    const state = initState(brief);
+    const recent = [];
+    logEvent(brief.leoDir, { event: "run_start", conductor: cfg.conductorModel });
+    console.log(`Leopold is conducting "${brief.root}". Git is locked. touch .leopold/STOP to halt.\n`);
+    const stop = (reason) => {
+        state.active = false;
+        state.stopped_reason = reason;
+        writeState(brief.leoDir, state);
+        clearRunTokens(brief.leoDir);
+        logEvent(brief.leoDir, { event: "stop", reason });
+    };
+    for (;;) {
+        if (killSwitch(brief.leoDir)) {
+            stop("kill_switch");
+            await notify(brief.leoDir, cfg.webhookUrl, "Leopold stopped", "Kill switch hit.");
+            return;
+        }
+        if (state.iteration >= state.max_iterations) {
+            stop("iteration_budget");
+            await notify(brief.leoDir, cfg.webhookUrl, "Leopold stopped", "Iteration budget reached.");
+            return;
+        }
+        if (state.consecutive_failures >= state.max_failures) {
+            stop("repeated_failure");
+            await notify(brief.leoDir, cfg.webhookUrl, "Leopold needs you", "Too many consecutive failures; stopping.");
+            return;
+        }
+        const item = nextOpenItem(brief.planPath);
+        if (!item) {
+            stop("plan_complete");
+            await notify(brief.leoDir, cfg.webhookUrl, "Leopold finished", `Plan complete for ${brief.root}. Everything is staged for your review; nothing was committed.`);
+            return;
+        }
+        state.iteration += 1;
+        writeState(brief.leoDir, state);
+        logEvent(brief.leoDir, { event: "item_start", iteration: state.iteration, item });
+        console.log(`\n--- turn ${state.iteration}: ${item} ---`);
+        const workerPrompt = `Work on this plan item now:\n\n${item}\n\n` +
+            `Do it completely and verify it (build, lint, tests). Decide reversible or charter-clear forks yourself per the mission and charter. When the item is done, or if you hit a fork only the conductor can settle, close your turn with the leopold-status block.`;
+        let escalated = false;
+        let itemDone = false;
+        await runItem({
+            brief,
+            cfg,
+            item,
+            workerPrompt,
+            onBlock: (tool, reason) => logEvent(brief.leoDir, { event: "guard_block", tool, reason }),
+            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"));
+                logDecision(brief.leoDir, state.iteration, status, verdict);
+                if (verdict.logTitle)
+                    recent.push(`${verdict.logTitle}: ${verdict.reply ?? "(finish)"}`);
+                if (verdict.action === "finish") {
+                    itemDone = true;
+                    return null;
+                }
+                if (verdict.action === "escalate") {
+                    escalated = true;
+                    await notify(brief.leoDir, cfg.webhookUrl, "Leopold needs a call from you", `Item: ${item}\nWorker: ${status.decisionNeeded ?? status.summary}\nWhy escalated: ${verdict.escalationReason}\n\n` +
+                        `The run is paused. Make the call, adjust PLAN.md or CHARTER.md if needed, then re-run leopold-driver.`);
+                    return null;
+                }
+                console.log(`  conductor -> ${verdict.reply}`);
+                return verdict.reply ?? "Proceed using your best judgment per the charter, then report status.";
+            },
+        });
+        if (escalated) {
+            stop("escalation");
+            return;
+        }
+        if (itemDone) {
+            const left = markItemDone(brief.planPath, item);
+            state.consecutive_failures = 0;
+            writeState(brief.leoDir, state);
+            logEvent(brief.leoDir, { event: "item_done", item, open_left: left });
+            console.log(`  done. ${left} items left.`);
+        }
+        else {
+            state.consecutive_failures += 1;
+            writeState(brief.leoDir, state);
+            logEvent(brief.leoDir, { event: "item_incomplete", item, fails: state.consecutive_failures });
+        }
+    }
+}

package/dist/notify.js

@@ -0,0 +1,19 @@
+// Notify the human on completion or escalation. Best-effort: terminal bell plus
+// an optional webhook (Slack/Discord/whatever accepts a JSON POST).
+import { logEvent } from "./log.js";
+export async function notify(leoDir, webhookUrl, title, body) {
+    process.stdout.write(`\x07\n=== ${title} ===\n${body}\n\n`);
+    logEvent(leoDir, { event: "notify", title, body });
+    if (!webhookUrl)
+        return;
+    try {
+        await fetch(webhookUrl, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ title, body, source: "leopold" }),
+        });
+    }
+    catch {
+        /* best-effort; a failed notification must not break the run */
+    }
+}

package/dist/protocol.js

@@ -0,0 +1,50 @@
+// Parser for the worker's end-of-cycle STATUS contract.
+//
+// The worker closes each turn with a fenced block:
+//
+//   ```leopold-status
+//   STATUS: done | needs-decision | blocked | working
+//   ITEM: <plan item>
+//   SUMMARY: <what happened>
+//   DECISION-NEEDED: <question + options, or empty>
+//   NEXT: <what it thinks comes next>
+//   EVIDENCE: <tests/build result>
+//   ```
+//
+// Parsing is deterministic; the conductor then reasons over the parsed result.
+const KINDS = ["done", "needs-decision", "blocked", "working"];
+function field(body, name) {
+    const re = new RegExp(`^\\s*${name}\\s*:\\s*(.*)$`, "im");
+    const m = body.match(re);
+    return m ? m[1].trim() : "";
+}
+/** Extract the last STATUS block from accumulated assistant text, if any. */
+export function parseStatus(text) {
+    // Prefer a fenced ```leopold-status block; fall back to a bare STATUS: line.
+    const fenceRe = /```leopold-status\s*([\s\S]*?)```/gi;
+    let body = null;
+    let m;
+    while ((m = fenceRe.exec(text)) !== null)
+        body = m[1]; // keep the last one
+    if (body === null) {
+        const idx = text.toUpperCase().lastIndexOf("STATUS:");
+        if (idx === -1)
+            return null;
+        body = text.slice(idx);
+    }
+    const rawKind = field(body, "STATUS").toLowerCase();
+    const kind = (KINDS.find((k) => rawKind.startsWith(k)) ?? "working");
+    return {
+        kind,
+        item: field(body, "ITEM"),
+        summary: field(body, "SUMMARY"),
+        decisionNeeded: field(body, "DECISION-NEEDED") || undefined,
+        next: field(body, "NEXT") || undefined,
+        evidence: field(body, "EVIDENCE") || undefined,
+        raw: body.trim(),
+    };
+}
+/** True when a turn looks complete (it emitted a terminal status). */
+export function isTurnComplete(status) {
+    return !!status && status.kind !== "working";
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// Core types shared across the driver.
+export {};

package/dist/worker.js

@@ -0,0 +1,75 @@
+// Runs one plan item as a back-and-forth with a FRESH Claude Code worker.
+//
+// Fresh context per item (the good idea Ralph has). Within an item, the worker
+// and the conductor exchange real messages through the input channel (the part
+// Ralph lacks): the worker closes a turn with a status block, the conductor
+// reads and judges it, and either pushes the next instruction or ends the item.
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { InputChannel } from "./channel.js";
+import { parseStatus, isTurnComplete } from "./protocol.js";
+import { makeGuard } from "./guard.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.
+- Close EVERY turn with a fenced status block, then stop and wait for the conductor's reply:
+
+\`\`\`leopold-status
+STATUS: done | needs-decision | blocked
+ITEM: <the item you are on>
+SUMMARY: <what you did this turn, 1-3 lines>
+DECISION-NEEDED: <if needs-decision: the exact question + options A/B + the tradeoff; else empty>
+NEXT: <what you think comes next>
+EVIDENCE: <build/lint/test result if relevant>
+\`\`\`
+
+Use needs-decision only for a fork you genuinely cannot resolve from the task and your own judgment. Use done only when the item is fully complete and verified.`;
+export async function runItem(opts) {
+    const { brief, cfg, item, workerPrompt, onBlock, onTurn } = opts;
+    const channel = new InputChannel();
+    channel.push(workerPrompt);
+    const guard = makeGuard(brief.leoDir, onBlock);
+    const q = query({
+        prompt: channel,
+        options: {
+            cwd: brief.root,
+            maxTurns: cfg.maxTurnsPerItem,
+            permissionMode: "default",
+            canUseTool: guard,
+            settingSources: ["user", "project"],
+            ...(cfg.workerModel ? { model: cfg.workerModel } : {}),
+            systemPrompt: { type: "preset", preset: "claude_code", append: WORKER_APPEND },
+        },
+    });
+    let turnText = "";
+    for await (const msg of q) {
+        if (msg.type === "assistant") {
+            for (const b of msg.message?.content ?? []) {
+                if (b.type === "text" && b.text)
+                    turnText += b.text;
+            }
+            const status = parseStatus(turnText);
+            if (isTurnComplete(status)) {
+                const captured = turnText;
+                turnText = "";
+                const next = await onTurn(status, captured);
+                if (next === null) {
+                    channel.close();
+                    break;
+                }
+                channel.push(next);
+            }
+        }
+        else if (msg.type === "result") {
+            // 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()) {
+                const status = parseStatus(turnText) ?? {
+                    kind: "blocked", item, summary: turnText.slice(-500), raw: turnText.slice(-500),
+                };
+                await onTurn(status, turnText);
+            }
+            break;
+        }
+    }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "leopold-driver",
+  "version": "0.1.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": { "leopold-driver": "dist/index.js" },
+  "main": "dist/index.js",
+  "files": ["dist", "README.md"],
+  "engines": { "node": ">=18" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jonhvmp/leopold.git",
+    "directory": "packages/driver"
+  },
+  "homepage": "https://github.com/Jonhvmp/leopold/tree/main/packages/driver#readme",
+  "bugs": { "url": "https://github.com/Jonhvmp/leopold/issues" },
+  "keywords": [
+    "claude-code",
+    "claude",
+    "ai-agents",
+    "agent-harness",
+    "autonomous-agents",
+    "orchestration",
+    "anthropic"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.179"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  },
+  "license": "MIT",
+  "author": "Jonhvmp"
+}