@devwithdavid/ledger 0.1.0

package/dist/db/migrations/index.js

@@ -0,0 +1,10 @@
+import { migration0001Init } from "./0001_init.js";
+import { migration0002ProjectHerdrWorkspace } from "./0002_project_herdr_workspace.js";
+import { migration0003AgentAuthorizationBasis } from "./0003_agent_authorization_basis.js";
+import { migration0004RoadmapPriority } from "./0004_roadmap_priority.js";
+export const migrations = [
+    migration0001Init,
+    migration0002ProjectHerdrWorkspace,
+    migration0003AgentAuthorizationBasis,
+    migration0004RoadmapPriority,
+].sort((a, b) => a.version - b.version);

package/dist/db/migrations/types.js

@@ -0,0 +1 @@
+export {};

package/dist/db/types.js

@@ -0,0 +1,33 @@
+export const ROADMAP_PRIORITIES = [
+    "high",
+    "normal",
+    "low",
+];
+export const AUTHORIZATION_BASES = [
+    "user-explicit",
+    "pre-authorized",
+];
+// Mirrors `herdr agent start --kind`'s accepted values.
+export const CODING_AGENT_KINDS = [
+    "pi",
+    "claude",
+    "codex",
+    "gemini",
+    "cursor",
+    "devin",
+    "agy",
+    "cline",
+    "omp",
+    "mastracode",
+    "opencode",
+    "copilot",
+    "kimi",
+    "kiro",
+    "droid",
+    "amp",
+    "grok",
+    "hermes",
+    "kilo",
+    "qodercli",
+    "maki",
+];

package/dist/lib/git.js

@@ -0,0 +1,61 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
+function resolveDefaultBranch(cwd) {
+    return execFileSync("git", ["symbolic-ref", "--short", "HEAD"], {
+        cwd,
+        encoding: "utf8",
+    }).trim();
+}
+/**
+ * Clones `source` (a remote URL or a local filesystem path) into
+ * `destPath`. A local path clones via git's own local-clone fast path
+ * (hardlinks where possible) and picks up every local commit/branch,
+ * including unpushed ones — the dirty working tree itself is the one
+ * thing that can never be captured, by design (see DESIGN.md).
+ */
+export function cloneProject(source, destPath) {
+    if (existsSync(destPath)) {
+        throw new Error(`clone destination already exists: ${destPath}`);
+    }
+    execFileSync("git", ["clone", source, destPath], { encoding: "utf8" });
+    return { defaultBranch: resolveDefaultBranch(destPath) };
+}
+/** True if `cwd`'s git repo already has a remote named `name`. */
+export function hasRemote(cwd, name) {
+    return getRemoteUrl(cwd, name) !== null;
+}
+/** The URL of `cwd`'s git remote `name`, or null if it doesn't exist. */
+export function getRemoteUrl(cwd, name) {
+    try {
+        // "No such remote" is an expected, routine outcome here (not an
+        // error to surface) — suppress git's own stderr for it specifically.
+        return execFileSync("git", ["remote", "get-url", name], {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+/** Adds a remote to `cwd`'s git repo. Caller should check `hasRemote` first. */
+export function addRemote(cwd, name, url) {
+    execFileSync("git", ["remote", "add", name, url], { cwd, encoding: "utf8" });
+}
+/**
+ * Creates a brand-new project from scratch at `destPath` — for work that
+ * doesn't exist anywhere yet (no repo to clone, local or remote). An empty
+ * initial commit gives treehouse a real ref to lease worktrees from;
+ * deliberately no scaffolding beyond that — what the project actually
+ * becomes is a dispatched agent's job, not ledger's.
+ */
+export function initProject(destPath) {
+    if (existsSync(destPath)) {
+        throw new Error(`init destination already exists: ${destPath}`);
+    }
+    mkdirSync(destPath, { recursive: true });
+    execFileSync("git", ["init", "--quiet", destPath], { encoding: "utf8" });
+    execFileSync("git", ["commit", "--allow-empty", "-m", "Initial commit (ledger project init)"], { cwd: destPath, encoding: "utf8" });
+    return { defaultBranch: resolveDefaultBranch(destPath) };
+}

package/dist/lib/herdr.js

@@ -0,0 +1,321 @@
+import { execFileSync } from "node:child_process";
+export class HerdrError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "HerdrError";
+    }
+}
+/** Throws HerdrError (or a generic Error) from a failed herdr invocation. */
+function throwHerdrFailure(args, err) {
+    const e = err;
+    // herdr's JSON error envelope can land on stdout or stderr depending on
+    // the command — confirmed live: `workspace get` on a missing id writes
+    // it to stderr, unlike every other failure observed so far (stdout).
+    // Check both rather than assuming one.
+    for (const text of [e.stdout, e.stderr]) {
+        if (!text)
+            continue;
+        const parsed = tryParseEnvelope(text);
+        if (parsed?.error) {
+            throw new HerdrError(parsed.error.code, parsed.error.message);
+        }
+    }
+    throw new Error(`herdr ${args.join(" ")} failed: ${(e.stderr ?? e.message).trim()}`);
+}
+function runHerdr(args, opts) {
+    let stdout;
+    try {
+        stdout = execFileSync("herdr", args, {
+            encoding: "utf8",
+            // Explicit "pipe" (not the default) captures stderr for
+            // throwHerdrFailure to parse WITHOUT echoing it to the terminal —
+            // "ignore" would lose it entirely, breaking error-code detection
+            // for errors that land on stderr (see DECISIONS.md).
+            ...(opts?.quiet ? { stdio: ["ignore", "pipe", "pipe"] } : {}),
+        });
+    }
+    catch (err) {
+        throwHerdrFailure(args, err);
+    }
+    const parsed = tryParseEnvelope(stdout);
+    if (!parsed) {
+        throw new Error(`herdr ${args.join(" ")}: could not parse JSON output`);
+    }
+    if (parsed.error) {
+        throw new HerdrError(parsed.error.code, parsed.error.message);
+    }
+    if (parsed.result === undefined) {
+        throw new Error(`herdr ${args.join(" ")}: response had no result`);
+    }
+    return parsed.result;
+}
+/**
+ * Like `runHerdr`, but for commands confirmed live to return empty stdout
+ * on success rather than herdr's usual JSON envelope (`pane send-keys` —
+ * see DECISIONS.md). A non-throwing exit is success regardless of stdout
+ * content; a thrown error is still parsed the normal way.
+ */
+function runHerdrAction(args) {
+    try {
+        execFileSync("herdr", args, { encoding: "utf8" });
+    }
+    catch (err) {
+        throwHerdrFailure(args, err);
+    }
+}
+/**
+ * Like `runHerdr`, but for `pane read`, which (confirmed live) returns the
+ * pane's raw rendered terminal text on stdout, not herdr's usual JSON
+ * envelope.
+ */
+function runHerdrText(args, opts) {
+    try {
+        return execFileSync("herdr", args, {
+            encoding: "utf8",
+            // execFileSync leaks stderr straight to the parent's terminal by
+            // default even though it's also captured for throwHerdrFailure to
+            // parse (confirmed live) — same rationale as runHerdr's `quiet`:
+            // pass it when a failure is routine/handled, not worth echoing raw.
+            ...(opts?.quiet ? { stdio: ["ignore", "pipe", "pipe"] } : {}),
+        });
+    }
+    catch (err) {
+        throwHerdrFailure(args, err);
+    }
+}
+function tryParseEnvelope(text) {
+    try {
+        return JSON.parse(text.trim());
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Creates a new workspace (with its own root tab + root pane) at `cwd`. */
+export function createWorkspace(opts) {
+    const args = ["workspace", "create", "--cwd", opts.cwd, "--label", opts.label];
+    args.push(opts.focus ? "--focus" : "--no-focus");
+    return runHerdr(args);
+}
+export function closeWorkspace(workspaceId) {
+    runHerdr(["workspace", "close", workspaceId]);
+}
+/**
+ * Fetches a workspace's info (including its label). Throws HerdrError
+ * (e.g. `workspace_not_found`) when the id doesn't exist. Pass `quiet`
+ * when a missing workspace is an expected, handled outcome (same rationale
+ * as `workspaceExists`): it suppresses herdr's raw error envelope being
+ * echoed to the terminal, while `throwHerdrFailure` still parses it from
+ * the piped stderr.
+ */
+export function getWorkspace(workspaceId, opts) {
+    const result = runHerdr(["workspace", "get", workspaceId], opts);
+    return result.workspace;
+}
+export function renameWorkspace(workspaceId, label) {
+    runHerdr(["workspace", "rename", workspaceId, label]);
+}
+/** True if `workspaceId` still exists (wasn't closed, e.g. by the user). */
+export function workspaceExists(workspaceId) {
+    try {
+        // quiet: this is a routine "is it still there?" check, run on every
+        // dispatch — a missing workspace is an expected, handled outcome, not
+        // noise worth printing to the terminal every time.
+        runHerdr(["workspace", "get", workspaceId], { quiet: true });
+        return true;
+    }
+    catch (err) {
+        if (err instanceof HerdrError && err.code === "workspace_not_found") {
+            return false;
+        }
+        throw err;
+    }
+}
+/** Adds a new tab (with its own root pane) to an existing workspace at `cwd`. */
+export function createTab(opts) {
+    const args = [
+        "tab",
+        "create",
+        "--workspace",
+        opts.workspace,
+        "--cwd",
+        opts.cwd,
+        "--label",
+        opts.label,
+    ];
+    args.push(opts.focus ? "--focus" : "--no-focus");
+    return runHerdr(args);
+}
+export function closeTab(tabId) {
+    runHerdr(["tab", "close", tabId]);
+}
+export function renameTab(tabId, label) {
+    runHerdr(["tab", "rename", tabId, label]);
+}
+const AGENT_START_READY_RETRY_BUDGET_MS = 10_000;
+const AGENT_START_READY_RETRY_INTERVAL_MS = 300;
+const CLAUDE_TRUST_DIALOG_KEY_SETTLE_MS = 300;
+const CLAUDE_TRUST_DIALOG_READY_TIMEOUT_MS = 15_000;
+// Text markers from Claude Code's one-time "do you trust this folder?"
+// dialog, confirmed live off a real `herdr pane read --format text` (see
+// DECISIONS.md). Matched literally, not as a prefix/suffix regex, since
+// the surrounding box-drawing/whitespace varies but this wording doesn't.
+const CLAUDE_TRUST_OPTION_TEXT = "Yes, I trust this folder";
+const CLAUDE_DECLINE_OPTION_TEXT = "No, exit";
+export function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Reads a pane's rendered terminal text — the general-purpose entry point
+ * (catch-up's idle-agent pane tails; anything else that needs to look at
+ * what a pane last showed). Throws HerdrError (e.g. `pane_not_found`) for a
+ * gone pane, or a generic Error for something more fundamental (socket
+ * unreachable) — callers that need to tell those apart use `instanceof
+ * HerdrError`, same as every other herdr-client call in this file.
+ */
+export function readPane(paneId, opts) {
+    const args = ["pane", "read", paneId, "--source", opts?.source ?? "recent", "--format", "text"];
+    if (opts?.lines !== undefined) {
+        args.push("--lines", String(opts.lines));
+    }
+    return runHerdrText(args, opts?.quiet !== undefined ? { quiet: opts.quiet } : undefined);
+}
+function readPaneText(paneId) {
+    return readPane(paneId);
+}
+function looksLikeClaudeTrustDialog(paneText) {
+    return (paneText.includes(CLAUDE_TRUST_OPTION_TEXT) &&
+        paneText.includes(CLAUDE_DECLINE_OPTION_TEXT));
+}
+/** True if the pane's rendered text shows the "trust" option as the currently-highlighted (❯) one. */
+function isTrustOptionHighlighted(paneText) {
+    return paneText
+        .split("\n")
+        .some((line) => /^❯\s*/.test(line.trim()) && line.includes(CLAUDE_TRUST_OPTION_TEXT));
+}
+/**
+ * Dismisses Claude Code's one-time "do you trust this folder?" dialog,
+ * choosing "Yes, I trust this folder" specifically — confirmed live (see
+ * DECISIONS.md) that the dialog's default-highlighted option is NOT
+ * reliable: one real run defaulted to "Yes, I trust this folder", another
+ * (same Claude Code version) defaulted to "No, exit". A blind Enter risks
+ * declining trust instead of accepting it, so this reads the pane's actual
+ * rendered text first and only sends keys once it recognizes exactly what's
+ * on screen — an unrecognized stuck state fails loud instead of guessing.
+ */
+function dismissClaudeTrustDialog(paneId) {
+    const text = readPaneText(paneId);
+    if (!looksLikeClaudeTrustDialog(text)) {
+        throw new Error(`herdr reported the agent on pane ${paneId} as not ready, but its screen ` +
+            `doesn't show Claude Code's known "trust this folder?" dialog — refusing ` +
+            `to send keystrokes to an unrecognized stuck state. Pane text:\n${text}`);
+    }
+    if (!isTrustOptionHighlighted(text)) {
+        sendKeys(paneId, "down");
+        sleepSync(CLAUDE_TRUST_DIALOG_KEY_SETTLE_MS);
+        const afterDown = readPaneText(paneId);
+        if (!isTrustOptionHighlighted(afterDown)) {
+            throw new Error(`sent Down to move the Claude Code trust dialog's selection to ` +
+                `"${CLAUDE_TRUST_OPTION_TEXT}" on pane ${paneId}, but it still isn't ` +
+                `highlighted — refusing to guess further. Pane text:\n${afterDown}`);
+        }
+    }
+    sendKeys(paneId, "enter");
+}
+/**
+ * Starts a supported interactive coding agent in an existing pane at its
+ * shell prompt. A pane created moments earlier (e.g. right after
+ * `createWorkspace`, called with zero delay in `agent dispatch`) is often
+ * not yet at rest — confirmed live (see DECISIONS.md): `herdr agent start`
+ * fails immediately with `agent_pane_busy: "... is not an available
+ * shell"` in that window. `--timeout` does *not* cover this — that only
+ * governs a later readiness wait, and passing it made no difference in
+ * testing. What actually resolves it is real elapsed wall-clock time, so
+ * retry specifically on `agent_pane_busy` with a short synchronous
+ * backoff; any other error fails immediately, not retried.
+ *
+ * For `kind: "claude"`, a second real blocker (confirmed live, see
+ * DECISIONS.md): Claude Code's one-time "do you trust this folder?" dialog
+ * blocks herdr's own readiness detection, so `agent start` throws
+ * `agent_not_ready` while it's showing — success never comes for it to be
+ * dismissed after the fact. On that specific error, dismiss the dialog
+ * directly (see `dismissClaudeTrustDialog`) and then wait for readiness via
+ * `agent wait` on the *pane*, not by re-invoking `agent start` with the
+ * same name: once herdr has detected and named the agent on this pane
+ * (which happens even though the first `agent start` call threw), a second
+ * `agent start` call fails with `agent_name_taken` — confirmed live, even
+ * though the error payload's own `status` field shows the agent as Idle
+ * (ready) at that point.
+ */
+export function startAgent(opts) {
+    const args = ["agent", "start", opts.name, "--kind", opts.kind, "--pane", opts.pane];
+    if (opts.extraArgs && opts.extraArgs.length > 0) {
+        args.push("--", ...opts.extraArgs);
+    }
+    const deadline = Date.now() + AGENT_START_READY_RETRY_BUDGET_MS;
+    for (;;) {
+        try {
+            runHerdr(args);
+            return;
+        }
+        catch (err) {
+            const isPaneBusy = err instanceof HerdrError && err.code === "agent_pane_busy";
+            if (isPaneBusy && Date.now() < deadline) {
+                sleepSync(AGENT_START_READY_RETRY_INTERVAL_MS);
+                continue;
+            }
+            const isNotReady = err instanceof HerdrError && err.code === "agent_not_ready";
+            if (opts.kind === "claude" && isNotReady) {
+                dismissClaudeTrustDialog(opts.pane);
+                // --until idle specifically: confirmed live, right after dismissal
+                // Claude Code passes through a transient "blocked" status before
+                // settling into "idle" — `agent wait`'s default (idle/done/blocked)
+                // matches that transient blocked state and returns too early, so a
+                // caller that then immediately prompts the agent hits herdr's own
+                // agent_blocked error. Only "idle" actually means ready for prompts
+                // here.
+                runHerdr([
+                    "agent",
+                    "wait",
+                    opts.pane,
+                    "--until",
+                    "idle",
+                    "--timeout",
+                    String(CLAUDE_TRUST_DIALOG_READY_TIMEOUT_MS),
+                ]);
+                return;
+            }
+            throw err;
+        }
+    }
+}
+export function sendKeys(paneId, ...keys) {
+    runHerdrAction(["pane", "send-keys", paneId, ...keys]);
+}
+/**
+ * Submits the initial task instruction to a running agent. Confirmed live
+ * (see DECISIONS.md): for text long/multi-line enough that Claude Code's
+ * TUI collapses it into a "[Pasted text #N +M lines]" placeholder — which
+ * every real dispatch hits, since `buildTaskPrompt` always appends a
+ * multi-paragraph reporting contract — `herdr agent prompt` pastes the
+ * text into the input box but does not submit it; the agent sits idle
+ * until something sends Enter. Always follow up with an explicit Enter
+ * keypress to guarantee submission regardless of text length.
+ *
+ * Never pass `--wait` to the `agent prompt` call itself: it would block
+ * waiting for a state change that can't happen until *after* the
+ * follow-up Enter below is sent (a deadlock/stall). If waiting is
+ * requested, do it as its own step afterward via `agent wait`.
+ */
+export function promptAgent(opts) {
+    runHerdr(["agent", "prompt", opts.target, opts.text]);
+    sendKeys(opts.target, "enter");
+    if (opts.wait) {
+        const waitArgs = ["agent", "wait", opts.target];
+        if (opts.timeoutMs)
+            waitArgs.push("--timeout", String(opts.timeoutMs));
+        runHerdr(waitArgs);
+    }
+}

package/dist/lib/treehouse.js

@@ -0,0 +1,23 @@
+import { execFileSync } from "node:child_process";
+/**
+ * Durably leases a worktree from the pool rooted at `repoCwd` (treehouse
+ * discovers the repo from cwd) and returns its absolute path. Never opens a
+ * subshell (`--lease`), never removed by prune until explicitly returned.
+ */
+export function leaseWorktree(opts) {
+    const stdout = execFileSync("treehouse", ["get", "--lease", "--lease-holder", opts.leaseHolder], { cwd: opts.repoCwd, encoding: "utf8" });
+    const path = stdout.trim();
+    if (!path) {
+        throw new Error("treehouse get --lease returned no path");
+    }
+    return path;
+}
+/**
+ * Returns a leased worktree to the pool. Uses --force (clean, reset,
+ * return without prompting) since ledger's own CLI is non-interactive.
+ */
+export function returnWorktree(path) {
+    execFileSync("treehouse", ["return", path, "--force"], {
+        encoding: "utf8",
+    });
+}

package/dist/plugin/watcher.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * herdr event-hook entrypoint, registered in herdr-plugin.toml against the
+ * `pane.agent_status_changed` event hook. Not a daemon: herdr invokes this
+ * once per event and it exits. If herdr isn't running, this never fires —
+ * which is correct, since no agents can be running either (see DESIGN.md).
+ *
+ * Payload shape confirmed empirically (not documented): herdr wraps the
+ * event as `{ event: "pane_agent_status_changed", data: {...} }` — an
+ * underscored `event` name even though the manifest's `on` field is dotted
+ * (`pane.agent_status_changed`), with the actual fields nested under `data`,
+ * not flat. See DECISIONS.md.
+ */
+import { getDb } from "../db/client.js";
+function main() {
+    const raw = process.env["HERDR_PLUGIN_EVENT_JSON"];
+    if (!raw) {
+        // Not invoked as an event hook (e.g. run manually without the env var).
+        process.exit(0);
+    }
+    const envelope = JSON.parse(raw);
+    const event = envelope.data;
+    if (!event?.pane_id || !event.agent_status) {
+        process.exit(0);
+    }
+    const db = getDb();
+    const agentRow = db
+        .prepare("SELECT * FROM agents WHERE herdr_pane = ? ORDER BY id DESC LIMIT 1")
+        .get(event.pane_id);
+    if (!agentRow) {
+        // This pane isn't one ledger dispatched (e.g. the clerk's own pane).
+        process.exit(0);
+    }
+    db.prepare(`INSERT INTO events (agent_id, event_type, payload) VALUES (?, 'state_change', ?)`).run(agentRow.id, JSON.stringify(event));
+    // herdr's AgentStatus includes "unknown", which ledger's durable status
+    // field does not — an unknown reading is usually transient detection
+    // noise, so it's logged above but doesn't overwrite the last known status.
+    //
+    // `done` and `blocked` are terminal for this row while the row sits in
+    // them. Confirmed live (see DECISIONS.md): herdr keeps reporting pane
+    // activity after a self-reported `done` — e.g. the `agent update`
+    // command itself finishing causes the pane to settle back to `idle` a
+    // moment later — which would otherwise silently clobber a just-recorded
+    // completion back to `idle`. A self-reported `blocked` needs the same
+    // protection (A3): the agent is meaningfully waiting on a decision, and
+    // a late blip — often the very `agent update` that recorded the block
+    // settling the pane — must not decay it to `idle` on the board. A
+    // dispatch's row/pane/tab is never reused for a different task, so
+    // there's no real "back to working" transition this could be losing:
+    // leaving either state is always an explicit act (a fresh `agent
+    // update`), never a watcher blip.
+    const terminal = ["done", "blocked"];
+    if (event.agent_status !== "unknown" && !terminal.includes(agentRow.status)) {
+        db.prepare(`UPDATE agents SET status = ?, updated_at = datetime('now') WHERE id = ?`).run(event.agent_status, agentRow.id);
+    }
+}
+try {
+    main();
+}
+catch (err) {
+    console.error(`ledger watcher error: ${err.message}`);
+    process.exit(1);
+}

package/herdr-plugin.toml

@@ -0,0 +1,16 @@
+# The ledger watcher: not a daemon, just an event hook. herdr invokes
+# `node dist/plugin/watcher.js` once per pane_agent_status_changed event; the
+# process reads HERDR_PLUGIN_EVENT_JSON, updates the ledger, and exits.
+# See DESIGN.md ("The watcher: a herdr plugin, not a daemon").
+#
+# Local development: `herdr plugin link .` from this repo (after `npm run build`).
+
+id = "ledger"
+name = "ledger"
+version = "0.1.0"
+min_herdr_version = "0.7.0"
+description = "Watcher for the ledger agent-orchestration state store: keeps agents.status and the events audit trail in sync with herdr pane state, with zero standing process."
+
+[[events]]
+on = "pane.agent_status_changed"
+command = ["node", "dist/plugin/watcher.js"]

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@devwithdavid/ledger",
+  "version": "0.1.0",
+  "description": "Personal agent-orchestration ledger: SQLite state store, CLI, and herdr watcher plugin.",
+  "type": "module",
+  "bin": {
+    "ledger": "dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "LEDGER.md",
+    "README.md",
+    "herdr-plugin.toml"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "watch": "tsc -p tsconfig.json --watch",
+    "dev": "tsc -p tsconfig.json && node dist/cli/index.js",
+    "prepare": "tsc -p tsconfig.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "better-sqlite3": "^11.10.0",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.11",
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  }
+}