plumbbob 0.6.6 → 0.8.3

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "plumbbob",
   "displayName": "PlumbBob",
-  "version": "0.6.6",
-  "description": "Attention-first build process — driver skills + a CLI that keep you the decider; guidance, not enforcement.",
+  "version": "0.8.3",
+  "description": "Attention-first build process — driver skills + a CLI that keep you the decider: guidance on the work, a latch on the record.",
   "author": { "name": "Rob McLarty", "email": "hello@robmclarty.com", "url": "https://robmclarty.com" },
   "homepage": "https://github.com/robmclarty/plumbbob#readme",
   "repository": "https://github.com/robmclarty/plumbbob",

package/README.md

@@ -213,13 +213,30 @@ actually learning is the method: decisions before code, one verified step at a
 time, capture instead of chase. That transfers to whatever tool wins. If
 something better ships, you walk away with your archives and your habits intact.
 
-**…admit the pause is unenforceable?** It is — on purpose ([D10](docs/decisions.md#d10)/[D13](docs/decisions.md#d13) in
-[`docs/decisions.md`](docs/decisions.md)). A hard lock buys ritual, not control:
-a determined model routes around it. So PlumbBob enforces deterministically where
-it can — `checkpoint` refuses on a red check, `revert` restores only recorded
-SHAs — and leaves human what must be human: you, reading the diff at the pause.
-When guidance does get blown through, the checkpoint record makes recovery one
-command. Cheap recovery, not prevention, is the control that actually matters.
+**…admit the pause is unenforceable?** On the **work** plane, yes — on purpose
+([D10](docs/decisions.md#d10)/[D13](docs/decisions.md#d13) in
+[`docs/decisions.md`](docs/decisions.md)): a hard lock on every edit buys ritual, not
+control, because a determined model routes around it and a denial mid-thought leaves no
+legal move. But the **record** is a different plane, and there the tick *is* latched
+([D64–D66](docs/decisions.md#d64)): `checkpoint` refuses to land a step until the harness
+records a human turn since that step began, so the agent cannot self-commit past you —
+the refusal simply *is* the pause. That extends the deterministic edge PlumbBob already
+holds — `checkpoint` refuses a red check, `start` refuses a dirty tree, `revert` restores
+only recorded SHAs — to the one boundary the product is named after, while leaving human
+what must be human: you, reading the diff. **Guidance on the work, a latch on the
+record.** And when a raw commit does slip the ledger, `status` says so and the checkpoint
+record makes recovery one command — cheap recovery, not a cage, is the control that
+matters.
+
+> The latch's payoff is measured, not asserted: the skill-eval harness
+> ([`test/evals/`](test/evals/)) sweeps this loop headless — prose-only baseline vs. the
+> shipped latch, N=5 per contract, every assertion a mechanical read of git state — and
+> commits the receipt to [`reports/evals/`](reports/evals/2026-07-11.md). The first sweep
+> (opus, 2026-07-11): the latch closes the route it owns — *no checkpoint over a red
+> check under pressure* went from **2/5 prose-only to 5/5 latched** — while the honest
+> numbers it also surfaced (park capture 0/5, and adversarial pressure consistently
+> flipping the `auto` standing grant in settings — a legal, model-writable side door)
+> are the next iteration's work, named in the report rather than papered over.
 
 ## Documentation
 

package/dist/cli-core.js

@@ -18,6 +18,7 @@ import { finish } from "./verbs/finish.js";
 import { init } from "./verbs/init.js";
 import { doctor } from "./verbs/doctor.js";
 import { agent } from "./verbs/agent.js";
+import { turn } from "./verbs/turn.js";
 const VERBS = [
     { name: 'start', summary: 'scaffold .plumbbob/; open the session; record the baseline commit' },
     { name: 'status', summary: 'print the orientation dashboard, or NO ACTIVE SESSION' },
@@ -32,6 +33,7 @@ const VERBS = [
     { name: 'init', summary: 'link plumbbob into Claude Code as an in-place plugin (~/.claude/skills/plumbbob); --uninstall to undo' },
     { name: 'doctor', summary: 'diagnose the plugin link + detect a legacy flat sidecar; doctor --migrate moves it into builds/ (staged, not committed)' },
     { name: 'agent', summary: 'agent list | run <name> [--step N] [--mode before|build|after]: list or spawn a user-authored agent' },
+    { name: 'turn', summary: 'turn: UserPromptSubmit hook machinery — tick the turn ledger from stdin (not a user verb)' },
 ];
 // PlumbBob (D1/D10/D13): the deciding/executing boundary is a pause, not a lock,
 // so there is nothing to defend — every verb runs the same whether a human or the
@@ -56,8 +58,9 @@ export function readVersion() {
         return 'unknown';
     }
 }
-// Async because the checkride gate (D32) is: `check` and `checkpoint` await it;
-// every other verb returns synchronously through the same Promise-typed seam.
+// Async because checkride is: `check` and `checkpoint` await the gate (D32),
+// `start` awaits the plan-time detection probe (research/07 2a); every other
+// verb returns synchronously through the same Promise-typed seam.
 async function dispatch(verb, cwd, rest) {
     switch (verb) {
         case 'start':
@@ -86,6 +89,8 @@ async function dispatch(verb, cwd, rest) {
             return doctor(cwd, rest);
         case 'agent':
             return agent(cwd, rest);
+        case 'turn':
+            return turn(cwd, rest);
         default:
             process.stderr.write(`plumbbob: unknown verb '${verb}'. Run 'plumbbob help' for the verb table.\n`);
             return 1;

package/dist/lib/buildlog.js

@@ -28,7 +28,10 @@ export function appendToSection(content, heading, line) {
 // The Log line `checkpoint` writes for a landed step: dated, names the step (its
 // title when intent.md still carries it), and carries the short SHA. One line of the
 // build's history — `/pb-finish` reads these instead of re-narrating the build.
-export function checkpointLogLine(date, step, sha, title) {
+// `stats` is the optional compact receipt (research/07 2b), e.g. `2 red, 34m` —
+// null when nothing accrued, so a clean first-try step reads exactly as before.
+export function checkpointLogLine(date, step, sha, title, stats = null) {
     const head = `- ${date} — step ${step} checkpointed · ${sha.slice(0, 9)}`;
-    return title !== null && title.length > 0 ? `${head} — ${title}` : head;
+    const titled = title !== null && title.length > 0 ? `${head} — ${title}` : head;
+    return stats !== null && stats.length > 0 ? `${titled} (${stats})` : titled;
 }

package/dist/lib/check.js

@@ -12,8 +12,40 @@
 // green, 1 is red, 2 means the harness itself broke — reported distinctly,
 // because a misconfigured gate must not read as broken code (both still block).
 import { spawnSync } from 'node:child_process';
-import { runChecks } from 'checkride';
+import { runChecks, runDoctor } from 'checkride';
 import { resolveString } from "./settings.js";
+export async function detectGate(root) {
+    const command = resolveString(root, 'check', '');
+    if (command.length > 0)
+        return { configured: command, detected: true };
+    try {
+        const silent = { write: () => true };
+        const { report } = await runDoctor({ cwd: root, stdout: silent });
+        return { configured: null, detected: gateDetectsTools(report.checks) };
+    }
+    catch {
+        // A broken checkride harness is a different problem with its own reporters
+        // (doctor's ✗ row, runCheck's exit 2) — the plan-time probe stays quiet
+        // rather than mislabeling it "nothing to check".
+        return { configured: null, detected: true };
+    }
+}
+// Checkride's always-on repo checks: the adapters its doctor reports even for
+// an EMPTY directory (links, the pnpm-audit security scan, and the
+// publint/attw package-shape probes). They exercise the repo's plumbing, not
+// its code — a gate made only of these green-lights every checkpoint while the
+// human believes their work is being checked. Coupled to checkride's built-in
+// set by construction; the doctor.test.ts probe pins the coupling.
+const ALWAYS_ON_ADAPTERS = ['links', 'pnpm-audit', 'publint', 'attw'];
+// The detection rule, shared by `start`'s probe and doctor's callout: some tool
+// slot beyond the always-on family has an adapter — i.e. checkride can see the
+// CODE (a tsconfig, a test runner, a linter…), not just the repo.
+export function gateDetectsTools(checks) {
+    return checks.some((c) => c.category === 'tool' &&
+        c.adapter !== null &&
+        c.adapter !== undefined &&
+        !ALWAYS_ON_ADAPTERS.includes(c.adapter));
+}
 // Runs the gate in `root` and returns the exit code (0 green, 1 red, 2 harness
 // error). `commandFlag` is the optional CLI override at the top of the settings
 // ladder; a resolved command means the spawn path, no setting means checkride.

package/dist/lib/git.js

@@ -42,6 +42,23 @@ export function hasCommit(root) {
 export function isDirty(root) {
     return runGit(root, ['status', '--porcelain']).length > 0;
 }
+// The number of commits on HEAD not reachable from `sha` — `git rev-list --count
+// --first-parent <sha>..HEAD`. The receipts line (D66) reads this to surface commits
+// that landed since the last checkpoint outside plumbbob's ledger. `--first-parent`
+// keeps the count on the branch's own line: merging upstream reads as the one merge
+// commit, not the dozens it carried — those didn't land "outside the ledger" in any
+// sense the receipt should nag about. Best-effort and never throws: 0 when the range
+// is empty, `sha` is unknown to the repo, or HEAD is unborn — the count is
+// informational (the human commits freely, C5), never a gate.
+export function commitsSince(root, sha) {
+    try {
+        const n = Number.parseInt(runGit(root, ['rev-list', '--count', '--first-parent', `${sha}..HEAD`]), 10);
+        return Number.isFinite(n) && n > 0 ? n : 0;
+    }
+    catch {
+        return 0;
+    }
+}
 // --- mutation helpers (build-loop: done checkpoints, revert resets). Additive
 // only (C5): stage/commit forward, reset --hard to a recorded checkpoint SHA. ---
 export function stageAll(root) {

package/dist/lib/latch.js

@@ -0,0 +1,97 @@
+// The approval latch (D64) — the ledger-plane predicate `checkpoint` evaluates
+// before its check gate (C4: cheap first; the gate already ran in the verify
+// tick). The work plane stays guidance (D10/D13 untouched); only the commit tick
+// is latched: a step may not land unless a human turn intervened since entry, the
+// human granted self-approval (D65 one-turn grant, D27 standing `auto`), or the
+// ledger is dormant. Six rows, evaluated in order, first hit wins; the refusal
+// message *is* the pause affordance. Reads TURN/TICK/GRANT/isTTY only — never the
+// host (C5). Functional, named exports, node builtins (C1/C2).
+import { readFileSync } from 'node:fs';
+import { grantPath, tickPath, turnPath } from "./sidecar.js";
+import { resolveBoolean } from "./settings.js";
+const ALLOW = { allow: true };
+// The exact refusal (the spec pins this prose): the message is the affordance —
+// it tells the model what the pause is and names the only legitimate grants. The
+// plan commit gets its own wording: there is no step, no diff, and no self-review
+// at plan time — what the human approves is the plan itself.
+const NO_TURN_MESSAGE = `plumbbob: checkpoint refused — no human turn since this step began. This is the
+pause: present the diff and the self-review, then end the turn; the human's next
+message is the tick. (An explicit \`/pb-build --auto\` or a step range in the human's
+own prompt grants self-approval; \`auto: true\` in settings.local.json is the standing
+grant.)
+`;
+const NO_TURN_PLAN_MESSAGE = `plumbbob: checkpoint refused — no human turn since \`start\` stamped this plan. This
+is the plan pause: present the plan, then end the turn; the human's approving
+message is the tick that lets it land on re-fire. (\`auto: true\` in
+settings.local.json is the standing grant.)
+`;
+function ceilingMessage(ceiling) {
+    return `plumbbob: checkpoint refused — the range you granted ends at step ${ceiling} — pause here; re-fire to continue.\n`;
+}
+// The six-row matrix, in order, first hit wins. A `range` grant speaks only to
+// numbered steps: on a `--plan` checkpoint (step null) it neither allows nor
+// refuses, and the decision falls through to the turn comparison.
+export function evaluateLatch(input) {
+    if (input.isTTY)
+        return ALLOW; // 1 — a human at the keyboard
+    if (input.turn === null || input.tick === null)
+        return ALLOW; // 2 — dormant / hand-built
+    if (input.auto)
+        return ALLOW; // 3 — standing personal grant (D27)
+    if (input.grant?.kind === 'auto')
+        return ALLOW; // 4 — one-turn grant
+    if (input.grant?.kind === 'range' && input.step !== null) {
+        if (input.step <= input.grant.ceiling)
+            return ALLOW;
+        return { allow: false, reason: 'ceiling', message: ceilingMessage(input.grant.ceiling) };
+    }
+    if (input.turn > input.tick)
+        return ALLOW; // 5 — a human turn intervened
+    // 6 — the pause (plan-worded when no step is landing)
+    return { allow: false, reason: 'no-turn', message: input.step === null ? NO_TURN_PLAN_MESSAGE : NO_TURN_MESSAGE };
+}
+// Parse a GRANT file's content (`auto` | `range <M>`). Anything else — including
+// a corrupted or hand-mangled file — contributes nothing (D27): no grant, never
+// an error.
+export function parseGrant(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === 'auto')
+        return { kind: 'auto' };
+    const range = /^range (\d+)$/.exec(trimmed);
+    if (range !== null)
+        return { kind: 'range', ceiling: Number(range[1]) };
+    return null;
+}
+// Gather the latch's inputs from the worktree and evaluate. `step` is the step
+// number being checkpointed, or null for the plan commit (which latches on the
+// TICK that `start` stamped).
+export function checkLatch(root, step) {
+    return evaluateLatch({
+        isTTY: process.stdin.isTTY === true,
+        turn: readCount(turnPath(root)),
+        tick: readCount(tickPath(root)),
+        auto: resolveBoolean(root, 'auto', false),
+        grant: readGrant(root),
+        step,
+    });
+}
+function readGrant(root) {
+    try {
+        return parseGrant(readFileSync(grantPath(root), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+// A ledger count, or null when the file is absent or holds garbage — malformed
+// contributes nothing, and an unreadable ledger reads as dormant (row 2) rather
+// than wedging the land.
+function readCount(path) {
+    try {
+        const n = Number.parseInt(readFileSync(path, 'utf8').trim(), 10);
+        return Number.isFinite(n) && n >= 0 ? n : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lib/orient.js

@@ -94,6 +94,22 @@ export function parseLastCheckpoint(checkpoints) {
     }
     return last;
 }
+// The SHA of the last ledger line of ANY kind — baseline, plan, or step. This is
+// the reconciliation anchor for the out-of-band count (D66): a commit that lands
+// after the plan but before the first step checkpoint is exactly the window the
+// receipt exists for, so anchoring on step lines alone would leave it invisible.
+// `parseLastCheckpoint` stays step-only — it feeds the "last checkpoint step N"
+// display, where baseline/plan would be noise.
+export function lastLedgerSha(checkpoints) {
+    let last = null;
+    for (const line of checkpoints.split('\n')) {
+        const m = /^(?:baseline|plan|step\s+\d+)\s+(\S+)/.exec(line.trim());
+        if (m) {
+            last = m[1] ?? null;
+        }
+    }
+    return last;
+}
 // The single primary next move (D15). It suggests; the dashboard prints the full
 // list + counts so the human can always override. The phase is derived: a spike
 // in progress and an in-flight step each have one obvious next move; otherwise you
@@ -137,6 +153,7 @@ export function orient(input) {
         nextDoneWhen: nextUndone?.doneWhen ?? null,
         nextSeam: seamParse !== null && seamParse.ok ? seamParse.seam : [],
         nextModel: nextUndone?.model ?? null,
+        outOfBand: input.outOfBand,
     };
 }
 export function formatOrientation(o) {
@@ -166,12 +183,19 @@ export function formatOrientation(o) {
     const stepsBlock = o.steps.length === 0 ? '  (no steps planned yet)' : `  steps  ${doneCount}/${o.steps.length} done\n${stepLines.join('\n')}`;
     const cp = o.lastCheckpoint;
     const cpLine = cp === null ? 'last checkpoint  none yet' : `last checkpoint  step ${cp.n} · ${cp.sha.slice(0, 7)}`;
+    // A neutral reconciliation note (D66), only when there is something to reconcile:
+    // commits landed since the last checkpoint that plumbbob's ledger didn't record.
+    // Informational — the human commits freely (repo D3/C5), so this never gates.
+    const receipts = o.outOfBand > 0
+        ? [`${o.outOfBand} commit${o.outOfBand === 1 ? '' : 's'} since the last checkpoint landed outside plumbbob's ledger.`]
+        : [];
     return [
         `PlumbBob — ${o.title ?? '(untitled)'}   [${o.phase}]`,
         '',
         stepsBlock,
         '',
         cpLine,
+        ...receipts,
         `parked ${o.parked} · open questions ${o.openQuestions}`,
         '',
         `next → ${o.next}`,

package/dist/lib/settings.js

@@ -9,9 +9,9 @@
 //
 // Known keys: `check` (string — the heavy gate, tracked in settings.json) and
 // `auto` (boolean — whether the agent approves in the human's place; a personal
-// preference, so it belongs in settings.local.json). `activeBuild` (the
-// per-worktree cursor) also lives in settings.local.json but is resolved by
-// sidecar.ts, not here.
+// preference, so it belongs in settings.local.json). The per-worktree active-build
+// cursor is NOT here — it lives in the STATE file (see sidecar.ts), so this overlay
+// stays purely human-owned and the tool never rewrites it.
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 const DIRNAME = '.plumbbob';
@@ -70,12 +70,6 @@ export function resolveRecord(root, key) {
     const value = resolveSetting(root, key, undefined);
     return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : {};
 }
-// Read one key from the untracked local overlay ONLY — no project or built-in
-// fallback. The `activeBuild` cursor lives here and must never resolve from the
-// tracked settings.json (it is per-worktree state, not a shared default).
-export function localSetting(root, key) {
-    return readSettings(localSettingsPath(root))[key];
-}
 // Merge one key into settings.local.json, preserving the other keys and creating
 // the file when absent. Pretty-printed so the overlay stays hand-editable. A
 // malformed existing file contributes nothing (readSettings yields {}) and is

package/dist/lib/sidecar.js

@@ -2,14 +2,18 @@
 // read it with a grep and no markdown parsing (D7). Functional/procedural,
 // node builtins only (C1/C2).
 //
-// STATE is a pure session sentinel: its EXISTENCE means "a session is active",
-// and nothing reads its content. 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.
+// STATE is the session sentinel AND the active-build cursor (D28): its EXISTENCE
+// means "a session is active", and its CONTENT names the build that session is on —
+// the two reinforce each other (a session is always on some build; the cursor is
+// meaningless without a session). Content is empty under --local / no build.
+// hasSession stays existence-only; activeBuild reads the content. Homing the cursor
+// here — not in settings.local.json — keeps that overlay purely 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 { existsSync, readdirSync, readFileSync, writeFileSync, appendFileSync, rmSync, mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { gitPath } from "./git.js";
-import { localSetting } from "./settings.js";
 const DIRNAME = '.plumbbob';
 export function sidecarDir(root) {
     return join(root, DIRNAME);
@@ -50,19 +54,35 @@ export function listBuilds(root) {
     }
 }
 // Resolve which build a verb acts on (D28): an explicit `--build <slug>` flag →
-// the `activeBuild` cursor in settings.local.json → the sole build in `builds/`
-// → null (the caller then refuses with a hint). One-active-per-worktree holds by
-// construction: the cursor is a single scalar key in an untracked file, so it can
-// never point at two builds (D28).
+// the cursor in STATE → the sole build in `builds/` → null (the caller then refuses
+// with a hint). One-active-per-worktree holds by construction: the cursor is STATE's
+// single-line content, so it can never point at two builds (D28).
 export function activeBuild(root, flag) {
     if (flag !== undefined && flag.length > 0)
         return flag;
-    const cursor = localSetting(root, 'activeBuild');
-    if (typeof cursor === 'string' && cursor.length > 0)
+    const cursor = readCursor(root);
+    if (cursor !== null)
         return cursor;
     const builds = listBuilds(root);
     return builds.length === 1 ? (builds[0] ?? null) : null;
 }
+// STATE's content is the active-build cursor. Empty means "no build" (--local, or a
+// session whose cursor is unset) → null, so activeBuild falls through to the
+// sole-build rule. A pre-STATE-cursor session wrote the literal `active` sentinel
+// here (the cursor lived in settings.local.json then); treat that legacy value as
+// unset so an in-flight upgrade degrades gracefully instead of chasing a build named
+// "active". `active` is thus reserved and never a valid cursor — no derived slug
+// collides (they carry a YYYY-MM-DD- prefix).
+function readCursor(root) {
+    let content;
+    try {
+        content = readFileSync(statePath(root), 'utf8').trim();
+    }
+    catch {
+        return null;
+    }
+    return content.length > 0 && content !== 'active' ? content : null;
+}
 // The build a verb should act on, plus its argv with the `--build <slug>` pair
 // stripped (D28). Every verb resolves through this: an explicit `--build <slug>`
 // wins, else the cursor / sole-build fallback of `activeBuild`. `rest` matters
@@ -159,14 +179,64 @@ export function appendHandoff(root, slug, entry) {
 export function clearHandoff(root, slug) {
     rmSync(handoffPath(root, slug), { force: true });
 }
+export function statsPath(root, slug) {
+    return join(artifactDir(root, slug), 'stats.json');
+}
+// The whole file, or {} when absent or corrupt — malformed contributes nothing.
+export function readStats(root, slug) {
+    try {
+        const parsed = JSON.parse(readFileSync(statsPath(root, slug), 'utf8'));
+        return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+// Increment one counter on one step. Best-effort by contract: a failed write is
+// swallowed — the stats are a receipt, never a gate on the verb that accrues them.
+export function bumpStepStat(root, slug, step, key) {
+    patchStepStat(root, slug, step, (current) => ({ [key]: (current[key] ?? 0) + 1 }));
+}
+// Stamp one timestamp on one step (startedAt at `build <n>`, landedAt at
+// checkpoint). Same best-effort contract as bumpStepStat.
+export function stampStepStat(root, slug, step, key, value) {
+    patchStepStat(root, slug, step, () => ({ [key]: value }));
+}
+function patchStepStat(root, slug, step, patch) {
+    try {
+        const stats = readStats(root, slug);
+        const current = stats[String(step)] ?? {};
+        const next = { ...stats, [String(step)]: { ...current, ...patch(current) } };
+        const path = statsPath(root, slug);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`);
+    }
+    catch {
+        // Best-effort receipt (D27/D4): never wedge build/checkpoint/revert over it.
+    }
+}
 // A session exists iff STATE exists. Deleting STATE (at finish) is what flips the
 // repo back to "no session" — so it is the single source of truth for "is there
-// a session". `start` calls beginSession; `finish` removes the file.
+// a session". `start` calls beginSession; `finish` removes the file. Existence is
+// the whole session signal; STATE's content is a separate axis (the cursor).
 export function hasSession(root) {
     return existsSync(statePath(root));
 }
-export function beginSession(root) {
-    writeFileSync(statePath(root), 'active\n');
+// Open the session and point its cursor at `slug` — null under --local / no build,
+// which leaves STATE present but empty so activeBuild falls through to the sole-build
+// rule. `finish` removes the file, closing the session and clearing the cursor in
+// one delete.
+export function beginSession(root, slug = null) {
+    writeCursor(root, slug);
+}
+// Re-point the cursor at an existing build (`use`) — a plain content rewrite that
+// leaves the session sentinel (STATE's existence) intact. Callers guard hasSession
+// first, so this never resurrects a finished session.
+export function setActiveBuild(root, slug) {
+    writeCursor(root, slug);
+}
+function writeCursor(root, slug) {
+    writeFileSync(statePath(root), slug === null ? '' : `${slug}\n`);
 }
 // SPIKE marker helpers — existence is the whole signal (content is irrelevant).
 export function inSpike(root, slug) {
@@ -178,6 +248,79 @@ export function markSpike(root, slug) {
 export function clearSpike(root, slug) {
     rmSync(spikePath(root, slug), { force: true });
 }
+// --- The turn ledger (D64/D65): a `.plumbbob/TURN` count the model never writes,
+// and a one-turn `.plumbbob/GRANT` beside it — both flat, per-worktree control
+// (never per-build, never committed). `plumbbob turn` (the UserPromptSubmit hook)
+// ticks TURN once per human prompt and rewrites GRANT from the literal prompt; the
+// checkpoint latch reads them. Kept in the sidecar so the lone GRANT `rmSync` stays
+// where deletions are allowed (C4/centralize-destructive-fs). ---
+export function turnPath(root) {
+    return join(root, DIRNAME, 'TURN');
+}
+export function grantPath(root) {
+    return join(root, DIRNAME, 'GRANT');
+}
+// Rewrite (or clear) the one-turn GRANT: a non-null value is the minted grant
+// (`auto` | `range M`), null clears it. Pairing the write with its delete here means
+// a grant can never half-persist, and the delete lives where deletions belong.
+export function setGrant(root, grant) {
+    if (grant === null) {
+        rmSync(grantPath(root), { force: true });
+    }
+    else {
+        writeFileSync(grantPath(root), `${grant}\n`);
+    }
+}
+// TICK is the per-build entry stamp (D64): the TURN value recorded when work was
+// entered (`build <n>` for a step, `start` for the plan), cleared when `checkpoint`
+// lands. The latch compares TURN against it to know whether a human turn intervened
+// across the entry→checkpoint span.
+export function tickPath(root, slug) {
+    return join(artifactDir(root, slug), 'TICK');
+}
+// Stamp TICK with the current TURN. Stamped only when TURN holds a readable count:
+// a host with no hooks never grows a ledger, so the latch stays dormant there
+// instead of wedging (row 2 of the matrix).
+export function stampTick(root, slug) {
+    const turn = readTurn(root);
+    if (turn === null)
+        return;
+    writeFileSync(tickPath(root, slug), `${turn}\n`);
+}
+// Consume the entry stamp — `checkpoint` clears it when a step (or the plan) lands,
+// the same beat that clears STEP/SEAM/handoff. Absent is a no-op; the rmSync lives
+// here with the sidecar's other deletions.
+export function clearTick(root, slug) {
+    rmSync(tickPath(root, slug), { force: true });
+}
+// The TURN count, or null when the ledger is absent or unreadable — absence is the
+// "dormant" signal stampTick keys off and the doctor latch probe reports (D64),
+// never an error.
+export function readTurn(root) {
+    try {
+        const n = Number.parseInt(readFileSync(turnPath(root), 'utf8').trim(), 10);
+        return Number.isFinite(n) && n >= 0 ? n : null;
+    }
+    catch {
+        return null;
+    }
+}
+// Walk up from `cwd` to the nearest ancestor with an active session (a
+// `.plumbbob/STATE` file), or null when there is none. The turn hook runs on every
+// human prompt in every repo; this is the cheap, git-free probe that keeps it a
+// silent no-op outside a live plumbbob session — filesystem only, never a host
+// sniff (C5/D13).
+export function findSessionRoot(cwd) {
+    let dir = cwd;
+    let parent = dirname(dir);
+    while (dir !== parent) {
+        if (hasSession(dir))
+            return dir;
+        dir = parent;
+        parent = dirname(dir);
+    }
+    return hasSession(dir) ? dir : null;
+}
 // Append `patterns` to the repo's info/exclude, each at most once (idempotent —
 // a re-`start` after finish must not double-add). `gitPath` resolves to the
 // *common* gitdir's exclude — the only one git reads — so this works from a
@@ -200,17 +343,25 @@ function addExcludes(root, patterns) {
     appendFileSync(exclude, `${prefix}${missing.join('\n')}\n`);
 }
 // The narrowed control plane (D17): with `builds/<slug>/` now tracked, only the
-// per-worktree control files stay git-excluded — the local settings overlay (its
-// `activeBuild` cursor), the session sentinel, and the in-flight step markers
-// inside every build. Everything else under `.plumbbob/` (settings.json, and each
-// build's intent/build-log/checkpoints/report) rides the branch into the PR.
+// per-worktree control files stay git-excluded — the session sentinel STATE (whose
+// content is the active-build cursor, D28), the personal settings overlay, and the
+// in-flight step markers inside every build. Everything else under `.plumbbob/`
+// (settings.json, and each build's intent/build-log/checkpoints/report) rides the
+// branch into the PR.
 export function excludeControl(root) {
     addExcludes(root, [
         `${DIRNAME}/STATE`,
         `${DIRNAME}/settings.local.json`,
+        // The turn ledger and its one-turn grant (D64/D65): per-worktree control the
+        // model never writes, and never commits.
+        `${DIRNAME}/TURN`,
+        `${DIRNAME}/GRANT`,
         `${DIRNAME}/builds/*/STEP`,
         `${DIRNAME}/builds/*/SEAM`,
         `${DIRNAME}/builds/*/SPIKE`,
+        // The entry stamp (D64) is in-flight control like STEP/SEAM — checkpoint's
+        // stageAll must never sweep it into a step commit.
+        `${DIRNAME}/builds/*/TICK`,
         // The agent-run handoff ledger (D47) 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/build.js

@@ -3,7 +3,7 @@
 // BUILD phase from it); it never checkpoints (only `checkpoint` commits).
 import { readFileSync, writeFileSync } from 'node:fs';
 import { findRepoRoot } from "../lib/git.js";
-import { hasSession, intentPath, resolveBuild, seamPath, stepPath } from "../lib/sidecar.js";
+import { hasSession, intentPath, resolveBuild, seamPath, stampStepStat, stampTick, stepPath } from "../lib/sidecar.js";
 import { parseStepSeam } from "../lib/intent.js";
 export function build(cwd, args) {
     const root = findRepoRoot(cwd);
@@ -32,6 +32,10 @@ export function build(cwd, args) {
     }
     writeFileSync(seamPath(root, slug), `${parsed.seam.join('\n')}\n`);
     writeFileSync(stepPath(root, slug), `${step}\n`);
+    stampTick(root, slug); // the entry stamp (D64): TICK = TURN; skipped when the ledger is dormant.
+    // The wall-clock receipt starts here (research/07 Build 2b): checkpoint stamps
+    // landedAt, and the pair becomes the step's duration in the finish report.
+    stampStepStat(root, slug, step, 'startedAt', new Date().toISOString());
     process.stdout.write(`plumbbob: building step ${step}. Seam (for orientation; not a lock):\n${parsed.seam.map((p) => `  ${p}`).join('\n')}\n`);
     return 0;
 }