plumbbob 0.12.1 → 0.13.1

package/dist/verbs/doctor.js

@@ -2,9 +2,9 @@
 //
 // 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
+//    Code loads it in place as a plugin (skills `/plumbbob:*`, the hooks 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 hooks, 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).
 //
@@ -80,7 +80,7 @@ function linkedPackage(link) {
     }
 }
 /**
- * The link-install checks: manifest, skill set, and post-edit hook, each with its fix.
+ * The link-install checks: manifest, skill set, and hooks, each with its fix.
  *
  * `shipped` is the canonical skill list read from the package itself; an installed
  * count below it means a stale or partial link, and every fix is the same re-link.
@@ -96,10 +96,29 @@ function buildChecks(link, pkg, shipped) {
             ? { ok: true, label: `skills present (${installed.length}) — load as /plumbbob:*` }
             : { ok: false, label: `skills incomplete (${installed.length}/${shipped.length})`, fix: 're-link: plumbbob init' },
         existsSync(join(pkg, 'hooks', 'hooks.json'))
-            ? { ok: true, label: 'post-edit hook present (hooks/hooks.json, auto-registers)' }
+            ? { ok: true, label: hooksLabel(wiredEvents(join(pkg, 'hooks', 'hooks.json'))) }
             : { ok: false, label: 'hook missing (hooks/hooks.json)', fix: 're-link: plumbbob init' },
     ];
 }
+/**
+ * The hooks line's label: every event the package wires, so a link that
+ * predates a hook reads as one at a glance. A file whose events cannot be read
+ * still counts as present, the way the line read before it named any.
+ */
+function hooksLabel(events) {
+    const named = events.length === 0 ? '' : `: ${events.join(', ')}`;
+    return `hooks present (hooks/hooks.json${named}; auto-registers)`;
+}
+/** The events a hooks.json wires, in file order, or none when it does not parse. */
+function wiredEvents(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return typeof parsed.hooks === 'object' && parsed.hooks !== null ? Object.keys(parsed.hooks) : [];
+    }
+    catch {
+        return [];
+    }
+}
 /**
  * The plugin-link diagnostic: how plumbbob is installed into Claude Code, as checks.
  *

package/dist/verbs/finish.js

@@ -17,7 +17,7 @@ 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";
-import { advisory, ending, notice, transition } from "../lib/notice.js";
+import { advisory, ending, notice, printEnding, transition } from "../lib/notice.js";
 // The pointer finish leaves the turn on. Every other one is `handoff`'s, but a
 // finished session has no state left to render from, and past a closed build
 // the only move is framing the next goal.
@@ -84,23 +84,27 @@ export function finish(cwd, args = []) {
     // the turn's last text. finish renders that pointer itself: it just cleared
     // the session `handoff` would read one from.
     const where = slug === null ? '.plumbbob/' : `.plumbbob/builds/${slug}/`;
-    process.stdout.write(ending({
-        lead: transition({
-            label: 'Session',
-            fact: 'finished',
-            detail: [sha.slice(0, 9), `${where} rides your branch into the PR`],
+    printEnding(root, {
+        tier: 'orientation',
+        render: 'finish',
+        text: ending({
+            lead: transition({
+                label: 'Session',
+                fact: 'finished',
+                detail: [sha.slice(0, 9), `${where} rides your branch into the PR`],
+            }),
+            advisories: reported
+                ? []
+                : [
+                    advisory({
+                        fact: 'no report.md found',
+                        detail: ['finished without one', 'no gate here by design'],
+                        remedy: '/plumbbob:finish normally writes the report first',
+                    }),
+                ],
+            pointer: NEXT_UP,
         }),
-        advisories: reported
-            ? []
-            : [
-                advisory({
-                    fact: 'no report.md found',
-                    detail: ['finished without one', 'no gate here by design'],
-                    remedy: '/plumbbob:finish normally writes the report first',
-                }),
-            ],
-        pointer: NEXT_UP,
-    }));
+    });
     return 0;
 }
 /**

package/dist/verbs/handoff.js

@@ -1,13 +1,21 @@
 // `plumbbob handoff`: emit the CLI-owned ending of a turn as one contiguous
-// block (docs/presentation.md). Read-only, no state change. Every part outside
+// block (docs/presentation.md). Changes no state but three: at a pause it
+// leaves the detail file with a blank line around each heading, at a step pause
+// it stamps what the card showed in `PAUSE`, and every render it prints is
+// recorded in `RELAY` for the check at the turn's end. Every part outside
 // the readout fence is a bold label, a colon, and text that wraps, one blank
 // line between blocks and no fence but the readout's own. It derives the moment
-// from the session: a step in flight ⇒ the decision-tier ending (the labeled
-// Readout and its fence, the inline diff when the change is 20 lines or fewer,
-// the Verdict, Next Up, Your Call, and the Recommendation last); a landed step
+// from the session: a step in flight ⇒ the decision-tier ending (the Now line
+// naming that step, the labeled Readout and its fence, the inline diff when
+// the change is 20 lines or fewer, the Verdict, Next Up, Your Call, and the
+// Recommendation last); a landed step
 // with none in flight ⇒ the orientation-tier ending (Verdict and Next Up); a
 // fresh session with nothing yet measured ⇒ the forward pointer alone.
 //
+// A step pause renders its card once (D87 (pause-once)). While the stamp still
+// matches, a later render is the one-line reminder, the driver pointer back at
+// the step; the card comes back when the pause changes or on `--full`.
+//
 // The whole decision turn is rendered here, its opening block included: the
 // Summary lead and the numbered highlights come out of `.plumbbob/detail.md`
 // as the markdown the model wrote, with the `(details: …)` bracket appended so
@@ -29,22 +37,18 @@
 // the step names closing the spike, a step exit (a revert, an abandon, a spike
 // closed at the boundary) finds nothing in flight and points forward, with no
 // Verdict either way, since nothing landed.
-import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { join, relative } from 'node:path';
-import { commitsSince, diffNumstat, diffPatch, findRepoRoot } from "../lib/git.js";
-import { blocks } from "../lib/notice.js";
+import { PLAN_COMMIT_MARKER, commitsSince, diffNumstat, diffPatch, findRepoRoot } from "../lib/git.js";
+import { blocks, printEnding, transition } from "../lib/notice.js";
 import { isArtifactPath, parseStepSeam } from "../lib/intent.js";
-import { buildLogPath, checkpointsPath, detailPath, hasSession, inSpike, intentPath, readStats, readTurn, resolveBuild, seamPath, stepPath, tickPath, } from "../lib/sidecar.js";
-import { buildOrderPhrase, countDiff, diffRowValue, foldVerdict, lastLedgerSha, parkedPhrase, parseBuildOrder, parseConstraintCount, parseLastCheckpoint, parseOrderedSteps, parseParkTotals, parseRecap, parseRecommendation, parseSections, parseSteps, parseSummary, recapLines, remainingOrder, seamRowFromDiff, spentRowValue, summaryCheckRow, } from "../lib/orient.js";
+import { buildLogPath, checkpointsPath, detailPath, hasSession, inSpike, intentPath, pausePath, readStats, readTurn, resolveBuild, seamPath, stepPath, tickPath, } from "../lib/sidecar.js";
+import { buildOrderPhrase, countDiff, diffRowValue, foldVerdict, lastLedgerSha, normalizeDetailHeadings, parkedPhrase, parseBuildOrder, parseBuildRanges, parseConstraintCount, parseLastCheckpoint, parseOrderedSteps, parseParkTotals, parseRecap, parseRecommendation, parseSections, parseSteps, parseSummary, rangeStanding, recapLines, remainingOrder, seamRowFromDiff, spentRowValue, summaryCheckRow, } from "../lib/orient.js";
 // The inline-diff threshold (docs/presentation.md): at 20 changed lines or
 // fewer the patch rides the turn; at 21 it stays in the working tree behind
 // the counted diff row.
 const INLINE_DIFF_MAX = 20;
-// plumbbob's own plan commits carry this marker on a line of their body. A
-// `chore(plan)` harvest lands between nearly every step, so counting them as
-// out-of-band would trip the advisory rung on routine housekeeping and stop
-// meaning anything within three steps.
-const PLAN_COMMIT_MARKER = '^plumbbob plan$';
 // The seam rule, and the one tier that still has a seam to mark: at the plan
 // pause the model presents the framed plan above the relay, so the rule keeps
 // a label from reading as the tail of what precedes it, and a run of blank
@@ -58,11 +62,14 @@ const SEAM_RULE = '\n---';
  *
  * Requires an active session (the STATE sentinel under `.plumbbob/`). The step
  * tiers are derived, not passed: a step in flight yields the full
- * decision-tier ending (the Readout and its fence, the inline diff when small
- * enough, the Verdict, Next Up, Your Call, and the Recommendation), and so does
+ * decision-tier ending (the Now line, the Readout and its fence, the inline
+ * diff when small enough, the Verdict, Next Up, Your Call, and the
+ * Recommendation), and so does
  * a named step that has not landed when nothing is in flight (a hand-built diff
- * under verify), a landed step yields the orientation-tier ending (Verdict and
- * Next Up, no Your Call),
+ * under verify). That card renders once: a later render of the same pause, with
+ * nothing in it changed, is the one-line reminder, and `--full` prints the card
+ * whatever the stamp says. A landed step yields the orientation-tier ending
+ * (Verdict and Next Up, no Your Call),
  * and a fresh session with nothing to report yields only
  * the forward pointer. The two endings no session state can distinguish are
  * named by a flag: `--plan` is the plan pause (a decision turn about the plan,
@@ -80,13 +87,16 @@ export function handoff(cwd, args = []) {
         process.stderr.write('plumbbob: handoff: --plan and --driver name different tiers; pass one.\n');
         return 1;
     }
+    // A build named by flag rides any command that reprints this ending, since
+    // the cursor may point elsewhere.
+    const named = args.includes('--build') ? slug : null;
     const intent = readOr(intentPath(root, slug));
     // In build order, so the pointer names the step a bare `plumbbob build`
     // would enter; the build-log feeds the park count beneath it.
     const steps = parseOrderedSteps(intent);
     const buildLog = readOr(buildLogPath(root, slug));
     const inFlight = readMarker(stepPath(root, slug));
-    const detail = readOr(detailPath(root));
+    const rawDetail = readOr(detailPath(root));
     // Where a pointer sends the reader to read the step itself: the intent file
     // as the human would type it, relative to the repo root.
     const where = relative(root, intentPath(root, slug));
@@ -95,12 +105,14 @@ export function handoff(cwd, args = []) {
         // renders; the pointer and the moves both aim at the first undone step. A
         // decision turn still ends on the model's recommendation when it wrote one.
         const first = steps.find((s) => !s.done);
+        const detail = settleDetail(root, rawDetail);
         const plan = [
             SEAM_RULE,
-            nextUpBlock(first, steps.length, where, nextUpNote(intent, buildLog, null)),
+            nextUpBlock(intent, buildLog, first, null, where),
             planCallBlock(first),
         ];
-        return emit(withRecommendation(plan, parseRecommendation(detail)));
+        const command = reprintCommand('--plan', undefined, named);
+        return emit(root, { tier: 'decision', render: 'plan', command }, withRecommendation(plan, parseRecommendation(detail)));
     }
     const explicit = rest.find((a) => /^\d+$/.test(a));
     const lastDone = parseLastCheckpoint(readOr(checkpointsPath(root, slug)));
@@ -120,11 +132,13 @@ export function handoff(cwd, args = []) {
         // (a step exit: a revert, an abandon, a spike closed at the boundary) the
         // ordinary forward pointer stands, and no Verdict rides above it: nothing
         // landed to measure.
-        return emit([driverPointer(root, slug)]);
+        return emit(root, { tier: 'driver', render: 'driver' }, [driverPointer(root, slug)]);
     }
     if (current === null) {
         // Nothing measured yet (a fresh session): no Verdict, just the forward pointer.
-        return emit([nextUpBlock(nextUp, steps.length, where, nextUpNote(intent, buildLog, current))]);
+        return emit(root, { tier: 'orientation', render: 'pointer' }, [
+            nextUpBlock(intent, buildLog, nextUp, current, where),
+        ]);
     }
     // A step is pending, and its hand-off is the pause, while it is in flight.
     // With nothing in flight, a step the turn names that has not landed is
@@ -133,16 +147,19 @@ export function handoff(cwd, args = []) {
     // which pause to render.
     const pending = inFlight !== null || (explicit !== undefined && steps.some((s) => s.n === current && !s.done));
     if (!pending) {
-        // The boundary: the orientation-tier ending, the state word and the forward
-        // pointer, no decision pending and so no Your Call. The same two parts the
-        // checkpoint printed for itself, from the same call.
+        // The boundary: the orientation-tier ending, the state word, the Stop part
+        // where a range just landed, and the forward pointer, no decision pending
+        // and so no Your Call. The same parts the checkpoint printed for itself,
+        // from the same call.
         const landed = boundaryEnding(root, slug, current);
-        return emit([landed.verdict, landed.pointer]);
+        return emit(root, { tier: 'orientation', render: 'boundary' }, [landed.verdict, landed.stop, landed.pointer]);
     }
     // The pause: the whole turn as one contiguous block, each part a labeled line
     // with one blank line between, and the only fence the readout's own (plus the
-    // inline diff when the change is small enough). It opens on the Summary the
-    // model wrote into the detail file, so there is no seam left to rule off.
+    // inline diff when the change is small enough). It opens on the step in
+    // flight and then the Summary the model wrote into the detail file, so there
+    // is no seam left to rule off.
+    const detail = settleDetail(root, rawDetail);
     const { rows, work, summary, checkGreen } = measured(root, slug, intent, detail, current);
     const { ladder, worst } = foldVerdict(rows, accruedStats(root, slug, current));
     const verdict = verdictLine(ladder, worst);
@@ -150,44 +167,153 @@ export function handoff(cwd, args = []) {
     const changed = counts.added + counts.removed;
     // The patch comes first so `· inline below` is a promise the fence keeps: a
     // small change git can still print nothing for (a vanished path) falls back
-    // to the bare counts rather than pointing at a fence that never arrives.
-    const patch = changed > 0 && changed <= INLINE_DIFF_MAX ? diffPatch(root, work) : '';
+    // to the bare counts rather than pointing at a fence that never arrives. The
+    // stamp hashes it at any size, so it is read whenever there is a change.
+    const fullPatch = changed > 0 ? diffPatch(root, work) : '';
+    const patch = changed <= INLINE_DIFF_MAX ? fullPatch : '';
     const inline = patch.length > 0;
+    const diffRow = diffRowValue(counts, inline);
+    const stamp = pauseStamp(current, detail, measuredLines(rows, diffRow), fullPatch);
+    if (!rest.includes('--full') && readOr(pausePath(root, slug)).trim() === stamp) {
+        // The pause the human already read, unchanged: the answer above this line
+        // is what they asked for, and the card would push it off the screen.
+        const command = reprintCommand(null, explicit, named);
+        return emit(root, { tier: 'decision', render: 'reminder', command }, [
+            `**Next Up**: Back to ${stepPhrase(current, steps)}`,
+        ]);
+    }
+    writePause(root, slug, stamp);
     const readout = recapLines(rows, {
-        diff: diffRowValue(counts, inline),
+        diff: diffRow,
         spent: spentRowValue(spentInputs(root, slug, current, summary)),
         constraints: parseConstraintCount(intent),
     });
-    const parts = [summaryBlock(parseSummary(detail), relative(root, detailPath(root)))];
+    const parts = [
+        `**Now**: ${stepPhrase(current, steps)}`,
+        summaryBlock(parseSummary(detail), relative(root, detailPath(root))),
+    ];
     if (readout.length > 0) {
-        parts.push([readoutLabel(current, steps), '', ...fence('text', readout)].join('\n'));
+        parts.push([READOUT_LABEL, '', ...fence('text', readout)].join('\n'));
     }
     if (inline) {
         parts.push(fence('diff', patch.split('\n')).join('\n'));
     }
-    parts.push(verdict, nextUpBlock(nextUp, steps.length, where, nextUpNote(intent, buildLog, current)), yourCallBlock(current, checkGreen));
-    return emit(withRecommendation(parts, parseRecommendation(detail)));
+    parts.push(verdict, nextUpBlock(intent, buildLog, nextUp, current, where), yourCallBlock(current, checkGreen));
+    const command = reprintCommand('--full', explicit, named);
+    return emit(root, { tier: 'decision', render: 'card', command }, withRecommendation(parts, parseRecommendation(detail)));
+}
+/**
+ * The detail file's text with a blank line around each heading, written back to
+ * disk when that changed anything, so the file the gate lints before
+ * `checkpoint` clears it is clean whatever the model typed.
+ *
+ * The render goes out on the normalized text either way. A failed write costs
+ * only the lint guard: stdout and the exit code are the same as if it had
+ * landed.
+ */
+function settleDetail(root, raw) {
+    const clean = normalizeDetailHeadings(raw);
+    if (clean !== raw) {
+        try {
+            writeFileSync(detailPath(root), clean);
+        }
+        catch {
+            // Read-only tree or a vanished directory: the pause still renders.
+        }
+    }
+    return clean;
+}
+/**
+ * The stamp of a step pause: its number and a hash of everything on the card a
+ * later turn could change, so the reminder prints only while the pause is the
+ * one the human already read.
+ *
+ * Hashed: the detail file as normalized, the measured check and seam rows and
+ * the diff row as rendered, and the patch the diff row counts, so an edit that
+ * keeps the counts still reads as a touched file. Never `spent`: it counts
+ * turns, so it moves on every turn and would make every render look new.
+ */
+function pauseStamp(step, detail, rendered, patch) {
+    const hash = createHash('sha256');
+    for (const part of [detail, ...rendered, patch]) {
+        hash.update(part).update('\0');
+    }
+    return `${step} ${hash.digest('hex')}`;
+}
+/**
+ * The readout rows the CLI measured, as the card renders them: `check`,
+ * `seam`, and `diff`. The judgment rows ride the detail file, which the stamp
+ * hashes whole, and `spent` stays out of it.
+ */
+function measuredLines(rows, diff) {
+    const measuredRows = {};
+    if (rows.check !== undefined) {
+        measuredRows.check = rows.check;
+    }
+    if (rows.seam !== undefined) {
+        measuredRows.seam = rows.seam;
+    }
+    return recapLines(measuredRows, { diff, spent: null, constraints: 0 });
+}
+/**
+ * Record the stamp of the card just printed. A failed write costs one more
+ * full card on a later turn, never this turn's output or its exit code.
+ */
+function writePause(root, slug, stamp) {
+    try {
+        writeFileSync(pausePath(root, slug), `${stamp}\n`);
+    }
+    catch {
+        // A read-only tree or a vanished build folder: the card still renders.
+    }
 }
 /**
- * The two CLI-rendered parts of a boundary ending: the Verdict folded from
- * everything measurable right now, and the pointer at the step to come.
+ * The CLI-rendered parts of a boundary ending: the Verdict folded from
+ * everything measurable right now, the Stop part when the landing finished a
+ * range, and the pointer at the step to come.
  *
  * `step` is the step that just landed, or null at a plan commit, where nothing
- * was measured and the Verdict vanishes. A transition verb prints these beneath
- * its own lead line, so a boundary reads identically whether `checkpoint`
- * emitted it or a later `handoff` did; the paths a stray advisory named are the
- * one part that does not survive, and the commit holds those.
+ * was measured and the Verdict and the Stop part both vanish. A transition verb
+ * prints these beneath its own lead line, so a boundary reads identically
+ * whether `checkpoint` emitted it or a later `handoff` did; the paths a stray
+ * advisory named are the one part that does not survive, and the commit holds
+ * those.
  */
 export function boundaryEnding(root, slug, step) {
     const intent = readOr(intentPath(root, slug));
     const steps = parseOrderedSteps(intent);
     const nextUp = steps.find((s) => !s.done && s.n !== step);
-    const note = nextUpNote(intent, readOr(buildLogPath(root, slug)), step);
+    const where = relative(root, intentPath(root, slug));
     return {
         verdict: step === null ? null : landedVerdict(root, slug, intent, step),
-        pointer: nextUpBlock(nextUp, steps.length, relative(root, intentPath(root, slug)), note),
+        stop: stopLine(intent, steps, step, where),
+        pointer: nextUpBlock(intent, readOr(buildLogPath(root, slug)), nextUp, step, where),
     };
 }
+/**
+ * The Stop part: why the build stops at this boundary, when the step that
+ * landed was the last undone step of a range that lands its steps. One labeled
+ * line, the range over the count, a plain hyphen, the stop as the plan wrote
+ * it, and a bracket pointing at the item, where its note can be read.
+ *
+ * Null for every other boundary: a landing that leaves the range open, a bare
+ * range (its stop was its own pause), a plan without ranges, and the plan
+ * commit, where nothing landed.
+ */
+function stopLine(intent, steps, step, where) {
+    if (step === null) {
+        return null;
+    }
+    const { count, completed } = rangeStanding(parseBuildRanges(intent), steps, step);
+    if (completed === null || completed.bare) {
+        return null;
+    }
+    return transition({
+        label: 'Stop',
+        fact: `Range ${completed.item} of ${count} landed - ${completed.stop}`,
+        detail: [`details: \`${where}:${completed.line}\``],
+    });
+}
 /**
  * The step's record for the build-log's Log: the pause as the human approved
  * it, with the full story behind each highlight beneath. The Summary and its
@@ -195,6 +321,9 @@ export function boundaryEnding(root, slug, step) {
  * numbered sections' bodies, blank-line separated and unindented; the caller
  * nests it under the Log's dated line.
  *
+ * The record carries no Now line, and its Readout label stays bare like the
+ * card's: the dated Log line above it already names the step.
+ *
  * Measured, not recalled: the check, seam, and diff rows are read the same way
  * the pause read them. Both measures run against HEAD, so staging no longer
  * moves the counts and the caller's build-then-stage order is a nicety rather
@@ -224,7 +353,7 @@ export function stepRecord(root, slug, step, detail) {
         parts.push(recordSummary(summary));
     }
     if (readout.length > 0) {
-        parts.push([readoutLabel(step, parseSteps(intent)), '', ...fence('text', readout)].join('\n'));
+        parts.push([READOUT_LABEL, '', ...fence('text', readout)].join('\n'));
     }
     parts.push(verdictLine(ladder, worst));
     return [...withRecommendation(parts, recommendation), ...sectionBlocks(sections)].join('\n\n');
@@ -275,7 +404,7 @@ export function driverPointer(root, slug) {
     // driver line itself stays one line, with no note beneath it.
     const steps = parseOrderedSteps(intent);
     const inFlight = readMarker(stepPath(root, slug));
-    const driver = inSpike(root, slug) ? spikeNextUpLine(inFlight) : driverNextUpLine(steps, inFlight, steps.length);
+    const driver = inSpike(root, slug) ? spikeNextUpLine(inFlight) : driverNextUpLine(steps, inFlight);
     // The forward fallback skips the step just landed as well as the one open, so
     // a checkpoint whose `[x]` flip failed still points on rather than back at
     // work already recorded.
@@ -315,22 +444,33 @@ function measured(root, slug, intent, detail, step) {
     return { rows, work, summary, checkGreen: measuredCheck?.verdict === 'true' };
 }
 /**
- * Write an ending to stdout and return handoff's exit code.
+ * Print an ending, record it for the relay check, and return handoff's exit
+ * code.
  *
  * The parts are stacked by the same assembly a transition verb prints its own
  * ending through, so the block reads the same whichever command emitted it.
  */
-function emit(parts) {
-    process.stdout.write(blocks(parts));
+function emit(root, kind, parts) {
+    printEnding(root, { ...kind, text: blocks(parts) });
     return 0;
 }
+/**
+ * The command that prints a decision ending again, for the retry the relay
+ * check asks for: handoff in the form that printed it, with the step a verify
+ * pause was named by and the build a flag named, so the retry lands on the
+ * same pause with nothing in flight and the cursor elsewhere.
+ */
+function reprintCommand(form, step, build) {
+    const parts = ['plumbbob handoff', form, step, build === null ? null : `--build ${build}`];
+    return parts.filter((p) => p !== null && p !== undefined).join(' ');
+}
 /**
  * The Verdict line from an already-folded result: the ladder rung, and the
  * worst component in a trailing parenthetical when one exists.
  *
- * No step segment rides here. The identity renders once per turn: the Readout
- * label names the step, Next Up carries the progress count, and the Verdict is
- * left saying the one thing only it says.
+ * No step segment rides here. The identity renders once per turn: the Now line
+ * names the step in flight with its count, Next Up names the step to come with
+ * its own, and the Verdict is left saying the one thing only it says.
  */
 function verdictLine(ladder, worst) {
     const state = `**Verdict**: ${ladder.glyph} ${ladder.state}`;
@@ -356,13 +496,26 @@ function summaryBlock(summary, where) {
     }
     return [lead, '', ...summary.highlights.map((h) => `${h.n}. ${h.title}`)].join('\n');
 }
+// The Readout's label, bare on the card and in the record alike: the Now line
+// at the top of the card names the step the fence measures, and a label that
+// named it too would put the step on the card twice.
+const READOUT_LABEL = '**Readout**:';
 /**
- * The Readout's label: the step the fence below it measures, named once.
+ * A step named the way every pointer names it: the number, the count out of
+ * the whole plan, and the title behind a plain hyphen.
+ *
+ * The count is the plan's own, step number over total, so the Now line and
+ * Next Up agree under a re-sequenced build order. It is dropped only where it
+ * would lie: a step the plan no longer holds is its number alone, since
+ * "Step 9 of 3" would be worse than no count.
  */
-function readoutLabel(step, steps) {
-    const open = steps.find((s) => s.n === step);
-    const title = open !== undefined && open.title.length > 0 ? ` - ${open.title}` : '';
-    return `**Readout**: Step ${step}${title}`;
+function stepPhrase(n, steps) {
+    const step = steps.find((s) => s.n === n);
+    if (step === undefined) {
+        return `Step ${n}`;
+    }
+    const title = step.title.length > 0 ? ` - ${step.title}` : '';
+    return `Step ${n} of ${steps.length}${title}`;
 }
 /**
  * What the `spent` row is rendered from: the step's own stamps and counters
@@ -467,16 +620,18 @@ function readCheckSummary(root) {
  *
  * Nobody types "needs work", so the block names what really happens instead:
  * a message that asks is an expand (nothing changes), and a message that
- * directs is the fix. `revert` comes last, because a destructive move is named
- * rather than discovered. `looks good` renders only while the measured check is
- * green; offering a move that would refuse teaches a false ceremony.
+ * directs is the fix. The expand move also names the way back to the card,
+ * since an expand turn ends on the reminder and the reminder states no move.
+ * `revert` comes last, because a destructive move is named rather than
+ * discovered. `looks good` renders only while the measured check is green;
+ * offering a move that would refuse teaches a false ceremony.
  */
 function yourCallBlock(step, checkGreen) {
     const moves = [];
     if (checkGreen) {
         moves.push(callLine('`looks good`', `I checkpoint Step ${step}; back to the boundary`));
     }
-    moves.push(callLine('`expand`, or any question', 'I show more of what is there; nothing changes'));
+    moves.push(callLine('`expand`, or any question', 'I show more of what is there; nothing changes, and `show the pause` brings all of this back'));
     moves.push(callLine('anything that reads as direction', 'I take it as what to change; nothing lands until you approve'));
     moves.push(callLine('`revert`', 'I wind the work back to the last checkpoint'));
     return ['**Your Call**:', '', ...moves].join('\n');
@@ -511,16 +666,8 @@ function planCallBlock(first) {
  * step is already being built, so the `/model` call is behind us. Null when no
  * step is open, which is the caller's cue to fall back to the forward pointer.
  */
-function driverNextUpLine(steps, inFlight, total) {
-    if (inFlight === null) {
-        return null;
-    }
-    const open = steps.find((s) => s.n === inFlight);
-    const title = open !== undefined && open.title.length > 0 ? ` - ${open.title}` : '';
-    // The progress count rides every tier's pointer, but only where the plan
-    // actually holds the step: "step 9 of 3" would be worse than no count.
-    const progress = open === undefined ? '' : ` of ${total}`;
-    return `**Next Up**: Back to Step ${inFlight}${progress}${title}`;
+function driverNextUpLine(steps, inFlight) {
+    return inFlight === null ? null : `**Next Up**: Back to ${stepPhrase(inFlight, steps)}`;
 }
 /**
  * The driver pointer while a spike is open: the spike outranks the step it
@@ -539,10 +686,11 @@ function spikeNextUpLine(inFlight) {
 // count. The line is a reminder; the dashboard holds the whole sequence.
 const ORDER_CAP = 5;
 /**
- * The line beneath the forward pointer: the build order from the step it
- * names, when `## Build order` re-sequences the plan away from its numbering,
- * and the park count, when anything has been parked; '' when neither says
- * anything, so a plan nobody re-sequenced with an empty park list renders the
+ * The line beneath the forward pointer: the range segment, when the plan
+ * declares build ranges; the build order from the step the pointer names, when
+ * `## Build order` re-sequences the plan away from its numbering; and the park
+ * count, when anything has been parked. '' when none says anything, so a plan
+ * with no ranges, nobody re-sequenced, and an empty park list renders the
  * pointer alone, as before.
  *
  * Indented two spaces, because an indented line continues the part above it
@@ -551,9 +699,10 @@ const ORDER_CAP = 5;
  * `Nothing planned`: an unharvested list at the end of the plan is the one
  * reminder that matters there.
  */
-function nextUpNote(intent, buildLog, exclude) {
+function nextUpNote(intent, buildLog, exclude, range) {
     const parks = parseParkTotals(buildLog);
     const segments = [
+        range,
         buildOrderPhrase(remainingOrder(parseSteps(intent), parseBuildOrder(intent), exclude), ORDER_CAP),
         parks.total > 0 ? parkedPhrase(parks) : '',
     ].filter((s) => s.length > 0);
@@ -562,11 +711,41 @@ function nextUpNote(intent, buildLog, exclude) {
 /**
  * The forward pointer with its note beneath, as one part: `blocks` keeps a
  * part's own newlines, so the note rides flush under the line it qualifies.
+ *
+ * `exclude` is the step the turn is about: the step in flight at a pause, the
+ * step just landed at a boundary, null at the plan pause and the plan commit.
+ * While the note suggests a range, the bracket bolds the range's model, since
+ * the run is the range and that is the `/model` the human picks before typing
+ * it.
  */
-function nextUpBlock(nextUp, total, where, note) {
-    const line = nextUpLine(nextUp, total, where);
+function nextUpBlock(intent, buildLog, nextUp, exclude, where) {
+    const steps = parseOrderedSteps(intent);
+    const range = rangeSegment(intent, steps, nextUp, exclude);
+    const line = nextUpLine(nextUp, steps.length, where, range.model ?? nextUp?.model ?? null);
+    const note = nextUpNote(intent, buildLog, exclude, range.segment);
     return note.length === 0 ? line : `${line}\n${note}`;
 }
+/**
+ * The range segment that leads the note, and the model the pointer's bracket
+ * bolds while it suggests a range: `range 3 of 5: /plumbbob:build 6-9` with
+ * the range's model, the re-cut words for a flagged range, the words for a step
+ * no range names, or '' for a plan without ranges.
+ *
+ * The step the turn is about reads as landed, so a step pause names what is
+ * left of the range once the step in flight lands. A flagged range, and a
+ * range with no `- model:` line, leave the step's model in the bracket.
+ */
+function rangeSegment(intent, steps, nextUp, exclude) {
+    const landed = steps.map((s) => (s.n === exclude ? { ...s, done: true } : s));
+    const { count, holding, command, flag } = rangeStanding(parseBuildRanges(intent), landed, nextUp?.n ?? null);
+    if (holding !== null && command !== null) {
+        return { segment: `range ${holding.item} of ${count}: ${command}`, model: holding.model };
+    }
+    if (flag === null) {
+        return { segment: '', model: null };
+    }
+    return { segment: holding === null ? flag : `range ${holding.item} of ${count} needs a re-cut (${flag})`, model: null };
+}
 /**
  * The forward pointer: the next undone step with the progress count, its
  * title, and a closing bracket carrying its advisory `- model:` recommendation
@@ -579,12 +758,12 @@ function nextUpBlock(nextUp, total, where, note) {
  * reads as a path in a PR diff. The line alone is the driver tier's pointer;
  * every other tier rides `nextUpNote` beneath it, through `nextUpBlock`.
  */
-function nextUpLine(nextUp, total, where) {
+function nextUpLine(nextUp, total, where, model = nextUp?.model ?? null) {
     if (nextUp === undefined) {
         return '**Next Up**: Nothing planned - /plumbbob:step or /plumbbob:finish';
     }
     const title = nextUp.title.length > 0 ? ` - ${nextUp.title}` : '';
-    const token = modelToken(nextUp.model);
+    const token = modelToken(model);
     const bracket = token === null ? [] : [`model: **${capitalize(token)}**`];
     bracket.push(`details: \`${where}:${nextUp.line}\``);
     return `**Next Up**: Step ${nextUp.n} of ${total}${title} (${bracket.join(', ')})`;