@devwithdavid/ledger 0.1.5 → 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,18 @@ 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
@@ -261,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
@@ -282,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
 
@@ -356,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
@@ -489,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/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
@@ -426,31 +555,6 @@ function deriveLabel(task) {
     const truncated = raw.slice(0, 32).replace(/-+$/g, "");
     return truncated || "task";
 }
-/**
- * True only if `workspaceId` still exists AND is still the workspace
- * belonging to `project` — 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.
- * Workspaces are created with `label: project.name` (see openDispatchPane
- * below), so comparing the label is how identity — not just existence — is
- * verified.
- */
-function workspaceBelongsToProject(workspaceId, project) {
-    try {
-        // quiet: this is a routine "is it still ours?" check, run on every
-        // dispatch — a missing/stale workspace is an expected, handled outcome,
-        // not noise worth printing to the terminal every time.
-        const workspace = herdr.getWorkspace(workspaceId, { quiet: true });
-        return workspace.label === project.name;
-    }
-    catch (err) {
-        if (err instanceof herdr.HerdrError && err.code === "workspace_not_found") {
-            return false;
-        }
-        throw err;
-    }
-}
 /**
  * One herdr workspace per project, not per dispatch (per the user — see
  * DECISIONS.md): reuses the project's existing workspace as a new tab when
@@ -460,7 +564,7 @@ function workspaceBelongsToProject(workspaceId, project) {
  * last dispatch.
  */
 function openDispatchPane(project, cwd, label) {
-    if (project.herdr_workspace && workspaceBelongsToProject(project.herdr_workspace, project)) {
+    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,6 @@
 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";
@@ -47,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) {
@@ -73,7 +112,8 @@ 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(async (opts) => {
         const db = getDb();
@@ -110,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 > ?";
@@ -122,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);
@@ -147,6 +202,8 @@ export function registerCatchupCommand(program) {
             blocked,
             idle,
             idle_pane_read_note: idlePaneGlobalNote,
+            done_with_live_pane: doneWithLivePane,
+            done_pane_read_note: donePaneGlobalNote,
             events,
             roadmap,
             update_available: updateAvailable,
@@ -176,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}`);

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/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/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

@@ -116,6 +116,41 @@ export function getWorkspace(workspaceId, opts) {
 export function renameWorkspace(workspaceId, label) {
     runHerdr(["workspace", "rename", workspaceId, label]);
 }
+/**
+ * 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 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") {
+            return false;
+        }
+        throw err;
+    }
+}
 /** Adds a new tab (with its own root pane) to an existing workspace at `cwd`. */
 export function createTab(opts) {
     const args = [

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@devwithdavid/ledger",
-  "version": "0.1.5",
+  "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"