plumbbob 0.12.0 → 0.13.0

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.
@@ -536,6 +551,131 @@ 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.
+    }
+}
+/**
+ * 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.
@@ -600,16 +740,22 @@ export function excludeControl(root) {
         `${DIRNAME}/TURN`,
         `${DIRNAME}/GRANT`,
         // 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/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,7 +8,7 @@ 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 { parseSteps } from "../lib/orient.js";
+import { parseOrderedSteps, skippedBefore } from "../lib/orient.js";
 import { stepLabel, syncBuildLogState } from "../lib/buildlogsync.js";
 import { readGrant } from "../lib/latch.js";
 import { notice } from "../lib/notice.js";
@@ -18,8 +18,8 @@ import { notice } from "../lib/notice.js";
  * 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.
  * On entry it stamps the turn ledger and the step's start time, re-renders the
- * build-log's Current step line, and says so when the step is the top of a
- * range the human typed.
+ * build-log's Current step line, and names the step when it is the last one a
+ * self-approval grant reaches.
  */
 export function build(cwd, args) {
     const root = findRepoRoot(cwd);
@@ -48,7 +48,9 @@ export function build(cwd, args) {
         return 1;
     }
     const intent = readFileSync(intentPath(root, slug), 'utf8');
-    const steps = parseSteps(intent);
+    // In build order: the sequence `## Build order` declares when a refined plan
+    // has one, else the numbering, so this pick and the dashboard's agree.
+    const steps = parseOrderedSteps(intent);
     // No argument ⇒ enter the next undone step in intent.md (the same idiom
     // `checkpoint` uses), so a bare `plumbbob build` advances the loop without the
     // skill re-deriving the step in prose. Every step checkpointed ⇒ a `/plumbbob:step`
@@ -89,30 +91,20 @@ export function build(cwd, args) {
     const title = steps.find((s) => s.n === step)?.title ?? null;
     syncBuildLogState(root, slug, stepLabel(step, title));
     // An explicit jump past undone work says so out loud: the entered step and
-    // the count it skips read back to the human (and to the transcript), so a
-    // deliberate `build 22` and a confused one look different on the page.
-    const skipped = raw === undefined ? 0 : steps.filter((s) => !s.done && s.n < step).length;
+    // the count it skips (the undone steps ahead of it in build order) read back
+    // to the human (and to the transcript), so a deliberate `build 22` and a
+    // confused one look different on the page.
+    const skipped = raw === undefined ? 0 : skippedBefore(steps, step).length;
     const picked = raw === undefined
         ? ['next undone']
         : skipped > 0
             ? ['explicitly requested', `skips ${skipped} undone step${skipped === 1 ? '' : 's'}`]
             : [];
-    // The top step of a typed range lands like every step under it, and the turn
-    // ends on its checkpoint. Saying so as the step is entered puts that fact in
-    // front of the model before it chooses between landing the step and holding
-    // it at a pause, which is the choice a range kept getting wrong.
-    const grant = readGrant(root);
-    const top = grant?.kind === 'range' && grant.ceiling === step
-        ? notice({
-            fact: `step ${step} is the top of the range you granted`,
-            remedy: 'land it on green, then stop at the boundary',
-        })
-        : '';
-    // Two lines (three at a range's top), 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), 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.
     process.stdout.write(notice({ fact: `building step ${step}`, detail: picked }) +
-        top +
+        lastGrantedNotice(readGrant(root), steps, step) +
         notice({
             fact: 'the seam is orientation, not a lock',
             detail: [`${parsed.seam.length} path${parsed.seam.length === 1 ? '' : 's'}`],
@@ -120,3 +112,34 @@ export function build(cwd, args) {
         `${parsed.seam.map((path) => `  ${path}`).join('\n')}\n`);
     return 0;
 }
+/**
+ * The line naming the last step a self-approval grant reaches this turn, or ''
+ * for any other step and when no grant is live.
+ *
+ * That step lands like every step before it, and then the turn ends on its
+ * checkpoint: a clean halt. Saying so as the step is entered puts the fact in
+ * front of the model before it chooses between landing the step and holding it
+ * at a pause, which is the choice a clean halt kept getting wrong. A range
+ * 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.
+ */
+function lastGrantedNotice(grant, steps, step) {
+    if (grant === null) {
+        return '';
+    }
+    const remedy = 'land it on green, then stop at the boundary';
+    if (grant.kind === 'range') {
+        if (step === grant.ceiling) {
+            return notice({ fact: `step ${step} is the top of the range you granted`, remedy });
+        }
+        const after = steps.slice(steps.findIndex((s) => s.n === step) + 1).find((s) => !s.done);
+        const more = after !== undefined && after.n <= grant.ceiling;
+        return step < grant.ceiling && !more
+            ? notice({ fact: `step ${step} is the last undone step in the range you granted`, remedy })
+            : '';
+    }
+    const more = steps.some((s) => !s.done && s.n !== step);
+    return more ? '' : notice({ fact: `step ${step} is the last undone step in the plan`, remedy });
+}

package/dist/verbs/checkpoint.js

@@ -3,7 +3,7 @@
 // `/plumbbob:build` run, your own hands, a vibe session, or another harness all
 // checkpoint identically. It does NOT require a STEP marker (the flat control
 // file recording the step in flight): the step is whatever you pass, else the
-// in-flight STEP, else the next undone step in intent.md. It evaluates the
+// in-flight STEP, else the next undone step in intent.md's build order. It evaluates the
 // approval latch, gates on a green check, commits any pending work (or records
 // the existing HEAD when the tree is already clean: the human's commit skill
 // may have committed first), records the SHA, flips the intent checkbox to
@@ -12,16 +12,16 @@
 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";
-import { markStepDone, parseDetailStep, parseSteps } from "../lib/orient.js";
+import { markStepDone, parseDetailStep, parseOrderedSteps, parseSteps } from "../lib/orient.js";
 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,22 @@ 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],
+            pointer: landed.pointer,
+        }),
+    });
     return 0;
 }
 /**
@@ -172,19 +177,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;
 }
 /**
@@ -200,7 +209,7 @@ function planSubject(root) {
 /**
  * Resolve the step being checkpointed, or null when none can be determined.
  *
- * Explicit arg > in-flight STEP file > first undone step in intent.md. A `-m`
+ * Explicit arg > in-flight STEP file > first undone step in build order. A `-m`
  * value is a message, never a step: `checkpoint -m "2"` must not read as
  * step 2.
  */
@@ -214,7 +223,7 @@ function resolveStep(root, args) {
         return inFlight;
     }
     try {
-        return parseSteps(readFileSync(intentPath(root), 'utf8')).find((s) => !s.done)?.n ?? null;
+        return parseOrderedSteps(readFileSync(intentPath(root), 'utf8')).find((s) => !s.done)?.n ?? null;
     }
     catch {
         return null;

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;
 }
 /**