plumbbob 0.12.1 → 0.13.1

package/dist/lib/sidecar.js

@@ -213,6 +213,21 @@ export function stepPath(root, slug) {
 export function clearStep(root, slug) {
     rmSync(stepPath(root, slug), { force: true });
 }
+/**
+ * PAUSE: the stamp of the step pause `handoff` last rendered whole, the step
+ * number and a hash of what the card showed. While a later render matches it,
+ * handoff prints the one-line reminder instead of the card.
+ */
+export function pausePath(root, slug) {
+    return join(artifactDir(root, slug), 'PAUSE');
+}
+/**
+ * Remove the PAUSE stamp: a checkpoint, a revert, or an abandon ends the pause
+ * it recorded, so the next pause renders whole. Absent is a no-op.
+ */
+export function clearPause(root, slug) {
+    rmSync(pausePath(root, slug), { force: true });
+}
 /**
  * The build's `checkpoints` ledger: the recorded SHAs of landed plan and step
  * commits, one line each.
@@ -458,6 +473,9 @@ export function clearSpike(root, slug) {
 // `plumbbob turn` (the UserPromptSubmit hook) ticks TURN once per human prompt
 // and rewrites GRANT from the literal prompt; the checkpoint latch reads them to
 // refuse a land until a human turn has intervened since the step was entered.
+// A background job's notice reaches the same hook and ticks neither; PROMPT,
+// beside them, records the id of the last prompt the hook saw, so the hook can
+// tell a notice folded into the running turn from one that starts its own.
 // Kept in the sidecar so the lone GRANT `rmSync` stays where deletions of control
 // state are allowed. ---
 /**
@@ -489,6 +507,41 @@ export function setGrant(root, grant) {
         writeFileSync(grantPath(root), `${grant}\n`);
     }
 }
+/**
+ * PROMPT: the id of the last prompt the turn hook saw, typed or not.
+ */
+export function promptPath(root) {
+    return join(root, DIRNAME, 'PROMPT');
+}
+/**
+ * The id of the last prompt the turn hook saw, or null when none is recorded.
+ *
+ * A notice the harness folds into a running turn arrives under that turn's id,
+ * where one that starts a turn of its own arrives under a fresh one, so the
+ * hook compares a notice's id against this one to tell the two apart.
+ */
+export function readPrompt(root) {
+    try {
+        const id = readFileSync(promptPath(root), 'utf8').trim();
+        return id === '' ? null : id;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Record the id of the prompt the hook just saw, or clear the record when the
+ * payload carried none, so a stale id can never make a later notice look as
+ * though it joined the running turn.
+ */
+export function notePrompt(root, id) {
+    if (id === null) {
+        rmSync(promptPath(root), { force: true });
+    }
+    else {
+        writeFileSync(promptPath(root), `${id}\n`);
+    }
+}
 /**
  * TICK: the per-build entry stamp: the TURN value recorded when work was
  * entered (`build <n>` for a step, `start` for the plan), cleared when
@@ -536,6 +589,143 @@ export function readTurn(root) {
         return null;
     }
 }
+// --- The relay record: `.plumbbob/RELAY`, the ending the CLI printed last, so a
+// Stop hook can check that the turn closed on it. The verb that prints an
+// ending records it here: it knows what it printed, where a hook scraping
+// stdout would have to guess which command ran. Flat like TURN, because the
+// turn it is checked against is the session's, not a build's. A later ending
+// overwrites an earlier one, so a turn is judged by the last thing it printed. ---
+// The tiers of docs/presentation.md, which decide how a turn has to carry an
+// ending: a decision ending closes the turn, an orientation ending appears in
+// it, and a driver ending is recorded only so that the last ending wins.
+const RELAY_TIERS = ['decision', 'orientation', 'driver'];
+// Which ending printed: handoff's six forms first, then one per transition. It
+// is what the check's reason names when the ending went missing.
+const RELAY_RENDERS = [
+    'card',
+    'reminder',
+    'plan',
+    'boundary',
+    'pointer',
+    'driver',
+    'checkpoint',
+    'plan-commit',
+    'park',
+    'revert',
+    'abandon',
+    'spike-open',
+    'spike-report',
+    'spike-done',
+    'use',
+    'order',
+    'finish',
+    'start',
+];
+/**
+ * RELAY: the ending the CLI printed last, at the flat sidecar root.
+ */
+export function relayPath(root) {
+    return join(root, DIRNAME, 'RELAY');
+}
+/**
+ * Record an ending in RELAY, stamped with the current TURN: a header of
+ * `key value` lines, a blank line, then the text exactly as it printed.
+ *
+ * Written only while TURN holds a count, the same dormancy `stampTick` keeps: a
+ * host with no turn hook has no turn to check the ending against. Best-effort
+ * by contract, since the ending has already reached stdout and a failed record
+ * must not change it or the exit code.
+ */
+export function writeRelay(root, relay) {
+    const turn = readTurn(root);
+    if (turn === null)
+        return;
+    // A hold the check already spent on this turn survives the ending the retry
+    // reprints, or a turn whose retry missed again would be held a second time.
+    const held = readRelay(root)?.held === turn ? { held: turn } : {};
+    try {
+        writeFileSync(relayPath(root), formatRelay({ ...relay, turn, ...held }));
+    }
+    catch {
+        // A read-only tree or a directory in the way: the ending already printed.
+    }
+}
+/**
+ * Drop the recorded ending, so the `Stop` check has nothing to judge until a
+ * verb prints another.
+ *
+ * The turn hook calls this when a background job's notice starts a turn of its
+ * own. The ending was judged when its own turn ended, and a notice leaves TURN
+ * where it was, so without this the notice's turn would read as the one that
+ * printed the ending and be held open for a card the human has already read.
+ */
+export function clearRelay(root) {
+    rmSync(relayPath(root), { force: true });
+}
+/**
+ * Stamp the record with the turn the check held open over it, so the check
+ * holds at most once per turn. False when the stamp could not be written, and
+ * the check then holds nothing, since a hold it cannot count could repeat.
+ */
+export function holdRelay(root, record) {
+    try {
+        writeFileSync(relayPath(root), formatRelay({ ...record, held: record.turn }));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** A record as RELAY stores it: the header's `key value` lines, a blank line, then the text. */
+function formatRelay(record) {
+    const header = [`turn ${record.turn}`, `tier ${record.tier}`, `render ${record.render}`];
+    if (record.command !== undefined)
+        header.push(`command ${record.command}`);
+    if (record.held !== undefined)
+        header.push(`held ${record.held}`);
+    return `${header.join('\n')}\n\n${record.text}`;
+}
+/**
+ * The recorded ending, or null when RELAY is absent or its header does not
+ * parse: a record the check cannot read is no record.
+ */
+export function readRelay(root) {
+    let raw;
+    try {
+        raw = readFileSync(relayPath(root), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const split = raw.indexOf('\n\n');
+    if (split === -1)
+        return null;
+    const fields = new Map();
+    for (const line of raw.slice(0, split).split('\n')) {
+        const space = line.indexOf(' ');
+        if (space > 0)
+            fields.set(line.slice(0, space), line.slice(space + 1));
+    }
+    const turn = count(fields.get('turn'));
+    const tier = RELAY_TIERS.find((t) => t === fields.get('tier'));
+    const render = RELAY_RENDERS.find((r) => r === fields.get('render'));
+    if (turn === null || tier === undefined || render === undefined)
+        return null;
+    const command = fields.get('command');
+    const held = count(fields.get('held'));
+    return {
+        turn,
+        tier,
+        render,
+        ...(command === undefined ? {} : { command }),
+        ...(held === null ? {} : { held }),
+        text: raw.slice(split + 2),
+    };
+}
+/** A header field read as a bare count, or null when it is absent or anything else. */
+function count(field) {
+    return field !== undefined && /^\d+$/.test(field) ? Number(field) : null;
+}
 /**
  * Walk up from `cwd` to the nearest ancestor with an active session (a
  * `.plumbbob/STATE` file), or null when there is none.
@@ -599,17 +789,26 @@ export function excludeControl(root) {
         // never writes, and never commits.
         `${DIRNAME}/TURN`,
         `${DIRNAME}/GRANT`,
+        // The id of the last prompt the turn hook saw, which tells a notice folded
+        // into the running turn from one that starts its own.
+        `${DIRNAME}/PROMPT`,
         // The in-flight step's detail file: flat per-session control the model
-        // overwrites before every pause. checkpoint folds it into the commit body
-        // and then clears it, so its archive is the commit, never a tracked path;
-        // excluding it keeps stageAll from ever sweeping it into a step commit.
+        // overwrites before every pause. checkpoint records it in the build-log's
+        // Log and then clears it, so its archive is the tracked ledger, never this
+        // path; excluding it keeps stageAll from ever sweeping it into a step commit.
         `${DIRNAME}/detail.md`,
+        // The ending the CLI printed last, for the Stop check: per-worktree
+        // control, rewritten by every ending, and never a step commit's to carry.
+        `${DIRNAME}/RELAY`,
         `${DIRNAME}/builds/*/STEP`,
         `${DIRNAME}/builds/*/SEAM`,
         `${DIRNAME}/builds/*/SPIKE`,
         // The entry stamp is in-flight control like STEP/SEAM: checkpoint's
         // stageAll must never sweep it into a step commit.
         `${DIRNAME}/builds/*/TICK`,
+        // The pause stamp is in-flight control too: what handoff last showed, so
+        // a repeat prints the reminder. It must never ride a step commit.
+        `${DIRNAME}/builds/*/PAUSE`,
         // The agent-run handoff ledger is step-scoped in-flight state, not a
         // tracked artifact: it must never ride a step commit into the PR.
         `${DIRNAME}/builds/*/handoff.json`,

package/dist/lib/steplist.js

@@ -0,0 +1,128 @@
+// A step expression: the one grammar a `/plumbbob:build` range is typed in. The
+// turn hook reads it to mint a grant, the latch to land exactly what the grant
+// names, `build` to say where a range stops, and the dashboard to point at where
+// one starts, so no two of them can read the same keystrokes two ways. An
+// expression is one number, a span `N-M` with N no greater than M, or numbers
+// and spans joined by commas (`20,5-9`). It names plan numbers, never positions
+// in the build order, and it is held as the spans it was written in, so
+// `1-100000` stays two numbers rather than a hundred thousand. Pure: no fs.
+/**
+ * Parse a step expression, or null when it is anything else.
+ *
+ * Every item is a positive number or a span whose first number is no greater
+ * than its last. An empty item, a stray dash, or a space inside the expression
+ * reads as no list at all, so a malformed range names nothing and grants
+ * nothing.
+ */
+export function parseStepList(text) {
+    const spans = [];
+    for (const item of text.split(',')) {
+        const m = /^(\d+)(?:-(\d+))?$/.exec(item);
+        if (m === null)
+            return null;
+        const from = Number(m[1]);
+        const to = m[2] === undefined ? from : Number(m[2]);
+        if (!Number.isSafeInteger(to) || from < 1 || to < from)
+            return null;
+        spans.push({ from, to });
+    }
+    return spans;
+}
+/** Whether a list names step `n`. */
+export function hasStep(list, n) {
+    return list.some((span) => n >= span.from && n <= span.to);
+}
+/**
+ * Write steps back as an expression in the order given, folding each run that
+ * climbs by one into a span: `[20, 5, 6, 7, 8, 9]` writes `20,5-9`.
+ *
+ * The order is the caller's, because a list has none of its own: the card
+ * writes one in build order, so its first number is where the range starts.
+ */
+export function formatStepList(steps) {
+    const runs = [];
+    for (const n of steps) {
+        const last = runs.at(-1);
+        if (last !== undefined && n === last.to + 1) {
+            last.to = n;
+        }
+        else {
+            runs.push({ from: n, to: n });
+        }
+    }
+    return runs.map(spanText).join(',');
+}
+/**
+ * A list's normal form: its spans sorted and merged, so two ways of typing the
+ * same steps write the same line (`20, 5-9` and `5-9,20` both write `5-9,20`).
+ *
+ * The grant stores this form and never the expansion, so a range of any length
+ * is one short line.
+ */
+export function normalizeStepList(list) {
+    const merged = [];
+    for (const span of [...list].sort((a, b) => a.from - b.from)) {
+        const last = merged.at(-1);
+        if (last !== undefined && span.from <= last.to + 1) {
+            last.to = Math.max(last.to, span.to);
+        }
+        else {
+            merged.push({ from: span.from, to: span.to });
+        }
+    }
+    return merged.map(spanText).join(',');
+}
+/**
+ * The numbers a list names, in the order written, each span walked only while
+ * `known` holds and stopped at the first number it does not, which is kept.
+ *
+ * A build order is a sequence rather than a set, so its spans expand in place
+ * (`1,6,2-4` names 1, 6, 2, 3, 4). The number kept past the plan is the one a
+ * caller reports the plan lacks, and stopping there means `2-100000` costs one
+ * number past the last planned step rather than a hundred thousand.
+ */
+export function expandStepList(list, known) {
+    const numbers = [];
+    for (const span of list) {
+        for (let n = span.from; n <= span.to; n += 1) {
+            numbers.push(n);
+            if (!known(n))
+                break;
+        }
+    }
+    return numbers;
+}
+/** One span as it is typed: a lone number, or `from-to`. */
+function spanText(span) {
+    return span.from === span.to ? String(span.from) : `${span.from}-${span.to}`;
+}
+/**
+ * Read the arguments a build invocation carries, up to the first token that is
+ * not one: `--auto`, or a run of digits, commas, and dashes.
+ *
+ * Once any number carries a comma or a dash, every number and span in the run
+ * joins one list, so `20, 5-9` typed with a space reads as `20,5-9`. Trailing
+ * sentence punctuation is the sentence's (`/build 1-3.`), and so is a comma
+ * after the run's last number (`/build 2, then review`), which separates
+ * nothing.
+ */
+export function readBuildArgs(text) {
+    let auto = false;
+    const words = [];
+    for (const token of text.split(/\s+/)) {
+        const word = token.replace(/[.;:!?]+$/, '');
+        if (word === '')
+            continue;
+        if (word === '--auto') {
+            auto = true;
+            continue;
+        }
+        if (!/^[\d,-]+$/.test(word))
+            break;
+        words.push(word);
+    }
+    const items = words.map((w, i) => (i === words.length - 1 ? w.replace(/,+$/, '') : w)).filter((w) => w !== '');
+    const range = items.some((w) => /[,-]/.test(w));
+    const steps = items.length === 0 ? null : parseStepList(items.join(',').replace(/,{2,}/g, ','));
+    return { auto, range, steps };
+}

package/dist/verbs/abandon.js

@@ -1,11 +1,11 @@
 // `plumbbob abandon`: the third exit from an in-flight step. Checkpoint lands
 // the step and revert destroys the work; abandon drops the attempt but keeps the
 // working-tree diff exactly where it is. Its only writes are the in-flight
-// control markers it clears (STEP, SEAM, TICK, and the step-scoped handoff
-// ledger), a build-log line, and the stats receipt: it touches neither the
-// working tree nor git nor the intent checkbox, so the step stays planned and
-// re-buildable with its diff still in the tree for the human to keep, rework, or
-// commit by hand.
+// control markers it clears (STEP, SEAM, TICK, the PAUSE stamp, and the
+// step-scoped handoff ledger), a build-log line, and the stats receipt: it
+// touches neither the working tree nor git nor the intent checkbox, so the step
+// stays planned and re-buildable with its diff still in the tree for the human
+// to keep, rework, or commit by hand.
 //
 // A step exit is a boundary crossing, so abandon honors the same approval latch
 // as checkpoint. That is not decoration: abandon clears the entry stamp the
@@ -15,11 +15,11 @@
 // control-state clears; abandon itself never calls the raw fs deleters.
 import { readFileSync, writeFileSync } from 'node:fs';
 import { findRepoRoot } from "../lib/git.js";
-import { bumpStepStat, buildLogPath, clearHandoff, clearSeam, clearStep, clearTick, hasSession, intentPath, resolveBuild, stepPath, } from "../lib/sidecar.js";
+import { bumpStepStat, buildLogPath, clearHandoff, clearPause, clearSeam, clearStep, clearTick, hasSession, intentPath, resolveBuild, stepPath, } from "../lib/sidecar.js";
 import { checkLatch } from "../lib/latch.js";
 import { abandonLogLine, appendToSection } from "../lib/buildlog.js";
 import { parseSteps } from "../lib/orient.js";
-import { ending, notice, transition } from "../lib/notice.js";
+import { ending, notice, printEnding, transition } from "../lib/notice.js";
 import { driverPointer } from "./handoff.js";
 /**
  * Drop the in-flight step while keeping its work: latch, clear the markers,
@@ -55,18 +55,23 @@ export function abandon(cwd, args) {
     clearSeam(root, slug);
     clearTick(root, slug);
     clearHandoff(root, slug);
+    clearPause(root, slug);
     bumpStepStat(root, slug, step, 'abandons');
     logAbandon(root, slug, step);
     // A step exit: with the step back at `[ ]` and its markers gone, the pointer
     // aims forward from the boundary, at the very step just dropped.
-    process.stdout.write(ending({
-        lead: transition({
-            label: 'Abandoned',
-            fact: `Step ${step}`,
-            detail: ['work kept in the tree', 'the step stays planned'],
+    printEnding(root, {
+        tier: 'driver',
+        render: 'abandon',
+        text: ending({
+            lead: transition({
+                label: 'Abandoned',
+                fact: `Step ${step}`,
+                detail: ['work kept in the tree', 'the step stays planned'],
+            }),
+            pointer: driverPointer(root, slug),
         }),
-        pointer: driverPointer(root, slug),
-    }));
+    });
     return 0;
 }
 /**

package/dist/verbs/build.js

@@ -8,18 +8,21 @@ import { readFileSync, writeFileSync } from 'node:fs';
 import { findRepoRoot } from "../lib/git.js";
 import { hasSession, intentPath, resolveBuild, seamPath, stampStepStat, stampTick, stepPath } from "../lib/sidecar.js";
 import { parseStepSeam } from "../lib/intent.js";
-import { parseOrderedSteps, skippedBefore } from "../lib/orient.js";
+import { parseBuildRanges, parseOrderedSteps, rangeStanding, rangeStart, skippedBefore } from "../lib/orient.js";
 import { stepLabel, syncBuildLogState } from "../lib/buildlogsync.js";
 import { readGrant } from "../lib/latch.js";
 import { notice } from "../lib/notice.js";
+import { hasStep, readBuildArgs } from "../lib/steplist.js";
 /**
  * Enter step n (or the next undone step) and write its SEAM/STEP markers.
  *
- * Refuses a missing session, a malformed step argument, an `N-M` range (a
- * `/plumbbob:build` skill feature, not a CLI one), and a seam that fails to parse.
+ * Refuses a missing session, a malformed step argument, a range such as `N-M`
+ * or `20,5-9` (a `/plumbbob:build` skill feature, not a CLI one), and a seam
+ * that fails to parse.
  * On entry it stamps the turn ledger and the step's start time, re-renders the
  * build-log's Current step line, and names the step when it is the last one a
- * self-approval grant reaches.
+ * self-approval grant reaches, or, under `--auto`, a call the plan's ranges
+ * reserve for the human.
  */
 export function build(cwd, args) {
     const root = findRepoRoot(cwd);
@@ -29,15 +32,15 @@ export function build(cwd, args) {
     }
     const { build: slug, rest } = resolveBuild(root, args);
     const raw = rest.find((a) => !a.startsWith('--'));
-    // A step range like `1-3` is a `/plumbbob:build` skill affordance (auto-approve
-    // every step through the range's top, then stop), not a CLI capability: the CLI
+    // A step range like `1-3` or `20,5-9` is a `/plumbbob:build` skill affordance
+    // (auto-approve each step it names, then stop), not a CLI capability: the CLI
     // records one in-flight step at a time. Name it rather than bounce off the
-    // generic usage.
-    if (raw !== undefined && /^\d+-\d*$/.test(raw)) {
+    // generic usage, and point at the step the range starts at.
+    if (raw !== undefined && /^\d[\d,-]*$/.test(raw) && /[,-]/.test(raw)) {
         process.stderr.write(notice({
             fact: 'build takes one step number',
             detail: [`\`${raw}\` is a /plumbbob:build range, which auto-approves through its top and then stops`],
-            remedy: `plumbbob build ${raw.split('-')[0]}`,
+            remedy: `plumbbob build ${rangeEntry(intentPath(root, slug), rest.join(' '), raw)}`,
         }));
         return 1;
     }
@@ -100,11 +103,15 @@ export function build(cwd, args) {
         : skipped > 0
             ? ['explicitly requested', `skips ${skipped} undone step${skipped === 1 ? '' : 's'}`]
             : [];
-    // Two lines (three on the last step a grant reaches), one colon each, then
-    // the seam as a plain readout beneath the notice that frames it: the paths
-    // are a list, and a list is not a one-liner.
+    // Two lines (three on the last step a grant reaches, or on a call the plan
+    // reserves), one colon each, then the seam as a plain readout beneath the
+    // notice that frames it: the paths are a list, and a list is not a one-liner.
+    // A reserved call outranks the last-step line, since the step stops at its
+    // pause rather than landing.
+    const grant = readGrant(root);
+    const reserved = grant?.kind === 'auto' ? reservedCallNotice(intent, steps, step) : '';
     process.stdout.write(notice({ fact: `building step ${step}`, detail: picked }) +
-        lastGrantedNotice(readGrant(root), steps, step) +
+        (reserved.length > 0 ? reserved : lastGrantedNotice(grant, steps, step)) +
         notice({
             fact: 'the seam is orientation, not a lock',
             detail: [`${parsed.seam.length} path${parsed.seam.length === 1 ? '' : 's'}`],
@@ -112,6 +119,45 @@ export function build(cwd, args) {
         `${parsed.seam.map((path) => `  ${path}`).join('\n')}\n`);
     return 0;
 }
+/**
+ * The step a range typed at the CLI starts at: its first undone step in build
+ * order when the plan reads, else its first number written.
+ *
+ * Best-effort, since it only fills the refusal's remedy: a plan that cannot be
+ * read, or a range that does not parse, still points at a number the human typed.
+ */
+function rangeEntry(intent, args, raw) {
+    const list = readBuildArgs(args).steps;
+    try {
+        const start = list === null ? null : rangeStart(parseOrderedSteps(readFileSync(intent, 'utf8')), list);
+        if (start !== null)
+            return String(start);
+    }
+    catch {
+        // No plan to order by: fall back to the number typed first.
+    }
+    return /\d+/.exec(raw)?.[0] ?? '1';
+}
+/**
+ * The line saying a step ends at its pause under `--auto`, because the plan's
+ * build ranges name it as a bare range: a call the plan reserves for the
+ * human. '' for any other step.
+ *
+ * The halt is this line's and the skill's, never the latch's: the ranges are
+ * advice, so `--auto` still grants the checkpoint, and saying so as the step
+ * is entered is what puts the stop in front of the model before it lands one.
+ */
+function reservedCallNotice(intent, steps, step) {
+    const { count, holding } = rangeStanding(parseBuildRanges(intent), steps, step);
+    if (holding === null || !holding.bare) {
+        return '';
+    }
+    return notice({
+        fact: `step ${step} ends at its pause, where the plan reserves the call for the human`,
+        detail: [`range ${holding.item} of ${count}`],
+        remedy: 'hold it there for their approval, --auto or not',
+    });
+}
 /**
  * The line naming the last step a self-approval grant reaches this turn, or ''
  * for any other step and when no grant is live.
@@ -123,13 +169,26 @@ export function build(cwd, args) {
  * reaches its top, or the last undone step under its top when the plan ends
  * first, or when the build order puts a number past the top ahead of the rest
  * (a range names plan numbers, and the skill halts before one past its top);
- * `--auto` reaches the plan's last undone step.
+ * `--auto` reaches the plan's last undone step. A range that lists its steps
+ * walks them in build order, so its top is the last undone step it names, and
+ * it reaches no further than a step it does not name.
  */
 function lastGrantedNotice(grant, steps, step) {
     if (grant === null) {
         return '';
     }
     const remedy = 'land it on green, then stop at the boundary';
+    if (grant.kind === 'steps') {
+        if (!hasStep(grant.steps, step))
+            return '';
+        const rest = steps.slice(steps.findIndex((s) => s.n === step) + 1).filter((s) => !s.done && s.n !== step);
+        const after = rest[0];
+        if (after !== undefined && hasStep(grant.steps, after.n))
+            return '';
+        return rest.some((s) => hasStep(grant.steps, s.n))
+            ? notice({ fact: `step ${step} is the last undone step in the range you granted`, remedy })
+            : notice({ fact: `step ${step} is the top of the range you granted`, remedy });
+    }
     if (grant.kind === 'range') {
         if (step === grant.ceiling) {
             return notice({ fact: `step ${step} is the top of the range you granted`, remedy });

package/dist/verbs/checkpoint.js

@@ -12,7 +12,7 @@
 import { appendFileSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { relative } from 'node:path';
 import { commit, findRepoRoot, headSha, isDirty, stageAll, stagePath, stagedPaths, stagedStat } from "../lib/git.js";
-import { activeBuild, buildFolder, buildLogPath, buildScope, bumpStepStat, checkpointsPath, clearDetail, clearHandoff, clearTick, detailPath, hasSession, intentPath, readStats, refreshExcludes, seamPath, stampStepStat, stepPath, } from "../lib/sidecar.js";
+import { activeBuild, buildFolder, buildLogPath, buildScope, bumpStepStat, checkpointsPath, clearDetail, clearHandoff, clearPause, clearTick, detailPath, 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";
@@ -21,7 +21,7 @@ import { parseBuildScope, parseStepSeam, scopeDrift } from "../lib/intent.js";
 import { conventionalSubject, subjectFromTitle, withMarker } from "../lib/commitmsg.js";
 import { appendToSection, checkpointLogLine, logEntry, planLogLine } from "../lib/buildlog.js";
 import { AT_BOUNDARY, syncBuildLogState } from "../lib/buildlogsync.js";
-import { advisory, ending, notice, transition } from "../lib/notice.js";
+import { advisory, ending, notice, printEnding, transition } from "../lib/notice.js";
 import { boundaryEnding, planRecord, stepRecord } from "./handoff.js";
 /**
  * Land a step: latch, check gate, commit, record, return to the boundary.
@@ -116,17 +116,23 @@ export async function checkpoint(cwd, args) {
     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.
+    clearPause(root); // the pause it stamped is over; the next step's pause renders whole.
     // The whole ending, one block: the lead line, the Verdict folded over what
     // just landed, the advisories this checkpoint alone can state, and the
     // pointer. Read after the flip and the ledger append, so the fold and the
     // pointer both see the boundary the human is standing at.
     const landed = boundaryEnding(root, activeBuild(root), step);
-    process.stdout.write(ending({
-        lead: transition({ label: 'Checkpoint', fact: `Step ${step} complete`, detail: leadDetail(sha, pointer) }),
-        verdict: landed.verdict,
-        advisories: [drift, flipNotice],
-        pointer: landed.pointer,
-    }));
+    printEnding(root, {
+        tier: 'orientation',
+        render: 'checkpoint',
+        text: ending({
+            lead: transition({ label: 'Checkpoint', fact: `Step ${step} complete`, detail: leadDetail(sha, pointer) }),
+            verdict: landed.verdict,
+            advisories: [drift, flipNotice],
+            stop: landed.stop,
+            pointer: landed.pointer,
+        }),
+    });
     return 0;
 }
 /**
@@ -172,19 +178,23 @@ function checkpointPlan(root, args) {
     clearTick(root);
     // No Verdict: the plan commit measures nothing. The pointer aims at the step
     // the build starts on, which is what `handoff` renders from a null step.
-    process.stdout.write(ending({
-        lead: transition({ label: 'Plan', fact: 'committed', detail: leadDetail(sha, pointer) }),
-        advisories: staged
-            ? []
-            : [
-                advisory({
-                    fact: 'the plan rides the commit message',
-                    detail: ['record-only', '.plumbbob/ is gitignored, so the files stay untracked'],
-                    remedy: 'unignore .plumbbob/builds/ to keep the record in the tree',
-                }),
-            ],
-        pointer: boundaryEnding(root, activeBuild(root), null).pointer,
-    }));
+    printEnding(root, {
+        tier: 'orientation',
+        render: 'plan-commit',
+        text: ending({
+            lead: transition({ label: 'Plan', fact: 'committed', detail: leadDetail(sha, pointer) }),
+            advisories: staged
+                ? []
+                : [
+                    advisory({
+                        fact: 'the plan rides the commit message',
+                        detail: ['record-only', '.plumbbob/ is gitignored, so the files stay untracked'],
+                        remedy: 'unignore .plumbbob/builds/ to keep the record in the tree',
+                    }),
+                ],
+            pointer: boundaryEnding(root, activeBuild(root), null).pointer,
+        }),
+    });
     return 0;
 }
 /**