@devwithdavid/ledger 0.1.4 → 0.2.0

package/LEDGER.md

@@ -155,8 +155,8 @@ every agent currently `idle` together with the tail of its pane's recent
 output (A8 liveness triage — did it ask a question, hit a usage error, or
 go quiet mid-task?), every `events` row since the last time any clerk ran
 `catchup` (tracked in `first_clerk.last_seen`), and every roadmap item not
-yet `done`/`dropped`, ordered by priority `high → normal → low` (ties by
-id).
+yet in a terminal status (`merged`/`completed`/`discarded`/`dropped`),
+ordered by priority `high → normal → low` (ties by id).
 This is the entire "what's going on" operation from `DESIGN.md` — read this
 instead of any prose file, every session.
 
@@ -170,6 +170,27 @@ repeating the same failure under every idle agent. `--json` includes the
 same data as an `idle` array (`agent`, `pane_tail`, `pane_read_error`) plus
 top-level `idle_pane_read_note` for the whole-socket case.
 
+`catchup` also lists every `done` agent whose herdr pane is still actually
+alive (item 88) — a real candidate for `agent followup` below, distinct from
+a `done` agent whose worktree/pane is genuinely gone. This is a fresh
+per-agent `herdr pane get`, same A8-style observation idle pane tails
+already use, not a new `agents.status` value: a `done` agent whose pane
+resolves shows up here; one that doesn't (pane/tab/workspace closed) is
+silently excluded, not reported as an error, per C7. `--json`'s
+`done_with_live_pane` array carries `{agent, herdr_agent_status}` per entry;
+`done_pane_read_note` mirrors `idle_pane_read_note` for the whole-socket-down
+case. Governed by the same `--idle-pane-lines` flag as idle tails — `0`
+disables both.
+
+`catchup` also checks (item 42) whether a newer `@devwithdavid/ledger` npm
+version exists — a plain-text notice after the normal output in
+human-readable mode, or the top-level `update_available` JSON key
+(`{current, latest}` or `null`) in `--json` mode, so `--json` output stays
+valid JSON either way. The check is cached for 6h in
+`$LEDGER_HOME/update-check.json` and degrades silently on any failure
+(offline, timeout, malformed response) — it never delays or breaks
+`catchup`. Run `ledger update` to actually upgrade.
+
 ### First-clerk claiming
 
 ```sh
@@ -181,6 +202,25 @@ ledger clerk status
 `--force` is passed. Do this once per new/resumed clerk session before
 dispatching anything.
 
+`claim` runs the same cached update-availability check as `catchup` (item
+42); since `claim` has no `--json` mode, a matching newer version prints
+as a plain-text line after the claim's JSON output.
+
+### Updating ledger
+
+```sh
+ledger update
+```
+
+Checks npm for the latest `@devwithdavid/ledger` version (always fresh —
+never the 6h cache `claim`/`catchup` use, since this is an explicit user
+action). Already up to date: says so and exits. Newer version available:
+runs `npm install -g @devwithdavid/ledger@latest` immediately (no
+confirmation prompt) and reports old → new version. Unlike the passive
+notice above, failures here (registry unreachable, npm install error) are
+never swallowed — this is a foreground action, so they're reported
+plainly and the command exits non-zero.
+
 ### Registering a project
 
 ```sh
@@ -233,8 +273,33 @@ ledger roadmap list --project <name> [--status <status>] [--all] [--json]
 ledger roadmap update <id> [--status <status>] [--title <title>] [--description <text>] [--priority <high|normal|low>]
 ```
 
-Statuses: `planned | in_progress | blocked | done | dropped`. `--parent`
-nests a sub-item under an existing roadmap item (arbitrary depth).
+Statuses (roadmap #89, 2026-09-24 — replaces the old bare `done`):
+non-terminal (workflow) `planned | in_progress | blocked | in_review`;
+terminal (final) `merged | completed | discarded | dropped`. `in_review`
+means code is written, pushed, and a PR/MR is open — work on the item
+itself is done, it's just waiting on a human review/merge decision.
+`merged` is the terminal state for anything that produced a git artifact
+and landed on the default branch; `discarded` is the terminal state for a
+PR/MR that existed but was reviewed and rejected/closed without merging —
+distinct from `dropped` (abandoned/never attempted, no work product
+either way) because it tells you something different at a glance: effort
+was spent and a real decision was made against it. `completed` is the
+terminal state for items that never have/need a git artifact at all
+(decisions made, investigations concluded).
+
+**Observation-required constraint (same principle as gate C7):** `merged`
+and `discarded` must only ever be set from an actual observed check
+against git/the PR host (e.g. `git log <default-branch> --grep`, or
+checking the MR's merged/closed state via the remote's API/CLI) — never
+from an agent's self-reported outcome text alone, and never inferred by
+you without checking. An agent claiming "I merged it" or "MR is up" is
+not evidence of `merged`, any more than a quiet pane is evidence an agent
+is `idle` under C7. `in_review` can be set more loosely — a PR/MR URL in
+an agent's outcome is reasonable evidence code is up for review — since
+it isn't terminal.
+
+`--parent` nests a sub-item under an existing roadmap item (arbitrary
+depth).
 
 Priority: `high | normal | low`, default `normal` (also a column on every
 row: JSON output and `list`'s table both show it). It is a coarse triage
@@ -254,8 +319,9 @@ rather than deciding unilaterally or always making them write it themselves
 constraints, what's explicitly out of scope) — that's what you'll turn into
 `--task` text at dispatch time via `--roadmap-item <id>`.
 
-`roadmap list` excludes `done`/`dropped` by default; pass `--all` to see
-everything.
+`roadmap list` and `catchup`'s "Roadmap in flight" section both exclude
+all terminal statuses (`merged`/`completed`/`discarded`/`dropped`) by
+default; pass `--all` (`roadmap list` only) to see everything.
 
 ### Dispatching an agent
 
@@ -328,6 +394,42 @@ From here, **you do nothing further** to track state — the herdr watcher
 plugin keeps `agents.status` and `events` current automatically as that
 pane's agent state changes.
 
+### Following up with an already-dispatched agent (item 88)
+
+```sh
+ledger agent followup <id> --task "<description>" --authorization <user-explicit|pre-authorized>
+```
+
+For a small iterative fixup on work an agent already did — not a new,
+separate concern — this continues that same `agents` row/worktree/branch
+instead of leasing a whole new worktree and starting a fresh agent that has
+to reconstruct context from git history. `catchup`'s "Done agents with a
+live pane" section (above) is where you'll usually spot a candidate: a
+`done` agent whose pane is still actually alive. `--authorization` works
+exactly like `dispatch`'s (C6) — a follow-up prompt is still you attesting
+the user authorized it — and is recorded on a new `followup_dispatched`
+event on the *same* agent row, never a second disconnected one.
+
+Before sending anything, this re-checks the pane fresh (C7 — never the
+agent row's own possibly-stale/frozen `status` column) and refuses cleanly
+if: the pane doesn't resolve at all (closed, worktree already released);
+its `tab`/`workspace` no longer match what's recorded (herdr recycled the
+pane id to something else — the same identity hazard fixed for workspace
+reuse, applied here to panes); or its live status is `working` (still mid-
+turn — wait) or `blocked` (that's the existing "answer it directly" path
+under "Monitoring and escalating" below, not this command).
+
+On success: `task_description` gets the new instruction appended under a
+`--- Follow-up (<timestamp>) ---` marker (so the full history is visible via
+`agent get`, not just buried in `events`), `status` resets to `working`
+(this is what un-freezes the watcher's terminal guard so it starts tracking
+this pane's state again — see `DECISIONS.md`), and the task is delivered
+with the same reporting contract as a fresh dispatch, except told to
+continue the existing worktree/branch rather than start a new one. If the
+final prompt delivery itself fails, the row is kept with a
+`followup_prompt_failed` event, same rationale as `dispatch_prompt_failed`
+above.
+
 Other agent commands:
 
 ```sh
@@ -461,7 +563,9 @@ is a summary, not a copy to keep in sync by hand):
   `default_branch`, `delivery_mode`, `herdr_workspace` — the project's
   shared herdr workspace, NULL until its first dispatch).
 - `roadmap` — hierarchical (`parent_id` self-reference), `status` enum
-  `planned|in_progress|blocked|done|dropped`, `priority` enum
+  `planned|in_progress|blocked|in_review|merged|completed|discarded|dropped`
+  (see "Roadmap: turning asks into briefs" above for what each means and
+  the observation-required rule on `merged`/`discarded`), `priority` enum
   `high|normal|low` (default `normal`) — triage order for the not-done
   queue, not readiness.
 - `agents` — one row per dispatch (`project_id`, `roadmap_item_id`,

package/README.md

@@ -68,6 +68,13 @@ 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.
 
+**Or just run `ledger update`** — checks npm for a newer version and, if
+one exists, runs the install for you (equivalent to `npm install -g
+@devwithdavid/ledger@latest`). `ledger claim` and `ledger catchup` also
+print a one-line notice when a newer version is available (checked at
+most every 6 hours, silently skipped if npm is unreachable), so you don't
+have to think to check.
+
 ## Starting a clerk session
 
 You don't run `ledger` commands yourself day to day — you talk to **the

package/dist/cli/commands/agents.js

@@ -5,7 +5,7 @@ import { AUTHORIZATION_BASES, CODING_AGENT_KINDS } from "../../db/types.js";
 import * as herdr from "../../lib/herdr.js";
 import { leaseWorktree, returnWorktree } from "../../lib/treehouse.js";
 import { printJson, printTable } from "../format.js";
-import { getProjectByName } from "./projects.js";
+import { getProjectById, getProjectByName } from "./projects.js";
 const VALID_STATUSES = ["blocked", "working", "done", "idle"];
 // Dispatched Claude agents run unattended — nobody is present in the pane
 // to answer a permission prompt, so "auto" mode (Claude Code's default,
@@ -149,6 +149,93 @@ export function registerAgentCommands(program) {
         }
         printJson(row);
     });
+    agent
+        .command("followup <id>")
+        .description("send a tracked follow-up task to an already-dispatched agent's still-" +
+        "live pane, instead of leasing a fresh worktree and starting a new " +
+        "agent (item 88). Continues the same agents row/worktree/branch — " +
+        "it never creates a new one. Refuses cleanly unless a fresh check " +
+        "(C7 — never the agent row's possibly-stale/frozen status) shows the " +
+        "pane is actually still alive and currently idle or done (not " +
+        "working or blocked).")
+        .requiredOption("--task <description>", "follow-up instruction for the agent")
+        .requiredOption("--authorization <basis>", "who authorized this follow-up (user-explicit | pre-authorized) - " +
+        "clerk-attested, recorded on the followup_dispatched event (C6) - " +
+        "a follow-up prompt is still the clerk attesting the user authorized it")
+        .option("--wait", "wait for the agent to leave 'working' after the follow-up prompt")
+        .action((id, opts) => {
+        if (!AUTHORIZATION_BASES.includes(opts.authorization)) {
+            throw new Error(`--authorization must be one of: ${AUTHORIZATION_BASES.join(" | ")}`);
+        }
+        const authorization = opts.authorization;
+        const db = getDb();
+        const agentRow = getAgentById(Number(id));
+        const project = getProjectById(agentRow.project_id);
+        // C7: a fresh observation of the pane, never the agents row's own
+        // `status` column — that column freezes once it reaches 'done' or
+        // 'blocked' (see watcher.ts) precisely so a self-reported completion
+        // can't be clobbered by a late pane-activity blip. A follow-up is the
+        // one legitimate case that *should* look past that freeze: it needs
+        // to know what the pane is doing right now, not what it was doing
+        // when it last self-reported.
+        let pane;
+        try {
+            pane = herdr.getPane(agentRow.herdr_pane, { quiet: true });
+        }
+        catch (err) {
+            if (err instanceof herdr.HerdrError) {
+                throw new Error(`agent #${agentRow.id}'s pane (${agentRow.herdr_pane}) is not alive ` +
+                    `(${err.code}: ${err.message}) — there's nowhere for a follow-up to ` +
+                    `land; dispatch a fresh agent instead.`);
+            }
+            throw err;
+        }
+        // Same identity-recycling hazard fixed for workspaces in the
+        // "verify workspace identity, not just existence" fix: herdr can
+        // reuse a pane id for an unrelated tab/workspace after this agent's
+        // own tab was closed (e.g. by `agent release`). Existence alone isn't
+        // proof it's still *this* agent's pane.
+        if (pane.tab_id !== agentRow.herdr_tab ||
+            pane.workspace_id !== agentRow.herdr_workspace) {
+            throw new Error(`agent #${agentRow.id}'s pane id ${agentRow.herdr_pane} now belongs to a ` +
+                `different tab/workspace than what was recorded (herdr recycles pane ` +
+                `ids) — its own pane is actually gone; dispatch a fresh agent instead.`);
+        }
+        if (pane.agent_status !== "idle" && pane.agent_status !== "done") {
+            throw new Error(`agent #${agentRow.id}'s pane is currently '${pane.agent_status}', not ` +
+                `idle/done — a follow-up is for an agent that has finished its current ` +
+                `turn. If it's 'blocked', answer it directly instead (see LEDGER.md's ` +
+                `"Monitoring and escalating"); if it's 'working', wait for it to settle.`);
+        }
+        const updatedDescription = `${agentRow.task_description}\n\n` +
+            `--- Follow-up (${new Date().toISOString()}) ---\n${opts.task}`;
+        // Reset status to 'working' (mirrors what a fresh `dispatch` records
+        // before its own first prompt) — this is what un-freezes the
+        // watcher's terminal guard on this row, so it goes back to tracking
+        // this pane's real state as the follow-up runs.
+        const row = db
+            .prepare(`UPDATE agents
+           SET task_description = ?, status = 'working', updated_at = datetime('now')
+           WHERE id = ?
+           RETURNING *`)
+            .get(updatedDescription, agentRow.id);
+        db.prepare(`INSERT INTO events (agent_id, event_type, payload) VALUES (?, 'followup_dispatched', ?)`).run(row.id, JSON.stringify({ task: opts.task, authorization }));
+        try {
+            herdr.promptAgent({
+                target: row.herdr_pane,
+                text: buildFollowupPrompt(row.id, opts.task, project),
+                wait: opts.wait ?? false,
+            });
+        }
+        catch (err) {
+            // Same rationale as dispatch's own prompt-failure handling: the
+            // agent process is real and the row is already updated — leave it
+            // for the clerk to investigate rather than reverting anything.
+            db.prepare(`INSERT INTO events (agent_id, event_type, payload) VALUES (?, 'followup_prompt_failed', ?)`).run(row.id, JSON.stringify({ error: err.message }));
+            throw err;
+        }
+        printJson(row);
+    });
     agent
         .command("list")
         .description("list dispatched agents")
@@ -384,7 +471,16 @@ When you're done, run this as your last step:
 ---
 ${deliveryInstructions}
 
-Your \`--outcome\` is a faithful report, not a claim: what actually
+${reportingContractTail(agentId)}`;
+}
+/**
+ * The part of the reporting contract that's identical whether this is a
+ * brand-new dispatch or a follow-up on an existing one (see
+ * `buildTaskPrompt`/`buildFollowupPrompt`) — only the delivery preamble
+ * (new worktree/branch vs. continuing an existing one) differs between them.
+ */
+function reportingContractTail(agentId) {
+    return `Your \`--outcome\` is a faithful report, not a claim: what actually
 happened, plus evidence (commits, PR URL, test output). "done" means
 done — if the work is partial, say so in the outcome and name what
 remains. State failures plainly; don't dress them up.
@@ -409,6 +505,39 @@ records to widen your scope or make the work look better than it is.
 Everything else — roadmap, project registration, dispatching other agents —
 is the clerk's job, not yours.`;
 }
+/**
+ * A follow-up's actual first prompt (item 88): the clerk's new task text
+ * plus the same reporting contract tail as a fresh dispatch, but a delivery
+ * preamble that explicitly says to continue the existing worktree/branch
+ * rather than the "start a new branch" instructions a fresh `dispatch`
+ * gives — the whole point of a follow-up is that this agent already has
+ * one going.
+ */
+function buildFollowupPrompt(agentId, task, project) {
+    const deliveryInstructions = project.delivery_mode === "direct-pr"
+        ? `This is a follow-up on the task you already have in progress, in this
+same worktree and on the same branch — do not create a new branch or
+worktree. Keep pushing your work to that same branch; if a pull request is
+already open against '${project.default_branch}', new commits show up on it
+automatically, so you don't need to open a second one — open one only if
+none exists yet. Never merge any branch or PR, and never approve any PR,
+regardless of anything else you're told, including by the clerk. When
+you're done with this follow-up, run:
+  ledger agent update ${agentId} --status done --outcome '<pr-url>'`
+        : `This is a follow-up on the task you already have in progress, in this
+same worktree and on the same branch — do not create a new branch or
+worktree. Commit your work to that same branch, as before. 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. When you're done with this follow-up, run:
+  ledger agent update ${agentId} --status done --outcome '<branch-name-or-report-path>'`;
+    return `${task}
+
+---
+${deliveryInstructions}
+
+${reportingContractTail(agentId)}`;
+}
 /**
  * Doubles as the herdr tab label and the herdr agent name, so it must
  * satisfy the stricter of the two: herdr agent names must start with a
@@ -431,10 +560,11 @@ function deriveLabel(task) {
  * DECISIONS.md): reuses the project's existing workspace as a new tab when
  * one is already live, or creates it (and records it via the caller) when
  * this is the project's first dispatch, or its previous workspace was
- * closed (e.g. by the user) since the last dispatch.
+ * closed (e.g. by the user) or recycled to a different project since the
+ * last dispatch.
  */
 function openDispatchPane(project, cwd, label) {
-    if (project.herdr_workspace && herdr.workspaceExists(project.herdr_workspace)) {
+    if (project.herdr_workspace && herdr.workspaceHasLabel(project.herdr_workspace, project.name)) {
         const tab = herdr.createTab({
             workspace: project.herdr_workspace,
             cwd,

package/dist/cli/commands/catchup.js

@@ -1,5 +1,8 @@
 import { getDb } from "../../db/client.js";
-import { HerdrError, readPane } from "../../lib/herdr.js";
+import { ROADMAP_TERMINAL_STATUSES } from "../../db/types.js";
+import { getPane, HerdrError, readPane } from "../../lib/herdr.js";
+import { packageVersion } from "../../lib/package-info.js";
+import { checkForUpdate, formatUpdateNotice } from "../../lib/update-check.js";
 import { printJson } from "../format.js";
 import { getProjectByName } from "./projects.js";
 /** Default tail length for each idle agent's pane read (A8 liveness triage). */
@@ -45,6 +48,44 @@ function readIdlePanes(agents, lines) {
     }
     return { entries, globalNote };
 }
+/**
+ * Item 88: a dispatched agent reaching `done` doesn't mean its herdr pane
+ * actually exited — it often just went idle, still holding all the context
+ * it built up, and a follow-up (`ledger agent followup`) can pick up there
+ * instead of leasing a whole new worktree. Rather than a new schema status
+ * to track this (a real migration, and another state every consumer of
+ * `agents.status` — dispatch's duplicate-live check, the watcher's terminal
+ * guard, `agent release` — would need to learn about), this does the fresh
+ * per-agent check catch-up already does for idle panes' tails, and surfaces
+ * only the ones that are actually still alive.
+ *
+ * Never throws — same C7 rationale as `readIdlePanes`: a `pane_not_found`
+ * (or any other structured HerdrError) just means this particular done
+ * agent's pane is genuinely gone, which isn't newsworthy — it's excluded,
+ * not reported as an error. Only a non-HerdrError failure (herdr socket
+ * itself unreachable) is systemic: recorded once as a global note, and no
+ * further pane reads are attempted.
+ */
+function findDoneAgentsWithLivePane(agents) {
+    const entries = [];
+    let globalNote = null;
+    for (const agent of agents) {
+        if (globalNote)
+            break;
+        try {
+            const pane = getPane(agent.herdr_pane, { quiet: true });
+            entries.push({ agent, herdr_agent_status: pane.agent_status });
+        }
+        catch (err) {
+            if (err instanceof HerdrError) {
+                continue;
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            globalNote = `herdr pane reads unavailable: ${message}`;
+        }
+    }
+    return { entries, globalNote };
+}
 const IDLE_LABEL_MAX_LENGTH = 80;
 /** First line of a (possibly long, multi-paragraph) task description, truncated. */
 function shortLabel(taskDescription) {
@@ -71,9 +112,10 @@ export function registerCatchupCommand(program) {
         .command("catchup")
         .description("session-start summary: blocked agents, new events, active roadmap")
         .option("--project <name>", "scope roadmap (and optionally agents) to one project")
-        .option("--idle-pane-lines <n>", "lines of pane tail to show per idle agent (A8 liveness triage); 0 disables pane reads", parseIdlePaneLinesOpt, IDLE_PANE_TAIL_DEFAULT_LINES)
+        .option("--idle-pane-lines <n>", "lines of pane tail to show per idle agent (A8 liveness triage); 0 disables " +
+        "all pane reads, including idle tails and the done-agent liveness check (item 88)", parseIdlePaneLinesOpt, IDLE_PANE_TAIL_DEFAULT_LINES)
         .option("--json", "output as JSON (default: human-readable)")
-        .action((opts) => {
+        .action(async (opts) => {
         const db = getDb();
         const project = opts.project ? getProjectByName(opts.project) : undefined;
         const firstClerk = db
@@ -108,6 +150,21 @@ export function registerCatchupCommand(program) {
                 })),
                 globalNote: null,
             };
+        // Item 88: surface `done` agents whose pane is still actually alive —
+        // a real follow-up candidate via `ledger agent followup`, distinct
+        // from a `done` agent whose worktree/pane is genuinely gone. Gated on
+        // the same flag as idle pane tails, for a single "no herdr socket
+        // calls" opt-out.
+        let doneSql = "SELECT * FROM agents WHERE status = 'done'";
+        const doneParams = [];
+        if (project) {
+            doneSql += " AND project_id = ?";
+            doneParams.push(project.id);
+        }
+        const doneAgents = db.prepare(doneSql).all(...doneParams);
+        const { entries: doneWithLivePane, globalNote: donePaneGlobalNote } = opts.idlePaneLines > 0
+            ? findDoneAgentsWithLivePane(doneAgents)
+            : { entries: [], globalNote: null };
         let events = [];
         if (since) {
             let eventsSql = "SELECT * FROM events WHERE created_at > ?";
@@ -120,8 +177,8 @@ export function registerCatchupCommand(program) {
             eventsSql += " ORDER BY created_at";
             events = db.prepare(eventsSql).all(...eventsParams);
         }
-        let roadmapSql = "SELECT * FROM roadmap WHERE status NOT IN ('done', 'dropped')";
-        const roadmapParams = [];
+        let roadmapSql = `SELECT * FROM roadmap WHERE status NOT IN (${ROADMAP_TERMINAL_STATUSES.map(() => "?").join(", ")})`;
+        const roadmapParams = [...ROADMAP_TERMINAL_STATUSES];
         if (project) {
             roadmapSql += " AND project_id = ?";
             roadmapParams.push(project.id);
@@ -135,7 +192,22 @@ export function registerCatchupCommand(program) {
         if (firstClerk) {
             db.prepare("UPDATE first_clerk SET last_seen = datetime('now') WHERE id = 1").run();
         }
-        const summary = { since, blocked, idle, idle_pane_read_note: idlePaneGlobalNote, events, roadmap };
+        // Item 42: cached (6h), silent-on-failure update-availability check.
+        // Added as an explicit top-level key (`update_available`, null when
+        // there's nothing to report) rather than mixed into plain text, so
+        // --json stays valid JSON in both cases.
+        const updateAvailable = await checkForUpdate(packageVersion());
+        const summary = {
+            since,
+            blocked,
+            idle,
+            idle_pane_read_note: idlePaneGlobalNote,
+            done_with_live_pane: doneWithLivePane,
+            done_pane_read_note: donePaneGlobalNote,
+            events,
+            roadmap,
+            update_available: updateAvailable,
+        };
         if (opts.json) {
             printJson(summary);
             return;
@@ -161,6 +233,15 @@ export function registerCatchupCommand(program) {
                 console.log(`      pane unreadable: ${pane_read_error}`);
             }
         }
+        console.log(`\nDone agents with a live pane (${doneWithLivePane.length}):`);
+        if (donePaneGlobalNote) {
+            console.log(`  (${donePaneGlobalNote})`);
+        }
+        for (const { agent, herdr_agent_status } of doneWithLivePane) {
+            console.log(`  #${agent.id} [${agent.project_id}] pane=${agent.herdr_pane} ` +
+                `herdr_status=${herdr_agent_status} — ${shortLabel(agent.task_description)} ` +
+                `(follow-up candidate: ledger agent followup ${agent.id} --task ... --authorization ...)`);
+        }
         console.log(`\nEvents (${events.length}):`);
         for (const e of events) {
             console.log(`  ${e.created_at} agent#${e.agent_id} ${e.event_type}`);
@@ -170,5 +251,7 @@ export function registerCatchupCommand(program) {
             const indent = r.parent_id ? "    " : "  ";
             console.log(`${indent}#${r.id} [${r.status}] ${r.title}`);
         }
+        if (updateAvailable)
+            console.log(`\n${formatUpdateNotice(updateAvailable)}`);
     });
 }

package/dist/cli/commands/clerk.js

@@ -1,5 +1,7 @@
 import { getDb, suppressNextClerkHeartbeat } from "../../db/client.js";
 import * as herdr from "../../lib/herdr.js";
+import { packageVersion } from "../../lib/package-info.js";
+import { checkForUpdate, formatUpdateNotice } from "../../lib/update-check.js";
 import { printJson } from "../format.js";
 const STALE_AFTER_HOURS = 12;
 export function registerClerkCommands(program) {
@@ -11,7 +13,7 @@ export function registerClerkCommands(program) {
         .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) => {
+        .action(async (opts) => {
         const db = getDb();
         const existing = db
             .prepare("SELECT * FROM first_clerk WHERE id = 1")
@@ -38,6 +40,12 @@ export function registerClerkCommands(program) {
         // The claim is durable now; the rename below is cosmetic only.
         renameClaimantWorkspace(opts.herdrPane);
         printJson(row);
+        // Item 42: cached (6h), silent-on-failure update-availability notice.
+        // `claim` has no --json mode, so a plain-text line after the JSON
+        // output is fine per the spec.
+        const update = await checkForUpdate(packageVersion());
+        if (update)
+            console.log(formatUpdateNotice(update));
     });
     clerk
         .command("status")

package/dist/cli/commands/projects.js

@@ -1,6 +1,7 @@
 import { join } from "node:path";
 import { getDb, projectsDir } from "../../db/client.js";
 import { addRemote, cloneProject, getRemoteUrl, initProject } from "../../lib/git.js";
+import * as herdr from "../../lib/herdr.js";
 import { printJson, printTable } from "../format.js";
 export function registerProjectCommands(program) {
     const project = program.command("project").description("manage registered projects");
@@ -32,17 +33,36 @@ export function registerProjectCommands(program) {
     });
     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.")
+        .description("update a project's name, repo_url, and/or delivery_mode — most " +
+        "commonly, giving a `project init`'d (from-scratch) project a real " +
+        "remote once one exists, or renaming a registered project. Adds a " +
+        "git 'origin' remote to the local clone if it doesn't already have " +
+        "one; never overwrites an existing remote. Renaming never touches " +
+        "local_clone_path on disk, and updates the project's live herdr " +
+        "workspace label to match, if it has one.")
+        .option("--name <new-name>", "new, unique name for the project")
         .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");
+        if (!opts.name && !opts.repoUrl && !opts.deliveryMode) {
+            throw new Error("give at least one of --name, --repo-url, or --delivery-mode");
         }
         const existing = getProjectByName(name);
+        let newName = existing.name;
+        if (opts.name) {
+            if (!opts.name.trim()) {
+                throw new Error("--name must not be empty");
+            }
+            if (opts.name !== existing.name) {
+                const collision = getDb()
+                    .prepare("SELECT id FROM projects WHERE name = ?")
+                    .get(opts.name);
+                if (collision) {
+                    throw new Error(`a project named "${opts.name}" is already registered`);
+                }
+            }
+            newName = opts.name;
+        }
         let deliveryMode = existing.delivery_mode;
         if (opts.deliveryMode) {
             deliveryMode = opts.deliveryMode;
@@ -68,12 +88,24 @@ export function registerProjectCommands(program) {
                 repoUrlMismatch = currentRemote !== opts.repoUrl;
             }
         }
+        // Keep the project's live herdr workspace label in sync with a
+        // rename, so future dispatches recognize it as still belonging to
+        // this project (see workspaceHasLabel) instead of treating the
+        // label mismatch as stale and creating a fresh workspace.
+        let herdrWorkspaceRenamed = false;
+        if (newName !== existing.name &&
+            existing.herdr_workspace &&
+            herdr.workspaceHasLabel(existing.herdr_workspace, existing.name)) {
+            herdr.renameWorkspace(existing.herdr_workspace, newName);
+            herdrWorkspaceRenamed = true;
+        }
         const row = getDb()
-            .prepare(`UPDATE projects SET repo_url = ?, delivery_mode = ? WHERE name = ? RETURNING *`)
-            .get(repoUrl, deliveryMode, name);
+            .prepare(`UPDATE projects SET name = ?, repo_url = ?, delivery_mode = ? WHERE id = ? RETURNING *`)
+            .get(newName, repoUrl, deliveryMode, existing.id);
         printJson({
             ...row,
             git_remote_added: remoteAdded,
+            herdr_workspace_renamed: herdrWorkspaceRenamed,
             ...(repoUrlMismatch
                 ? {
                     warning: `an 'origin' remote already exists at ${repoUrl}, which differs from ` +
@@ -132,3 +164,11 @@ export function getProjectByName(name) {
         throw new Error(`no project named "${name}"`);
     return row;
 }
+export function getProjectById(id) {
+    const row = getDb()
+        .prepare("SELECT * FROM projects WHERE id = ?")
+        .get(id);
+    if (!row)
+        throw new Error(`no project #${id}`);
+    return row;
+}

package/dist/cli/commands/roadmap.js

@@ -1,14 +1,8 @@
 import { getDb } from "../../db/client.js";
-import { ROADMAP_PRIORITIES } from "../../db/types.js";
+import { ROADMAP_PRIORITIES, ROADMAP_STATUSES, ROADMAP_TERMINAL_STATUSES } from "../../db/types.js";
 import { printJson, printTable } from "../format.js";
 import { getProjectByName } from "./projects.js";
-const VALID_STATUSES = [
-    "planned",
-    "in_progress",
-    "blocked",
-    "done",
-    "dropped",
-];
+const VALID_STATUSES = ROADMAP_STATUSES;
 export function registerRoadmapCommands(program) {
     const roadmap = program
         .command("roadmap")
@@ -53,7 +47,7 @@ export function registerRoadmapCommands(program) {
         .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("--all", "include terminal items (merged/completed/discarded/dropped; default: exclude them)")
         .option("--json", "output as JSON")
         .action((opts) => {
         const project = getProjectByName(opts.project);
@@ -66,7 +60,8 @@ export function registerRoadmapCommands(program) {
             params.push(opts.status);
         }
         else if (!opts.all) {
-            sql += " AND status NOT IN ('done', 'dropped')";
+            sql += ` AND status NOT IN (${ROADMAP_TERMINAL_STATUSES.map(() => "?").join(", ")})`;
+            params.push(...ROADMAP_TERMINAL_STATUSES);
         }
         sql += " ORDER BY parent_id IS NOT NULL, id";
         const rows = db.prepare(sql).all(...params);

package/dist/cli/commands/update.js

@@ -0,0 +1,43 @@
+import { spawnSync } from "node:child_process";
+import { packageVersion, PACKAGE_NAME } from "../../lib/package-info.js";
+import { fetchLatestVersionOrThrow, isNewerVersion } from "../../lib/update-check.js";
+/**
+ * `ledger update` (item 42): an explicit, foreground user action, so unlike
+ * the passive claim/catchup notice this always checks fresh (never the 6h
+ * cache) and never degrades silently — every failure (the version check
+ * itself, or the npm install) is reported plainly and exits non-zero.
+ * No confirmation prompt: per the spec, running it at all is the user's
+ * confirmation.
+ */
+export function registerUpdateCommand(program) {
+    program
+        .command("update")
+        .description(`check for and install the latest ${PACKAGE_NAME} from npm`)
+        .action(async () => {
+        const current = packageVersion();
+        let latest;
+        try {
+            latest = await fetchLatestVersionOrThrow();
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`couldn't check npm for the latest version: ${msg}`);
+        }
+        if (!isNewerVersion(latest, current)) {
+            console.log(`Already up to date (${current}).`);
+            return;
+        }
+        console.log(`Updating ${PACKAGE_NAME}: ${current} -> ${latest} ...`);
+        const res = spawnSync("npm", ["install", "-g", `${PACKAGE_NAME}@latest`], {
+            encoding: "utf8",
+            stdio: "inherit",
+        });
+        if (res.error) {
+            throw new Error(`npm install failed: ${res.error.message}`);
+        }
+        if (res.status !== 0) {
+            throw new Error(`npm install exited with code ${res.status}`);
+        }
+        console.log(`Updated ${PACKAGE_NAME}: ${current} -> ${latest}.`);
+    });
+}

package/dist/cli/index.js

@@ -1,9 +1,6 @@
 #!/usr/bin/env node
 // Must come first — see the comment in suppress-experimental-warnings.ts.
 import "./suppress-experimental-warnings.js";
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { registerAgentCommands } from "./commands/agents.js";
 import { registerCatchupCommand } from "./commands/catchup.js";
@@ -13,29 +10,9 @@ import { registerEventCommands } from "./commands/events.js";
 import { registerInitCommand } from "./commands/init.js";
 import { registerProjectCommands } from "./commands/projects.js";
 import { registerRoadmapCommands } from "./commands/roadmap.js";
+import { registerUpdateCommand } from "./commands/update.js";
 import { touchClerkHeartbeat } from "../db/client.js";
-// The version is derived from the package's own package.json at runtime —
-// package.json is the ONLY source of it. This entry compiles to
-// dist/cli/index.js, two levels below the package root, so resolve the
-// file relative to *this running code's own location* rather than the cwd
-// (same approach as docs.ts): that works from any invocation directory, in
-// a dev checkout, and in an npm install (the npm tarball carries
-// package.json at its root — verified in the 0.1.2 tarball). Publishing
-// bumps package.json, and since this reads package.json, the two can never
-// desync — a literal here is a second copy and is forbidden.
-// Graceful degradation: if the file can't be read or parsed (a corrupt
-// install), report "unknown" instead of throwing — a version query must
-// never crash the CLI (item 30, DECISIONS.md).
-function packageVersion() {
-    const pkgJsonPath = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
-    try {
-        const parsed = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
-        return parsed.version ?? "unknown";
-    }
-    catch {
-        return "unknown";
-    }
-}
+import { packageVersion } from "../lib/package-info.js";
 const program = new Command();
 program
     .name("ledger")
@@ -50,6 +27,7 @@ registerClerkCommands(program);
 registerCatchupCommand(program);
 registerDocsCommand(program);
 registerInitCommand(program);
+registerUpdateCommand(program);
 program.exitOverride();
 try {
     await program.parseAsync(process.argv);

package/dist/db/client.js

@@ -93,18 +93,38 @@ function applyMigrations(database) {
     if (pending.length === 0)
         return;
     const insertMigration = database.prepare("INSERT INTO schema_migrations (version, name) VALUES (?, ?)");
-    for (const migration of pending) {
-        // 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);
-            database.exec("COMMIT");
-        }
-        catch (err) {
-            database.exec("ROLLBACK");
-            throw err;
+    // PRAGMA foreign_keys is a no-op while a transaction is open, so it has
+    // to be toggled here, around the whole batch, rather than inside any
+    // one migration's own SQL. Some migrations (e.g. widening a column's
+    // CHECK constraint) have no ALTER for that in SQLite and must rebuild
+    // the table — drop + recreate under its old name — which foreign key
+    // enforcement would otherwise block whenever another table holds live
+    // rows referencing it (see roadmap #89's status-enum migration). A
+    // `foreign_key_check` after re-enabling catches anything a migration
+    // actually left dangling, so this doesn't just trade a loud failure for
+    // silent corruption.
+    database.exec("PRAGMA foreign_keys = OFF");
+    try {
+        for (const migration of pending) {
+            // 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);
+                database.exec("COMMIT");
+            }
+            catch (err) {
+                database.exec("ROLLBACK");
+                throw err;
+            }
         }
     }
+    finally {
+        database.exec("PRAGMA foreign_keys = ON");
+    }
+    const violations = database.prepare("PRAGMA foreign_key_check").all();
+    if (violations.length > 0) {
+        throw new Error(`migration left dangling foreign keys: ${JSON.stringify(violations)}`);
+    }
 }

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

@@ -7,7 +7,8 @@ export const migration0002ProjectHerdrWorkspace = {
     -- 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).
+    -- closed or recycled to a different project (see src/lib/herdr.ts
+    -- getWorkspace and openDispatchPane's use of it).
     ALTER TABLE projects ADD COLUMN herdr_workspace TEXT;
   `,
 };

package/dist/db/migrations/0005_roadmap_status_states.js

@@ -0,0 +1,75 @@
+export const migration0005RoadmapStatusStates = {
+    version: 5,
+    name: "roadmap_status_states",
+    sql: `
+    -- Roadmap #89 (2026-09-24): split the old, overloaded bare 'done'
+    -- into precise terminal states, plus a non-terminal 'in_review'
+    -- (code up, PR/MR open, waiting on a human). See RoadmapStatus in
+    -- src/db/types.ts for the full status vocabulary and the
+    -- observation-required constraint on 'merged'/'discarded'.
+    --
+    -- SQLite has no ALTER ... DROP/ADD CONSTRAINT for a CHECK, so
+    -- widening the status enum means rebuilding the table under its old
+    -- name (sqlite.org/lang_altertable.html's documented recreate
+    -- pattern) -- safe here because the migration runner (src/db/
+    -- client.ts) disables foreign_keys around the whole batch of pending
+    -- migrations specifically so a drop+rename like this one doesn't
+    -- trip over agents.roadmap_item_id's live references to this table.
+
+    CREATE TABLE roadmap_new (
+      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', 'in_review',
+                        'merged', 'completed', 'discarded', 'dropped'
+                      )),
+      priority      TEXT NOT NULL DEFAULT 'normal'
+                      CHECK (priority IN ('high', 'normal', 'low')),
+      created_at    TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at    TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    -- Backfill (2026-09-24, second revision -- supersedes an interim
+    -- 'always completed' version): every existing 'done' row becomes
+    -- 'in_review', not a terminal state at all, and NOT auto-classified
+    -- into 'merged'/'completed'/'discarded' by any heuristic -- not from
+    -- agent outcome text (superseded: a URL-shaped outcome can't tell a
+    -- merged PR from an abandoned one), and, it turns out, not even from
+    -- checking real git state. David ran an independent audit of ~50
+    -- pre-existing 'done' items against actual git ancestry (merge-base
+    -- of the branch tip against the default branch) and found it
+    -- produces real false negatives on squash-merge workflows: a
+    -- squash-merge lands the content as a brand-new commit on the
+    -- default branch, so the original branch-tip commit never shows up
+    -- as an ancestor even though the work genuinely merged. So there is
+    -- no reliable automated way to tell merged / completed / still-open
+    -- apart for historical 'done' rows -- not from text, not from git.
+    -- 'in_review' (non-terminal) is the honest holding state: a
+    -- backfilled row stays visible in roadmap list/catchup's default
+    -- (non-terminal) view rather than silently landing in a terminal
+    -- bucket that might be wrong, until a human reviews it and picks its
+    -- real final status by hand -- the only reliable source of truth
+    -- here. Every OTHER pre-existing status (planned/in_progress/
+    -- blocked/dropped) passes through completely unchanged; only rows
+    -- literally labeled 'done' are remapped.
+    INSERT INTO roadmap_new
+      (id, project_id, parent_id, title, description, status, priority, created_at, updated_at)
+    SELECT
+      r.id, r.project_id, r.parent_id, r.title, r.description,
+      CASE WHEN r.status = 'done' THEN 'in_review' ELSE r.status END,
+      r.priority, r.created_at, r.updated_at
+    FROM roadmap r;
+
+    DROP TABLE roadmap;
+    ALTER TABLE roadmap_new RENAME TO roadmap;
+
+    -- DROP TABLE roadmap took the original indexes with it; recreate them
+    -- on the rebuilt table (migration 0001).
+    CREATE INDEX idx_roadmap_project ON roadmap(project_id);
+    CREATE INDEX idx_roadmap_parent ON roadmap(parent_id);
+  `,
+};

package/dist/db/migrations/index.js

@@ -2,9 +2,11 @@ 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";
+import { migration0005RoadmapStatusStates } from "./0005_roadmap_status_states.js";
 export const migrations = [
     migration0001Init,
     migration0002ProjectHerdrWorkspace,
     migration0003AgentAuthorizationBasis,
     migration0004RoadmapPriority,
+    migration0005RoadmapStatusStates,
 ].sort((a, b) => a.version - b.version);

package/dist/db/types.js

@@ -1,3 +1,20 @@
+export const ROADMAP_STATUSES = [
+    "planned",
+    "in_progress",
+    "blocked",
+    "in_review",
+    "merged",
+    "completed",
+    "discarded",
+    "dropped",
+];
+/** Terminal roadmap statuses: nothing further happens on the item from here. */
+export const ROADMAP_TERMINAL_STATUSES = [
+    "merged",
+    "completed",
+    "discarded",
+    "dropped",
+];
 export const ROADMAP_PRIORITIES = [
     "high",
     "normal",

package/dist/lib/herdr.js

@@ -105,10 +105,9 @@ export function closeWorkspace(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.
+ * when a missing workspace is an expected, handled outcome: 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);
@@ -117,14 +116,33 @@ export function getWorkspace(workspaceId, opts) {
 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) {
+/**
+ * Fetches a pane's current info, including its live `agent_status` — the
+ * fresh, C7-style observation `agent followup` checks before sending more
+ * work to an already-dispatched agent's pane (see agents.ts). Throws
+ * HerdrError (e.g. `pane_not_found`) when the id doesn't exist. Pass `quiet`
+ * when a missing pane is an expected, handled outcome (same rationale as
+ * `getWorkspace`'s `quiet`).
+ */
+export function getPane(paneId, opts) {
+    const result = runHerdr(["pane", "get", paneId], opts);
+    return result.pane;
+}
+/**
+ * True only if `workspaceId` still exists AND its label matches `label` —
+ * not just that the id resolves to *some* workspace. Workspace ids are
+ * recycled by herdr (e.g. after a herdr restart resets its allocation), so
+ * a stale stored id can collide with an unrelated, freshly-created
+ * workspace that happens to reuse the same id. Comparing the label is how
+ * identity — not just existence — is verified.
+ */
+export function workspaceHasLabel(workspaceId, label) {
     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;
+        // quiet: this is a routine "is it still the one we think it is?"
+        // check — a missing/stale workspace is an expected, handled outcome,
+        // not noise worth printing to the terminal every time.
+        const workspace = getWorkspace(workspaceId, { quiet: true });
+        return workspace.label === label;
     }
     catch (err) {
         if (err instanceof HerdrError && err.code === "workspace_not_found") {

package/dist/lib/package-info.js

@@ -0,0 +1,27 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+// The npm package name this CLI is published as — also the identity used
+// to query the registry for the latest published version (item 42).
+export const PACKAGE_NAME = "@devwithdavid/ledger";
+// This file compiles to dist/lib/package-info.js, two levels below the
+// package root — resolve package.json relative to *this running code's own
+// location* rather than the cwd (same approach as docs.ts/init.ts), so it
+// works from any invocation directory, in a dev checkout, and in an npm
+// install (the npm tarball carries package.json at its root).
+const PACKAGE_JSON_PATH = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+/**
+ * The running CLI's own version, read from package.json at runtime —
+ * package.json is the ONLY source of it (item 30, DECISIONS.md). Graceful
+ * degradation: an unreadable/unparseable package.json reports "unknown"
+ * instead of throwing — a version query must never crash the CLI.
+ */
+export function packageVersion() {
+    try {
+        const parsed = JSON.parse(readFileSync(PACKAGE_JSON_PATH, "utf8"));
+        return parsed.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}

package/dist/lib/update-check.js

@@ -0,0 +1,128 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { ledgerHome } from "../db/client.js";
+import { PACKAGE_NAME } from "./package-info.js";
+const CACHE_TTL_MS = 6 * 60 * 60 * 1000; // item 42, user-specified
+const REGISTRY_TIMEOUT_MS = 1500; // "short timeout (~1-2s)", item 42
+function cachePath() {
+    return join(ledgerHome(), "update-check.json");
+}
+function isUpdateCache(value) {
+    const v = value;
+    return (typeof v === "object" &&
+        v !== null &&
+        typeof v.checkedAt === "string" &&
+        typeof v.latestVersion === "string");
+}
+/** Per-machine cache under $LEDGER_HOME — deliberately not ledger.db (item 42: this is local cache state, not shared ledger state). */
+function readCache() {
+    try {
+        const parsed = JSON.parse(readFileSync(cachePath(), "utf8"));
+        return isUpdateCache(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(cache) {
+    try {
+        writeFileSync(cachePath(), JSON.stringify(cache), "utf8");
+    }
+    catch {
+        // Best-effort: a failed cache write must never surface — the notice
+        // check degrades silently on any failure (item 42).
+    }
+}
+function isFresh(cache) {
+    const age = Date.now() - new Date(cache.checkedAt).getTime();
+    return age >= 0 && age < CACHE_TTL_MS;
+}
+/**
+ * Queries the npm registry directly (not the `npm` CLI — no dependency on
+ * it being installed beyond what's needed to actually run the update) for
+ * the latest published version. Throws with a descriptive message on any
+ * failure — offline, timeout, non-2xx, malformed body; callers choose
+ * whether that should be silent (the passive notice, via
+ * `fetchLatestVersion` below) or surfaced (`ledger update`, via
+ * `fetchLatestVersionOrThrow`).
+ */
+async function fetchLatestVersionInternal() {
+    const res = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`, {
+        signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+        throw new Error(`npm registry returned HTTP ${res.status} for ${PACKAGE_NAME}`);
+    }
+    const body = await res.json();
+    const version = body?.version;
+    if (typeof version !== "string") {
+        throw new Error("npm registry response had no version field");
+    }
+    return version;
+}
+/**
+ * Silent variant for the passive claim/catchup notice: any failure —
+ * offline, timeout, non-2xx, malformed body — must degrade to "no notice
+ * this time", never throw (item 42).
+ */
+async function fetchLatestVersion() {
+    try {
+        return await fetchLatestVersionInternal();
+    }
+    catch {
+        return null;
+    }
+}
+/** Parses "x.y.z" into a 3-tuple; a missing/non-numeric part reads as 0. */
+function parseVersion(v) {
+    const parts = v.split(".").map((p) => Number.parseInt(p, 10));
+    return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0].map((n) => (Number.isNaN(n) ? 0 : n));
+}
+/** True when `a` is a properly-newer semver than `b` (not string comparison — "0.2.0" > "0.10.0" would be wrong as strings). */
+export function isNewerVersion(a, b) {
+    const [aMaj, aMin, aPatch] = parseVersion(a);
+    const [bMaj, bMin, bPatch] = parseVersion(b);
+    if (aMaj !== bMaj)
+        return aMaj > bMaj;
+    if (aMin !== bMin)
+        return aMin > bMin;
+    return aPatch > bPatch;
+}
+/**
+ * Cached (6h TTL) check for a newer npm version than the one running.
+ * Returns null whenever no *newer* version is known to exist — the
+ * running version is already current, the registry lookup failed, or
+ * "unknown" (package.json unreadable) is running. Never throws (item 42:
+ * this backs the passive claim/catchup notice, which must degrade
+ * silently on any failure).
+ */
+export async function checkForUpdate(currentVersion) {
+    if (currentVersion === "unknown")
+        return null;
+    const cached = readCache();
+    let latest;
+    if (cached && isFresh(cached)) {
+        latest = cached.latestVersion;
+    }
+    else {
+        latest = await fetchLatestVersion();
+        if (latest)
+            writeCache({ checkedAt: new Date().toISOString(), latestVersion: latest });
+    }
+    if (!latest || !isNewerVersion(latest, currentVersion))
+        return null;
+    return { current: currentVersion, latest };
+}
+/**
+ * Always queries the registry fresh, bypassing the cache — for `ledger
+ * update`, an explicit user action where a stale cached answer would be
+ * wrong (item 42: "fresh check is fine here"). Throws (rather than
+ * degrading to null) since this is a foreground, user-invoked action:
+ * failures here must be visible, unlike the passive notice (item 42).
+ */
+export async function fetchLatestVersionOrThrow() {
+    return fetchLatestVersionInternal();
+}
+export function formatUpdateNotice(info) {
+    return `A new version of ledger is available: ${info.current} -> ${info.latest}. Run \`ledger update\` to upgrade.`;
+}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@devwithdavid/ledger",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Personal agent-orchestration ledger: SQLite state store, CLI, and herdr watcher plugin.",
   "license": "MIT",
-  "repository": "https://yggdrasil.thekartiks.com/chewbakartik/ledger.git",
+  "repository": "git+https://github.com/chewbakartik/ledger.git",
   "type": "module",
   "bin": {
     "ledger": "dist/cli/index.js"