plumbbob 0.13.0 → 0.13.2

package/dist/lib/sidecar.js

@@ -18,6 +18,7 @@
 // human-owned (check/auto): the tool only ever reads it, never rewrites it. The
 // phase the dashboard shows (DESIGN/BUILD/SPIKE) is derived, not stored: BUILD ⇔
 // a STEP is in flight, SPIKE ⇔ the SPIKE marker is present, otherwise DESIGN.
+import { createHash } from 'node:crypto';
 import { existsSync, readdirSync, readFileSync, writeFileSync, appendFileSync, rmSync, mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { gitPath } from "./git.js";
@@ -228,6 +229,61 @@ export function pausePath(root, slug) {
 export function clearPause(root, slug) {
     rmSync(pausePath(root, slug), { force: true });
 }
+/**
+ * STOP: the stamp of the stop card `handoff --stop` last rendered whole, the
+ * range it reviews, the TURN it printed in, a hash of what the card showed,
+ * and a digest of the detail file it printed from. While a later render
+ * matches the range and the hash, handoff prints the one-line reminder;
+ * `plumbbob harvest` records the stop only from the detail the card showed,
+ * and only once a human turn has read it.
+ */
+export function stopPath(root, slug) {
+    return join(artifactDir(root, slug), 'STOP');
+}
+/**
+ * The stamp of the stop card last rendered, or null when STOP is absent or
+ * does not parse.
+ */
+export function readStop(root, slug) {
+    try {
+        const m = /^(\d+) (\d+|-) (\S+)(?: (\S+))?$/.exec(readFileSync(stopPath(root, slug), 'utf8').trim());
+        if (m === null)
+            return null;
+        return { range: Number(m[1]), turn: m[2] === '-' ? null : Number(m[2]), hash: m[3] ?? '', detail: m[4] ?? null };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Record the stamp of the stop card just printed, with the digest of the
+ * detail file as it stands, which is the file the card was rendered from.
+ * Best-effort: a failed write costs one more full card on a later turn, never
+ * this turn's output or its exit code.
+ */
+export function writeStop(root, slug, stamp) {
+    try {
+        const detail = detailDigest(readFileSync(detailPath(root), 'utf8'));
+        writeFileSync(stopPath(root, slug), `${stamp.range} ${stamp.turn ?? '-'} ${stamp.hash} ${detail}\n`);
+    }
+    catch {
+        // A read-only tree or a vanished build folder: the card still renders.
+    }
+}
+/**
+ * Remove the STOP stamp: the stop's record ends the card it recorded. Absent
+ * is a no-op.
+ */
+export function clearStop(root, slug) {
+    rmSync(stopPath(root, slug), { force: true });
+}
+/**
+ * The digest a STOP stamp keeps of a detail file, so the record can tell the
+ * detail a card showed from one written after it.
+ */
+export function detailDigest(detail) {
+    return createHash('sha256').update(detail).digest('hex');
+}
 /**
  * The build's `checkpoints` ledger: the recorded SHAs of landed plan and step
  * commits, one line each.
@@ -473,6 +529,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,7 +548,7 @@ export function grantPath(root) {
 }
 /**
  * Rewrite (or clear) the one-turn GRANT: a non-null value is the minted grant
- * (`auto` | `range M`), null clears it.
+ * (`auto` | `steps <list>`), null clears it.
  *
  * The turn hook calls this on every human prompt (minted on a match, cleared
  * otherwise) so a grant lives exactly one turn by construction. Pairing the
@@ -504,6 +563,75 @@ export function setGrant(root, grant) {
         writeFileSync(grantPath(root), `${grant}\n`);
     }
 }
+/**
+ * RUN: the range a `/plumbbob:run` the human typed is landing, written beside
+ * GRANT by the turn hook so the checkpoint that completes the range knows a
+ * run landed it. The latch never reads it.
+ */
+export function runPath(root) {
+    return join(root, DIRNAME, 'RUN');
+}
+/**
+ * The range number the RUN mark names, or null when the mark is absent or
+ * holds anything but a positive number.
+ */
+export function readRun(root) {
+    try {
+        const n = Number(readFileSync(runPath(root), 'utf8').trim());
+        return Number.isSafeInteger(n) && n > 0 ? n : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Rewrite (or clear) the RUN mark: a range number marks that range's run,
+ * null clears it. The turn hook calls this on every typed prompt, beside
+ * `setGrant`, and the delete lives here with the grant's.
+ */
+export function setRun(root, item) {
+    if (item === null) {
+        rmSync(runPath(root), { force: true });
+    }
+    else {
+        writeFileSync(runPath(root), `${item}\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
@@ -561,11 +689,13 @@ export function readTurn(root) {
 // 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.
+// Which ending printed: handoff's eight forms first, then one per transition.
+// It is what the check's reason names when the ending went missing.
 const RELAY_RENDERS = [
     'card',
     'reminder',
+    'stop',
+    'stop-reminder',
     'plan',
     'boundary',
     'pointer',
@@ -580,6 +710,7 @@ const RELAY_RENDERS = [
     'spike-done',
     'use',
     'order',
+    'harvest',
     'finish',
     'start',
 ];
@@ -612,6 +743,18 @@ export function writeRelay(root, relay) {
         // 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
@@ -631,10 +774,18 @@ 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.owes !== undefined) {
+        header.push(`owes range ${record.owes.range} of ${record.owes.count} after step ${record.owes.step}`);
+    }
     if (record.held !== undefined)
         header.push(`held ${record.held}`);
     return `${header.join('\n')}\n\n${record.text}`;
 }
+/** The `owes` header field read back, or null when it is absent or does not parse. */
+function owedOf(field) {
+    const m = /^range (\d+) of (\d+) after step (\d+)$/.exec(field ?? '');
+    return m === null ? null : { range: Number(m[1]), count: Number(m[2]), step: Number(m[3]) };
+}
 /**
  * The recorded ending, or null when RELAY is absent or its header does not
  * parse: a record the check cannot read is no record.
@@ -662,12 +813,14 @@ export function readRelay(root) {
     if (turn === null || tier === undefined || render === undefined)
         return null;
     const command = fields.get('command');
+    const owes = owedOf(fields.get('owes'));
     const held = count(fields.get('held'));
     return {
         turn,
         tier,
         render,
         ...(command === undefined ? {} : { command }),
+        ...(owes === null ? {} : { owes }),
         ...(held === null ? {} : { held }),
         text: raw.slice(split + 2),
     };
@@ -739,6 +892,11 @@ export function excludeControl(root) {
         // never writes, and never commits.
         `${DIRNAME}/TURN`,
         `${DIRNAME}/GRANT`,
+        // The range a typed run is landing, written beside the grant.
+        `${DIRNAME}/RUN`,
+        // 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 records it in the build-log's
         // Log and then clears it, so its archive is the tracked ledger, never this
@@ -756,6 +914,9 @@ export function excludeControl(root) {
         // 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 stop stamp likewise: what the stop card last showed, and the turn it
+        // printed in, for the reminder and the record's latch.
+        `${DIRNAME}/builds/*/STOP`,
         // 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/build.js

@@ -8,18 +8,22 @@ 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, stopFollowUp } 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";
+import { waitingCard } from "./handoff.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), a stop card
+ * still waiting for its reply, 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 +33,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;
     }
@@ -48,6 +52,15 @@ export function build(cwd, args) {
         return 1;
     }
     const intent = readFileSync(intentPath(root, slug), 'utf8');
+    // A stop card waiting for its reply holds every step, bare or named: the
+    // step's pause would write over the range's review in the detail file before
+    // the reply recorded it. Nothing is written, and on the plan's last range the
+    // card outranks "no undone step".
+    const waiting = waitingNotice(root, slug, intent);
+    if (waiting.length > 0) {
+        process.stderr.write(waiting);
+        return 1;
+    }
     // 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);
@@ -100,11 +113,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 +129,70 @@ export function build(cwd, args) {
         `${parsed.seam.map((path) => `  ${path}`).join('\n')}\n`);
     return 0;
 }
+/**
+ * The refusal while a stop card waits for its reply, or '' when none waits:
+ * the card, then the reply that records it. `looks good` always does, and the
+ * remedy adds the move the card's second row names, read through the same
+ * `stopFollowUp`: the next range's run, the finish on the plan's last range,
+ * or nothing more when the next run would refuse. The remedy spends a
+ * semicolon, since the refusal register keeps its one colon for the prefix.
+ */
+function waitingNotice(root, slug, intent) {
+    const card = waitingCard(root, slug, intent);
+    if (card === null) {
+        return '';
+    }
+    const follow = stopFollowUp(intent);
+    const also = follow === null
+        ? ''
+        : follow === 'finish'
+            ? ', and /plumbbob:finish records it, then writes the report'
+            : `, and /plumbbob:run records it, then runs range ${follow.range.item} of ${follow.count}`;
+    return notice({
+        fact: 'no step entered',
+        detail: [`range ${card.range} of ${card.count}'s stop card is waiting for its reply`],
+        remedy: `reply to the card; looks good records it${also}`,
+    });
+}
+/**
+ * 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 +204,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 });