plumbbob 0.13.3 → 0.13.5

package/dist/lib/sidecar.js

@@ -18,7 +18,6 @@
 // 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";
@@ -215,56 +214,85 @@ 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.
+ * PAUSE: which card the human has already read, so a later `handoff` prints
+ * the one line that points back at it instead of the card. It holds a step
+ * number once that step's pause card has shown (`2`), or `landed 2` once the
+ * boundary step 2 landed on has shown.
+ *
+ * It records that a card showed, never what the card said: a later turn that
+ * changes the work is the model's reply, and the card comes back only on
+ * request (D110 (reply-after-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.
+ * The card PAUSE says has shown, or null when the file is absent or does not
+ * parse. A stamp written before D110 (reply-after-the-card) holds a step
+ * number and a hash, and reads as that step's pause.
+ */
+export function readPause(root, slug) {
+    try {
+        const m = /^(landed )?(\d+)(?:\s|$)/.exec(readFileSync(pausePath(root, slug), 'utf8').trim());
+        return m === null ? null : { kind: m[1] === undefined ? 'pause' : 'landed', step: Number(m[2]) };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Record that a card has shown. 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 writePause(root, slug, stamp) {
+    try {
+        writeFileSync(pausePath(root, slug), `${stamp.kind === 'landed' ? 'landed ' : ''}${stamp.step}\n`);
+    }
+    catch {
+        // A read-only tree or a vanished build folder: the card still renders.
+    }
+}
+/**
+ * Remove the PAUSE stamp: 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 });
 }
 /**
  * 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.
+ * range it reviews and the TURN it printed in. While a later render names the
+ * same range, handoff prints the one-line reminder, whatever changed since;
+ * `plumbbob harvest` records the stop only once a card for the range has shown
+ * and 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.
+ * does not parse. A stamp written before D110 (reply-after-the-card) carries
+ * a hash and a digest after the turn, and both are ignored.
  */
 export function readStop(root, slug) {
     try {
-        const m = /^(\d+) (\d+|-) (\S+)(?: (\S+))?$/.exec(readFileSync(stopPath(root, slug), 'utf8').trim());
+        const m = /^(\d+) (\d+|-)(?:\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 };
+        return { range: Number(m[1]), turn: m[2] === '-' ? null : Number(m[2]) };
     }
     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.
+ * Record the stamp of the stop card just printed. 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`);
+        writeFileSync(stopPath(root, slug), `${stamp.range} ${stamp.turn ?? '-'}\n`);
     }
     catch {
         // A read-only tree or a vanished build folder: the card still renders.
@@ -277,13 +305,6 @@ export function writeStop(root, slug, stamp) {
 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.
@@ -689,7 +710,7 @@ 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 eight forms first, then one per transition.
+// Which ending printed: handoff's nine forms first, then one per transition.
 // It is what the check's reason names when the ending went missing.
 const RELAY_RENDERS = [
     'card',
@@ -700,6 +721,7 @@ const RELAY_RENDERS = [
     'boundary',
     'pointer',
     'driver',
+    'harvest-card',
     'checkpoint',
     'plan-commit',
     'park',
@@ -911,10 +933,10 @@ export function excludeControl(root) {
         // 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.
+        // The pause stamp is in-flight control too: which card has shown, so a
+        // later handoff prints its one line. It must never ride a step commit.
         `${DIRNAME}/builds/*/PAUSE`,
-        // The stop stamp likewise: what the stop card last showed, and the turn it
+        // The stop stamp likewise: the range whose card has shown, 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

package/dist/verbs/checkpoint.js

@@ -12,7 +12,7 @@
 import { appendFileSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { relative } from 'node:path';
 import { commit, findRepoRoot, headSha, isDirty, stageAll, stagePath, stagedPaths, stagedStat } from "../lib/git.js";
-import { activeBuild, buildFolder, buildLogPath, buildScope, bumpStepStat, checkpointsPath, clearDetail, clearHandoff, clearPause, clearTick, detailPath, hasSession, intentPath, readRun, readStats, refreshExcludes, seamPath, stampStepStat, stepPath, } from "../lib/sidecar.js";
+import { activeBuild, buildFolder, buildLogPath, buildScope, bumpStepStat, checkpointsPath, clearDetail, clearHandoff, clearTick, detailPath, hasSession, intentPath, readRun, readStats, refreshExcludes, seamPath, stampStepStat, stepPath, writePause, } from "../lib/sidecar.js";
 import { runCheck } from "../lib/check.js";
 import { readCommitBody } from "../lib/commitbody.js";
 import { checkLatch } from "../lib/latch.js";
@@ -22,8 +22,7 @@ import { conventionalSubject, subjectFromTitle, withMarker } from "../lib/commit
 import { appendToSection, checkpointLogLine, logEntry, planLogLine } from "../lib/buildlog.js";
 import { AT_BOUNDARY, syncBuildLogState } from "../lib/buildlogsync.js";
 import { advisory, ending, notice, printEnding, transition } from "../lib/notice.js";
-import { boundaryEnding, detailsLink, parseDetailRange, planRecord, stepRecord } from "./handoff.js";
-import { isHarvestDetail } from "./harvest.js";
+import { boundaryEnding, detailsLink, isHarvestDetail, parseDetailRange, planRecord, stepRecord } from "./handoff.js";
 /**
  * Land a step: latch, check gate, commit, record, return to the boundary.
  *
@@ -122,11 +121,14 @@ 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.
+    // The pause it stamped is over, and the boundary this ending prints is the
+    // card the stamp now names, so a later handoff here ends on its pointer
+    // (D110 (reply-after-the-card)); the next step's pause renders whole.
+    writePause(root, undefined, { kind: 'landed', step });
+    // The whole ending, one block: the lead line, the advisories this checkpoint
+    // alone can state, and the state table headed by the Verdict folded over
+    // what just landed. 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);
     // A landing that completes the range a typed run marked owes the stop card:
     // the record says so, and the relay check holds a turn that ends here.
@@ -137,10 +139,8 @@ export async function checkpoint(cwd, args) {
         ...(owes === null ? {} : { owes }),
         text: ending({
             lead: transition({ label: 'Checkpoint', fact: `Step ${step} complete`, detail: leadDetail(sha, pointer) }),
-            verdict: landed.verdict,
             advisories: [drift, flipNotice],
-            stop: landed.stop,
-            pointer: landed.pointer,
+            state: landed.state,
         }),
     });
     return 0;
@@ -202,7 +202,7 @@ function checkpointPlan(root, args) {
                         remedy: 'unignore .plumbbob/builds/ to keep the record in the tree',
                     }),
                 ],
-            pointer: boundaryEnding(root, activeBuild(root), null).pointer,
+            state: boundaryEnding(root, activeBuild(root), null).state,
         }),
     });
     return 0;

package/dist/verbs/finish.js

@@ -18,10 +18,10 @@ import { buildScope, checkpointsPath, clearTick, hasSession, intentPath, readSta
 import { conventionalSubject, withMarker } from "../lib/commitmsg.js";
 import { parseBuildScope } from "../lib/intent.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.
-const NEXT_UP = '**Next Up**: Nothing planned - /plumbbob:plan';
+// The pointer finish leaves the turn on, as its state table's one row. 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.
+const NEXT_UP = 'Nothing planned - /plumbbob:plan';
 /**
  * Close out the active build: report tail, final commit, control-state cleanup.
  *
@@ -80,8 +80,8 @@ export function finish(cwd, args = []) {
     rmSync(join(sidecarDir(root), 'STATE'), { force: true });
     // The whole ending in the fixed order: the lead line, the advisory that
     // qualifies it (finishing without a report is guidance, never a gate; the
-    // session is already closed by the time it prints), and the pointer, which is
-    // the turn's last text. finish renders that pointer itself: it just cleared
+    // session is already closed by the time it prints), and the state table's
+    // pointer, which is 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}/`;
     printEnding(root, {
@@ -102,7 +102,7 @@ export function finish(cwd, args = []) {
                         remedy: '/plumbbob:finish normally writes the report first',
                     }),
                 ],
-            pointer: NEXT_UP,
+            state: [{ label: 'Next Up', value: NEXT_UP }],
         }),
     });
     return 0;