plumbbob 0.13.1 → 0.13.2

package/dist/lib/orient.js

@@ -3,7 +3,7 @@
 // one suggested next move. Pure and best-effort by design: it takes raw file
 // contents (no fs), and a malformed document degrades to fewer fields rather
 // than throwing.
-import { parseStepSeam, scopeDrift } from "./intent.js";
+import { isArtifactPath, parseStepSeam, scopeDrift } from "./intent.js";
 import { expandStepList, formatStepList, hasStep, normalizeStepList, parseStepList, readBuildArgs, } from "./steplist.js";
 /**
  * The lines of a named `## Section`, from its heading to the next `## ` (or
@@ -106,15 +106,19 @@ export function parseBuildOrder(intent) {
     return expandStepList(list, (n) => planned.has(n));
 }
 /**
- * The steps in build order: the numbers `order` lists first, in that sequence,
- * then every step it leaves out, in document order.
+ * The steps in build order: the landed steps `order` leaves out, then the
+ * numbers it lists, in that sequence, then the undone steps it leaves out,
+ * each left-out group in document order.
  *
- * A listed number takes the first step in document order that carries it, and
- * a repeat of the number is ignored, so a doubled entry cannot double a step; a
- * number no step carries is dropped. An empty order is the identity, which is
- * what a plan with no `## Build order` section reads as. The steps themselves
- * never change, only the sequence, so `n`, `line`, and `done` stay what
- * `parseSteps` read.
+ * `plumbbob order` lists undone steps only, so a landed step the line leaves
+ * out landed before the line was written, and it reads as built ahead of the
+ * line rather than after it; the undone sequence is the same either way. A
+ * listed number takes the first step in document order that carries it, and a
+ * repeat of the number is ignored, so a doubled entry cannot double a step; a
+ * number no step carries is dropped. An order that names no step, an empty one
+ * included, is the identity, which is what a plan with no `## Build order`
+ * section reads as. The steps themselves never change, only the sequence, so
+ * `n`, `line`, and `done` stay what `parseSteps` read.
  */
 export function orderSteps(steps, order) {
     const taken = new Set();
@@ -126,7 +130,11 @@ export function orderSteps(steps, order) {
             ordered.push(step);
         }
     }
-    return [...ordered, ...steps.filter((s) => !taken.has(s))];
+    const rest = steps.filter((s) => !taken.has(s));
+    if (ordered.length === 0) {
+        return rest;
+    }
+    return [...rest.filter((s) => s.done), ...ordered, ...rest.filter((s) => !s.done)];
 }
 /**
  * The plan's steps in build order: `parseSteps` merged with `parseBuildOrder`.
@@ -159,10 +167,14 @@ export function remainingOrder(steps, order, exclude) {
     return byOrder.some((n, i) => n !== byDocument[i]) ? byOrder : [];
 }
 /**
- * The build order as a phrase: the next `cap` step numbers in sequence, the
- * rest folded to a count (`and 2 more`), the way a long detail degrades on
- * every one-liner; '' for an empty order. With no cap, the whole sequence,
- * which is the dashboard's row.
+ * The build order as the note's labeled field: `order:`, then the next `cap`
+ * step numbers in sequence, the rest folded to a count (`and 2 more`), the way
+ * a long detail degrades on every one-liner; '' for an empty order. With no
+ * cap, the whole sequence.
+ *
+ * A label, where the phrase once read `build order 7, 8, 5`, because the
+ * note's other segments read as labeled fields and a label is how the eye
+ * finds one in a line of three (D108 (order-label)).
  */
 export function buildOrderPhrase(order, cap) {
     if (order.length === 0) {
@@ -170,7 +182,7 @@ export function buildOrderPhrase(order, cap) {
     }
     const shown = cap === undefined ? order : order.slice(0, cap);
     const rest = order.length - shown.length;
-    return `build order ${shown.join(', ')}${rest > 0 ? ` (and ${rest} more)` : ''}`;
+    return `order: ${shown.join(', ')}${rest > 0 ? ` (and ${rest} more)` : ''}`;
 }
 /**
  * Write `order` as the one numeric line under `## Build order`: in place of
@@ -351,35 +363,56 @@ export function rangeStanding(plan, ordered, step) {
     };
 }
 /** Whether a range has landed: the plan holds a step it names, and every one it holds is done. */
-function rangeLanded(range, ordered) {
+export function rangeLanded(range, ordered) {
     const held = ordered.filter((s) => hasStep(range.steps, s.n));
     return held.length > 0 && held.every((s) => s.done);
 }
 /**
- * The ranges block the dashboard renders, and the move it suggests: the range
- * holding the next undone step and the command that runs what is left of it.
+ * The ranges block the dashboard renders, and the moves it suggests: the run
+ * of the range holding the next undone step, with what is left of it, and the
+ * stop card of the landed range `waiting` names.
  *
- * Null for a plan without ranges, so the block vanishes. The move is null when
- * the next step sits in no range, its range is flagged, or the step is still
- * unplanned, which leaves the dashboard's own step move in charge.
+ * Null for a plan without ranges, so the block vanishes. The run's move is
+ * null when the next step sits in no range, its range is flagged, or the step
+ * is still unplanned, which leaves the dashboard's own step move in charge.
+ * The card's move is null unless `waiting` names a range that parses and
+ * reads as landed, so a range re-cut to take a new step stops waiting.
  */
-function rangesView(intent, ordered, next) {
+function rangesView(intent, ordered, next, waiting) {
     const plan = parseBuildRanges(intent);
     const standing = rangeStanding(plan, ordered, next?.n ?? null);
     if (standing.count === 0) {
-        return { view: null, move: null };
+        return { view: null, move: null, waitingMove: null };
     }
     const own = (item) => standing.drift.filter((d) => d.item === item && d.kind !== 'malformed');
-    const rows = plan.ranges.map((range) => ({
-        range,
-        landed: rangeLanded(range, ordered),
-        next: range === standing.holding,
-        drift: own(range.item).map((d) => d.words),
-    }));
+    const rows = plan.ranges.map((range) => {
+        const landed = rangeLanded(range, ordered);
+        return { range, landed, next: range === standing.holding, waiting: landed && range.item === waiting, drift: own(range.item).map((d) => d.words) };
+    });
     const view = { count: standing.count, rows, plan: standing.drift.filter((d) => d.item === null || d.kind === 'malformed').map((d) => d.words) };
-    const { holding, command } = standing;
-    const move = holding === null || command === null || next?.planned !== true ? null : `build range ${holding.item} of ${standing.count} — \`${command}\``;
-    return { view, move };
+    const run = resolveRun({ intent, inFlight: null, spiking: false, item: null });
+    const card = rows.find((r) => r.waiting);
+    return {
+        view,
+        move: !run.ok || next?.planned !== true ? null : runMove(run),
+        waitingMove: card === undefined ? null : stopCardMove(card.range.item, standing.count, stopFollowUp(intent)),
+    };
+}
+/**
+ * The dashboard's pointer while a stop card waits: the card, and in its
+ * bracket the reply that records it from any session, the next range's run or
+ * the finish on the plan's last range, or the way back to the card when the
+ * next run would refuse. `looks good` is never named, since it records only
+ * with the card in the conversation.
+ */
+function stopCardMove(item, count, follow) {
+    const card = `reply to range ${item} of ${count}'s stop card`;
+    if (follow === null) {
+        return `${card} (\`show the stop\` brings it back)`;
+    }
+    return follow === 'finish'
+        ? `${card} (\`/plumbbob:finish\` records it, then writes the report)`
+        : `${card} (\`/plumbbob:run\` records it, then runs range ${follow.range.item} of ${follow.count})`;
 }
 /**
  * What is left of a range as the steps of a command: a landing range's last
@@ -454,15 +487,20 @@ function sharedDrift(range, ranges, ordered) {
 }
 /**
  * A range the build order cuts short: an undone step it does not name, placed
- * between two of its own, where a run of the range halts.
+ * between its first step and its last undone one, where a run of the range
+ * halts.
  *
- * An outside step ahead of the range's first step builds first and cuts
- * nothing, and the card names its range before this one.
+ * The span opens at the range's first step, landed or not, so a range a run
+ * halted inside stays flagged until the step that halted it lands. It ends at
+ * the range's last undone step, since a step placed after every one of them
+ * cuts nothing short, and a range with none left reports nothing. An outside
+ * step ahead of the range's first step builds first and cuts nothing, and the
+ * card names its range before this one.
  */
 function insideDrift(range, ordered) {
     const first = ordered.findIndex((s) => hasStep(range.steps, s.n));
-    const last = ordered.findLastIndex((s) => hasStep(range.steps, s.n));
-    const inside = first === -1 ? [] : ordered.slice(first + 1, last).filter((s) => !s.done && !hasStep(range.steps, s.n));
+    const last = ordered.findLastIndex((s) => !s.done && hasStep(range.steps, s.n));
+    const inside = last === -1 ? [] : ordered.slice(first + 1, last).filter((s) => !s.done && !hasStep(range.steps, s.n));
     if (inside.length === 0) {
         return [];
     }
@@ -477,6 +515,243 @@ function stepPhrase(items) {
     const one = items.length === 1 && /^\d+$/.test(items[0] ?? '');
     return { words: `${one ? 'step' : 'steps'} ${items.join(', ')}`, be: one ? 'is' : 'are' };
 }
+// --- The run: what `/plumbbob:run` names. The turn hook reads it to mint the
+// run's grant, `status --run` to print the run header, and the card to name the
+// run beneath Next Up, so all three read one answer from one plan. ---
+/**
+ * The range a run's arguments name, read from the one token after the verb:
+ * a range number names that range, and anything else, nothing included, names
+ * the range holding the next step.
+ *
+ * `--auto` beside the verb adds nothing, so it is passed over. Numbers joined
+ * by a dash or a comma are a span or a list of ranges (`2-4`, `2, 3`), a form
+ * no run defines, and read as null, so nothing is minted or resolved for them.
+ * Trailing sentence punctuation is the sentence's, and so is a comma after the
+ * last number (`/plumbbob:run 3, then review`), as it is after a build's.
+ */
+export function readRunArgs(text) {
+    const words = [];
+    for (const token of text.split(/\s+/)) {
+        const word = token.replace(/[.;:!?]+$/, '');
+        if (word === '' || word === '--auto') {
+            continue;
+        }
+        if (!/^[\d,-]+$/.test(word)) {
+            break;
+        }
+        words.push(word);
+    }
+    const run = words.join(' ').replace(/,+$/, '');
+    if (/[,-]/.test(run)) {
+        return null;
+    }
+    return { item: run === '' ? null : Number(run.split(' ')[0]) };
+}
+/**
+ * The range a run names and what is left of it, or the refusal that says why
+ * it names nothing it can walk.
+ *
+ * A step in flight decides the run: with no number typed, the run names the
+ * range holding that step, or with none in flight the range holding the next
+ * undone step in build order; a number names that range, and refuses when the
+ * range does not hold the step in flight. What is left counts the step in
+ * flight as undone and leads with it, since a run that started elsewhere would
+ * rewrite the step markers and sweep its half-built diff into another step's
+ * commit. A spike open refuses every run, and nothing left refuses before the
+ * ranges are read. The ranges are read through `rangeStanding`, so the run
+ * and the card name the same range and the same drift.
+ */
+export function resolveRun(input) {
+    if (input.spiking) {
+        return { ok: false, kind: 'spike' };
+    }
+    const ordered = parseOrderedSteps(input.intent);
+    const anchor = input.inFlight ?? ordered.find((s) => !s.done)?.n ?? null;
+    if (anchor === null) {
+        return { ok: false, kind: 'finished' };
+    }
+    const plan = parseBuildRanges(input.intent);
+    const standing = rangeStanding(plan, ordered, anchor);
+    const { count } = standing;
+    if (count === 0) {
+        return { ok: false, kind: 'no-ranges', step: anchor };
+    }
+    if (input.item === null) {
+        const { holding } = standing;
+        // With no range that parses, no step sits outside one, so the words are
+        // the first item's that does not.
+        const words = standing.flag ?? standing.drift.find((d) => d.kind === 'malformed')?.words ?? noRangeWords([anchor]);
+        return holding === null
+            ? { ok: false, kind: 'uncovered', step: anchor, words }
+            : walkRun(holding, standing, ordered, input.inFlight);
+    }
+    const item = input.item;
+    const range = plan.ranges.find((r) => r.item === item);
+    if (range === undefined) {
+        const malformed = standing.drift.find((d) => d.kind === 'malformed' && d.item === item);
+        return malformed === undefined
+            ? { ok: false, kind: 'missing', item, instead: resolveRun({ ...input, item: null }) }
+            : { ok: false, kind: 'flagged', item, count, words: malformed.words };
+    }
+    if (rangeLanded(range, ordered)) {
+        return { ok: false, kind: 'landed', item, count, instead: resolveRun({ ...input, item: null }) };
+    }
+    if (input.inFlight !== null && !hasStep(range.steps, input.inFlight)) {
+        return { ok: false, kind: 'in-flight', step: input.inFlight, holding: standing.holding?.item ?? null, count };
+    }
+    return walkRun(range, standing, ordered, input.inFlight);
+}
+/**
+ * A range as a run walks it: what is left of it, led by the step in flight,
+ * and the grant the hook mints; or the flagged refusal when the range's own
+ * drift names it.
+ */
+function walkRun(range, standing, ordered, inFlight) {
+    const flag = standing.drift.find((d) => d.item === range.item && d.kind !== 'malformed');
+    if (flag !== undefined) {
+        return { ok: false, kind: 'flagged', item: range.item, count: standing.count, words: flag.words };
+    }
+    const undone = ordered.filter((s) => hasStep(range.steps, s.n) && (!s.done || s.n === inFlight)).map((s) => s.n);
+    const left = inFlight !== null && undone.includes(inFlight) ? [inFlight, ...undone.filter((n) => n !== inFlight)] : undone;
+    return {
+        ok: true,
+        range,
+        count: standing.count,
+        left,
+        steps: formatStepList(left),
+        grant: range.bare ? null : `steps ${normalizeStepList(left.map((n) => ({ from: n, to: n })))}`,
+    };
+}
+/**
+ * The run a skill invocation's raw arguments name, read as the turn hook reads
+ * them: `readRunArgs`, then `resolveRun`. A span or a list of ranges names no
+ * run, and refuses with the run a bare `/plumbbob:run` names in its place.
+ */
+export function resolveRunArgs(text, build) {
+    const args = readRunArgs(text);
+    if (args === null) {
+        return { ok: false, kind: 'span', instead: resolveRun({ ...build, item: null }) };
+    }
+    return resolveRun({ ...build, item: args.item });
+}
+/**
+ * What is left of a run, as its bracket and its header write it: `steps 6-9`,
+ * `steps 20,5-9`, or `step 9` for one step.
+ */
+export function runSteps(run) {
+    return `${run.left.length === 1 ? 'step' : 'steps'} ${run.steps}`;
+}
+/**
+ * What the card's bracket says the run lands: what is left of it, and for a
+ * bare range that it builds the step to its pause (`step 10 to its pause`).
+ */
+export function runBracket(run) {
+    return run.range.bare ? `${runSteps(run)} to its pause` : runSteps(run);
+}
+/**
+ * The move after a stop, the one the stop card's second row, the dashboard's
+ * waiting pointer, and `plumbbob build`'s refusal all name: the run a bare
+ * `/plumbbob:run` names, `'finish'` once no step is left, or null when the
+ * next run would refuse, where a reply records the card and nothing more.
+ */
+export function stopFollowUp(intent) {
+    const run = resolveRun({ intent, inFlight: null, spiking: false, item: null });
+    if (run.ok) {
+        return run;
+    }
+    return run.kind === 'finished' ? 'finish' : null;
+}
+/**
+ * The pointer naming a run: the range and its count, the run's command, and
+ * the bracket, with a note beside the steps when one is given.
+ */
+export function runMove(run, note) {
+    return `run range ${run.range.item} of ${run.count} — \`/plumbbob:run\` (${runBracket(run)}${note === undefined ? '' : `; ${note}`})`;
+}
+/**
+ * The dashboard's pointer for a run that names nothing it can walk, in the
+ * dashboard's own register: the refusal and the move that unblocks it. Null
+ * for nothing left, whose move is the dashboard's own ending, which a run adds
+ * nothing to.
+ */
+export function runRefusalMove(refusal) {
+    const recut = 're-cut the ranges — `/plumbbob:refine ranges`';
+    switch (refusal.kind) {
+        case 'spike':
+            return 'close the spike — `plumbbob spike done`';
+        case 'finished':
+            return null;
+        case 'no-ranges':
+            return `cut the ranges — \`/plumbbob:refine ranges\` (the plan declares none; \`/plumbbob:build\` builds step ${refusal.step} alone)`;
+        case 'uncovered':
+            return `${recut} (${refusal.words})`;
+        case 'flagged':
+            return `${recut} (range ${refusal.item} of ${refusal.count} needs a re-cut: ${refusal.words})`;
+        case 'landed':
+            return insteadMove(refusal.instead, `range ${refusal.item} of ${refusal.count} has landed`);
+        case 'missing':
+            return insteadMove(refusal.instead, `the plan has no range ${refusal.item}`);
+        case 'span':
+            return insteadMove(refusal.instead, 'a run names one range');
+        case 'in-flight': {
+            const holds = refusal.holding === null ? 'no range names it' : `a run names range ${refusal.holding} of ${refusal.count}, which holds it`;
+            return `finish step ${refusal.step} — \`/plumbbob:verify\` (or \`/plumbbob:abandon\` it; ${holds})`;
+        }
+    }
+}
+/**
+ * The pointer at the run a bare `/plumbbob:run` names, carrying why the typed
+ * one was refused, or that run's own refusal when it names nothing either.
+ */
+function insteadMove(instead, note) {
+    return instead.ok ? runMove(instead, note) : runRefusalMove(instead);
+}
+/**
+ * The three-line header `status --run` prints above the dashboard: the range,
+ * what is left of it, and where the run ends; its stop; and the grant the
+ * hook minted, held against the one the run would mint.
+ *
+ * `grant` is the GRANT file's content in its normal form, or null when none
+ * stands. The grant line is the one the run skill trusts over the two above
+ * it, since the hook read the plan the human typed against, so it says when
+ * the two differ rather than choosing between them.
+ */
+export function formatRunHeader(run, grant) {
+    const last = run.left.at(-1) ?? run.range.steps[0]?.from;
+    const ends = run.range.bare ? `ends at step ${last}'s pause` : `ends at step ${last}'s boundary`;
+    return [
+        `run  range ${run.range.item} of ${run.count} · ${runSteps(run)} · ${ends}`,
+        `     stop: ${run.range.stop}`,
+        `     grant: ${grantWords(run, grant)}`,
+    ].join('\n');
+}
+/**
+ * The grant line's value: the grant as the hook minted it, `none` with its
+ * reason, or the grant marked unlike the run.
+ */
+function grantWords(run, grant) {
+    if (grant === null) {
+        return run.grant === null ? 'none, as a bare range builds to its pause' : 'none';
+    }
+    return grant === run.grant ? grant : `${grant}, unlike the run`;
+}
+/**
+ * The dashboard `status --run` prints for a run: beneath the run header, with
+ * the run's first step marked `← requested` and the pointer naming the run;
+ * or, for a run that names nothing it can walk, the dashboard as it renders
+ * without the flag, its pointer carrying the refusal. Nothing left keeps the
+ * dashboard's own pointer, which names the stop card while one waits on the
+ * plan's last range, its bracket the finish that records it.
+ */
+export function formatRunDashboard(input, run, grant) {
+    if (!run.ok) {
+        const plain = orient({ ...input, requested: null });
+        return formatOrientation({ ...plain, next: runRefusalMove(run) ?? plain.next });
+    }
+    const first = run.left[0] ?? null;
+    const repointed = orient({ ...input, requested: first === null ? null : [{ from: first, to: first }] });
+    return `${formatRunHeader(run, grant)}\n\n${formatOrientation({ ...repointed, next: runMove(run) })}`;
+}
 /**
  * Flip step N's `[ ]` checkbox to `[x]` within the `## Steps` section.
  *
@@ -712,9 +987,13 @@ export function orient(input) {
     const seamParse = target === undefined ? null : parseStepSeam(input.intent, target.n);
     const phase = input.spiking ? 'SPIKE' : input.inFlight !== null ? 'BUILD' : 'DESIGN';
     // At the boundary with nothing asked for, the move names the range holding
-    // the next step; a spike, a step in flight, or a request keeps its own.
-    const ranges = rangesView(input.intent, ordered, nextUndone);
-    const atBoundary = !input.spiking && input.inFlight === null && requested === null;
+    // the next step; a spike, a step in flight, or a request keeps its own. A
+    // stop card waiting for its reply outranks the run and a request, since a
+    // step entered now would write over the range's review; a spike and a step
+    // in flight still keep theirs.
+    const ranges = rangesView(input.intent, ordered, nextUndone, input.waiting);
+    const idle = !input.spiking && input.inFlight === null;
+    const atBoundary = idle && requested === null;
     return {
         title: parseTitle(input.intent),
         phase,
@@ -723,7 +1002,9 @@ export function orient(input) {
         parked: parks.open,
         parkedTotal: parks.total,
         openQuestions: parseOpenQuestions(input.intent),
-        next: (atBoundary ? ranges.move : null) ?? nextMove(input.spiking, ordered, input.inFlight, parks.open, requested),
+        next: (idle ? ranges.waitingMove : null) ??
+            (atBoundary ? ranges.move : null) ??
+            nextMove(input.spiking, ordered, input.inFlight, parks.open, requested),
         nextUndone: nextUndone?.n ?? null,
         buildOrder: remainingOrder(steps, order, null),
         ranges: ranges.view,
@@ -773,19 +1054,24 @@ function classifyRecapRow(name, value) {
  * `── recap · step N of M ──` header, the (subset of) five measuring rows
  * present, and the free-text diff row. Null when no header is found.
  *
+ * A range's detail opens its rows under `── recap · range N of M ──` instead,
+ * and only the `range` scope reads that header, so a step pause never takes a
+ * stop's judgment rows for its own, and the stop card never takes a step's.
+ *
  * A row absent from the block is simply missing from `rows`: a vanished row
  * the fold treats exactly like one that never applied, never like a failure.
  * An indented `- ` or `→ ` line attaches to the row above it, which is how a
  * row carrying two or more items, or a pointer at its evidence, survives the
  * round trip through the file.
  */
-export function parseRecap(detail) {
+export function parseRecap(detail, scope = 'step') {
     const lines = detail.split('\n');
-    const headerIdx = lines.findIndex((l) => /^──\s*recap\s*·\s*step\s+\d+\s+of\s+\d+\s*──$/.test(l.trim()));
+    const opener = new RegExp(`^──\\s*recap\\s*·\\s*${scope}\\s+\\d+\\s+of\\s+\\d+\\s*──$`);
+    const headerIdx = lines.findIndex((l) => opener.test(l.trim()));
     if (headerIdx === -1) {
         return null;
     }
-    const header = /step\s+(\d+)\s+of\s+(\d+)/.exec(lines[headerIdx] ?? '');
+    const header = new RegExp(`${scope}\\s+(\\d+)\\s+of\\s+(\\d+)`).exec(lines[headerIdx] ?? '');
     if (header === null) {
         return null;
     }
@@ -824,7 +1110,7 @@ export function parseRecap(detail) {
             }
         }
     }
-    return { step: Number(header[1]), total: Number(header[2]), rows, diff };
+    return { n: Number(header[1]), total: Number(header[2]), rows, diff };
 }
 const PLUMB = { glyph: '●', state: 'Plumb' };
 const A_HAIR_OFF = { glyph: '◐', state: 'A hair off' };
@@ -842,8 +1128,13 @@ const NOT_STANDING = { glyph: '✗', state: 'Not standing' };
  * carries the stray; at the boundary the tree is clean, the row has vanished,
  * and the stat the checkpoint bumped carries it instead. Both name it
  * `seam strayed`, so the rung does not change between the two.
+ *
+ * A stop card folds a range the same way, its stats summed across the steps,
+ * and only the revert's words change with the scope (`1 revert in the
+ * range`), since the other advisories already read across whatever they
+ * count.
  */
-export function foldVerdict(rows, stats) {
+export function foldVerdict(rows, stats, scope = 'step') {
     for (const name of RECAP_ROW_NAMES) {
         if (rows[name]?.verdict === 'drift') {
             return { ladder: NOT_STANDING, worst: `${name} drifted` };
@@ -871,7 +1162,8 @@ export function foldVerdict(rows, stats) {
         return { ladder: A_HAIR_OFF, worst: `${stats.redChecks} red run${stats.redChecks === 1 ? '' : 's'} before green` };
     }
     if (stats.reverts > 0) {
-        return { ladder: A_HAIR_OFF, worst: `${stats.reverts} revert${stats.reverts === 1 ? '' : 's'} on this step` };
+        const where = scope === 'range' ? 'in the range' : 'on this step';
+        return { ladder: A_HAIR_OFF, worst: `${stats.reverts} revert${stats.reverts === 1 ? '' : 's'} ${where}` };
     }
     if (stats.outOfBand > 0) {
         return { ladder: A_HAIR_OFF, worst: `${stats.outOfBand} commit${stats.outOfBand === 1 ? '' : 's'} outside the ledger` };
@@ -898,15 +1190,20 @@ const CHECK_SUMMARY = '.check/summary.json';
  * Red expands where green collapses: one failing slot is named in the row and
  * its raw output is the `→` pointer, and two or more collapse to a count with
  * one `- ` line per slot.
+ *
+ * A stop card passes the range's `landings`, and a green row counts them
+ * behind the gate's size: every landing passed the gate, since the checkpoint
+ * refuses on red.
  */
-export function summaryCheckRow(summary) {
+export function summaryCheckRow(summary, landings = 0) {
     const ran = summary.checks.filter((c) => c.skipped !== true);
     const skipped = summary.checks.filter((c) => c.skipped === true).map((c) => c.name);
     const named = skipped.length === 0 ? '' : ` · without ${skipped.join(', ')}`;
     const counted = skipped.length === 0 ? '' : ` · without ${skipped.length} others`;
     const fit = (long, short) => (long.length <= RECAP_VALUE_BUDGET ? long : short);
     if (summary.ok) {
-        const size = `${ran.length} of ${summary.checks.length} checks`;
+        const landed = landings === 0 ? '' : `, ${landings} landing${landings === 1 ? '' : 's'}`;
+        const size = `${ran.length} of ${summary.checks.length} checks${landed}`;
         return { verdict: 'true', word: 'green', evidence: fit(`green: ${size}${named}`, `green: ${size}${counted}`) };
     }
     const failing = ran.filter((c) => !c.ok);
@@ -1023,8 +1320,16 @@ function elapsedSpent(input) {
         return null;
     }
     const landed = input.landedAt === undefined ? Number.NaN : Date.parse(input.landedAt);
-    const ms = (Number.isFinite(landed) ? landed : input.now) - started;
-    if (ms < 0) {
+    return durationWords((Number.isFinite(landed) ? landed : input.now) - started);
+}
+/**
+ * A span of time as the `spent` row says it: seconds under a minute, minutes
+ * under two hours, then hours and minutes. Null for a span that runs
+ * backwards or does not parse, since a negative age is worse than a missing
+ * one.
+ */
+function durationWords(ms) {
+    if (!Number.isFinite(ms) || ms < 0) {
         return null;
     }
     if (ms < 60_000) {
@@ -1065,12 +1370,20 @@ function collapseRow(name, row, constraints) {
  * column 14. A row's `- ` items and its `→ ` pointer follow it on indented
  * continuation lines.
  *
- * The step's identity is not in here: the `**Readout**:` label above the fence
- * carries it, so it renders once. Empty when no row survived, so the caller can
- * drop the label and the fence together rather than emit an empty instrument.
+ * The step's identity is not in here: the Now line above the card carries it,
+ * so it renders once. A stop card's range has no Now line, and its `steps`
+ * row opens the fence in that place. Empty when no row survived, so the caller
+ * can drop the label and the fence together rather than emit an empty
+ * instrument.
  */
 export function recapLines(rows, extras) {
     const body = [];
+    if (extras.steps !== undefined) {
+        body.push(`${'steps'.padEnd(13)}${extras.steps.evidence}`);
+        for (const item of extras.steps.items) {
+            body.push(`${RECAP_INDENT}- ${item}`);
+        }
+    }
     for (const name of RECAP_ROW_NAMES) {
         const row = rows[name];
         if (row === undefined) {
@@ -1093,6 +1406,230 @@ export function recapLines(rows, extras) {
     }
     return body;
 }
+/** The short form a sha takes on the `steps` row, a handle for `git show`. */
+const SHORT_SHA = 7;
+/**
+ * Measure a landed range for the stop card's readout: its `steps` row, the
+ * `check` and `seam` rows the CLI owns, the `diff` and `spent` rows, and the
+ * stats the Verdict folds.
+ *
+ * Each step is held to its own commit and its own seam, never the range's
+ * union, so a step that wandered into a neighbor's seam still wandered. A
+ * step the ledger holds no commit for reads `no checkpoint` on the `steps` row
+ * and adds nothing else. A step landed by hand, with a checkpoint but no
+ * `build` entry, adds its commit to every row and no time to `spent`; its
+ * counters still count, so a red run its checkpoint's gate refused reads the
+ * same on the `spent` row and in the Verdict.
+ */
+export function measureRange(input) {
+    const held = parseOrderedSteps(input.intent).filter((s) => hasStep(input.range.steps, s.n));
+    const shas = stepShas(input.checkpoints);
+    const landed = held.flatMap((s) => {
+        const sha = shas.get(s.n);
+        return sha === undefined ? [] : [{ n: s.n, files: input.commits[sha] ?? [] }];
+    });
+    const rows = {};
+    if (input.summary !== null) {
+        rows.check = summaryCheckRow(input.summary, landed.length);
+    }
+    const seam = rangeSeamRow(input.intent, landed, held.length);
+    if (seam !== null) {
+        rows.seam = seam;
+    }
+    const stats = held.map((s) => input.stats[String(s.n)] ?? {});
+    const sum = (key) => stats.reduce((total, s) => total + (s[key] ?? 0), 0);
+    const recorded = ledgerShas(input.checkpoints);
+    return {
+        steps: stepsRow(held, shas),
+        rows,
+        diff: rangeDiffValue(landed.flatMap((l) => l.files)),
+        spent: rangeSpentValue(stats),
+        stats: {
+            driftWarnings: sum('driftWarnings'),
+            redChecks: sum('redChecks'),
+            reverts: sum('reverts'),
+            outOfBand: input.between.filter((sha) => !recorded.has(sha)).length,
+        },
+    };
+}
+/**
+ * The ledger span a range landed across, for the out-of-band count: from the
+ * line before the range's first landing to the range's last. Null when no
+ * step of the range is on the ledger, or nothing precedes its first landing.
+ *
+ * The caller asks git for the first-parent commits in `from..to`, plumbbob's
+ * plan commits left out, and hands them to `measureRange` as `between`; the
+ * ledger's own commits drop out there, so what is left is the range's
+ * commits outside the ledger.
+ */
+export function rangeSpan(checkpoints, range) {
+    const lines = ledgerLines(checkpoints);
+    const inRange = (line) => line.step !== null && hasStep(range.steps, line.step);
+    const first = lines.findIndex(inRange);
+    const last = lines.findLastIndex(inRange);
+    const from = lines[first - 1]?.sha;
+    const to = lines[last]?.sha;
+    return first < 1 || from === undefined || to === undefined ? null : { from, to };
+}
+/**
+ * The ledger's lines of every kind, in the order they were written.
+ */
+function ledgerLines(checkpoints) {
+    return checkpoints.split('\n').flatMap((line) => {
+        const m = /^(?:baseline|plan|step\s+(\d+))\s+(\S+)/.exec(line.trim());
+        return m === null ? [] : [{ step: m[1] === undefined ? null : Number(m[1]), sha: m[2] ?? '' }];
+    });
+}
+/**
+ * Each step's checkpoint sha, the last line for a step landed twice (a revert,
+ * then a landing again), since that is the commit on the branch now.
+ */
+export function stepShas(checkpoints) {
+    const shas = new Map();
+    for (const line of ledgerLines(checkpoints)) {
+        if (line.step !== null) {
+            shas.set(line.step, line.sha);
+        }
+    }
+    return shas;
+}
+/**
+ * Every sha the ledger records, of any kind: the commits plumbbob made, so
+ * none of them counts as out-of-band.
+ */
+function ledgerShas(checkpoints) {
+    return new Set(ledgerLines(checkpoints).map((line) => line.sha));
+}
+/**
+ * The `steps` row: how many of the range's steps landed, then each step and
+ * its checkpoint sha in build order, packed onto continuation lines by width
+ * rather than one per step, since each is a handle and not an item to judge.
+ */
+function stepsRow(held, shas) {
+    const done = held.filter((s) => s.done).length;
+    const handles = held.map((s) => {
+        const sha = shas.get(s.n);
+        return `${s.n} ${sha === undefined ? 'no checkpoint' : sha.slice(0, SHORT_SHA)}`;
+    });
+    return { evidence: `${done} of ${held.length} landed`, items: packed(handles, RECAP_VALUE_BUDGET - 2) };
+}
+/**
+ * Pack items onto lines joined by ` · `, a new line when the next would
+ * overrun `width`.
+ */
+function packed(items, width) {
+    const lines = [];
+    for (const item of items) {
+        const last = lines.at(-1);
+        if (last !== undefined && `${last} · ${item}`.length <= width) {
+            lines[lines.length - 1] = `${last} · ${item}`;
+        }
+        else {
+            lines.push(item);
+        }
+    }
+    return lines;
+}
+/**
+ * The range's `seam` row: each landed step's commit against that step's own
+ * seam. Null when no step had both a commit and a seam to measure.
+ *
+ * Green counts the steps measured out of the range's steps. One strayed step
+ * is named in the row with its paths as the evidence, the way a step's pause
+ * names them; two or more break onto continuation lines, one per step. It is
+ * an advisory, as at a pause: a stray in a landed commit asks the same
+ * question of the plan.
+ */
+function rangeSeamRow(intent, landed, steps) {
+    const measured = landed.flatMap(({ n, files }) => {
+        const seam = parseStepSeam(intent, n);
+        return seam.ok ? [{ n, strays: scopeDrift(files.map((f) => f.path), seam.seam) }] : [];
+    });
+    if (measured.length === 0) {
+        return null;
+    }
+    const strayed = measured.filter((m) => m.strays.length > 0);
+    const only = strayed[0];
+    if (only === undefined) {
+        return { verdict: 'true', word: 'held', evidence: `held: ${measured.length} of ${steps} steps, no strays` };
+    }
+    if (strayed.length === 1) {
+        const evidence = `strayed: ${pathCount(only.strays.length)} outside step ${only.n}'s seam`;
+        const path = only.strays[0];
+        return only.strays.length === 1 && path !== undefined
+            ? { verdict: 'advisory', word: 'strayed', evidence, pointer: path }
+            : { verdict: 'advisory', word: 'strayed', evidence, items: only.strays };
+    }
+    const total = strayed.reduce((sum, m) => sum + m.strays.length, 0);
+    return {
+        verdict: 'advisory',
+        word: 'strayed',
+        evidence: `strayed: ${pathCount(total)} outside ${strayed.length} steps' seams`,
+        items: strayed.map((m) => strayedStep(m.n, m.strays)),
+    };
+}
+/** A count of paths: `1 path`, `3 paths`. */
+function pathCount(n) {
+    return `${n} path${n === 1 ? '' : 's'}`;
+}
+/**
+ * One strayed step's continuation line, `step 8: src/x.ts, src/y.ts`, fitted
+ * to the line by count rather than cut: the first path and how many others,
+ * then the count alone.
+ */
+function strayedStep(n, strays) {
+    const width = RECAP_VALUE_BUDGET - 2;
+    const whole = `step ${n}: ${strays.join(', ')}`;
+    if (whole.length <= width) {
+        return whole;
+    }
+    const others = strays.length - 1;
+    const first = `step ${n}: ${strays[0] ?? ''} and ${others} other${others === 1 ? '' : 's'}`;
+    return first.length <= width ? first : `step ${n}: ${pathCount(strays.length)}`;
+}
+/**
+ * The range's `diff` row: the commits summed, a file counted once however
+ * many commits touched it, plumbbob's own records left out as at a pause.
+ * Information that never folds, and at a stop it never vanishes.
+ */
+function rangeDiffValue(files) {
+    const work = files.filter((f) => !isArtifactPath(f.path));
+    const counts = { ...countDiff(work), files: new Set(work.map((f) => f.path)).size };
+    return diffRowValue(counts, false) ?? '+0 -0 across 0 files';
+}
+/**
+ * The range's `spent` row: from the first step's `startedAt` to the last
+ * step's `landedAt`, then the red runs summed across the steps, or `green
+ * first run at every landing`, then any drift warnings. Null when nothing is
+ * countable.
+ *
+ * The clock reads only the steps `build` entered, since a step landed by hand
+ * has no `startedAt` to count from. No gate clause rides here, because only
+ * the last of the range's gate runs is on disk, and no turn count, because the
+ * ledger counts a step's turns from the tick that entered it.
+ */
+function rangeSpentValue(stats) {
+    const entered = stats.filter((s) => s.startedAt !== undefined);
+    const started = Math.min(...entered.map((s) => Date.parse(s.startedAt ?? '')).filter(Number.isFinite));
+    const landed = Math.max(...entered.map((s) => Date.parse(s.landedAt ?? '')).filter(Number.isFinite));
+    const elapsed = Number.isFinite(started) && Number.isFinite(landed) ? durationWords(landed - started) : null;
+    const red = stats.reduce((sum, s) => sum + (s.redChecks ?? 0), 0);
+    const drift = stats.reduce((sum, s) => sum + (s.driftWarnings ?? 0), 0);
+    const parts = [];
+    if (elapsed !== null) {
+        parts.push(elapsed);
+    }
+    if (red > 0) {
+        parts.push(`${red} red run${red === 1 ? '' : 's'}`);
+    }
+    else if (elapsed !== null) {
+        parts.push('green first run at every landing');
+    }
+    if (drift > 0) {
+        parts.push(`${drift} drift warning${drift === 1 ? '' : 's'}`);
+    }
+    return parts.length === 0 ? null : parts.join(' · ');
+}
 // --- The detail file's prose: the Summary that opens a decision turn and the
 // recommendation that closes it (docs/presentation.md). The model writes both
 // into `.plumbbob/detail.md` and handoff renders them, so the whole turn is one
@@ -1311,16 +1848,22 @@ export function formatOrientation(o) {
  * row per range with its command as the plan wrote it and its model, `✓` for
  * a range landed and `▸` with the `← next` tail for the one holding the next
  * step. An undone range carries its stop beneath it, since the stops ahead are
- * what the human steers by, and a landed one folds to its row. A range's drift
- * rides beneath it, and the plan's own rows close the block.
+ * what the human steers by, and a landed one folds to its row, because its
+ * call was made. A landed range whose stop card waits is the exception: its
+ * call is still to make, so it keeps its stop and takes the
+ * `← stop card waiting` tail, and the `▸` row drops `← next`, so the block
+ * keeps one arrow. A range's drift rides beneath it, and the plan's own rows
+ * close the block.
  */
 function formatRanges(view) {
     const landed = view.rows.filter((r) => r.landed).length;
+    const waits = view.rows.some((r) => r.waiting);
     const rows = view.rows.flatMap((r) => {
         const marker = r.landed ? '✓' : r.next ? '▸' : ' ';
         const model = r.range.model === null ? '' : ` · ${r.range.model}`;
-        const head = `  ${marker} ${r.range.item}  ${r.range.command}${model}${r.next ? '   ← next' : ''}`;
-        const stop = r.landed ? [] : [`        stop: ${r.range.stop}`];
+        const tail = r.waiting ? '   ← stop card waiting' : r.next && !waits ? '   ← next' : '';
+        const head = `  ${marker} ${r.range.item}  ${r.range.command}${model}${tail}`;
+        const stop = r.landed && !r.waiting ? [] : [`        stop: ${r.range.stop}`];
         return [head, ...stop, ...r.drift.map((words) => `        ⚠ needs a re-cut: ${words}`)];
     });
     return [`  ranges  ${landed} of ${view.count} done`, ...rows, ...view.plan.map((words) => `  ⚠ ${words}`)].join('\n');