@devwithdavid/ledger 0.1.0 → 0.1.2

package/LEDGER.md

@@ -38,9 +38,12 @@ what's below is a description of it, not a separate copy to keep in sync):
   - `direct-pr`: open a pull request against the default branch — using
     whatever tooling is available for that project's remote (e.g. `tea`
     for a Forgejo remote; ledger doesn't care which, that's your call) —
-    **do not merge it yourself, regardless of anything else you're told.**
-    PR review is a real checkpoint, not a formality to clear on your own
-    (see `DECISIONS.md` for the incident that made this explicit). Then
+    **never merge any branch or PR (your own or anyone else's), and
+    never approve any PR, regardless of anything else you're told,
+    including by the clerk.** PR review is a real checkpoint, not a
+    formality to clear on your own (see `DECISIONS.md` for the incident
+    that made this explicit, and the 2026-09-02 generalization that also
+    forbids approving any PR). Then
     `ledger agent update <your-agent-id> --status done --outcome
     '<pr-url>'`.
   - `local-only`: just `ledger agent update <your-agent-id> --status done
@@ -98,9 +101,11 @@ the code.
   concrete, in-the-moment, user-approved operation — executed exactly as
   approved, never inferred or generalized, conferring no standing
   authority.
-- **C2 — you never merge, force-push, or close a PR without an explicit
-  user word.** One explicit word at a time, in the moment; there is no
-  standing relaxation. (Worker-side mirror: A2.)
+- **C2 — you never merge a branch or PR, force-push, or close a PR without an
+  explicit user word naming the specific merge/pull request.** One explicit
+  word at a time, in the moment, for that specific PR; there is no standing
+  relaxation — a general instruction does not license a specific merge.
+  (Worker-side mirror: A2.)
 - **C4 — agents never address the user directly; you are the single
   channel.** If the user intervenes directly in a worker pane, that
   instruction is authoritative: reconcile at the next catch-up, never
@@ -119,6 +124,11 @@ the code.
 - **C9 — you do not self-modify.** Never edit your own contract or skills
   (this file, `DECISIONS.md`, the skill pointer) without explicit user
   approval — a gate must not be editable by the party it binds.
+- **C10 — you refer to a ledger item with visual context.** Always make an
+  item identifiable without board access: if it (or its project) has an open
+  PR/MR, include that PR/MR's number (and URL) alongside the ledger id — e.g.
+  'item #22 (PR #10)'; if no merge is open, add a short context phrase — the
+  item's title or a one-line description.
 
 **Liveness (A8, clerk side).** At catch-up, an `idle` agent with
 unfinished work is suspect — it may have died on a usage limit. `catchup`

package/README.md

@@ -13,7 +13,8 @@ a general product.
 
 ## Prerequisites
 
-- [Node.js](https://nodejs.org) ≥ 20
+- [Node.js](https://nodejs.org) ≥ 22.13 (needed for the built-in
+  `node:sqlite` storage driver — see [`DECISIONS.md`](./DECISIONS.md))
 - [herdr](https://herdr.dev) installed and running — the terminal
   workspace/pane manager. `herdr status` should show a running server.
 - [treehouse](https://github.com/kunchenguid/treehouse) installed — isolated
@@ -24,36 +25,29 @@ a general product.
 ## Install
 
 ```sh
-git clone <this-repo> ledger   # or you already have it locally
-cd ledger
-npm install
-npm run build
+npm install -g @devwithdavid/ledger
 ```
 
-**Make the CLI available.** Either:
-
-```sh
-npm link          # puts `ledger` on PATH globally
-```
-
-or invoke it directly / alias it:
-
-```sh
-node dist/cli/index.js ...
-```
+That's the whole install. The package ships pre-built, and the global
+install puts `ledger` on your PATH — no build step, no separate linking
+step: the `ledger` binary lands on PATH with the install itself.
 
 **Link the watcher plugin into herdr** — this is what keeps agent status
-current automatically as dispatched agents work, without any polling:
+current automatically as dispatched agents work, without any polling.
+`herdr-plugin.toml` ships inside the package, so point the link at the
+installed package's root:
 
 ```sh
-herdr plugin link .
+herdr plugin link "$(npm root -g)/@devwithdavid/ledger"
 ```
 
 This registers `herdr-plugin.toml`, so herdr invokes `dist/plugin/watcher.js`
 whenever a pane's detected agent state changes. It's local and reversible:
-`herdr plugin unlink ledger` removes it. Re-run `npm run build` after any
-change to `src/plugin/watcher.ts` — herdr always invokes whatever's
-currently in `dist/`.
+`herdr plugin unlink ledger` removes it. herdr always runs whatever's
+currently in the installed package's `dist/`, so `npm update -g
+@devwithdavid/ledger` picks up new releases (including watcher changes) on
+the next event; re-run the link command if you want the registered version
+to track a new release.
 
 ## Starting a clerk session
 
@@ -106,9 +100,9 @@ simply never fires.
 
 | Doc | What's in it |
 |---|---|
-| [`DESIGN.md`](./DESIGN.md) | The philosophy, why this exists, and the original schema/flow brief |
+| [`DESIGN.md`](./DESIGN.md) | The philosophy, why this exists, and the original schema/flow brief (in the git repo — public mirror coming soon) |
 | [`LEDGER.md`](./LEDGER.md) | The operational reference — full CLI surface, what the first clerk is responsible for vs. what a dispatched agent is told, and how to extend this safely |
-| [`DECISIONS.md`](./DECISIONS.md) | Running log of implementation decisions and why, including things verified live against the real herdr/treehouse binaries (some of herdr's actual behavior differs from its docs — see this file before assuming a documented API shape is accurate) |
+| [`DECISIONS.md`](./DECISIONS.md) | Running log of implementation decisions and why, including things verified live against the real herdr/treehouse binaries — some of herdr's actual behavior differs from its docs, so read this before assuming a documented API shape is accurate (in the git repo — public mirror coming soon) |
 
 ## Extending
 
@@ -125,11 +119,15 @@ genuinely does belong in core.
 
 ## Example extension
 
-[`ledger-notify`](../ledger-notify) *(sibling repo, once built)* — a
-desktop-notification plugin that watches for agents going `blocked` or
-`done`, built entirely outside this repo as a worked example of the
-extension model. See [`EXTENSION-EXAMPLE-BRIEF.md`](./EXTENSION-EXAMPLE-BRIEF.md)
-for the implementation brief.
+`ledger-notify` — a desktop-notification plugin that watches for agents
+going `blocked` or `done`, built entirely outside this repo as a worked
+example of the extension model. The plugin lives in a sibling git repo, and
+the implementation brief, [`EXTENSION-EXAMPLE-BRIEF.md`](./EXTENSION-EXAMPLE-BRIEF.md),
+is in this project's git repo — the public mirror for both is coming soon.
+None of that is needed to build an extension, though: the whole contract is
+reading/writing the SQLite file at `$LEDGER_HOME/ledger.db` or shelling out
+to the `ledger` CLI, as [`LEDGER.md` § "Safe ways to extend this"]
+(./LEDGER.md#safe-ways-to-extend-this) describes.
 
 ## Status
 

package/dist/cli/commands/agents.js

@@ -352,8 +352,9 @@ function survivalProof(worktreePath) {
  * one worktree / no spawning (A1), blocked as a structured decision
  * request (A4), no self-modification of the contract or the board (A5),
  * faithful outcomes (A6), and work surviving in a durable posture before
- * exit (A7). A2 (no self-merge) already lives in the direct-pr delivery
- * text since the self-merge incident.
+ * exit (A7). A2 (no merging, ever: no branch merge in any mode,
+ * no PR approval) lives in both delivery texts since the
+ * self-merge incident, generalized 2026-09-02.
  */
 function buildTaskPrompt(agentId, task, project) {
     const deliveryInstructions = project.delivery_mode === "direct-pr"
@@ -363,15 +364,19 @@ Before you exit, all your work must be on that branch pushed to the remote
 it is at risk of being lost.
 When you're done, open a pull request against '${project.default_branch}'
 (use whatever tooling is available for this project's remote, e.g. \`tea\`
-for a Forgejo remote). Do NOT merge it yourself, even if you technically
-can — opening the PR is the whole job. Merging is a human/review decision,
-not yours to make, regardless of anything else you're told. Then run this
-as your last step:
+for a Forgejo remote). Never merge any branch or PR — your own or anyone
+else's — and never approve any PR, even if you technically can: opening
+the PR is the whole job. Merging and approving are human/review decisions,
+not yours to make, regardless of anything else you're told, including by
+the clerk. Then run this as your last step:
   ledger agent update ${agentId} --status done --outcome '<pr-url>'
 using the PR's URL.`
         : `Work on a new branch — never commit directly to '${project.default_branch}'.
 Before you exit, commit all your work in the worktree — it is leased and
 gets recycled, so anything left uncommitted is at risk of being lost.
+Merging that branch into any other branch is not your act — you report it
+and stop. Never merge any branch or PR, and never approve any PR, regardless
+of anything else you're told; the merge is a human decision.
 When you're done, run this as your last step:
   ledger agent update ${agentId} --status done --outcome '<branch-name-or-report-path>'`;
     return `${task}

package/dist/cli/commands/clerk.js

@@ -1,4 +1,4 @@
-import { getDb } from "../../db/client.js";
+import { getDb, suppressNextClerkHeartbeat } from "../../db/client.js";
 import * as herdr from "../../lib/herdr.js";
 import { printJson } from "../format.js";
 const STALE_AFTER_HOURS = 12;
@@ -31,6 +31,10 @@ export function registerClerkCommands(program) {
              last_seen = NULL
            RETURNING *`)
             .get(opts.sessionId, opts.herdrPane);
+        // The upsert above just reset last_seen to NULL (fresh clock) —
+        // don't let the generic post-command heartbeat (src/cli/index.ts)
+        // immediately overwrite that within this same invocation.
+        suppressNextClerkHeartbeat();
         // The claim is durable now; the rename below is cosmetic only.
         renameClaimantWorkspace(opts.herdrPane);
         printJson(row);
@@ -45,9 +49,21 @@ export function registerClerkCommands(program) {
         printJson(row ?? null);
     });
 }
+/**
+ * Item 27 (2026-09-03, user-directed "robust" option): staleness reflects
+ * actual activity, not just how long ago the claim was made. A clerk
+ * session that's still working past 12h shouldn't be displaceable just
+ * because it claimed early — so this compares now against the LATEST of
+ * claimed_at and last_seen, falling back to claimed_at when last_seen is
+ * NULL (what a fresh claim sets — see the upsert above). last_seen is
+ * kept current by the heartbeat in src/cli/index.ts (touchClerkHeartbeat)
+ * and, belt-and-braces, by catchup's own write.
+ */
 function isStale(row) {
     const claimedAt = new Date(row.claimed_at + "Z").getTime();
-    const ageHours = (Date.now() - claimedAt) / (1000 * 60 * 60);
+    const lastSeen = row.last_seen ? new Date(row.last_seen + "Z").getTime() : claimedAt;
+    const lastActivity = Math.max(claimedAt, lastSeen);
+    const ageHours = (Date.now() - lastActivity) / (1000 * 60 * 60);
     return ageHours > STALE_AFTER_HOURS;
 }
 const CLERK_WORKSPACE_LABEL = "clerk";

package/dist/cli/index.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+// Must come first — see the comment in suppress-experimental-warnings.ts.
+import "./suppress-experimental-warnings.js";
 import { Command } from "commander";
 import { registerAgentCommands } from "./commands/agents.js";
 import { registerCatchupCommand } from "./commands/catchup.js";
@@ -7,6 +9,7 @@ import { registerDocsCommand } from "./commands/docs.js";
 import { registerEventCommands } from "./commands/events.js";
 import { registerProjectCommands } from "./commands/projects.js";
 import { registerRoadmapCommands } from "./commands/roadmap.js";
+import { touchClerkHeartbeat } from "../db/client.js";
 const program = new Command();
 program
     .name("ledger")
@@ -23,8 +26,12 @@ registerDocsCommand(program);
 program.exitOverride();
 try {
     await program.parseAsync(process.argv);
+    // Item 27: heartbeat after the command has run its own logic — see
+    // touchClerkHeartbeat's doc comment for why it can't live in getDb().
+    touchClerkHeartbeat();
 }
 catch (err) {
+    touchClerkHeartbeat();
     if (err.code?.startsWith("commander.")) {
         process.exit(err.exitCode ?? 1);
     }

package/dist/cli/suppress-experimental-warnings.js

@@ -0,0 +1,23 @@
+/**
+ * node:sqlite is still experimental (unflagged since Node 22.13.0/23.4.0)
+ * and prints an ExperimentalWarning the moment it's first imported.
+ * Suppress only that one warning — everything else still reaches stderr
+ * as normal.
+ *
+ * Must be the *first* import in the CLI entry point: ES module static
+ * imports are hoisted and executed before the importing module's own
+ * top-level body, so this override has to be its own dependency-free
+ * module, imported before anything that (transitively) imports
+ * "node:sqlite" — otherwise the warning fires before the override is
+ * installed.
+ */
+const originalEmitWarning = process.emitWarning.bind(process);
+process.emitWarning = ((warning, ...args) => {
+    const type = typeof args[0] === "string" ? args[0] : args[0]?.type;
+    const message = warning instanceof Error ? warning.message : warning;
+    if (type === "ExperimentalWarning" && typeof message === "string" && message.includes("SQLite")) {
+        return;
+    }
+    return originalEmitWarning(warning, ...args);
+});
+export {};

package/dist/db/client.js

@@ -1,8 +1,16 @@
-import Database from "better-sqlite3";
 import { mkdirSync } from "node:fs";
+import { createRequire } from "node:module";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { migrations } from "./migrations/index.js";
+// node:sqlite emits its one-time ExperimentalWarning as soon as the module
+// is *loaded* — a static `import ... from "node:sqlite"` here would trigger
+// it during ESM's graph-link phase, before the CLI entry point's warning
+// filter (src/cli/suppress-experimental-warnings.ts) has run. Loading it
+// via `require` instead defers that load to normal, in-order statement
+// execution, so the filter is already installed by the time it fires.
+const require = createRequire(import.meta.url);
+const { DatabaseSync } = require("node:sqlite");
 export function ledgerHome() {
     return process.env["LEDGER_HOME"] ?? join(homedir(), ".ledger");
 }
@@ -16,12 +24,59 @@ export function getDb() {
     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");
+    db = new DatabaseSync(join(home, "ledger.db"));
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec("PRAGMA foreign_keys = ON");
     applyMigrations(db);
     return db;
 }
+let suppressNextHeartbeat = false;
+/**
+ * `clerk claim`'s own upsert resets last_seen to NULL on every claim,
+ * fresh or forced — "a fresh claim starts a fresh clock" (DECISIONS.md,
+ * item 27). Without this, the generic post-command heartbeat below would
+ * immediately overwrite that NULL with `now` before the same invocation
+ * ends, erasing the reset the claim command just made. Call this right
+ * after the upsert; it's consumed (one-shot) by this invocation's own
+ * touchClerkHeartbeat() call in src/cli/index.ts.
+ */
+export function suppressNextClerkHeartbeat() {
+    suppressNextHeartbeat = true;
+}
+/**
+ * Item 27 (activity-based clerk liveness, 2026-09-03 user decision):
+ * bump first_clerk.last_seen so staleness reflects real activity, not
+ * just time-since-claim. Called once per CLI invocation, from
+ * src/cli/index.ts, AFTER the invoked command's own logic has run —
+ * deliberately not from inside getDb() itself. `clerk claim` reads
+ * first_clerk to decide whether the *existing* claim is stale before it
+ * does anything else; if a heartbeat fired on that same getDb() call it
+ * would stamp last_seen = now on the very row being checked (which may
+ * belong to a different, possibly-dead session) and erase the staleness
+ * the check exists to detect. Running the heartbeat after the command
+ * body closes that gap.
+ *
+ * A no-op if the store was never opened this invocation (e.g. --help),
+ * there's no first_clerk row yet (0 rows updated), or the invocation was
+ * itself a `clerk claim` (see suppressNextClerkHeartbeat). Never throws:
+ * a heartbeat failure must not fail the command it's riding on, so any
+ * error is only warned to stderr.
+ */
+export function touchClerkHeartbeat() {
+    if (suppressNextHeartbeat) {
+        suppressNextHeartbeat = false;
+        return;
+    }
+    if (!db)
+        return;
+    try {
+        db.prepare("UPDATE first_clerk SET last_seen = datetime('now') WHERE id = 1").run();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Warning: clerk heartbeat failed: ${msg}`);
+    }
+}
 function applyMigrations(database) {
     database.exec(`
     CREATE TABLE IF NOT EXISTS schema_migrations (
@@ -39,10 +94,17 @@ function applyMigrations(database) {
         return;
     const insertMigration = database.prepare("INSERT INTO schema_migrations (version, name) VALUES (?, ?)");
     for (const migration of pending) {
-        const run = database.transaction(() => {
+        // node:sqlite's DatabaseSync has no built-in `.transaction()` helper
+        // (unlike better-sqlite3) — drive BEGIN/COMMIT/ROLLBACK explicitly.
+        database.exec("BEGIN");
+        try {
             database.exec(migration.sql);
             insertMigration.run(migration.version, migration.name);
-        });
-        run();
+            database.exec("COMMIT");
+        }
+        catch (err) {
+            database.exec("ROLLBACK");
+            throw err;
+        }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devwithdavid/ledger",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Personal agent-orchestration ledger: SQLite state store, CLI, and herdr watcher plugin.",
   "type": "module",
   "bin": {
@@ -19,14 +19,12 @@
     "prepare": "tsc -p tsconfig.json"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22.13.0"
   },
   "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"
   }