plumbbob 0.5.3 → 0.6.1

package/dist/lib/intent.js

@@ -1,13 +1,16 @@
-// The strict intent parser. `build <n>` reads the nth step under `## Steps` and
-// extracts its seam — the backtick-wrapped paths on the single `seam:` sub-line.
-// Strict by design: it refuses precisely on globs, absolute paths, a missing
-// step, a missing seam, or more than one seam line, rather than guessing.
+// The intent parser. `build <n>` reads the nth step under `## Steps` and extracts
+// its seam — the backtick-wrapped paths on the single `seam:` sub-line. The seam
+// half is strict by design (it gates git behavior): it refuses precisely on globs,
+// absolute paths, a missing step, a missing seam, or more than one seam line,
+// rather than guessing. The best-effort scrapers below (title, done-when,
+// decisions, constraints) feed an agent's context, not a gate, so they never
+// refuse — they return what they can and report the lines they skipped (D61).
 const GLOB_CHARS = /[*?[\]{}]/;
-export function parseStepSeam(content, step) {
+function sliceStep(content, step) {
     const lines = content.split('\n');
     const stepsIdx = lines.findIndex((l) => l.trim() === '## Steps');
     if (stepsIdx === -1) {
-        return fail('intent.md has no "## Steps" section.');
+        return { ok: false, error: 'intent.md has no "## Steps" section.' };
     }
     let sectionEnd = lines.findIndex((l, i) => i > stepsIdx && l.startsWith('## '));
     if (sectionEnd === -1) {
@@ -22,12 +25,19 @@ export function parseStepSeam(content, step) {
     }
     const pos = itemStarts.findIndex((s) => s.n === step);
     if (pos === -1) {
-        return fail(`intent.md has no step ${step} under "## Steps".`);
+        return { ok: false, error: `intent.md has no step ${step} under "## Steps".` };
     }
     const itemStart = itemStarts[pos]?.idx ?? stepsIdx;
     const nextStart = itemStarts[pos + 1]?.idx;
     const itemEnd = nextStart === undefined ? sectionEnd : nextStart;
-    const itemLines = lines.slice(itemStart, itemEnd);
+    return { ok: true, itemLines: lines.slice(itemStart, itemEnd) };
+}
+export function parseStepSeam(content, step) {
+    const slice = sliceStep(content, step);
+    if (!slice.ok) {
+        return fail(slice.error);
+    }
+    const itemLines = slice.itemLines;
     const seamLines = itemLines
         .map((l, i) => ({ l, i }))
         .filter(({ l }) => /^\s*-\s*seam:/.test(l))
@@ -102,6 +112,86 @@ export function scopeDrift(paths, seam) {
     }
     return paths.filter((p) => !matchesSeam(p, seam) && !isArtifactPath(p));
 }
+const DONE_WHEN = /\*\*done when:\*\*/i;
+export function parseStepMeta(content, step) {
+    const slice = sliceStep(content, step);
+    if (!slice.ok) {
+        return { title: '', doneWhen: '' };
+    }
+    // Gather the opener and its wrapped continuation lines, stopping at the first
+    // sub-bullet (`- seam:` and friends), then flatten to one line.
+    const collected = [];
+    for (let i = 0; i < slice.itemLines.length; i++) {
+        const line = slice.itemLines[i] ?? '';
+        if (i > 0 && /^\s*-\s/.test(line)) {
+            break;
+        }
+        collected.push(line.trim());
+    }
+    const body = collected.join(' ').replace(/^\d+\.\s*(?:\[[ xX]\]\s*)?/, '').trim();
+    const m = DONE_WHEN.exec(body);
+    if (m === null) {
+        return { title: stripTrailingDash(body), doneWhen: '' };
+    }
+    return {
+        title: stripTrailingDash(body.slice(0, m.index)),
+        doneWhen: body.slice(m.index + m[0].length).trim(),
+    };
+}
+// The build title — the first `# ` heading. '' when absent.
+export function parseBuildTitle(content) {
+    for (const line of content.split('\n')) {
+        const m = /^#\s+(.+)$/.exec(line);
+        if (m) {
+            return (m[1] ?? '').trim();
+        }
+    }
+    return '';
+}
+export function scrapeBullets(content, heading) {
+    const lines = content.split('\n');
+    const start = lines.findIndex((l) => l.trim() === heading);
+    if (start === -1) {
+        return { items: [], skipped: [] };
+    }
+    let end = lines.findIndex((l, i) => i > start && l.startsWith('## '));
+    if (end === -1) {
+        end = lines.length;
+    }
+    const items = [];
+    const skipped = [];
+    let current = null;
+    const flush = () => {
+        if (current !== null) {
+            items.push(current.join(' '));
+            current = null;
+        }
+    };
+    for (let i = start + 1; i < end; i++) {
+        const line = lines[i] ?? '';
+        const bullet = /^-\s+(.*)$/.exec(line);
+        if (bullet !== null) {
+            flush();
+            current = [(bullet[1] ?? '').trim()];
+        }
+        else if (line.trim() === '') {
+            flush();
+        }
+        else if (current !== null && /^\s+\S/.test(line)) {
+            current.push(line.trim());
+        }
+        else {
+            skipped.push(line);
+        }
+    }
+    flush();
+    return { items, skipped };
+}
+// Trim a trailing em-dash or hyphen (the `Title —` separator) plus surrounding
+// space, so a title never carries the marker that introduced its done-when.
+function stripTrailingDash(text) {
+    return text.replace(/\s*[—-]+\s*$/, '').trim();
+}
 function fail(error) {
     return { ok: false, error };
 }

package/dist/lib/settings.js

@@ -53,6 +53,23 @@ export function resolveBoolean(root, key, fallback, flag) {
     const value = resolveSetting(root, key, flag);
     return typeof value === 'boolean' ? value : fallback;
 }
+// Resolve a non-negative integer setting (e.g. `agentTimeout`, D51). A missing
+// rung, or one holding a non-finite / negative / non-integer number, yields the
+// caller's fallback rather than a garbage timeout — 0 means "no timeout", so a
+// broken value must never silently become one.
+export function resolveNumber(root, key, fallback, flag) {
+    const value = resolveSetting(root, key, flag);
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : fallback;
+}
+// Resolve an object-valued setting (e.g. the `agents` slot-binding defaults, D57)
+// across the same ladder. The first defined, object-typed rung wins; a missing
+// rung, or one holding a non-object / array / scalar, yields {} rather than
+// garbage — mirrors the string/boolean/number resolvers above. No flag rung: the
+// caller (`agent run`) merges these under the per-build harness, not over a flag.
+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).

package/dist/lib/sidecar.js

@@ -27,8 +27,9 @@ export function buildDir(root, slug) {
 // Derive a filesystem-safe slug from a build title: lowercased, every run of
 // non-alphanumerics collapsed to a single hyphen, trimmed of leading/trailing
 // hyphens. The CLI stays dumb and explicit (D38) — collision handling belongs to
-// the caller (`start` refuses rather than silently suffixing `-2`). A title with
-// no alphanumerics yields `''`, which the caller must reject or override.
+// the caller (`start` refuses rather than silently suffixing `-2`, and prepends
+// the `YYYY-MM-DD-` date that keeps `listBuilds`' lexical sort chronological). A
+// title with no alphanumerics yields `''`, which the caller must reject or override.
 export function slugify(title) {
     return title
         .toLowerCase()
@@ -125,6 +126,39 @@ export function buildLogPath(root, slug) {
 export function reportPath(root, slug) {
     return join(artifactDir(root, slug), 'report.md');
 }
+// handoff.json is the agent-run ledger (D47): each `agent run` appends its
+// validated envelope here so a later invocation can thread earlier results into
+// the next call's `context[]` — the CLI itself is memoryless between runs, and
+// the file survives context-window compaction where inline stdout does not. It is
+// in-flight control state like STEP/SEAM: untracked (excludeControl), scoped to
+// the current step, cleared when the step checkpoints (`clearHandoff`).
+export function handoffPath(root, slug) {
+    return join(artifactDir(root, slug), 'handoff.json');
+}
+// Append one entry to the build's handoff.json, creating the file (as a JSON
+// array) when absent and tolerating a malformed existing file by starting fresh —
+// a corrupt ledger must never wedge a run. Pretty-printed so it stays readable.
+export function appendHandoff(root, slug, entry) {
+    const path = handoffPath(root, slug);
+    let entries = [];
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (Array.isArray(parsed))
+            entries = parsed;
+    }
+    catch {
+        entries = [];
+    }
+    entries.push(entry);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(entries, null, 2)}\n`);
+}
+// Remove the build's handoff.json — the step-scoped ledger is cleared when the
+// step checkpoints (D47), the same beat that clears STEP/SEAM. Absent file is a
+// no-op (`force`).
+export function clearHandoff(root, slug) {
+    rmSync(handoffPath(root, slug), { force: true });
+}
 // 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.
@@ -177,6 +211,9 @@ export function excludeControl(root) {
         `${DIRNAME}/builds/*/STEP`,
         `${DIRNAME}/builds/*/SEAM`,
         `${DIRNAME}/builds/*/SPIKE`,
+        // 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`,
         // The checkride gate (D32) writes raw tool output to `.check/`; checkpoint's
         // stageAll must never sweep it into a step commit.
         '.check/',

package/dist/verbs/agent.js

@@ -0,0 +1,312 @@
+// `plumbbob agent <subcommand>` — the doorway to user-authored agents (D39/D41).
+// `agent list` walks the two tiers and prints each resolvable agent. `agent run
+// <name> [--step N] [--mode before|build|after]` (D60) composes the StepContext,
+// spawns the manifest command, streams its stderr live, captures and validates
+// the child's envelope, re-emits it on this verb's own stdout (machine) with the
+// human summary on stderr (D46/D47), lands `parked[]` through the build-log (D44),
+// and appends the envelope to the step-scoped handoff ledger (D47). There is no
+// code path here to checkpoint, flip a step, or chain agents — the identity
+// invariant (C6) holds by construction. A thin read-write shell: resolution,
+// composition, and spawn mechanics live in lib/agents.ts.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { findRepoRoot } from "../lib/git.js";
+import { SLOTS, composeStepContext, formatAgentList, isSlot, listAgents, parseSlotBindings, readHarnessFile, resolveAgent, resolveSlotAgents, runAgent, } from "../lib/agents.js";
+import { appendToSection } from "../lib/buildlog.js";
+import { resolveBoolean, resolveNumber, resolveRecord } from "../lib/settings.js";
+import { appendHandoff, buildFolder, buildLogPath, hasSession, intentPath, resolveBuild, stepPath } from "../lib/sidecar.js";
+export async function agent(cwd, args = []) {
+    const [sub, ...rest] = args;
+    if (sub === 'list')
+        return list(cwd, rest);
+    if (sub === 'run')
+        return run(cwd, rest);
+    const known = 'Available subcommands: list, run.';
+    const message = sub === undefined ? `plumbbob agent <subcommand>. ${known}` : `plumbbob: unknown 'agent' subcommand '${sub}'. ${known}`;
+    process.stderr.write(`${message}\n`);
+    return 1;
+}
+function list(cwd, _args) {
+    const root = findRepoRoot(cwd);
+    if (root === null) {
+        process.stderr.write('plumbbob: not inside a git repository.\n');
+        return 1;
+    }
+    process.stdout.write(`${formatAgentList(listAgents(root))}\n`);
+    return 0;
+}
+// `agent run`: with a name (or `--agent` flag) run exactly that agent, failing
+// loud on a miss (D54); with no name run the step's harness-bound agents for the
+// requested slot (D42). Either way this composes the StepContext, spawns, and
+// applies side effects — never advancing the loop.
+async function run(cwd, args) {
+    const root = findRepoRoot(cwd);
+    if (root === null || !hasSession(root)) {
+        process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
+        return 1;
+    }
+    const { build: slug, rest } = resolveBuild(root, args);
+    const parsed = parseRunArgs(rest);
+    if (typeof parsed === 'string') {
+        process.stderr.write(`${parsed}\n`);
+        return 1;
+    }
+    const step = parsed.step ?? readStep(root, slug);
+    if (step === null) {
+        process.stderr.write('plumbbob: no step to run against — pass --step N, or `plumbbob build N` first.\n');
+        return 1;
+    }
+    // A `--agent <path>` flag still needs a name — it labels an explicit run (the
+    // handoff ledger and the human summary key on the name), it does not name one.
+    if (parsed.name === undefined && parsed.flagPath !== undefined) {
+        process.stderr.write('plumbbob: --agent needs an agent name too, for the run label. Try: plumbbob agent run reviewer --agent ./path --step 3.\n');
+        return 1;
+    }
+    // Explicit ask (a name, above the bindings — D57): run exactly it, fail loud on
+    // a miss. No name: resolve the harness bindings for the slot and run them.
+    if (parsed.name !== undefined) {
+        return runOne(root, slug, step, {
+            name: parsed.name,
+            flagPath: parsed.flagPath,
+            mode: parsed.mode,
+            ambient: false,
+        });
+    }
+    return runBound(root, slug, step, parsed.mode);
+}
+async function runOne(root, slug, step, spec) {
+    const resolution = resolveAgent(root, spec.name, spec.flagPath !== undefined ? { flagPath: spec.flagPath } : {});
+    if (!resolution.ok) {
+        return degrade(spec.ambient, `plumbbob: ${resolution.error}`, `plumbbob: bound agent "${spec.name}" did not resolve — ${resolution.error} Skipping (D54 — the loop works without it).`);
+    }
+    const { manifest, dir } = resolution.agent;
+    const resolved = resolveMode(spec.mode, manifest);
+    if (!resolved.ok) {
+        return degrade(spec.ambient, resolved.error, `plumbbob: bound agent "${spec.name}" — ${resolved.error.replace(/^plumbbob:\s*/, '')} Skipping (D54).`);
+    }
+    const mode = resolved.mode;
+    let intent;
+    try {
+        intent = readFileSync(intentPath(root, slug), 'utf8');
+    }
+    catch {
+        process.stderr.write('plumbbob: no intent.md for the active build — cannot compose the agent input.\n');
+        return 1;
+    }
+    const composed = composeStepContext({
+        intent,
+        slug: slug ?? '',
+        step,
+        mode,
+        settings: {
+            auto: resolveBoolean(root, 'auto', false),
+            agentTimeout: resolveNumber(root, 'agentTimeout', 0),
+        },
+    });
+    if (!composed.ok) {
+        process.stderr.write(`plumbbob: ${composed.error}\n`);
+        return 1;
+    }
+    for (const warning of composed.warnings) {
+        process.stderr.write(`${warning}\n`);
+    }
+    const result = await runAgent({
+        root,
+        command: manifest.command,
+        agentDir: dir,
+        input: composed.input,
+        timeoutSeconds: resolveNumber(root, 'agentTimeout', 0),
+    });
+    return report(root, slug, spec.name, mode, step, result);
+}
+// No name given: run the harness-bound agents for the requested slot (D42). The
+// bindings merge the ladder — per-step over harness defaults over settings-level
+// defaults (D57). A missing bound agent degrades to a warning (D54); an absent
+// harness, or one that binds nothing to this slot, is a clean no-op. Each bound
+// agent runs in turn; the batch exits 1 if any agent that actually ran failed.
+async function runBound(root, slug, step, modeFlag) {
+    if (modeFlag === undefined) {
+        process.stderr.write('plumbbob: agent run needs an agent name, or --mode <slot> to run the step\'s bound agents.\n');
+        return 1;
+    }
+    if (!isSlot(modeFlag)) {
+        process.stderr.write(`plumbbob: unknown --mode '${modeFlag}' — slots are ${SLOTS.join(', ')}.\n`);
+        return 1;
+    }
+    const harness = readHarnessFile(join(buildFolder(root, slug), 'harness.json'));
+    if (harness !== null && !harness.ok) {
+        process.stderr.write(`plumbbob: ${harness.error}\n`);
+        return 1;
+    }
+    const settingsDefaults = parseSlotBindings(resolveRecord(root, 'agents'));
+    const names = resolveSlotAgents({
+        harness: harness?.harness ?? null,
+        settingsDefaults,
+        step,
+        slot: modeFlag,
+    });
+    if (names.length === 0) {
+        process.stderr.write(`plumbbob: no agents bound to the '${modeFlag}' slot for step ${step} — nothing to run.\n`);
+        return 0;
+    }
+    let worst = 0;
+    for (const name of names) {
+        const code = await runOne(root, slug, step, { name, flagPath: undefined, mode: modeFlag, ambient: true });
+        if (code !== 0)
+            worst = code;
+    }
+    return worst;
+}
+// Emit the loud error or the soft warning by whether this run was an explicit ask
+// (name/flag) or an ambient harness binding (D54/D54), and return the matching
+// code — a hard miss stops with 1, a degraded one warns and returns 0 so a batch
+// of bound agents carries on.
+function degrade(ambient, hard, soft) {
+    process.stderr.write(`${ambient ? soft : hard}\n`);
+    return ambient ? 0 : 1;
+}
+// Split `run`'s argv (with `--build` already stripped by resolveBuild) into the
+// agent name and the value flags. A value flag missing its value, or `--step`
+// given a non-number, is a loud error (returned as a string) rather than a silent
+// default. Unknown `--flags` are ignored — the point is the named agent.
+function parseRunArgs(args) {
+    const positionals = [];
+    let step;
+    let mode;
+    let flagPath;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--step') {
+            const value = args[++i];
+            if (value === undefined || !/^\d+$/.test(value) || Number(value) < 1) {
+                return 'plumbbob: --step needs a positive step number.';
+            }
+            step = Number(value);
+        }
+        else if (arg === '--mode') {
+            const value = args[++i];
+            if (value === undefined)
+                return `plumbbob: --mode needs a slot (${SLOTS.join(', ')}).`;
+            mode = value;
+        }
+        else if (arg === '--agent') {
+            const value = args[++i];
+            if (value === undefined)
+                return 'plumbbob: --agent needs a path to an agent directory.';
+            flagPath = value;
+        }
+        else if (!arg.startsWith('--')) {
+            positionals.push(arg);
+        }
+    }
+    return { name: positionals[0], step, mode, flagPath };
+}
+// Resolve the slot the agent runs in. An explicit `--mode` must name a real slot
+// AND one the manifest declares — an undeclared slot is refused loud (D54). With
+// no `--mode`, a single-slot agent uses its only slot; a multi-slot agent must be
+// told which one (step 5's harness bindings pick the slot from the lifecycle
+// point; a bare `run` cannot guess).
+function resolveMode(flag, manifest) {
+    if (flag !== undefined) {
+        if (!isSlot(flag))
+            return { ok: false, error: `plumbbob: unknown --mode '${flag}' — slots are ${SLOTS.join(', ')}.` };
+        if (!manifest.slots.includes(flag)) {
+            return {
+                ok: false,
+                error: `plumbbob: agent "${manifest.name}" does not declare the '${flag}' slot (it declares ${manifest.slots.join(', ')}).`,
+            };
+        }
+        return { ok: true, mode: flag };
+    }
+    if (manifest.slots.length === 1)
+        return { ok: true, mode: manifest.slots[0] };
+    return {
+        ok: false,
+        error: `plumbbob: agent "${manifest.name}" declares multiple slots (${manifest.slots.join(', ')}) — pass --mode <slot>.`,
+    };
+}
+// Map the run outcome to reporting and side effects (D46). A failed run — non-zero
+// exit, out-of-contract stdout, timeout, interrupt, or a shell that never
+// started — reports on stderr and stops with NO side effects (the envelope of a
+// failed child is not authoritative). A clean run lands `parked[]` (D44), records
+// the envelope in the handoff ledger (D47), prints the human summary on stderr,
+// and re-emits the machine envelope on stdout — nothing else, ever (the stream
+// discipline: stdout carries the envelope alone).
+function report(root, slug, name, mode, step, result) {
+    if (!result.ok) {
+        process.stderr.write(`${failureLine(name, result)}\n`);
+        return 1;
+    }
+    const { envelope } = result;
+    applyParked(root, slug, envelope.parked);
+    appendHandoff(root, slug, { agent: name, mode, step, envelope });
+    process.stderr.write(humanSummary(name, mode, envelope));
+    process.stdout.write(`${JSON.stringify(envelope)}\n`);
+    return 0;
+}
+function failureLine(name, result) {
+    switch (result.reason) {
+        case 'exit':
+            return `plumbbob: agent "${name}" exited ${result.code} — failed run, stopping. No side effects applied.`;
+        case 'contract':
+            return `plumbbob: agent "${name}" is out of contract — ${result.error}`;
+        case 'timeout':
+            return `plumbbob: agent "${name}" timed out after ${result.seconds}s — killed.`;
+        case 'interrupted':
+            return `plumbbob: interrupted — killed agent "${name}".`;
+        case 'spawn':
+            return `plumbbob: could not spawn agent "${name}" — ${result.error}`;
+    }
+}
+// Land each parked concern through the build-log's Park list (D44 — the agent
+// never writes .plumbbob/ itself). A build-log with no "## Park list" section, or
+// no build-log at all, warns once rather than losing the lines silently.
+function applyParked(root, slug, parked) {
+    if (parked.length === 0)
+        return;
+    const path = buildLogPath(root, slug);
+    let content;
+    try {
+        content = readFileSync(path, 'utf8');
+    }
+    catch {
+        process.stderr.write(`plumbbob: no build-log.md — could not park ${parked.length} line(s) the agent returned.\n`);
+        return;
+    }
+    for (const line of parked) {
+        const updated = appendToSection(content, 'Park list', `- [ ] ${line}`);
+        if (updated === null) {
+            process.stderr.write(`plumbbob: no "## Park list" in build-log.md — could not park: ${line}\n`);
+            return;
+        }
+        content = updated;
+        process.stderr.write(`plumbbob: parked — ${line}\n`);
+    }
+    writeFileSync(path, content);
+}
+// The human-facing summary on stderr (D47): a headline plus, for a halt, the
+// route the skills name (D52) — `blocked` unblocks and re-runs, `drift` sends the
+// plan to /pb-refine. The machine envelope on stdout carries the same status for
+// the calling skill; this is the terminal read.
+function humanSummary(name, mode, envelope) {
+    const head = `plumbbob: agent "${name}" (${mode}) — ${envelope.status}: ${envelope.summary}\n`;
+    const notes = envelope.notes.length > 0 ? `  notes: ${envelope.notes}\n` : '';
+    if (envelope.status === 'blocked') {
+        return `${head}  blocked — the agent couldn't finish; unblock and re-run.\n${notes}`;
+    }
+    if (envelope.status === 'drift') {
+        return `${head}  drift — the plan no longer matches reality; /pb-refine before continuing.\n${notes}`;
+    }
+    return head;
+}
+// The in-flight step for this build (the STEP marker `build` wrote), or null when
+// none is set — the caller then requires an explicit `--step`.
+function readStep(root, slug) {
+    try {
+        const raw = readFileSync(stepPath(root, slug), 'utf8').trim();
+        return /^\d+$/.test(raw) ? Number(raw) : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/verbs/checkpoint.js

@@ -9,7 +9,7 @@
 // the same way.
 import { appendFileSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { commit, findRepoRoot, headSha, isDirty, stageAll, stagePath, stagedPaths, stagedStat } from "../lib/git.js";
-import { buildFolder, buildLogPath, checkpointsPath, hasSession, intentPath, seamPath, stepPath } from "../lib/sidecar.js";
+import { buildFolder, buildLogPath, checkpointsPath, clearHandoff, hasSession, intentPath, seamPath, stepPath, } from "../lib/sidecar.js";
 import { runCheck } from "../lib/check.js";
 import { markStepDone, parseSteps, parseTitle } from "../lib/orient.js";
 import { parseStepSeam, scopeDrift } from "../lib/intent.js";
@@ -50,6 +50,7 @@ export async function checkpoint(cwd, args) {
     logCheckpoint(root, step, sha);
     rmSync(seamPath(root), { force: true });
     rmSync(stepPath(root), { force: true });
+    clearHandoff(root); // the agent-run ledger is step-scoped (D47) — clear it with the markers.
     process.stdout.write(`plumbbob: step ${step} checkpointed — ${sha.slice(0, 9)}. Back at the boundary.\n`);
     return 0;
 }

package/dist/verbs/doctor.js

@@ -22,11 +22,12 @@
 //    "detected but tool missing" is the footgun this exists for.
 //
 // Functional, node builtins plus checkride (C1/C2).
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { accessSync, constants, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { dirname, isAbsolute, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { runDoctor } from 'checkride';
+import { listAgents } from "../lib/agents.js";
 import { marketplacePlumbbob } from "../lib/plugins.js";
 import { findRepoRoot, gitPath, stagePath } from "../lib/git.js";
 import { buildDir, excludeControl, listBuilds, sidecarDir, slugify } from "../lib/sidecar.js";
@@ -264,6 +265,96 @@ function sidecarReport(cwd, migrate) {
     lines.push('        (archive/ + the active session → builds/, config → settings.json; staged, never committed)');
     return { lines, failed: 1 };
 }
+// --- agent validation (D48) ---
+// Interpreters recognized as the program of a manifest `command`: when the command
+// is `sh <script>` / `node <script>` / …, the checkable artifact is the script
+// argument (the interpreter reads it — the file need not carry +x), not the
+// interpreter, which we trust to be on PATH.
+const INTERPRETERS = new Set(['sh', 'bash', 'zsh', 'dash', 'node', 'deno', 'bun', 'python', 'python3', 'ruby', 'perl']);
+// Expand PLUMBBOB_AGENT_DIR (D49) in a command and split it into bare tokens
+// (surrounding quotes stripped). A deliberately shallow split — enough for the
+// static command check below, not a shell parser (which is neither possible nor
+// wanted for a best-effort diagnostic).
+function commandTokens(command, agentDir) {
+    const expanded = command.replaceAll('${PLUMBBOB_AGENT_DIR}', agentDir).replaceAll('$PLUMBBOB_AGENT_DIR', agentDir);
+    return expanded
+        .split(/\s+/)
+        .filter((t) => t.length > 0)
+        .map((t) => t.replace(/^['"]/, '').replace(/['"]$/, ''));
+}
+// Statically check a manifest `command` for the footgun D48 names: a script file
+// that does not exist, or a directly-invoked one missing its +x bit. The command
+// is a shell string spawned via `sh -c` at the repo root (D49), so a relative path
+// resolves against `root` and PLUMBBOB_AGENT_DIR points at the agent's own dir.
+// Best-effort by design — a path-shaped program or an interpreter's script
+// argument is checked; a bare command (a PATH binary, an inline `node -e` program)
+// is trusted, because we cannot prove a shell line broken without running it.
+// Returns the problem string, or null when nothing checkable is wrong.
+function checkCommand(command, agentDir, root) {
+    const tokens = commandTokens(command, agentDir);
+    if (tokens.length === 0)
+        return null;
+    const resolve = (p) => (isAbsolute(p) ? p : join(root, p));
+    const program = tokens[0];
+    // A path-shaped program is invoked directly, so it must exist AND be executable.
+    if (program.includes('/')) {
+        const path = resolve(program);
+        if (!existsSync(path))
+            return `command program ${program} does not exist`;
+        try {
+            accessSync(path, constants.X_OK);
+        }
+        catch {
+            return `command program ${program} is not executable — chmod +x it`;
+        }
+        return null;
+    }
+    // An interpreter reads its script argument, so the script need only exist.
+    if (INTERPRETERS.has(program)) {
+        const script = tokens.slice(1).find((t) => t.includes('/'));
+        if (script !== undefined && !existsSync(resolve(script))) {
+            return `command script ${script} does not exist`;
+        }
+    }
+    return null;
+}
+// One agent's problem (D48), or null when it validates: a malformed or
+// unsupported-contract manifest surfaces as its resolution error; an
+// otherwise-valid agent is checked for a missing/non-executable command.
+function agentProblem(listing, root) {
+    if (!listing.resolution.ok)
+        return listing.resolution.error;
+    const { manifest, dir } = listing.resolution.agent;
+    return checkCommand(manifest.command, dir, root);
+}
+// The agent-validation section (D48): walk every resolvable agent across both
+// tiers (project + personal) and flag a malformed agent.json, an unsupported
+// contract version (both arrive as the listing's parse error), or a
+// missing/non-executable command. A repo with no agents shows no section (like the
+// sidecar one), keeping doctor quiet for the common case; outside a repo there is
+// no project tier to anchor to, so the section is skipped entirely.
+function agentReport(cwd) {
+    const root = findRepoRoot(cwd);
+    if (root === null)
+        return { lines: [], failed: 0 };
+    const listings = listAgents(root);
+    if (listings.length === 0)
+        return { lines: [], failed: 0 };
+    const lines = ['', 'plumbbob doctor — agents (D48)'];
+    let failed = 0;
+    for (const listing of listings) {
+        const problem = agentProblem(listing, root);
+        if (problem === null) {
+            const slots = listing.resolution.ok ? ` [${listing.resolution.agent.manifest.slots.join(', ')}]` : '';
+            lines.push(`  ✓ ${listing.name} (${listing.origin})${slots}`);
+        }
+        else {
+            lines.push(`  ✗ ${listing.name} (${listing.origin}) — ${problem}`);
+            failed += 1;
+        }
+    }
+    return { lines, failed };
+}
 // The check-gate section (D32): a configured `check` setting names the spawn
 // override and asks nothing more; otherwise checkride's own doctor reports the
 // slot/adapter table. Only rows checkride marks `required` count as problems —
@@ -319,9 +410,11 @@ export async function doctor(cwd, args = []) {
     }
     const sidecar = sidecarReport(cwd, args.includes('--migrate'));
     out.push(...sidecar.lines);
+    const agents = agentReport(cwd);
+    out.push(...agents.lines);
     const gate = await gateReport(cwd);
     out.push(...gate.lines);
-    const failed = checks.filter((c) => !c.ok).length + sidecar.failed + gate.failed;
+    const failed = checks.filter((c) => !c.ok).length + sidecar.failed + agents.failed + gate.failed;
     out.push('');
     out.push(failed === 0
         ? 'plumbbob: all checks passed. If a skill still misbehaves, restart Claude Code (or /reload-plugins).'