plumbbob 0.9.5 → 0.10.0

package/dist/verbs/checkpoint.js

@@ -1,18 +1,19 @@
-// `plumbbob checkpoint [<n>] [-m <msg>]` — the commit tick that lands a step.
+// `plumbbob checkpoint [<n>] [-m <msg>]`: the commit tick that lands a step.
 // Executor-agnostic and author-blind: it reads the diff, not who wrote it, so a
 // `/plumbbob:build` run, your own hands, a vibe session, or another harness all
 // checkpoint identically. It does NOT require a STEP marker (the flat control
 // file recording the step in flight): the step is whatever you pass, else the
 // in-flight STEP, else the next undone step in intent.md. It evaluates the
 // approval latch, gates on a green check, commits any pending work (or records
-// the existing HEAD when the tree is already clean — the human's commit skill
+// the existing HEAD when the tree is already clean: the human's commit skill
 // may have committed first), records the SHA, flips the intent checkbox to
-// `[x]`, and clears the STEP/SEAM markers — returning the dashboard to the
+// `[x]`, and clears the STEP/SEAM markers: returning the dashboard to the
 // DESIGN boundary.
 import { appendFileSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { commit, findRepoRoot, headSha, isDirty, stageAll, stagePath, stagedPaths, stagedStat } from "../lib/git.js";
 import { activeBuild, buildFolder, buildLogPath, buildScope, bumpStepStat, checkpointsPath, clearHandoff, clearTick, hasSession, intentPath, readStats, refreshExcludes, seamPath, stampStepStat, stepPath, } from "../lib/sidecar.js";
 import { runCheck } from "../lib/check.js";
+import { readCommitBody } from "../lib/commitbody.js";
 import { checkLatch } from "../lib/latch.js";
 import { markStepDone, parseSteps } from "../lib/orient.js";
 import { parseBuildScope, parseStepSeam, scopeDrift } from "../lib/intent.js";
@@ -22,7 +23,7 @@ import { AT_BOUNDARY, syncBuildLogState } from "../lib/buildlogsync.js";
 /**
  * Land a step: latch, check gate, commit, record, return to the boundary.
  *
- * Exit 1 on any refusal — no session, no resolvable step, a latched tick, or a
+ * Exit 1 on any refusal: no session, no resolvable step, a latched tick, or a
  * red/broken check; each refusal says what unblocks it.
  */
 export async function checkpoint(cwd, args) {
@@ -31,7 +32,7 @@ export async function checkpoint(cwd, args) {
         process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
         return 1;
     }
-    // Before either staging path — `-A` below, and the plan commit's folder-scoped
+    // Before either staging path: `-A` below, and the plan commit's folder-scoped
     // add, which also leans on the excludes to skip the in-flight markers inside
     // the build folder.
     refreshExcludes(root);
@@ -43,10 +44,18 @@ export async function checkpoint(cwd, args) {
         process.stderr.write('plumbbob: no step to checkpoint — pass a number, or plan a step in intent.md first.\n');
         return 1;
     }
-    // The approval latch runs before the check gate — cheap first. The tick may
+    // Checked before the latch and the check gate: a socket stdin can never
+    // deliver the requested body, so there is no point latching or running a
+    // ~55s check only to discover that afterward.
+    const bodyResult = readCommitBody(args);
+    if (!bodyResult.ok) {
+        process.stderr.write(bodyResult.message);
+        return 1;
+    }
+    // The approval latch runs before the check gate: cheap first. The tick may
     // not land without a human turn since the step was entered, a one-turn grant
     // the human typed, or a dormant ledger. A refusal is not an error: the
-    // message is the pause affordance — exit 1 and hand the turn back.
+    // message is the pause affordance: exit 1 and hand the turn back.
     const latch = checkLatch(root, step);
     if (!latch.allow) {
         process.stderr.write(latch.message);
@@ -69,7 +78,7 @@ export async function checkpoint(cwd, args) {
     if (isDirty(root)) {
         stageAll(root);
         warnScopeDrift(root, step);
-        const body = withMarker(`plumbbob step ${step}`, bodyArg(args) ?? fallbackBody(root, step));
+        const body = withMarker(`plumbbob step ${step}`, bodyResult.body ?? fallbackBody(root, step));
         sha = commit(root, messageArg(args) ?? subjectForStep(root, step), body);
     }
     else {
@@ -86,8 +95,8 @@ export async function checkpoint(cwd, args) {
     syncBuildLogState(root, activeBuild(root), AT_BOUNDARY);
     rmSync(seamPath(root), { force: true });
     rmSync(stepPath(root), { force: true });
-    clearHandoff(root); // the agent-run handoff ledger is step-scoped — clear it with the markers.
-    clearTick(root); // the step's entry stamp is spent — the next `build <n>` re-stamps.
+    clearHandoff(root); // the agent-run handoff ledger is step-scoped; clear it with the markers.
+    clearTick(root); // the step's entry stamp is spent; the next `build <n>` re-stamps.
     process.stdout.write(`plumbbob: step ${step} checkpointed — ${sha.slice(0, 9)}. Back at the boundary.\n`);
     return 0;
 }
@@ -97,33 +106,46 @@ export async function checkpoint(cwd, args) {
  *
  * Giving the plan its own commit keeps the first step's diff from absorbing the
  * scaffold, so `git log` reads baseline → plan → steps. No check gate (there is
- * no code work to verify yet), no intent flip, no step markers — the plan lives
+ * no code work to verify yet), no intent flip, no step markers: the plan lives
  * entirely in DESIGN. An optional `--body` (stdin heredoc) rides after the
  * `plumbbob plan` marker line; the folder is whitelisted artifact plane, so
  * there is no scope drift to warn about.
  */
 function checkpointPlan(root, args) {
     // The latch covers the plan commit too, keyed on the TICK that `start`
-    // stamped: the plan pause is a real pause. No step number — a step-range
+    // stamped: the plan pause is a real pause. No step number: a step-range
     // grant does not speak to a plan.
     const latch = checkLatch(root, null);
     if (!latch.allow) {
         process.stderr.write(latch.message);
         return 1;
     }
-    stagePath(root, buildFolder(root));
-    const sha = commit(root, planSubject(root), withMarker('plumbbob plan', bodyArg(args) ?? undefined));
+    const bodyResult = readCommitBody(args);
+    if (!bodyResult.ok) {
+        process.stderr.write(bodyResult.message);
+        return 1;
+    }
+    // A repo that gitignores the sidecar (its `.gitignore`, not plumbbob's own
+    // info/exclude) makes this folder-scoped add impossible; stagePath skips it
+    // and reports false, and the plan still lands as a valid record-only commit:
+    // its body carries the plan, the files stay untracked, and `--allow-empty`
+    // (in commit) makes the empty diff legal. History still reads baseline → plan
+    // → steps.
+    const staged = stagePath(root, buildFolder(root));
+    const sha = commit(root, planSubject(root), withMarker('plumbbob plan', bodyResult.body ?? undefined));
     appendFileSync(checkpointsPath(root), `plan ${sha}\n`);
     // Landing the plan consumes `start`'s entry stamp: a later hand-built diff
     // (no `build <n>`) must find no stale TICK and stay guidance-governed.
     clearTick(root);
-    process.stdout.write(`plumbbob: plan committed — ${sha.slice(0, 9)}. Baseline → plan → steps.\n`);
+    process.stdout.write(staged
+        ? `plumbbob: plan committed — ${sha.slice(0, 9)}. Baseline → plan → steps.\n`
+        : `plumbbob: plan committed (record-only — sidecar is gitignored; the plan rides the commit message, the files stay untracked) — ${sha.slice(0, 9)}. Baseline → plan → steps.\n`);
     return 0;
 }
 /**
  * Compose the plan commit's CLI-owned subject: `chore(<scope>): plan`.
  *
- * The scope resolves through the build-default fallback chain — a bare
+ * The scope resolves through the build-default fallback chain: a bare
  * `chore: plan` when none resolves. The `plumbbob plan` identifier rides the
  * body marker line, never the subject.
  */
@@ -134,7 +156,7 @@ function planSubject(root) {
  * Resolve the step being checkpointed, or null when none can be determined.
  *
  * Explicit arg > in-flight STEP file > first undone step in intent.md. A `-m`
- * value is a message, never a step — `checkpoint -m "2"` must not read as
+ * value is a message, never a step: `checkpoint -m "2"` must not read as
  * step 2.
  */
 function resolveStep(root, args) {
@@ -154,10 +176,10 @@ function resolveStep(root, args) {
     }
 }
 /**
- * Warn — never refuse — when the staged tree reaches beyond the step's seam.
+ * Warn (never refuse) when the staged tree reaches beyond the step's seam.
  *
  * Guidance, not a gate: the checkpoint captures the drift and says so. The seam
- * (the step's edit grant — exact paths or `dir/` prefixes) comes from the
+ * (the step's edit grant: exact paths or `dir/` prefixes) comes from the
  * in-flight SEAM file when a build is live, else the step's declared seam in
  * intent.md. Plumbbob's own artifact plane is whitelisted inside `scopeDrift`,
  * so the `[x]` flip and build-log line this very checkpoint stages never read
@@ -177,7 +199,7 @@ function warnScopeDrift(root, step) {
  *
  * The normalized SEAM file `build` wrote is authoritative while a build is
  * live; fall back to the step's declared seam parsed from intent.md. Empty when
- * neither resolves — the caller then skips the drift warning rather than
+ * neither resolves: the caller then skips the drift warning rather than
  * flagging the whole tree.
  */
 function seamTokens(root, step) {
@@ -191,14 +213,14 @@ function seamTokens(root, step) {
         }
     }
     catch {
-        // no SEAM file — fall through to the declared seam.
+        // no SEAM file: fall through to the declared seam.
     }
     return seamForStep(root, step);
 }
 /**
  * Flip the step's checkbox in intent.md to `[x]`.
  *
- * Best-effort bookkeeping — the checkpoint SHA is the source of truth — but the
+ * Best-effort bookkeeping (the checkpoint SHA is the source of truth) but the
  * dashboard reads intent.md, so a swallowed failure here would make orientation
  * lie; the catch warns and asks for a hand flip instead.
  */
@@ -216,7 +238,7 @@ function flipIntent(root, step) {
  *
  * The build's history accrues at each checkpoint instead of being reconstructed
  * at finish; the step's title is lifted from intent.md when still present.
- * Best-effort: a missing or odd build-log never blocks a checkpoint — the
+ * Best-effort: a missing or odd build-log never blocks a checkpoint; the
  * `checkpoints` SHA is the source of truth.
  */
 function logCheckpoint(root, step, sha) {
@@ -236,7 +258,7 @@ function logCheckpoint(root, step, sha) {
 /**
  * The compact stats receipt riding the Log line, or null when nothing accrued.
  *
- * Only what happened is shown — a clean first-try step gets no suffix at all.
+ * Only what happened is shown: a clean first-try step gets no suffix at all.
  * Wall-clock needs both stamps: a hand-built step never ran `build <n>`, so it
  * has no startedAt.
  */
@@ -280,7 +302,7 @@ function subjectForStep(root, step) {
  * The build-default Conventional scope, or null for a bare subject.
  *
  * The `**Scope:**` header field in intent.md wins when authored and filled;
- * else the build slug with its date prefix stripped; else null — a build with
+ * else the build slug with its date prefix stripped; else null: a build with
  * neither field keeps producing bare subjects.
  */
 function buildDefaultScope(root) {
@@ -291,7 +313,7 @@ function buildDefaultScope(root) {
         }
     }
     catch {
-        // no intent.md yet — fall through to the slug rung.
+        // no intent.md yet: fall through to the slug rung.
     }
     return buildScope(activeBuild(root));
 }
@@ -313,27 +335,6 @@ function messageArg(args) {
     const i = args.indexOf('-m');
     return i !== -1 && i + 1 < args.length ? (args[i + 1] ?? null) : null;
 }
-/**
- * Read the `--body` commit body from stdin, or null when absent or empty.
- *
- * The stdin heredoc lets a skill compose proportional prose the CLI never
- * could; null either way hands over to the deterministic fallback body. Reading
- * fd 0 blocks until EOF, which the heredoc supplies; a read error (no stdin
- * attached) degrades to the fallback, and an interactive TTY — which would
- * never send EOF — skips the read instead of hanging.
- */
-function bodyArg(args) {
-    if (!args.includes('--body') || process.stdin.isTTY === true) {
-        return null;
-    }
-    try {
-        const raw = readFileSync(0, 'utf8').trimEnd();
-        return raw.length > 0 ? raw : null;
-    }
-    catch {
-        return null;
-    }
-}
 /**
  * The deterministic fallback commit body: the step's done-when, its seam, and
  * the staged diffstat.

package/dist/verbs/doctor.js

@@ -1,34 +1,34 @@
-// `plumbbob doctor` — the health report, five sections under one verb.
+// `plumbbob doctor`: the health report, five sections under one verb.
 //
 // 1. The global plugin link (read-only). After `plumbbob init`, plumbbob lives as a
 //    symlink at ~/.claude/skills/plumbbob pointing at the installed package; Claude
 //    Code loads it in place as a plugin (skills `/plumbbob:*`, the post-edit hook from
 //    hooks.json). doctor verifies the link resolves to a package carrying the manifest,
-//    the skills, and the hook — and names the fix for anything missing. The failure
+//    the skills, and the hook, and names the fix for anything missing. The failure
 //    class it exists for is SILENT (a `/plumbbob:status` that opens an empty dashboard
 //    because the plugin never linked).
 //
 // 2. The repo sidecar layout. plumbbob keeps its per-repo state in a `.plumbbob/`
 //    sidecar: a tracked artifact plane (settings.json plus one `builds/<slug>/` folder
-//    per build — intent, build-log, checkpoints, report — that rides its branch into
+//    per build (intent, build-log, checkpoints, report) that rides its branch into
 //    the PR) and a git-excluded control plane of per-worktree files. A repo scaffolded
 //    by an older plumbbob carries the legacy FLAT sidecar instead (`.plumbbob/intent.md`,
 //    `config`, `archive/`), fully git-excluded, whose record dies with
 //    `git worktree remove`. doctor detects it and, with `--migrate`, moves it into the
 //    tracked `builds/<slug>/` layout: archive entries and the active session become
 //    build folders, `config` becomes `settings.json`, and the whole move is STAGED but
-//    never committed — the human owns that commit.
+//    never committed: the human owns that commit.
 //
 // 3. Agent validation. Every resolvable user-authored agent gets its manifest and its
 //    `command` statically checked, so a broken agent surfaces here rather than mid-build.
 //
 // 4. The check gate. When a `check` setting overrides checkride (the default heavy
 //    check), doctor names the command; otherwise it runs checkride's own doctor and
-//    prints the slot/adapter table — "detected but tool missing" is the footgun this
+//    prints the slot/adapter table: "detected but tool missing" is the footgun this
 //    exists for.
 //
 // 5. The approval latch. Reports whether the harness's turn ledger is live (checkpoint
-//    can latch on a recorded human turn) or dormant (guidance only) — dormant is a
+//    can latch on a recorded human turn) or dormant (guidance only): dormant is a
 //    state, never a failure.
 //
 // Functional, node builtins plus checkride.
@@ -44,7 +44,7 @@ import { findRepoRoot, gitPath, stagePath } from "../lib/git.js";
 import { buildDir, excludeControl, listBuilds, readTurn, setActiveBuild, sidecarDir, slugify } from "../lib/sidecar.js";
 import { resolveBoolean, resolveString, settingsPath } from "../lib/settings.js";
 /**
- * Resolve a directory shipped inside the plumbbob package (e.g. its skills/).
+ * Resolve a directory shipped inside the plumbbob package (for example its skills/).
  *
  * Resolved off this module's URL so it lands the same from src/ (dev) and
  * dist/ (published).
@@ -103,10 +103,10 @@ function buildChecks(link, pkg, shipped) {
 /**
  * The plugin-link diagnostic: how plumbbob is installed into Claude Code, as checks.
  *
- * Two install kinds are recognized: the marketplace plugin (one green line — skills
+ * Two install kinds are recognized: the marketplace plugin (one green line: skills
  * load and the CLI rides the plugin's bin/, nothing to verify piecemeal) and the
  * init-style link at ~/.claude/skills/plumbbob (verified piece by piece). Both at
- * once is a collision — two plugins named plumbbob fight over /plumbbob:* — reported
+ * once is a collision (two plugins named plumbbob fight over /plumbbob:*), reported
  * first, with the keep-one fix.
  */
 function pluginChecks() {
@@ -148,7 +148,7 @@ function subdirs(dir) {
  * Detect a legacy flat sidecar, or null when the repo is on the current layout
  * (or has no sidecar).
  *
- * `config` and `archive/` are unambiguous legacy markers — the builds/ layout has
+ * `config` and `archive/` are unambiguous legacy markers: the builds/ layout has
  * neither. A flat `intent.md` alone would also match today's `--local` layout, so it
  * only counts as legacy when the repo is NOT already migrated (no `builds/`, no
  * `settings.json`): that guard is what keeps `--local` untouched.
@@ -166,7 +166,7 @@ export function inspectLegacy(root) {
     return { config, archive, session };
 }
 /**
- * The first `# Heading` in a flat intent.md — the build title the slug derives from.
+ * The first `# Heading` in a flat intent.md: the build title the slug derives from.
  */
 function titleFromIntent(path) {
     try {
@@ -200,7 +200,7 @@ function configCheck(path) {
 /**
  * A slug not already claimed by `taken`, suffixing `-2`, `-3`, … only on collision.
  *
- * `start` refuses a colliding slug outright — the human picks a new title — but
+ * `start` refuses a colliding slug outright (the human picks a new title), but
  * migration is mechanically moving folders that already exist, so it disambiguates
  * rather than aborting mid-move.
  */
@@ -245,14 +245,14 @@ function narrowExcludes(root) {
         writeFileSync(exclude, kept.join('\n'));
     }
     catch {
-        /* no exclude yet — excludeControl creates it */
+        /* no exclude yet: excludeControl creates it */
     }
     excludeControl(root);
 }
 /**
  * Perform the migration and return a human-readable list of what moved.
  *
- * STAGES the result but never commits — the human owns that commit. Call only when
+ * STAGES the result but never commits: the human owns that commit. Call only when
  * `inspectLegacy` reported a legacy layout; doctor prints the returned actions.
  */
 export function migrateSidecar(root) {
@@ -263,7 +263,7 @@ export function migrateSidecar(root) {
     const configPath = join(dir, 'config');
     if (existsSync(configPath)) {
         if (!existsSync(settingsPath(root))) {
-            // Carry forward ONLY what the legacy config actually held — a `check` line,
+            // Carry forward ONLY what the legacy config actually held: a `check` line,
             // nothing else. No invented `auto` (the config never had one, it defaults to
             // false, and it belongs in settings.local.json): migration yields exactly what
             // a fresh `start` would, plus the check. An empty config → an empty `{}`.
@@ -336,7 +336,7 @@ function sidecarReport(cwd, migrate) {
 /**
  * Interpreters recognized as the program of a manifest `command`: when the command
  * is `sh <script>` / `node <script>` / …, the checkable artifact is the script
- * argument (the interpreter reads it — the file need not carry +x), not the
+ * argument (the interpreter reads it: the file need not carry +x), not the
  * interpreter, which we trust to be on PATH.
  */
 const INTERPRETERS = new Set(['sh', 'bash', 'zsh', 'dash', 'node', 'deno', 'bun', 'python', 'python3', 'ruby', 'perl']);
@@ -344,7 +344,7 @@ const INTERPRETERS = new Set(['sh', 'bash', 'zsh', 'dash', 'node', 'deno', 'bun'
  * Expand PLUMBBOB_AGENT_DIR in a command and split it into bare tokens
  * (surrounding quotes stripped).
  *
- * A deliberately shallow split — enough for the static command check below, not a
+ * A deliberately shallow split: enough for the static command check below, not a
  * shell parser (which is neither possible nor wanted for a best-effort diagnostic).
  */
 function commandTokens(command, agentDir) {
@@ -356,11 +356,11 @@ function commandTokens(command, agentDir) {
 }
 /**
  * Statically check a manifest `command` for the silent footguns: a script file that
- * does not exist, or a directly-invoked one missing its +x bit.
+ * does not exist, or a directly invoked one missing its +x bit.
  *
  * The command is a shell string spawned via `sh -c` with the repo root as cwd, so a
  * relative path resolves against `root` and PLUMBBOB_AGENT_DIR points at the agent's
- * own dir. Best-effort by design — a path-shaped program or an interpreter's script
+ * own dir. Best-effort by design: a path-shaped program or an interpreter's script
  * argument is checked; a bare command (a PATH binary, an inline `node -e` program)
  * is trusted, because we cannot prove a shell line broken without running it.
  * Returns the problem string, or null when nothing checkable is wrong.
@@ -443,7 +443,7 @@ function agentReport(cwd) {
  *
  * A configured `check` setting names the spawn override and asks nothing more;
  * otherwise checkride's own doctor reports the slot/adapter table. Only rows
- * checkride marks `required` count as problems — an empty slot ("no tool detected")
+ * checkride marks `required` count as problems; an empty slot ("no tool detected")
  * is informational, not a failure, because the runtime gate already refuses a
  * vacuous run.
  */
@@ -474,7 +474,7 @@ async function gateReport(cwd, env) {
                 failed += 1;
         }
         // Called out where the human can see it coming: no CODE checks detected means
-        // checkpoints would be gated only by checkride's always-on repo checks — either
+        // checkpoints would be gated only by checkride's always-on repo checks: either
         // a vacuous refusal or, worse, a green that tested nothing. Informational, with
         // the exact fix; `start` surfaces the same probe at plan time.
         if (!gateDetectsTools(report.checks)) {
@@ -490,7 +490,8 @@ async function gateReport(cwd, env) {
 }
 /**
  * One slot line: `✓ types ← tsc (6.0.3)`, `✗ dead ← fallow` with its install
- * hint, or `○ spell — no tool detected` for an empty (skipping) slot.
+ * hint, or `○ spell` joined by an em dash to "no tool detected" for an empty
+ * (skipping) slot.
  */
 function toolRow(c) {
     if (c.adapter === null || c.adapter === undefined) {
@@ -507,8 +508,8 @@ function toolRow(c) {
  * The latch is `checkpoint`'s refusal to land a step until the harness has recorded
  * a human turn since the step was entered. `.plumbbob/TURN` holds a count once the
  * UserPromptSubmit hook has ticked at least once, so a present count means the latch
- * is armed — its absence means the tick is guidance-only. Dormant is a legitimate
- * state (a host with no hooks simply has no ledger), never a failure — so this
+ * is armed; its absence means the tick is guidance-only. Dormant is a legitimate
+ * state (a host with no hooks simply has no ledger), never a failure, so this
  * section adds nothing to the problem count. The dormant hint names the hook because
  * a missing ledger almost always means it never wired, and that hook rides in either
  * install kind (the marketplace plugin's hooks/hooks.json or an init-style link).
@@ -525,9 +526,9 @@ function latchReport(cwd) {
         : `  ✓ latch: live (turn ${turn})`;
     const lines = ['', 'plumbbob doctor — approval latch — D64 (approval-latch)', line];
     // The latch ignores a settings `auto`: a model can write that file, and a grant
-    // the model can forge is no grant — self-approval comes only from the human's
+    // the model can forge is no grant: self-approval comes only from the human's
     // typed `/build --auto`. Surface a set value so a human relying on it isn't
-    // silently changed — informational, never a problem.
+    // silently changed: informational, never a problem.
     if (resolveBoolean(root, 'auto', false)) {
         lines.push('  ○ auto: set in settings but not a grant since D67 (auto-not-a-grant) — self-approve per run with `/plumbbob:build --auto`');
     }

package/dist/verbs/finish.js

@@ -1,9 +1,9 @@
-// `plumbbob finish` — the close-out. It appends the checkpoint SHAs and per-step
+// `plumbbob finish`: the close-out. It appends the checkpoint SHAs and per-step
 // stats to report.md, makes the final commit, and clears the control state (the
 // untracked session and step markers under `.plumbbob/`). The build folder is NOT
-// deleted — the tracked `.plumbbob/builds/<slug>/` folder IS the archive: it
+// deleted; the tracked `.plumbbob/builds/<slug>/` folder IS the archive: it
 // merges with the branch and shows up in the PR, so nothing is copied into a
-// separate local archive. A missing report never blocks the exit — guidance
+// separate local archive. A missing report never blocks the exit: guidance
 // offers the artifact, it does not wall the door. The git footprint stays
 // additive: one forward commit under the Conventional `chore(<scope>): finish`
 // subject, with the `plumbbob finish` identifier riding a marker line at the head
@@ -11,6 +11,7 @@
 import { appendFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { commit, findRepoRoot, isDirty, stageAll } from "../lib/git.js";
+import { readCommitBody } from "../lib/commitbody.js";
 import { buildScope, checkpointsPath, clearTick, hasSession, intentPath, readStats, refreshExcludes, reportPath, resolveBuild, seamPath, setGrant, sidecarDir, spikePath, stepPath, } from "../lib/sidecar.js";
 import { conventionalSubject, withMarker } from "../lib/commitmsg.js";
 import { parseBuildScope } from "../lib/intent.js";
@@ -19,7 +20,7 @@ import { parseBuildScope } from "../lib/intent.js";
  *
  * Requires an active session (the `.plumbbob/STATE` sentinel). When report.md
  * exists it gains a `## Checkpoints` SHA list and a `## Stats` table first; when
- * it doesn't, finish notes the absence and proceeds — the exit is never gated on
+ * it doesn't, finish notes the absence and proceeds; the exit is never gated on
  * a report.
  */
 export function finish(cwd, args = []) {
@@ -28,6 +29,15 @@ export function finish(cwd, args = []) {
         process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
         return 1;
     }
+    // Checked before any of finish's writes: appendCheckpointShas/appendStats
+    // are plain appends, not idempotent, so a refusal after they ran would
+    // duplicate those sections on retry. A socket stdin can never deliver the
+    // requested body, so there is nothing to do first.
+    const bodyResult = readCommitBody(args);
+    if (!bodyResult.ok) {
+        process.stderr.write(bodyResult.message);
+        return 1;
+    }
     const { build: slug } = resolveBuild(root, args);
     if (existsSync(reportPath(root, slug))) {
         appendCheckpointShas(root, slug);
@@ -37,9 +47,9 @@ export function finish(cwd, args = []) {
         process.stderr.write('plumbbob: note — no report.md found; finishing without one ' +
             '(/plumbbob:finish normally writes the report first). No gate — D9 (finish-no-gate).\n');
     }
-    // The final commit: stage the report just written plus the build folder's tail —
-    // a step's commit sweeps its own bookkeeping along with the work, so the last
-    // step's `checkpoints` line lands one commit late and finish absorbs it — and
+    // The final commit: stage the report just written plus the build folder's tail
+    // (a step's commit sweeps its own bookkeeping along with the work, so the last
+    // step's `checkpoints` line lands one commit late and finish absorbs it) and
     // commit under the `finish` subject. `--allow-empty` (via `commit`) still marks
     // the narrative endpoint when the tree is already clean, or under `--local`,
     // where the whole sidecar is git-excluded and there is nothing tracked to stage.
@@ -47,18 +57,18 @@ export function finish(cwd, args = []) {
     if (isDirty(root)) {
         stageAll(root);
     }
-    const sha = commit(root, subject(root, slug), withMarker('plumbbob finish', bodyArg(args) ?? undefined));
+    const sha = commit(root, subject(root, slug), withMarker('plumbbob finish', bodyResult.body ?? undefined));
     // Clear the control state: the in-flight markers first, then the session
     // sentinel last (so "no session" flips exactly at the end). Deleting STATE also
-    // drops the active-build cursor — cursor and session share that one file, so a
-    // single delete does both. The tracked artifacts stay in place — only the
+    // drops the active-build cursor: cursor and session share that one file, so a
+    // single delete does both. The tracked artifacts stay in place; only the
     // ephemera go.
     rmSync(seamPath(root, slug), { force: true });
     rmSync(stepPath(root, slug), { force: true });
     rmSync(spikePath(root, slug), { force: true });
     // The checkpoint latch's per-build entry stamp and the one-turn self-approval
     // grant go with the session: a grant lives one turn by construction, but only
-    // because every tick rewrites it — the session's last tick was the last rewrite,
+    // because every tick rewrites it: the session's last tick was the last rewrite,
     // so left behind, a stale `auto` could self-approve the next session's first
     // landing.
     clearTick(root, slug);
@@ -74,7 +84,7 @@ export function finish(cwd, args = []) {
  *
  * The scope resolves through the same build-default fallback chain as the plan
  * and step subjects: the intent.md `**Scope:**` header field, else the build
- * slug, else bare (e.g. `--local`). The `plumbbob finish` identifier rides the
+ * slug, else bare (for example `--local`). The `plumbbob finish` identifier rides the
  * body marker, not the subject.
  */
 function subject(root, slug) {
@@ -83,7 +93,7 @@ function subject(root, slug) {
 /**
  * Resolve the commit scope: the intent.md `**Scope:**` header, else the slug.
  *
- * Twin of checkpoint.ts's helper — same fallback chain, but with this verb's own
+ * Twin of checkpoint.ts's helper: same fallback chain, but with this verb's own
  * `slug` resolution instead of the active-build cursor.
  */
 function buildDefaultScope(root, slug) {
@@ -94,38 +104,15 @@ function buildDefaultScope(root, slug) {
         }
     }
     catch {
-        // no intent.md — fall through to the slug rung.
+        // no intent.md: fall through to the slug rung.
     }
     return buildScope(slug);
 }
-/**
- * Read the `--body` final-commit body from stdin, or null.
- *
- * The body arrives as a single-quoted stdin heredoc — the CLI owns every commit
- * subject, but the finish skill composes a proportional close-out body this
- * way. Returns null when the flag is absent or stdin is empty; the commit then
- * carries subject only. Reading fd 0 blocks until EOF, which the heredoc
- * supplies; a read error (no stdin attached) degrades to null, and an
- * interactive TTY — which would never send EOF — skips the read instead of
- * hanging (twin of checkpoint.ts's guard).
- */
-function bodyArg(args) {
-    if (!args.includes('--body') || process.stdin.isTTY === true) {
-        return null;
-    }
-    try {
-        const raw = readFileSync(0, 'utf8').trimEnd();
-        return raw.length > 0 ? raw : null;
-    }
-    catch {
-        return null;
-    }
-}
 /**
  * Roll the per-step receipts into report.md as a `## Stats` table.
  *
- * One row per step plus totals — red checks, drift warnings, reverts,
- * wall-clock — so "is the loop worth it?" is a table, not a feeling. Silently
+ * One row per step plus totals (red checks, drift warnings, reverts,
+ * wall-clock) so "is the loop worth it?" is a table, not a feeling. Silently
  * skipped when nothing accrued (a build with no red/revert/drift and no
  * `build <n>` stamps has nothing to say).
  */
@@ -173,7 +160,7 @@ function wallClockMs(s) {
 /**
  * Format a wall-clock duration for the stats table.
  *
- * `—` when unknown (a hand-built step never ran `build <n>`, so it has no
+ * An em dash when unknown (a hand-built step never ran `build <n>`, so it has no
  * startedAt), `<1m` under a minute, whole minutes otherwise.
  */
 function formatWall(ms) {

package/dist/verbs/handoff.js

@@ -1,8 +1,8 @@
-// `plumbbob handoff` — print the standardized build hand-off block: the
+// `plumbbob handoff`: print the standardized build hand-off block: the
 // "state / choice / what's next" the human sees at each step boundary. Read-only,
-// no state change. It derives the moment from the session — a step in flight ⇒ the
+// no state change. It derives the moment from the session: a step in flight ⇒ the
 // pause block (built → looks-good/needs-work → next), none ⇒ the post-checkpoint
-// boundary block — and renders the next undone step plus its advisory `- model:`
+// boundary block, and renders the next undone step plus its advisory `- model:`
 // recommendation straight from intent.md, the build's plan document. Owning the
 // block here, rather than as prose in the build skill, keeps the skill from
 // drifting out of sync with `status`, which renders the same next-step detail
@@ -75,7 +75,7 @@ function boundaryBlock(step, title, nextUp) {
  * The forward pointer, shared by both blocks: the next undone step, its title,
  * and its advisory `- model:` recommendation.
  *
- * The recommendation renders as just the model token for the `/model` call —
+ * The recommendation renders as just the model token for the `/model` call;
  * the full rationale lives on the `status` dashboard. No next step ⇒ the
  * finish/step nudge instead.
  */
@@ -101,8 +101,9 @@ function titleOf(steps, n) {
     return steps.find((s) => s.n === n)?.title ?? null;
 }
 /**
- * The model token from a `- model:` recommendation — the first word, so a
- * `model: opus — <rationale>` line yields `opus` for the `/model` call.
+ * The model token from a `- model:` recommendation: the first word, so a
+ * `model: opus` line followed by an em dash and rationale yields `opus` for
+ * the `/model` call.
  *
  * Null when there is no recommendation, or it degraded to whitespace (folding
  * the null model into the same guard keeps both branches live).
@@ -112,7 +113,7 @@ function modelToken(model) {
     return first !== undefined && first.length > 0 ? first : null;
 }
 /**
- * Read a file as UTF-8, or return '' when it is missing or unreadable — an
+ * Read a file as UTF-8, or return '' when it is missing or unreadable: an
  * absent sidecar file reads as empty rather than throwing.
  */
 function readOr(path) {
@@ -124,7 +125,7 @@ function readOr(path) {
     }
 }
 /**
- * The in-flight step number from the STEP marker — the flat one-line file in
+ * The in-flight step number from the STEP marker: the flat one-line file in
  * the build folder that records which step is open. Null when no step is in
  * flight or the file holds anything but a bare number.
  */