plumbbob 0.9.5 → 0.10.1

package/dist/lib/agents.js

@@ -1,11 +1,11 @@
 // The agent contract. A user-authored agent is anything executable that speaks a
-// versioned JSON envelope — a JSON manifest on disk (`agent.json`), JSON on the
-// child's stdin, JSON on its stdout, prose on its stderr — so the doorway is
+// versioned JSON envelope (a JSON manifest on disk (`agent.json`), JSON on the
+// child's stdin, JSON on its stdout, prose on its stderr) so the doorway is
 // runtime-agnostic: any language, any framework, one subprocess boundary. This
 // module is the contract's validator, resolver, and runner: it type-narrows the
 // on-disk manifest and the output envelope a child returns (refusing a contract
 // major-version mismatch with an upgrade hint rather than guessing at a shape
-// that is only stable within a major — additions are a minor bump, removals or
+// that is only stable within a major: additions are a minor bump, removals or
 // renames a major), it walks the agent tiers to resolve an agent by name, it
 // composes the step context a child reads on stdin, and it spawns the child.
 // The validators are pure; the resolver reads `agent.json` files off disk with
@@ -28,7 +28,7 @@ export const CONTRACT_VERSION = 1;
  * The three lifecycle slots an agent may bind to: `before` (context in),
  * `build` (the diff), `after` (advisory review).
  *
- * Exactly these, never a fourth — "a salient point in the middle" is judgment
+ * Exactly these, never a fourth; "a salient point in the middle" is judgment
  * the host model handles in prose, not a declarative slot.
  */
 export const SLOTS = ['before', 'build', 'after'];
@@ -122,7 +122,7 @@ export function parseEnvelope(raw) {
  * True when a string names one of the three slots.
  *
  * Exported for the `agent run` verb's `--mode` refusal: a mode the manifest
- * doesn't declare is refused loud — the user who typed it asked for that slot
+ * doesn't declare is refused loud; the user who typed it asked for that slot
  * specifically.
  */
 export function isSlot(value) {
@@ -169,7 +169,7 @@ function parseSlots(value) {
 /**
  * Narrow the envelope's optional `parked[]` (absent = none).
  *
- * Present, it must be an array of non-blank strings — each becomes a park line
+ * Present, it must be an array of non-blank strings: each becomes a park line
  * the CLI lands through the park verb. A malformed list is refused rather than
  * silently dropped: losing a parked concern is a quiet data loss. Returns the
  * trimmed lines or an error string.
@@ -219,13 +219,13 @@ function envelopeFail(error) {
     return { ok: false, error };
 }
 /**
- * The project agents tier — `.plumbbob/agents/` under the repo root.
+ * The project agents tier: `.plumbbob/agents/` under the repo root.
  */
 export function projectAgentsDir(root) {
     return join(root, '.plumbbob', 'agents');
 }
 /**
- * The personal agents tier — `~/.plumbbob/agents/`, the user's own library.
+ * The personal agents tier: `~/.plumbbob/agents/`, the user's own library.
  */
 export function personalAgentsDir(home) {
     return join(home, '.plumbbob', 'agents');
@@ -246,7 +246,7 @@ function agentsHome(home) {
  * A `flagPath` (from `--agent <path>`) points straight at an agent directory
  * and takes top priority. A tier "hits" when it holds an `agent.json`: a
  * malformed one there is surfaced as an error (project still shadows
- * personal), never silently skipped in favor of a different agent — an
+ * personal), never silently skipped in favor of a different agent; an
  * explicit ask fails loud. Returns the not-found error only when no tier holds
  * a manifest at all.
  */
@@ -273,7 +273,7 @@ export function resolveAgent(root, name, opts = {}) {
 /**
  * Every resolvable agent across both tiers, sorted by name.
  *
- * Project shadows personal: a name defined in both resolves — and lists — from
+ * Project shadows personal: a name defined in both resolves (and lists) from
  * project. Each entry carries its origin and resolution; a malformed manifest
  * lands as an errored resolution rather than crashing the walk.
  */
@@ -325,7 +325,7 @@ export function formatAgentList(listings) {
  * Returns null when the directory holds no manifest (a tier miss, so
  * resolution falls through), an errored resolution when the manifest is
  * present but unreadable/malformed, else the resolved agent. A missing file
- * (ENOENT throw) is the miss signal — one read, no TOCTOU race.
+ * (ENOENT throw) is the miss signal: one read, no TOCTOU race.
  */
 function loadAgentDir(dir, origin) {
     const file = join(dir, 'agent.json');
@@ -367,10 +367,10 @@ function agentDirNames(dir) {
 /**
  * Compose the StepContext for one step.
  *
- * The strict seam parse is the only refusal path — a missing step or
+ * The strict seam parse is the only refusal path: a missing step or
  * unparseable seam gates git behavior, so it fails loud; everything else is
  * best-effort and lands whatever it can, returning `warnings` (skipped-bullet
- * lines) for the caller to print on stderr rather than writing there itself —
+ * lines) for the caller to print on stderr rather than writing there itself;
  * this module stays pure, the verb does the IO.
  */
 export function composeStepContext(params) {
@@ -410,7 +410,7 @@ function skipWarnings(heading, skipped) {
  * Validate a parsed harness.json.
  *
  * Contract first (a major mismatch gets the same upgrade hint as the manifest
- * and envelope). Structure is strict — a `steps` that is not an object, a
+ * and envelope). Structure is strict: a `steps` that is not an object, a
  * non-numeric step key, or a step entry that is not an object is the author's
  * error and is refused loud. Slot *contents* stay lenient: a slot value may be
  * one name or a list, and blanks/non-strings drop rather than refuse, because
@@ -445,9 +445,9 @@ function parseHarness(raw) {
 /**
  * Read and validate a harness.json at `path`.
  *
- * The caller builds the path from the build folder — this module stays
+ * The caller builds the path from the build folder; this module stays
  * ignorant of the sidecar layout, taking the full path. Returns null when the
- * file is absent (a build with no bound agents — a clean no-op); an errored
+ * file is absent (a build with no bound agents: a clean no-op); an errored
  * parse when present-but-broken (invalid JSON or a malformed structure the
  * author must fix); else the validated bindings. Shared so every reader
  * (`agent run`, `status`) parses the harness the same way.
@@ -474,7 +474,7 @@ export function readHarnessFile(path) {
  *
  * Accepts a harness `defaults` block, a per-step entry, or the settings-level
  * defaults. A slot value may be a single agent name or a list; blanks and
- * non-strings drop. Only the three real slots are read — `note` and any
+ * non-strings drop. Only the three real slots are read; `note` and any
  * stranger key are ignored here. A slot present but naming no valid agent
  * still counts as bound-to-nothing (an explicit override to none), so callers
  * get clean replace semantics up the ladder.
@@ -493,7 +493,7 @@ export function parseSlotBindings(raw) {
  * The agents bound to one slot for one step, merged down the bindings ladder.
  *
  * A per-step slot entry overrides the harness `defaults`, which override the
- * settings-level defaults — the first level that names the slot wins, replace
+ * settings-level defaults: the first level that names the slot wins, replace
  * not append, the same most-specific-wins shape as the settings ladder. The
  * `--agent` flag and an explicit name sit above all of this, but the verb
  * takes the single-agent path for those and never reaches here. Returns []
@@ -511,7 +511,7 @@ export function resolveSlotAgents(params) {
     return [];
 }
 /**
- * Coerce a slot value — one agent name or a list — to a trimmed name list,
+ * Coerce a slot value (one agent name or a list) to a trimmed name list,
  * dropping blanks and non-strings.
  */
 function asNameList(value) {
@@ -519,7 +519,7 @@ function asNameList(value) {
     return items.filter((v) => typeof v === 'string' && v.trim().length > 0).map((v) => v.trim());
 }
 /**
- * True when a value is a plain JSON object — not null, not an array.
+ * True when a value is a plain JSON object: not null, not an array.
  */
 function isObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -532,13 +532,13 @@ function isObject(value) {
  * directory rides in `PLUMBBOB_AGENT_DIR` so a root-cwd agent can still reach
  * its files. The composed StepContext is delivered as JSON on stdin. Stdout is
  * piped and captured (the envelope); stderr is inherited so the child's prose
- * streams live to the terminal — production (narrating) never collides with
+ * streams live to the terminal: production (narrating) never collides with
  * consumption (one structured result at the pause). A SIGINT while the child
- * runs kills it and reports `interrupted` rather than orphaning it — the human
+ * runs kills it and reports `interrupted` rather than orphaning it; the human
  * is present, Ctrl-C works. A positive `timeoutSeconds` arms a kill timer
  * (0 = off; a timeout is the user's explicit opt-in). Async `spawn`, not
  * `spawnSync`, so the parent stays live to interrupt gracefully. Never
- * rejects — every failure mode is a resolved `AgentRunResult`.
+ * rejects: every failure mode is a resolved `AgentRunResult`.
  */
 export function runAgent(params) {
     return new Promise((resolve) => {
@@ -576,7 +576,7 @@ export function runAgent(params) {
         child.stdout.on('data', (chunk) => {
             stdout += chunk.toString();
         });
-        // A shell that never launched (e.g. `sh` itself missing) — distinct from a
+        // A shell that never launched (for example `sh` itself missing): distinct from a
         // command that ran and exited non-zero, which arrives on `close`.
         child.on('error', (err) => {
             finish({ ok: false, reason: 'spawn', error: err.message });
@@ -599,9 +599,9 @@ export function runAgent(params) {
 /**
  * Parse the child's captured stdout into a validated envelope.
  *
- * JSON first (a non-JSON stdout is out of contract — the envelope must be one
+ * JSON first (a non-JSON stdout is out of contract: the envelope must be one
  * JSON object), then the envelope validator, which carries the
- * contract-mismatch hint. Kept private — `runAgent` is the only caller and the
+ * contract-mismatch hint. Kept private; `runAgent` is the only caller and the
  * verb reads the union, not this.
  */
 function parseChildEnvelope(stdout) {

package/dist/lib/buildlog.js

@@ -1,14 +1,14 @@
-// Mutations to the active build-log.md — the human-facing ledger inside the
+// Mutations to the active build-log.md: the human-facing ledger inside the
 // build's tracked `builds/<slug>/` folder. `park` appends to its Park list;
 // `checkpoint` appends to its Log so the build's history accrues line-by-line
 // *as it happens* rather than being reconstructed at finish. The `## Steps`
 // mirror and `**Current step:**` line are CLI-owned: `build`, `checkpoint`,
 // and `revert` re-render them from intent.md so the ledger's top half tracks
-// reality without a model turn. Pure string transforms — no fs, no classes;
+// reality without a model turn. Pure string transforms: no fs, no classes;
 // callers own the IO so these stay trivially testable.
 /**
- * Append `line` after the last non-blank line of the `## <heading>` section —
- * i.e. just before the next `## ` heading or EOF.
+ * Append `line` after the last non-blank line of the `## <heading>` section:
+ * that is, just before the next `## ` heading or EOF.
  *
  * Returns null when the section is absent so the caller can report rather than
  * silently corrupt the doc.
@@ -33,9 +33,9 @@ export function appendToSection(content, heading, line) {
     return lines.join('\n');
 }
 /**
- * Replace the `**Current step:**` line with `**Current step:** <label>` —
- * `build` sets it to `<n> — <title>` when a step opens; `checkpoint`/`revert`
- * reset it to `none (at the boundary)`.
+ * Replace the `**Current step:**` line with `**Current step:** <label>`:
+ * `build` sets it to the step's number and title joined by an em dash when a
+ * step opens; `checkpoint`/`revert` reset it to `none (at the boundary)`.
  *
  * Returns null when the line is absent so the caller skips rather than
  * corrupting the doc.
@@ -50,14 +50,14 @@ export function setCurrentStep(content, label) {
     return lines.join('\n');
 }
 /**
- * Regenerate the `## Steps` mirror from intent.md's parsed steps — one
+ * Regenerate the `## Steps` mirror from intent.md's parsed steps: one
  * `- ☑/☐ N. <title>` line each, in order.
  *
  * Only the mirror's own `- ☑/☐` list lines are owned; the italic instructions
  * paragraph (and any other prose) is preserved, and exactly one blank line
  * separates it from the list. Returns null when the section is absent so the
  * caller skips rather than corrupting the doc. With no steps the mirror
- * renders empty — the plan is not authored yet — rather than inventing a
+ * renders empty (the plan is not authored yet) rather than inventing a
  * placeholder.
  */
 export function syncStepsSection(content, steps) {
@@ -92,9 +92,9 @@ function isMirrorLine(line) {
  * The Log line `checkpoint` writes for a landed step: dated, names the step
  * (its title when intent.md still carries it), and carries the short SHA.
  *
- * One line of the build's history — `/plumbbob:finish` reads these instead of
+ * One line of the build's history: `/plumbbob:finish` reads these instead of
  * re-narrating the build. `stats` is the optional compact receipt of what the
- * step cost (e.g. `2 red, 34m`) — null when nothing accrued, so a clean
+ * step cost (for example `2 red, 34m`): null when nothing accrued, so a clean
  * first-try step reads as a bare line.
  */
 export function checkpointLogLine(date, step, sha, title, stats = null) {
@@ -102,3 +102,13 @@ export function checkpointLogLine(date, step, sha, title, stats = null) {
     const titled = title !== null && title.length > 0 ? `${head} — ${title}` : head;
     return stats !== null && stats.length > 0 ? `${titled} (${stats})` : titled;
 }
+/**
+ * The Log line `abandon` writes for a dropped-but-kept step: the first
+ * non-checkpoint event the log records. Dated, names the step (its title when
+ * intent.md still carries it), and states plainly that the work stayed in the
+ * tree, so the narrative never has a step go quiet mid-flight.
+ */
+export function abandonLogLine(date, step, title) {
+    const head = `- ${date} — step ${step} abandoned · work kept in tree`;
+    return title !== null && title.length > 0 ? `${head} — ${title}` : head;
+}

package/dist/lib/buildlogsync.js

@@ -1,22 +1,22 @@
-// Keep the build-log's top half — the `**Current step:**` line and the `## Steps`
-// mirror — in sync with intent.md, the build's plan document. The build-log is the
+// Keep the build-log's top half (the `**Current step:**` line and the `## Steps`
+// mirror) in sync with intent.md, the build's plan document. The build-log is the
 // human-facing ledger in the build's tracked `builds/<slug>/` folder; its top half
 // is CLI-owned so it never lies: `build` sets the current-step label when a step
 // opens, `checkpoint` and `revert` reset it to the boundary, and all three
 // re-render the mirror from intent.md's parsed steps so it tracks reality without
 // a model turn. The write is best-effort (a missing or hand-edited build-log never
-// fails a verb — the checkpoints ledger and intent.md stay the source of truth),
+// fails a verb: the checkpoints ledger and intent.md stay the source of truth),
 // matching how `checkpoint`'s Log append behaves.
 import { readFileSync, writeFileSync } from 'node:fs';
 import { buildLogPath, intentPath } from "./sidecar.js";
 import { parseSteps } from "./orient.js";
 import { setCurrentStep, syncStepsSection } from "./buildlog.js";
-/** The Current-step label for no step in flight — the loop is at the step boundary. */
+/** The Current-step label for no step in flight: the loop is at the step boundary. */
 export const AT_BOUNDARY = 'none (at the boundary)';
 /**
- * The current-step label for an open step: `<n> — <title>`, or a bare `<n>`
- * when the step carries no title. `build` passes this; the boundary verbs pass
- * AT_BOUNDARY.
+ * The current-step label for an open step: the number and title joined by an
+ * em dash, or a bare `<n>` when the step carries no title. `build` passes
+ * this; the boundary verbs pass AT_BOUNDARY.
  */
 export function stepLabel(n, title) {
     return title !== null && title.trim().length > 0 ? `${n} — ${title.trim()}` : String(n);
@@ -26,7 +26,7 @@ export function stepLabel(n, title) {
  * `label` and re-render the `## Steps` mirror from intent.md.
  *
  * Each transform is skipped when its target is absent (null), and the whole
- * thing swallows any IO error — the ledger must never block the verb.
+ * thing swallows any IO error: the ledger must never block the verb.
  */
 export function syncBuildLogState(root, slug, label) {
     try {

package/dist/lib/check.js

@@ -11,7 +11,7 @@
 //     pointers, and an all-slots-skipped run REFUSES rather than green-lighting
 //     a repo checkride can't see (a vacuous pass is not a pass).
 // Checkride's stream discipline holds: human progress goes to stderr. Exit 0 is
-// green, 1 is red, 2 means the harness itself broke — reported distinctly,
+// green, 1 is red, 2 means the harness itself broke: reported distinctly,
 // because a misconfigured gate must not read as broken code (both still block).
 import { spawnSync } from 'node:child_process';
 import { runChecks, runDoctor } from 'checkride';
@@ -21,7 +21,7 @@ import { resolveString } from "./settings.js";
  * Probe whether the check gate would have anything to run in `root`.
  *
  * A configured `check` command answers yes on its own; otherwise checkride's
- * doctor detection runs in-process — the same pass `plumbbob doctor` reports
+ * doctor detection runs in-process: the same pass `plumbbob doctor` reports
  * as a table. `start` reads this to surface "nothing to check" at plan time,
  * while the human is still deciding, instead of at the first refused
  * checkpoint.
@@ -37,19 +37,19 @@ export async function detectGate(root) {
     }
     catch {
         // A broken checkride harness is a different problem with its own reporters
-        // (doctor's ✗ row, runCheck's exit 2) — the plan-time probe stays quiet
+        // (doctor's ✗ row, runCheck's exit 2); the plan-time probe stays quiet
         // rather than mislabeling it "nothing to check".
         return { configured: null, detected: true };
     }
 }
 /**
  * Checkride's always-on repo checks: the adapters that resolve with no tool
- * config of their own — the built-in `links` slot, the pnpm-audit security
+ * config of their own: the built-in `links` slot, the pnpm-audit security
  * scan, the publint/attw package-shape probes, and the pack/smoke/snippets
  * publish-bundle slots. Several are named for their shape rather than because
  * a bare directory reports them: `publint`/`attw` resolve off a devDependency,
- * `build` off a `scripts.build` entry — which says the package can be built,
- * not that checkride can see the code that goes into it — and `snippets`
+ * `build` off a `scripts.build` entry (which says the package can be built,
+ * not that checkride can see the code that goes into it), and `snippets`
  * carries two adapters since checkride 0.10.2, so the dist-facing
  * `snippets-dist` is named beside it (this list matches ADAPTER names, not
  * slot names). Every one of them but `links` is an opt-in slot, so a default
@@ -72,7 +72,7 @@ const ALWAYS_ON_ADAPTERS = [
 ];
 /**
  * The detection rule, shared by `start`'s probe and doctor's callout: some
- * tool slot beyond the always-on family has an adapter — i.e. checkride can
+ * tool slot beyond the always-on family has an adapter: that is, checkride can
  * see the CODE (a tsconfig, a test runner, a linter…), not just the repo.
  */
 export function gateDetectsTools(checks) {
@@ -90,7 +90,7 @@ export function gateDetectsTools(checks) {
  */
 export async function runCheck(root, flags = {}, commandFlag) {
     if (gateIsRunningFor(root)) {
-        // This repo re-entering its OWN gate is never a slow gate — it is a
+        // This repo re-entering its OWN gate is never a slow gate: it is a
         // recursion whose next generation forks wider than this one. Exit 2 (the
         // harness broke), not 1: nothing has been learned about the code. A gate on
         // a DIFFERENT root is ordinary nested work (the test suite gating its
@@ -105,7 +105,7 @@ export async function runCheck(root, flags = {}, commandFlag) {
 }
 /**
  * The spawn override: stream the configured command's own output to the
- * terminal and return its exit code — the command is trusted verbatim, no
+ * terminal and return its exit code: the command is trusted verbatim, no
  * interpretation.
  */
 function runCommand(root, command, flags) {
@@ -133,7 +133,7 @@ async function runCheckride(root, flags) {
             include: flags.include !== undefined ? [...flags.include] : null,
             // Checkride's own vacuous-green refusal (0.10.2): zero checks executed is
             // an error, not a pass. It overlaps the refusal below and never reaches
-            // the human — our predicate is the broader one (it also catches a
+            // the human: our predicate is the broader one (it also catches a
             // links-only run, where a check DID execute) and fires first, so
             // plumbbob's message and its exit 1 are what a reader sees. Kept anyway:
             // it is the contract checkride asks a gate to run under, so a future
@@ -145,7 +145,7 @@ async function runCheckride(root, flags) {
     }
     catch (err) {
         // The harness broke, not the code: a malformed checkride.config.json or
-        // the like. Checkride's own CLI maps this to exit 2; so do we — a
+        // the like. Checkride's own CLI maps this to exit 2; so do we: a
         // misconfigured gate must report distinctly from red.
         const message = err instanceof Error ? err.message : String(err);
         process.stderr.write(`plumbbob: the check gate itself failed — ${message}\n` +
@@ -156,7 +156,7 @@ async function runCheckride(root, flags) {
         // Zero-config checkride skips slots with no detected tool; a repo it can't
         // see must refuse, not vacuously green-light the checkpoint. The built-in
         // `links` slot is always-on (empty detect list), so it alone proves
-        // nothing about the code — a links-only run is still vacuous.
+        // nothing about the code: a links-only run is still vacuous.
         process.stderr.write('plumbbob: checkride found nothing to check in this repo — refusing to call that green.\n' +
             '  Add tool configs (tsconfig, vitest, …) or a checkride.config.json custom check,\n' +
             '  or set the "check" key in .plumbbob/settings.json to gate through another command.\n');
@@ -171,7 +171,7 @@ async function runCheckride(root, flags) {
  * Name the failing slots and where their raw diagnostics landed, so the agent
  * (verify) reads the tool's own JSON instead of scraping scrollback.
  *
- * The summary is the canonical pointer — `output_file` is the adapter's
+ * The summary is the canonical pointer: `output_file` is the adapter's
  * preferred name, but non-JSON output falls back to `.check/<slot>.stdout.txt`.
  */
 function reportFailingSlots(summary) {
@@ -184,7 +184,7 @@ function reportFailingSlots(summary) {
     process.stderr.write(`plumbbob: failing slots:\n${lines.join('\n')}\n  Full report: .check/summary.json\n`);
 }
 /**
- * True when any narrowing flag was passed — the trigger for the spawn path's
+ * True when any narrowing flag was passed: the trigger for the spawn path's
  * flags-are-ignored warning.
  */
 function hasFlags(flags) {

package/dist/lib/commitbody.js

@@ -0,0 +1,72 @@
+// The `--body` stdin reader shared by `checkpoint` and `finish`: both verbs
+// take a commit body on fd 0 via a single-quoted heredoc (`--body <<'BODY'`),
+// never as an argument value. `evaluateCommitBody` is the pure decision over
+// an already-known fd-0 shape, so every shape is a direct unit test with no
+// fd tricks; `readCommitBody` gathers the real one: the mirror of latch.ts's
+// evaluateLatch/checkLatch split.
+//
+// Four fd-0 shapes reach this in practice: a heredoc is a regular file, a
+// pipe is a FIFO, an interactive terminal is a TTY, and an agent harness
+// hands the CLI a socket. The first three already degrade safely: a TTY
+// skips the read (it would never send EOF), a regular file/FIFO/`/dev/null`
+// read to EOF and fall back to the caller's own default body when empty. A
+// socket also never sends EOF on its own, so the same blind `readFileSync(0)`
+// blocks forever and, worse, drops the requested body silently. Refuse
+// instead: a silently dropped body reads as success.
+import { fstatSync, readFileSync } from 'node:fs';
+/**
+ * The refusal shown when `--body` is asked to read a socket: names the form
+ * that works so the retry succeeds instead of guessing again.
+ */
+export const SOCKET_REFUSAL = "plumbbob: --body refuses — stdin is a socket, and a socket never sends EOF the way a heredoc does, so the read would block forever and the body would be lost. Redirect it in with the `--body <<'BODY'` … `BODY` heredoc form instead.\n";
+/**
+ * Decide the `--body` outcome from an already-known fd-0 shape.
+ *
+ * Absent flag or a TTY both mean "don't read": the caller's fallback body
+ * applies. `other` covers a heredoc (regular file), a pipe (FIFO), and
+ * `/dev/null` (character device) alike: each is read to EOF, and an empty or
+ * failed read degrades to the same fallback an absent `--body` would use.
+ */
+export function evaluateCommitBody(hasBodyFlag, shape, read) {
+    if (!hasBodyFlag || shape === 'tty') {
+        return { ok: true, body: null };
+    }
+    if (shape === 'socket') {
+        return { ok: false, message: SOCKET_REFUSAL };
+    }
+    try {
+        const raw = read().trimEnd();
+        return { ok: true, body: raw.length > 0 ? raw : null };
+    }
+    catch {
+        return { ok: true, body: null };
+    }
+}
+/**
+ * Read the `--body` commit body from the real fd 0, or refuse when it can
+ * never deliver one.
+ *
+ * `checkpoint` and `finish` both call this where each used to call its own
+ * copy of `bodyArg`: one implementation, one refusal string, so the two
+ * verbs cannot drift apart on the wording.
+ */
+export function readCommitBody(args) {
+    return evaluateCommitBody(args.includes('--body'), stdinShape(), () => readFileSync(0, 'utf8'));
+}
+/**
+ * The fd-0 shape the guard cares about: a TTY skips the read (never sends
+ * EOF), a socket refuses (the same problem, but silent), everything else is
+ * read as before. An unreadable fd (no stdin attached at all) is treated the
+ * same as any other shape; the read attempt that follows fails safely.
+ */
+function stdinShape() {
+    if (process.stdin.isTTY === true) {
+        return 'tty';
+    }
+    try {
+        return fstatSync(0).isSocket() ? 'socket' : 'other';
+    }
+    catch {
+        return 'other';
+    }
+}

package/dist/lib/commitmsg.js

@@ -1,8 +1,8 @@
 // Conventional-Commit subject assembly. Plumbbob's commit subjects read as
-// `type(scope): description` — real feat/fix/chore types and a real parenthesised
-// scope — so `git log` speaks the same grammar as the rest of the branch. The
+// `type(scope): description` (real feat/fix/chore types and a real parenthesised
+// scope) so `git log` speaks the same grammar as the rest of the branch. The
 // `plumbbob`/`step N` identifiers ride a marker line at the head of the body,
-// which `withMarker` prepends — so `git log --grep plumbbob` finds every plumbbob
+// which `withMarker` prepends, so `git log --grep plumbbob` finds every plumbbob
 // commit. Functional and procedural, node builtins only, no gate: these only
 // shape a string the CLI is about to commit.
 /**
@@ -10,7 +10,7 @@
  * prefix on a step title.
  *
  * Anchoring on this closed set keeps a prose title like `Note: rewire the
- * cache` from being misread as a `Note` type — only these words, immediately
+ * cache` from being misread as a `Note` type; only these words, immediately
  * followed by an optional `(scope)`, an optional `!`, and a colon, count as an
  * author-supplied prefix.
  */
@@ -23,7 +23,7 @@ const PREFIX = new RegExp(`^(${TYPES.join('|')})(?:\\(([^)]+)\\))?(!)?:\\s+(.+)$
  *
  * `feat(escape-hatch): add the flag` → { type:'feat', scope:'escape-hatch',
  * breaking:false, description:'add the flag' }. A title with no recognised
- * prefix comes back whole as the description with a null type/scope — the
+ * prefix comes back whole as the description with a null type/scope; the
  * caller then defaults the type and fills the scope from the build.
  */
 export function parseConventionalTitle(title) {
@@ -46,11 +46,11 @@ export function conventionalSubject(parts) {
 /**
  * A Conventional subject from a step title, filling gaps from the build.
  *
- * An author-written prefix (`fix(parser): …`) is honoured verbatim — its type,
+ * An author-written prefix (`fix(parser): …`) is honoured verbatim: its type,
  * scope, breaking marker, and exact wording all win. A bare prose title
  * defaults to `defaultType` and the build `scope`, and gets its sentence-case
  * opener de-capitalised (`Add the flag` → `add the flag`) to match
- * Conventional style — while an all-caps acronym start (`API`, `OAuth`) is
+ * Conventional style, while an all-caps acronym start (`API`, `OAuth`) is
  * left alone.
  */
 export function subjectFromTitle(title, defaultType, scope) {