@devwithdavid/ledger 0.1.0

package/dist/cli/commands/clerk.js

@@ -0,0 +1,90 @@
+import { getDb } from "../../db/client.js";
+import * as herdr from "../../lib/herdr.js";
+import { printJson } from "../format.js";
+const STALE_AFTER_HOURS = 12;
+export function registerClerkCommands(program) {
+    const clerk = program.command("clerk").description("first-clerk authority (single row)");
+    clerk
+        .command("claim")
+        .description("claim first-clerk authority. Fails if another claim is active and not " +
+        "stale, unless --force is given")
+        .requiredOption("--session-id <id>", "this clerk session's id")
+        .requiredOption("--herdr-pane <id>", "this clerk's own herdr pane id")
+        .option("--force", "claim even if the existing claim is not stale")
+        .action((opts) => {
+        const db = getDb();
+        const existing = db
+            .prepare("SELECT * FROM first_clerk WHERE id = 1")
+            .get();
+        if (existing && !opts.force && !isStale(existing)) {
+            throw new Error(`first_clerk is already claimed by session ${existing.session_id} ` +
+                `(pane ${existing.herdr_pane}, claimed ${existing.claimed_at}). ` +
+                `Pass --force to override.`);
+        }
+        const row = db
+            .prepare(`INSERT INTO first_clerk (id, session_id, herdr_pane, claimed_at)
+           VALUES (1, ?, ?, datetime('now'))
+           ON CONFLICT(id) DO UPDATE SET
+             session_id = excluded.session_id,
+             herdr_pane = excluded.herdr_pane,
+             claimed_at = excluded.claimed_at,
+             last_seen = NULL
+           RETURNING *`)
+            .get(opts.sessionId, opts.herdrPane);
+        // The claim is durable now; the rename below is cosmetic only.
+        renameClaimantWorkspace(opts.herdrPane);
+        printJson(row);
+    });
+    clerk
+        .command("status")
+        .description("show the current first-clerk claim, if any")
+        .action(() => {
+        const row = getDb()
+            .prepare("SELECT * FROM first_clerk WHERE id = 1")
+            .get();
+        printJson(row ?? null);
+    });
+}
+function isStale(row) {
+    const claimedAt = new Date(row.claimed_at + "Z").getTime();
+    const ageHours = (Date.now() - claimedAt) / (1000 * 60 * 60);
+    return ageHours > STALE_AFTER_HOURS;
+}
+const CLERK_WORKSPACE_LABEL = "clerk";
+/**
+ * Renames the claimant's own herdr workspace to "clerk" (roadmap item 17):
+ * a clerk session started in a project folder otherwise gets a workspace
+ * label identical to that project's agent workspaces, and the user can't
+ * tell at a glance which workspace is the clerk. Pane ids look like
+ * "w3:p1", so the workspace id is the part before the colon.
+ *
+ * Idempotent: a no-op if the label is already "clerk". Only the
+ * claimant's own workspace is ever addressed — its id comes solely from
+ * the claimant's own --herdr-pane. Never fails the claim: on any error
+ * (workspace gone, herdr unreachable, ...) a warning goes to stderr and
+ * the claim stands. Known limitation (accepted for now): during a --force
+ * handover the previous claimant's workspace keeps the "clerk" label until
+ * it is renamed again; this function never touches workspaces it wasn't
+ * given.
+ */
+function renameClaimantWorkspace(herdrPane) {
+    const sep = herdrPane.indexOf(":");
+    const workspaceId = sep > 0 ? herdrPane.slice(0, sep) : undefined;
+    if (!workspaceId) {
+        console.error(`Warning: clerk claim succeeded, but the herdr pane "${herdrPane}" ` +
+            `has no "<workspace>:" prefix, so its workspace cannot be renamed ` +
+            `to "${CLERK_WORKSPACE_LABEL}".`);
+        return;
+    }
+    try {
+        const ws = herdr.getWorkspace(workspaceId, { quiet: true });
+        if (ws.label === CLERK_WORKSPACE_LABEL)
+            return; // idempotent
+        herdr.renameWorkspace(ws.workspace_id, CLERK_WORKSPACE_LABEL);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Warning: clerk claim succeeded, but renaming workspace ` +
+            `"${workspaceId}" to "${CLERK_WORKSPACE_LABEL}" failed: ${msg}`);
+    }
+}

package/dist/cli/commands/docs.js

@@ -0,0 +1,29 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+// This file compiles to dist/cli/commands/docs.js, three levels under the
+// repo root — resolve LEDGER.md relative to *this running code's own
+// location* rather than any hardcoded/machine-specific path, so `ledger
+// docs` works correctly regardless of where the repo was cloned or which
+// machine it's running on (including through an `npm link` symlink: ESM
+// resolves import.meta.url to the real file location).
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "../../..");
+const LEDGER_MD_PATH = join(REPO_ROOT, "LEDGER.md");
+export function registerDocsCommand(program) {
+    program
+        .command("docs")
+        .description("print LEDGER.md, the full clerk/agent reference — read this first " +
+        "if acting as the clerk")
+        .action(() => {
+        let content;
+        try {
+            content = readFileSync(LEDGER_MD_PATH, "utf8");
+        }
+        catch {
+            throw new Error(`couldn't read LEDGER.md at ${LEDGER_MD_PATH} — is this a ` +
+                `complete ledger install (git clone + npm run build), not just ` +
+                `a copied dist/ directory?`);
+        }
+        console.log(content);
+    });
+}

package/dist/cli/commands/events.js

@@ -0,0 +1,59 @@
+import { getDb } from "../../db/client.js";
+import { printJson, printTable } from "../format.js";
+import { getAgentById } from "./agents.js";
+export function registerEventCommands(program) {
+    const event = program.command("event").description("the append-only audit log");
+    event
+        .command("add")
+        .description("record a free-form event against an agent")
+        .requiredOption("--agent <id>", "agent id", parseIntOpt)
+        .requiredOption("--type <type>", "event type, e.g. note, state_change")
+        .option("--payload <json>", "free-form JSON payload")
+        .action((opts) => {
+        getAgentById(opts.agent); // throws if missing
+        if (opts.payload) {
+            try {
+                JSON.parse(opts.payload);
+            }
+            catch {
+                throw new Error("--payload must be valid JSON");
+            }
+        }
+        const row = getDb()
+            .prepare(`INSERT INTO events (agent_id, event_type, payload)
+           VALUES (?, ?, ?)
+           RETURNING *`)
+            .get(opts.agent, opts.type, opts.payload ?? null);
+        printJson(row);
+    });
+    event
+        .command("list")
+        .description("list events, newest first")
+        .option("--agent <id>", "filter by agent id", parseIntOpt)
+        .option("--since <iso>", "only events after this timestamp (e.g. from a prior catchup)")
+        .option("--json", "output as JSON")
+        .action((opts) => {
+        let sql = "SELECT * FROM events WHERE 1=1";
+        const params = [];
+        if (opts.agent !== undefined) {
+            sql += " AND agent_id = ?";
+            params.push(opts.agent);
+        }
+        if (opts.since) {
+            sql += " AND created_at > ?";
+            params.push(opts.since);
+        }
+        sql += " ORDER BY created_at DESC, id DESC";
+        const rows = getDb().prepare(sql).all(...params);
+        if (opts.json)
+            printJson(rows);
+        else
+            printTable(rows);
+    });
+}
+function parseIntOpt(value) {
+    const n = Number.parseInt(value, 10);
+    if (Number.isNaN(n))
+        throw new Error(`not a valid integer: ${value}`);
+    return n;
+}

package/dist/cli/commands/projects.js

@@ -0,0 +1,134 @@
+import { join } from "node:path";
+import { getDb, projectsDir } from "../../db/client.js";
+import { addRemote, cloneProject, getRemoteUrl, initProject } from "../../lib/git.js";
+import { printJson, printTable } from "../format.js";
+export function registerProjectCommands(program) {
+    const project = program.command("project").description("manage registered projects");
+    project
+        .command("add <source>")
+        .description("register a project by cloning it into ledger's own home directory " +
+        "(never the user's working checkout) — source is a remote URL or local path")
+        .requiredOption("--name <name>", "unique project name")
+        .option("--delivery-mode <mode>", "direct-pr | local-only", "direct-pr")
+        .action((source, opts) => {
+        const { db, deliveryMode, destPath } = prepareRegistration(opts);
+        const { defaultBranch } = cloneProject(source, destPath);
+        const row = insertProject(db, opts.name, source, destPath, defaultBranch, deliveryMode);
+        printJson(row);
+    });
+    project
+        .command("init")
+        .description("register a brand-new project that doesn't exist anywhere yet — no repo " +
+        "to clone, local or remote. Creates an empty git repo (one empty initial " +
+        "commit, so treehouse has a ref to lease worktrees from) in ledger's own " +
+        "home directory; a dispatched agent scaffolds it from there.")
+        .requiredOption("--name <name>", "unique project name")
+        .option("--delivery-mode <mode>", "direct-pr | local-only", "local-only")
+        .action((opts) => {
+        const { db, deliveryMode, destPath } = prepareRegistration(opts);
+        const { defaultBranch } = initProject(destPath);
+        const row = insertProject(db, opts.name, null, destPath, defaultBranch, deliveryMode);
+        printJson(row);
+    });
+    project
+        .command("update <name>")
+        .description("update a project's repo_url and/or delivery_mode — most commonly, " +
+        "giving a `project init`'d (from-scratch) project a real remote once " +
+        "one exists. Adds a git 'origin' remote to the local clone if it " +
+        "doesn't already have one; never overwrites an existing remote.")
+        .option("--repo-url <url>", "remote URL the project now has")
+        .option("--delivery-mode <mode>", "direct-pr | local-only")
+        .action((name, opts) => {
+        if (!opts.repoUrl && !opts.deliveryMode) {
+            throw new Error("give at least one of --repo-url or --delivery-mode");
+        }
+        const existing = getProjectByName(name);
+        let deliveryMode = existing.delivery_mode;
+        if (opts.deliveryMode) {
+            deliveryMode = opts.deliveryMode;
+            if (deliveryMode !== "direct-pr" && deliveryMode !== "local-only") {
+                throw new Error("--delivery-mode must be direct-pr or local-only");
+            }
+        }
+        // repo_url must always reflect the actual git remote, not just what
+        // was requested — an existing remote is never silently overwritten,
+        // so the DB record can't be allowed to silently diverge from it.
+        let repoUrl = existing.repo_url;
+        let remoteAdded = false;
+        let repoUrlMismatch = false;
+        if (opts.repoUrl) {
+            const currentRemote = getRemoteUrl(existing.local_clone_path, "origin");
+            if (currentRemote === null) {
+                addRemote(existing.local_clone_path, "origin", opts.repoUrl);
+                repoUrl = opts.repoUrl;
+                remoteAdded = true;
+            }
+            else {
+                repoUrl = currentRemote;
+                repoUrlMismatch = currentRemote !== opts.repoUrl;
+            }
+        }
+        const row = getDb()
+            .prepare(`UPDATE projects SET repo_url = ?, delivery_mode = ? WHERE name = ? RETURNING *`)
+            .get(repoUrl, deliveryMode, name);
+        printJson({
+            ...row,
+            git_remote_added: remoteAdded,
+            ...(repoUrlMismatch
+                ? {
+                    warning: `an 'origin' remote already exists at ${repoUrl}, which differs from ` +
+                        `the --repo-url given (${opts.repoUrl}) — ledger recorded the existing ` +
+                        `remote's actual URL and did not touch git; resolve manually if needed`,
+                }
+                : {}),
+        });
+    });
+    project
+        .command("list")
+        .description("list registered projects")
+        .option("--json", "output as JSON")
+        .action((opts) => {
+        const rows = getDb()
+            .prepare("SELECT * FROM projects ORDER BY name")
+            .all();
+        if (opts.json)
+            printJson(rows);
+        else
+            printTable(rows);
+    });
+    project
+        .command("get <name>")
+        .description("show a project by name")
+        .action((name) => {
+        const row = getProjectByName(name);
+        printJson(row);
+    });
+}
+function prepareRegistration(opts) {
+    const deliveryMode = opts.deliveryMode;
+    if (deliveryMode !== "direct-pr" && deliveryMode !== "local-only") {
+        throw new Error("--delivery-mode must be direct-pr or local-only");
+    }
+    const db = getDb();
+    const existing = db.prepare("SELECT id FROM projects WHERE name = ?").get(opts.name);
+    if (existing) {
+        throw new Error(`a project named "${opts.name}" is already registered`);
+    }
+    const destPath = join(projectsDir(), opts.name);
+    return { db, deliveryMode, destPath };
+}
+function insertProject(db, name, repoUrl, localClonePath, defaultBranch, deliveryMode) {
+    return db
+        .prepare(`INSERT INTO projects (name, repo_url, local_clone_path, default_branch, delivery_mode)
+       VALUES (?, ?, ?, ?, ?)
+       RETURNING *`)
+        .get(name, repoUrl, localClonePath, defaultBranch, deliveryMode);
+}
+export function getProjectByName(name) {
+    const row = getDb()
+        .prepare("SELECT * FROM projects WHERE name = ?")
+        .get(name);
+    if (!row)
+        throw new Error(`no project named "${name}"`);
+    return row;
+}

package/dist/cli/commands/roadmap.js

@@ -0,0 +1,120 @@
+import { getDb } from "../../db/client.js";
+import { ROADMAP_PRIORITIES } from "../../db/types.js";
+import { printJson, printTable } from "../format.js";
+import { getProjectByName } from "./projects.js";
+const VALID_STATUSES = [
+    "planned",
+    "in_progress",
+    "blocked",
+    "done",
+    "dropped",
+];
+export function registerRoadmapCommands(program) {
+    const roadmap = program
+        .command("roadmap")
+        .description("manage the hierarchical feature breakdown for a project");
+    roadmap
+        .command("add")
+        .description("add a roadmap item (top-level, or a sub-item via --parent)")
+        .requiredOption("--project <name>", "project name")
+        .requiredOption("--title <title>", "item title")
+        .option("--description <text>", "longer description")
+        .option("--parent <id>", "parent roadmap item id, for a sub-item", parseIntOpt)
+        .option("--priority <priority>", `item priority (${ROADMAP_PRIORITIES.join("|")}, default normal)`)
+        .action((opts) => {
+        const project = getProjectByName(opts.project);
+        const db = getDb();
+        // Note: assertValidPriority() is an assertion function (returns
+        // void) — it validates/narrows, it must not be used as the value.
+        let priority = "normal";
+        if (opts.priority !== undefined) {
+            assertValidPriority(opts.priority);
+            priority = opts.priority;
+        }
+        if (opts.parent !== undefined) {
+            const parent = db
+                .prepare("SELECT id, project_id FROM roadmap WHERE id = ?")
+                .get(opts.parent);
+            if (!parent)
+                throw new Error(`no roadmap item #${opts.parent}`);
+            if (parent.project_id !== project.id) {
+                throw new Error(`roadmap item #${opts.parent} belongs to a different project`);
+            }
+        }
+        const row = db
+            .prepare(`INSERT INTO roadmap (project_id, parent_id, title, description, priority)
+             VALUES (?, ?, ?, ?, ?)
+             RETURNING *`)
+            .get(project.id, opts.parent ?? null, opts.title, opts.description ?? null, priority);
+        printJson(row);
+    });
+    roadmap
+        .command("list")
+        .description("list roadmap items for a project")
+        .requiredOption("--project <name>", "project name")
+        .option("--status <status>", `filter by status (${VALID_STATUSES.join("|")})`)
+        .option("--all", "include done/dropped items (default: exclude them)")
+        .option("--json", "output as JSON")
+        .action((opts) => {
+        const project = getProjectByName(opts.project);
+        const db = getDb();
+        let sql = "SELECT * FROM roadmap WHERE project_id = ?";
+        const params = [project.id];
+        if (opts.status) {
+            assertValidStatus(opts.status);
+            sql += " AND status = ?";
+            params.push(opts.status);
+        }
+        else if (!opts.all) {
+            sql += " AND status NOT IN ('done', 'dropped')";
+        }
+        sql += " ORDER BY parent_id IS NOT NULL, id";
+        const rows = db.prepare(sql).all(...params);
+        if (opts.json)
+            printJson(rows);
+        else
+            printTable(rows);
+    });
+    roadmap
+        .command("update <id>")
+        .description("update a roadmap item's status/title/description/priority")
+        .option("--status <status>", `new status (${VALID_STATUSES.join("|")})`)
+        .option("--title <title>", "new title")
+        .option("--description <text>", "new description")
+        .option("--priority <priority>", `new priority (${ROADMAP_PRIORITIES.join("|")})`)
+        .action((id, opts) => {
+        if (opts.status)
+            assertValidStatus(opts.status);
+        if (opts.priority)
+            assertValidPriority(opts.priority);
+        const db = getDb();
+        const existing = db
+            .prepare("SELECT * FROM roadmap WHERE id = ?")
+            .get(Number(id));
+        if (!existing)
+            throw new Error(`no roadmap item #${id}`);
+        const row = db
+            .prepare(`UPDATE roadmap
+             SET status = ?, title = ?, description = ?, priority = ?, updated_at = datetime('now')
+             WHERE id = ?
+             RETURNING *`)
+            .get(opts.status ?? existing.status, opts.title ?? existing.title, opts.description ?? existing.description, opts.priority ?? existing.priority, Number(id));
+        printJson(row);
+    });
+}
+function assertValidStatus(status) {
+    if (!VALID_STATUSES.includes(status)) {
+        throw new Error(`--status must be one of: ${VALID_STATUSES.join(", ")}`);
+    }
+}
+function assertValidPriority(priority) {
+    if (!ROADMAP_PRIORITIES.includes(priority)) {
+        throw new Error(`--priority must be one of: ${ROADMAP_PRIORITIES.join(", ")}`);
+    }
+}
+function parseIntOpt(value) {
+    const n = Number.parseInt(value, 10);
+    if (Number.isNaN(n))
+        throw new Error(`not a valid integer: ${value}`);
+    return n;
+}

package/dist/cli/format.js

@@ -0,0 +1,19 @@
+export function printJson(value) {
+    console.log(JSON.stringify(value, null, 2));
+}
+/** Simple aligned-column table for terminal output (no dependency needed). */
+export function printTable(rows) {
+    if (rows.length === 0) {
+        console.log("(none)");
+        return;
+    }
+    const asRecords = rows;
+    const columns = Object.keys(asRecords[0]);
+    const widths = columns.map((col) => Math.max(col.length, ...asRecords.map((row) => String(row[col] ?? "").length)));
+    const formatRow = (cells) => cells.map((cell, i) => cell.padEnd(widths[i])).join("  ");
+    console.log(formatRow(columns));
+    console.log(formatRow(widths.map((w) => "-".repeat(w))));
+    for (const row of asRecords) {
+        console.log(formatRow(columns.map((col) => String(row[col] ?? ""))));
+    }
+}

package/dist/cli/index.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { registerAgentCommands } from "./commands/agents.js";
+import { registerCatchupCommand } from "./commands/catchup.js";
+import { registerClerkCommands } from "./commands/clerk.js";
+import { registerDocsCommand } from "./commands/docs.js";
+import { registerEventCommands } from "./commands/events.js";
+import { registerProjectCommands } from "./commands/projects.js";
+import { registerRoadmapCommands } from "./commands/roadmap.js";
+const program = new Command();
+program
+    .name("ledger")
+    .description("Durable state store for a personal agent-orchestration workflow " +
+    "(projects, roadmap, dispatched agents, events).")
+    .version("0.1.0");
+registerProjectCommands(program);
+registerRoadmapCommands(program);
+registerAgentCommands(program);
+registerEventCommands(program);
+registerClerkCommands(program);
+registerCatchupCommand(program);
+registerDocsCommand(program);
+program.exitOverride();
+try {
+    await program.parseAsync(process.argv);
+}
+catch (err) {
+    if (err.code?.startsWith("commander.")) {
+        process.exit(err.exitCode ?? 1);
+    }
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+}

package/dist/db/client.js

@@ -0,0 +1,48 @@
+import Database from "better-sqlite3";
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { migrations } from "./migrations/index.js";
+export function ledgerHome() {
+    return process.env["LEDGER_HOME"] ?? join(homedir(), ".ledger");
+}
+export function projectsDir() {
+    return join(ledgerHome(), "projects");
+}
+let db;
+export function getDb() {
+    if (db)
+        return db;
+    const home = ledgerHome();
+    mkdirSync(home, { recursive: true });
+    mkdirSync(projectsDir(), { recursive: true });
+    db = new Database(join(home, "ledger.db"));
+    db.pragma("journal_mode = WAL");
+    db.pragma("foreign_keys = ON");
+    applyMigrations(db);
+    return db;
+}
+function applyMigrations(database) {
+    database.exec(`
+    CREATE TABLE IF NOT EXISTS schema_migrations (
+      version     INTEGER PRIMARY KEY,
+      name        TEXT NOT NULL,
+      applied_at  TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+  `);
+    const appliedRow = database
+        .prepare("SELECT COALESCE(MAX(version), 0) AS v FROM schema_migrations")
+        .get();
+    const applied = appliedRow.v;
+    const pending = migrations.filter((m) => m.version > applied);
+    if (pending.length === 0)
+        return;
+    const insertMigration = database.prepare("INSERT INTO schema_migrations (version, name) VALUES (?, ?)");
+    for (const migration of pending) {
+        const run = database.transaction(() => {
+            database.exec(migration.sql);
+            insertMigration.run(migration.version, migration.name);
+        });
+        run();
+    }
+}

package/dist/db/migrations/0001_init.js

@@ -0,0 +1,72 @@
+export const migration0001Init = {
+    version: 1,
+    name: "init",
+    sql: `
+    CREATE TABLE projects (
+      id                INTEGER PRIMARY KEY,
+      name              TEXT NOT NULL UNIQUE,
+      repo_url          TEXT,  -- NULL for a from-scratch project (ledger project init): no origin exists yet
+      local_clone_path  TEXT NOT NULL,
+      default_branch    TEXT NOT NULL,
+      delivery_mode     TEXT NOT NULL DEFAULT 'direct-pr'
+                          CHECK (delivery_mode IN ('direct-pr', 'local-only')),
+      created_at        TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE roadmap (
+      id            INTEGER PRIMARY KEY,
+      project_id    INTEGER NOT NULL REFERENCES projects(id),
+      parent_id     INTEGER REFERENCES roadmap(id),
+      title         TEXT NOT NULL,
+      description   TEXT,
+      status        TEXT NOT NULL DEFAULT 'planned'
+                      CHECK (status IN ('planned', 'in_progress', 'blocked', 'done', 'dropped')),
+      created_at    TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at    TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE INDEX idx_roadmap_project ON roadmap(project_id);
+    CREATE INDEX idx_roadmap_parent ON roadmap(parent_id);
+
+    CREATE TABLE agents (
+      id                INTEGER PRIMARY KEY,
+      project_id        INTEGER NOT NULL REFERENCES projects(id),
+      roadmap_item_id   INTEGER REFERENCES roadmap(id),
+      task_description  TEXT NOT NULL,
+      worktree_path     TEXT NOT NULL,
+      herdr_workspace   TEXT NOT NULL,
+      herdr_tab         TEXT NOT NULL,
+      herdr_pane        TEXT NOT NULL,
+      coding_agent      TEXT NOT NULL,
+      status            TEXT NOT NULL DEFAULT 'working'
+                          CHECK (status IN ('blocked', 'working', 'done', 'idle')),
+      outcome           TEXT,
+      spawned_by        INTEGER REFERENCES agents(id),
+      created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at        TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE INDEX idx_agents_project ON agents(project_id);
+    CREATE INDEX idx_agents_status ON agents(status);
+    CREATE INDEX idx_agents_herdr_pane ON agents(herdr_pane);
+
+    CREATE TABLE events (
+      id          INTEGER PRIMARY KEY,
+      agent_id    INTEGER NOT NULL REFERENCES agents(id),
+      event_type  TEXT NOT NULL,
+      payload     TEXT,
+      created_at  TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE INDEX idx_events_agent ON events(agent_id);
+    CREATE INDEX idx_events_created_at ON events(created_at);
+
+    CREATE TABLE first_clerk (
+      id            INTEGER PRIMARY KEY CHECK (id = 1),
+      session_id    TEXT NOT NULL,
+      herdr_pane    TEXT NOT NULL,
+      claimed_at    TEXT NOT NULL DEFAULT (datetime('now')),
+      last_seen     TEXT
+    );
+  `,
+};

package/dist/db/migrations/0002_project_herdr_workspace.js

@@ -0,0 +1,13 @@
+export const migration0002ProjectHerdrWorkspace = {
+    version: 2,
+    name: "project_herdr_workspace",
+    sql: `
+    -- One herdr workspace per project, not per dispatch (per the user):
+    -- the first dispatch to a project creates its workspace and records
+    -- the id here; every later dispatch to the same project reuses it,
+    -- adding a new tab rather than a new workspace. NULL until a first
+    -- dispatch happens, and re-nulled/replaced if that workspace is found
+    -- closed (see src/lib/herdr.ts workspaceExists).
+    ALTER TABLE projects ADD COLUMN herdr_workspace TEXT;
+  `,
+};

package/dist/db/migrations/0003_agent_authorization_basis.js

@@ -0,0 +1,18 @@
+export const migration0003AgentAuthorizationBasis = {
+    version: 3,
+    name: "agent_authorization_basis",
+    sql: `
+    -- Clerk gate C6 (DECISIONS.md, 2026-08-23): every dispatch must record
+    -- who authorized it. 'user-explicit' = an in-the-moment green light
+    -- from the user; 'pre-authorized' = a previously granted, per-item,
+    -- revocable standing latitude the clerk requested. The value is
+    -- clerk-attested -- the CLI cannot know whether the user actually
+    -- said yes, it only enforces that a basis is declared and recorded so
+    -- every dispatch is auditable (the default is no longer "allowed").
+    -- NULL only for rows predating this column; the dispatch command
+    -- refuses any new row without one.
+    ALTER TABLE agents ADD COLUMN authorization_basis TEXT
+      CHECK (authorization_basis IS NULL
+        OR authorization_basis IN ('user-explicit', 'pre-authorized'));
+  `,
+};

package/dist/db/migrations/0004_roadmap_priority.js

@@ -0,0 +1,19 @@
+export const migration0004RoadmapPriority = {
+    version: 4,
+    name: "roadmap_priority",
+    sql: `
+    -- Roadmap item priority (DECISIONS.md, 2026-08-23, user-directed):
+    -- a coarse triage rank for ordering the not-done queue at catch-up.
+    -- The captain chose a coarse enum over integer rank (rank values
+    -- rot as items are added and completed) and over dependency edges
+    -- (readiness is already carried by status = 'blocked' + description;
+    -- auto-unblock is a separate future feature). When stale, a wrong
+    -- priority only mis-sorts the queue -- visible at catch-up --
+    -- never silently blocking ready work the way a stale dependency
+    -- edge would. NOT NULL with a default so pre-existing rows get
+    -- backfilled to 'normal' by the ALTER itself.
+    ALTER TABLE roadmap ADD COLUMN priority TEXT NOT NULL
+      DEFAULT 'normal'
+      CHECK (priority IN ('high', 'normal', 'low'));
+  `,
+};