plumbbob 0.5.4 → 0.6.1

package/.claude-plugin/plugin.json

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

package/README.md

@@ -144,6 +144,14 @@ hand — or vibe it in another session, or in another harness entirely — and r
 `/pb-verify` instead: same checks, same pause, same checkpoint. It reads the *diff,
 not the author*.
 
+**Bring your own agents.** Because the executor is author-blind, you can plug your
+own in. A **user-authored agent** is any executable that speaks one small JSON
+envelope; drop it under `.plumbbob/agents/`, bind it to a step's `before`, `build`,
+or `after` slot in the build's `harness.json`, and PlumbBob runs it through the same
+pause — with **no way for it to advance the loop** (checkride still gates, you're
+still the clock). The full contract for authors, with a copy-paste example, is in
+[`docs/agents.md`](docs/agents.md).
+
 ## Why "PlumbBob"
 
 The name is the method. A plumb bob is a weight on a string — gravity pulls it into a
@@ -203,6 +211,7 @@ Each doc answers one question — in rough reading order for a new user:
 - *Should I / can I / what about…?* → [`docs/faq.md`](docs/faq.md) — the adoption questions, answered straight.
 - *What is each method for?* → [`docs/techniques.md`](docs/techniques.md) — steps, seams, the pause, park/harvest, spikes.
 - *What does each skill do?* → [`docs/skills-reference.md`](docs/skills-reference.md) — all twelve `/pb-*` skills: inputs, effects, when to reach for each.
+- *How do I plug in my own agent?* → [`docs/agents.md`](docs/agents.md) — the subprocess envelope, the manifest, `harness.json`, and a working example.
 - *How do I install it, exactly?* → [`docs/install.md`](docs/install.md) — the full guide and the agent-neutral roadmap.
 - *What does the CLI underneath do?* → [`docs/cli-reference.md`](docs/cli-reference.md) — every verb, flag, exit code, and the `.plumbbob/` sidecar.
 - *Something's broken.* → [`docs/troubleshooting.md`](docs/troubleshooting.md) — fixes for the common snags.

package/dist/cli-core.js

@@ -17,6 +17,7 @@ import { use } from "./verbs/use.js";
 import { finish } from "./verbs/finish.js";
 import { init } from "./verbs/init.js";
 import { doctor } from "./verbs/doctor.js";
+import { agent } from "./verbs/agent.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' },
@@ -30,6 +31,7 @@ const VERBS = [
     { name: 'finish', summary: 'close-out: report + final commit (no gate), clear the control state, close the session' },
     { 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' },
 ];
 // 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
@@ -82,6 +84,8 @@ async function dispatch(verb, cwd, rest) {
             return init(rest);
         case 'doctor':
             return doctor(cwd, rest);
+        case 'agent':
+            return agent(cwd, rest);
         default:
             process.stderr.write(`plumbbob: unknown verb '${verb}'. Run 'plumbbob help' for the verb table.\n`);
             return 1;

package/dist/lib/agents.js

@@ -0,0 +1,498 @@
+// The agent contract (D39/D46): a user-authored agent is anything executable that
+// speaks a versioned JSON envelope — a JSON manifest on disk (`agent.json`), JSON
+// on the child's stdin, JSON on its stdout, prose on its stderr. This module is
+// the contract's validator AND resolver: it type-narrows the on-disk manifest and
+// the output envelope a child returns (refusing a contract major-version mismatch
+// with an upgrade hint rather than guessing at a shape that is only stable within a
+// major — C7: additions are minor, removals/renames are major), and it walks the
+// two agent tiers to resolve an agent by name. The validators are pure; the
+// resolver reads `agent.json` files off disk (node builtins only, C2). Invocation
+// (step 4) spawns on top of these.
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { parseBuildTitle, parseStepMeta, parseStepSeam, scrapeBullets } from "./intent.js";
+// The contract major version this plumbbob speaks. A manifest or envelope
+// declaring a different major is refused (D46): within a major the envelope only
+// gains fields, so an older CLI can read a newer minor, but a major gap means the
+// shapes may genuinely disagree.
+export const CONTRACT_VERSION = 1;
+// The three lifecycle slots an agent may bind to (D43): `before` (context in),
+// `build` (the diff), `after` (advisory review). Exactly these, never a fourth —
+// "a salient point in the middle" is judgment the host model handles in prose,
+// not a declarative slot.
+export const SLOTS = ['before', 'build', 'after'];
+// The terminal states an agent reports (D52). `done` = finished; `blocked` = it
+// couldn't finish, so the human unblocks and re-runs; `drift` = it finished but
+// found the plan no longer matches reality, so the route is /pb-refine repair.
+export const ENVELOPE_STATUSES = ['done', 'blocked', 'drift'];
+// Validate a parsed `agent.json`. Contract is checked first (a version mismatch
+// gets an upgrade hint, not a field complaint, since older field checks may not
+// apply across a major). Then: a non-empty `name` and `command`, and a `slots`
+// subset of {before, build, after}. Unknown keys pass through untouched.
+export function parseManifest(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return manifestFail('agent.json must be a JSON object.');
+    }
+    const obj = raw;
+    const versionError = checkContract(obj.contract, 'agent.json');
+    if (versionError !== null) {
+        return manifestFail(versionError);
+    }
+    if (typeof obj.name !== 'string' || obj.name.trim().length === 0) {
+        return manifestFail('agent.json needs a non-empty "name" string.');
+    }
+    if (typeof obj.command !== 'string' || obj.command.trim().length === 0) {
+        return manifestFail('agent.json needs a non-empty "command" string — the shell command plumbbob spawns.');
+    }
+    const slots = parseSlots(obj.slots);
+    if (typeof slots === 'string') {
+        return manifestFail(slots);
+    }
+    return {
+        ok: true,
+        manifest: {
+            contract: CONTRACT_VERSION,
+            name: obj.name.trim(),
+            command: obj.command,
+            slots,
+            description: asString(obj.description),
+            when: asString(obj.when),
+        },
+    };
+}
+// Validate a child's output envelope (already JSON-parsed from its stdout).
+// Contract first (mismatch → upgrade hint), then a `status` in {done, blocked,
+// drift}, a non-empty `summary`, and a well-formed `parked[]`. Optional prose
+// fields default to empty; unknown keys are tolerated (C7).
+export function parseEnvelope(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return envelopeFail('the agent envelope must be a JSON object on stdout.');
+    }
+    const obj = raw;
+    const versionError = checkContract(obj.contract, 'the agent envelope');
+    if (versionError !== null) {
+        return envelopeFail(versionError);
+    }
+    if (typeof obj.status !== 'string' || !isStatus(obj.status)) {
+        return envelopeFail(`the agent envelope needs a "status" of ${ENVELOPE_STATUSES.join(', ')}.`);
+    }
+    if (typeof obj.summary !== 'string' || obj.summary.trim().length === 0) {
+        return envelopeFail('the agent envelope needs a non-empty "summary" string.');
+    }
+    const parked = parseParked(obj.parked);
+    if (typeof parked === 'string') {
+        return envelopeFail(parked);
+    }
+    return {
+        ok: true,
+        envelope: {
+            contract: CONTRACT_VERSION,
+            status: obj.status,
+            summary: obj.summary,
+            body: asString(obj.body),
+            parked,
+            notes: asString(obj.notes),
+        },
+    };
+}
+// True when a string names one of the three slots. Exported for step 4's
+// `--mode` refusal (D54): a mode the manifest doesn't declare is refused loud.
+export function isSlot(value) {
+    return SLOTS.includes(value);
+}
+// Validate the shared `contract` field. A missing / non-integer contract is
+// malformed; a present-but-different major is a version mismatch (D46) and gets an
+// upgrade hint pointing at whichever side is behind. Returns an error string, or
+// null when the contract is the supported major.
+function checkContract(value, what) {
+    if (typeof value !== 'number' || !Number.isInteger(value)) {
+        return `${what} needs an integer "contract" version — this plumbbob speaks contract ${CONTRACT_VERSION}.`;
+    }
+    if (value !== CONTRACT_VERSION) {
+        const behind = value > CONTRACT_VERSION ? 'plumbbob CLI' : 'agent';
+        return (`${what} speaks contract ${value}, but this plumbbob speaks contract ${CONTRACT_VERSION}. ` +
+            `Upgrade the ${behind} to match — the envelope is only stable within a major version.`);
+    }
+    return null;
+}
+// Narrow the manifest's `slots` to the subset it declares. Must be a non-empty
+// array drawn from SLOTS, with strangers refused and duplicates collapsed.
+// Returns the narrowed slots, or an error string.
+function parseSlots(value) {
+    if (!Array.isArray(value) || value.length === 0) {
+        return `agent.json needs a non-empty "slots" array drawn from ${SLOTS.join(', ')}.`;
+    }
+    const seen = new Set();
+    for (const entry of value) {
+        if (typeof entry !== 'string' || !isSlot(entry)) {
+            return `agent.json "slots" has an invalid entry ${JSON.stringify(entry)} — allowed slots are ${SLOTS.join(', ')}.`;
+        }
+        seen.add(entry);
+    }
+    return [...seen];
+}
+// `parked[]` is optional (absent = none). Present, it must be an array of
+// non-blank strings — each becomes a park line the CLI lands through the park
+// verb (D44). A malformed list is refused rather than silently dropped: losing a
+// parked concern is a quiet data loss. Returns the trimmed lines or an error.
+function parseParked(value) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        return 'the agent envelope\'s "parked" must be an array of strings.';
+    }
+    const parked = [];
+    for (const entry of value) {
+        if (typeof entry !== 'string' || entry.trim().length === 0) {
+            return 'the agent envelope\'s "parked" must contain only non-empty strings.';
+        }
+        parked.push(entry.trim());
+    }
+    return parked;
+}
+// Optional prose fields (description, when, body, notes) default to empty —
+// absent and blank read the same to the host model, and a non-string value is
+// coerced away rather than refused, because these are advisory prose, not gates.
+function asString(value) {
+    return typeof value === 'string' ? value : '';
+}
+function isStatus(value) {
+    return ENVELOPE_STATUSES.includes(value);
+}
+function manifestFail(error) {
+    return { ok: false, error };
+}
+function envelopeFail(error) {
+    return { ok: false, error };
+}
+export function projectAgentsDir(root) {
+    return join(root, '.plumbbob', 'agents');
+}
+export function personalAgentsDir(home) {
+    return join(home, '.plumbbob', 'agents');
+}
+// The home dir the personal tier resolves under. Callers (verbs) pass nothing and
+// get the environment's HOME (matching doctor.ts); tests pass an explicit dir to
+// exercise an HOME-overridden personal library without touching process.env.
+function agentsHome(home) {
+    return home ?? process.env.HOME ?? homedir();
+}
+// Resolve an agent by name across the tiers (D41), first hit wins. A `flagPath`
+// (from `--agent <path>`) points straight at an agent directory and takes top
+// priority. A tier "hits" when it holds an `agent.json`: a malformed one there is
+// surfaced as an error (project still shadows personal — D54's fail-loud), never
+// silently skipped in favor of a different agent. Returns the not-found error only
+// when no tier holds a manifest at all.
+export function resolveAgent(root, name, opts = {}) {
+    if (opts.flagPath !== undefined) {
+        const hit = loadAgentDir(opts.flagPath, 'flag');
+        return hit ?? { ok: false, error: `no agent.json at --agent path ${opts.flagPath}` };
+    }
+    const home = agentsHome(opts.home);
+    const tiers = [
+        [join(projectAgentsDir(root), name), 'project'],
+        [join(personalAgentsDir(home), name), 'personal'],
+    ];
+    for (const [dir, origin] of tiers) {
+        const hit = loadAgentDir(dir, origin);
+        if (hit !== null)
+            return hit;
+    }
+    return {
+        ok: false,
+        error: `no agent named "${name}" — looked in ${projectAgentsDir(root)} and ${personalAgentsDir(home)}.`,
+    };
+}
+// Every resolvable agent across both tiers, sorted by name, project shadowing
+// personal (a name defined in both resolves — and lists — from project). Each
+// entry carries its origin and resolution; a malformed manifest lands as an errored
+// resolution rather than crashing the walk.
+export function listAgents(root, opts = {}) {
+    const home = agentsHome(opts.home);
+    const tiers = [
+        [projectAgentsDir(root), 'project'],
+        [personalAgentsDir(home), 'personal'],
+    ];
+    const origins = new Map();
+    for (const [dir, origin] of tiers) {
+        for (const agentName of agentDirNames(dir)) {
+            if (!origins.has(agentName))
+                origins.set(agentName, origin);
+        }
+    }
+    return [...origins.keys()].sort().map((name) => ({
+        name,
+        origin: origins.get(name),
+        resolution: resolveAgent(root, name, { home }),
+    }));
+}
+// Render `agent list`'s output. Pure so the verb stays a thin read-write shell and
+// the formatting is unit-tested here. Prints name, origin, slots, and description
+// per agent (D41's done-when); a malformed manifest gets a `✗ … invalid:` line.
+export function formatAgentList(listings) {
+    if (listings.length === 0) {
+        return 'plumbbob: no agents. Add one under .plumbbob/agents/<name>/ or ~/.plumbbob/agents/<name>/.';
+    }
+    const lines = ['plumbbob agents:'];
+    for (const listing of listings) {
+        if (!listing.resolution.ok) {
+            lines.push(`  ✗ ${listing.name} (${listing.origin}) — invalid: ${listing.resolution.error}`);
+            continue;
+        }
+        const { manifest } = listing.resolution.agent;
+        const description = manifest.description.length > 0 ? ` — ${manifest.description}` : '';
+        lines.push(`  ${listing.name} (${listing.origin}) [${manifest.slots.join(', ')}]${description}`);
+    }
+    return lines.join('\n');
+}
+// Load and validate the `agent.json` in one agent directory. Returns null when the
+// directory holds no manifest (a tier miss, so resolution falls through), an errored
+// resolution when the manifest is present but unreadable/malformed, else the resolved
+// agent. A missing file (ENOENT throw) is the miss signal — one read, no TOCTOU race.
+function loadAgentDir(dir, origin) {
+    const file = join(dir, 'agent.json');
+    let raw;
+    try {
+        raw = readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, error: `${file} is not valid JSON.` };
+    }
+    const result = parseManifest(parsed);
+    return result.ok
+        ? { ok: true, agent: { manifest: result.manifest, origin, dir } }
+        : { ok: false, error: `${file}: ${result.error}` };
+}
+// The names of subdirectories under an agents tier that actually carry an
+// `agent.json` — so `listAgents` never lists a bare folder that resolution would
+// then miss. An absent tier directory yields no names.
+function agentDirNames(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && existsSync(join(dir, entry.name, 'agent.json')))
+            .map((entry) => entry.name);
+    }
+    catch {
+        return [];
+    }
+}
+// Compose the StepContext for one step. The strict seam parse is the only refusal
+// path — a missing step or unparseable seam gates git behavior, so it fails loud;
+// everything else is best-effort and lands whatever it can, returning `warnings`
+// (skipped-bullet lines) for the caller to print on stderr rather than writing
+// there itself (this module stays pure — the verb does the IO).
+export function composeStepContext(params) {
+    const seam = parseStepSeam(params.intent, params.step);
+    if (!seam.ok) {
+        return { ok: false, error: seam.error };
+    }
+    const meta = parseStepMeta(params.intent, params.step);
+    const decisions = scrapeBullets(params.intent, '## Decisions');
+    const constraints = scrapeBullets(params.intent, '## Constraints');
+    const warnings = [
+        ...skipWarnings('## Decisions', decisions.skipped),
+        ...skipWarnings('## Constraints', constraints.skipped),
+    ];
+    return {
+        ok: true,
+        input: {
+            contract: CONTRACT_VERSION,
+            mode: params.mode,
+            build: { slug: params.slug, title: parseBuildTitle(params.intent) },
+            step: { n: params.step, title: meta.title, doneWhen: meta.doneWhen, seam: seam.seam },
+            decisions: decisions.items,
+            constraints: constraints.items,
+            context: params.context ?? [],
+            settings: params.settings ?? {},
+        },
+        warnings,
+    };
+}
+function skipWarnings(heading, skipped) {
+    return skipped.map((line) => `intent.md: skipped a non-bullet line under ${heading} — ${JSON.stringify(line.trim())}`);
+}
+// Validate a parsed harness.json. Contract first (a major mismatch gets the same
+// upgrade hint as the manifest/envelope, D46). Structure is strict — a `steps` that
+// is not an object, a non-numeric step key, or a step entry that is not an object
+// is the author's error and is refused loud. Slot *contents* stay lenient (D61): a
+// slot value may be one name or a list, and blanks/non-strings drop rather than
+// refuse, because bindings feed a spawn, not a git-gating parse.
+export function parseHarness(raw) {
+    if (!isObject(raw)) {
+        return { ok: false, error: 'harness.json must be a JSON object.' };
+    }
+    const versionError = checkContract(raw.contract, 'harness.json');
+    if (versionError !== null) {
+        return { ok: false, error: versionError };
+    }
+    const defaults = parseSlotBindings(raw.defaults);
+    const steps = new Map();
+    if (raw.steps !== undefined) {
+        if (!isObject(raw.steps)) {
+            return { ok: false, error: 'harness.json "steps" must be an object keyed by step number.' };
+        }
+        for (const [key, value] of Object.entries(raw.steps)) {
+            if (!/^\d+$/.test(key)) {
+                return { ok: false, error: `harness.json "steps" key ${JSON.stringify(key)} must be a step number.` };
+            }
+            if (!isObject(value)) {
+                return { ok: false, error: `harness.json step ${key} must be an object of slot bindings.` };
+            }
+            steps.set(Number(key), { bindings: parseSlotBindings(value), note: asString(value.note) });
+        }
+    }
+    return { ok: true, harness: { contract: CONTRACT_VERSION, defaults, steps } };
+}
+// Read and validate a harness.json at `path`. The caller builds the path from the
+// build folder — this module stays ignorant of the sidecar layout, taking the full
+// path. null when the file is absent (a build with no bound agents — a clean
+// no-op); an errored parse when present-but-broken (invalid JSON or a malformed
+// structure the author must fix); else the validated bindings. Shared so every
+// reader (`agent run`, `status`) parses the harness the same way.
+export function readHarnessFile(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, error: `${path} is not valid JSON.` };
+    }
+    return parseHarness(parsed);
+}
+// Narrow a raw slot→agents object (a harness `defaults`, a per-step entry, or the
+// settings-level defaults, D57) to the slots it actually binds. A slot value may be
+// a single agent name or a list; blanks and non-strings drop. Only the three real
+// slots are read — `note` and any stranger key are ignored here. A slot present but
+// naming no valid agent still counts as bound-to-nothing (an explicit override to
+// none), so callers get clean replace semantics up the ladder.
+export function parseSlotBindings(raw) {
+    if (!isObject(raw))
+        return {};
+    const out = {};
+    for (const slot of SLOTS) {
+        if (slot in raw)
+            out[slot] = asNameList(raw[slot]);
+    }
+    return out;
+}
+// The agents bound to one slot for one step, merging the ladder (D57): a per-step
+// slot entry overrides the harness `defaults`, which override the settings-level
+// defaults — the first level that names the slot wins (replace, not append). The
+// `--agent` flag and an explicit name sit above all of this, but the verb takes the
+// single-agent path for those and never reaches here. Returns [] when no level
+// binds the slot: nothing to run, a clean no-op.
+export function resolveSlotAgents(params) {
+    const perStep = params.harness?.steps.get(params.step)?.bindings;
+    if (perStep && params.slot in perStep)
+        return perStep[params.slot] ?? [];
+    const defaults = params.harness?.defaults;
+    if (defaults && params.slot in defaults)
+        return defaults[params.slot] ?? [];
+    if (params.slot in params.settingsDefaults)
+        return params.settingsDefaults[params.slot] ?? [];
+    return [];
+}
+function asNameList(value) {
+    const items = Array.isArray(value) ? value : [value];
+    return items.filter((v) => typeof v === 'string' && v.trim().length > 0).map((v) => v.trim());
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+// Spawn an agent's `command` via the shell (D49: `sh -c` on POSIX) at the repo
+// root, with the composed StepContext delivered as JSON on stdin. Stdout is piped
+// and captured (the envelope); stderr is inherited so the child's prose streams
+// live to the terminal (D46 — production narrates, consumption stays structured);
+// the agent's own directory rides in `PLUMBBOB_AGENT_DIR` (D49) so a root-cwd
+// agent can still reach its files. A SIGINT while the child runs kills it and
+// reports `interrupted` rather than orphaning it (D58); a positive `timeoutSeconds`
+// arms a kill timer (D51, 0 = off). Async `spawn`, not `spawnSync` (D60), so the
+// parent stays live to interrupt gracefully. Never rejects — every failure mode is
+// a resolved `AgentRunResult`.
+export function runAgent(params) {
+    return new Promise((resolve) => {
+        const child = spawn(params.command, {
+            cwd: params.root,
+            shell: true,
+            env: { ...process.env, PLUMBBOB_AGENT_DIR: params.agentDir },
+            stdio: ['pipe', 'pipe', 'inherit'],
+        });
+        let stdout = '';
+        let settled = false;
+        let timer = null;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== null)
+                clearTimeout(timer);
+            process.off('SIGINT', onSigint);
+            resolve(result);
+        };
+        // Kill the child and report, rather than let a Ctrl-C orphan it (D58). The
+        // SIGKILL escalation covers a child that ignores the interrupt.
+        function onSigint() {
+            child.kill('SIGKILL');
+            finish({ ok: false, reason: 'interrupted' });
+        }
+        process.on('SIGINT', onSigint);
+        if (params.timeoutSeconds > 0) {
+            timer = setTimeout(() => {
+                child.kill('SIGKILL');
+                finish({ ok: false, reason: 'timeout', seconds: params.timeoutSeconds });
+            }, params.timeoutSeconds * 1000);
+        }
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString();
+        });
+        // A shell that never launched (e.g. `sh` itself missing) — distinct from a
+        // command that ran and exited non-zero, which arrives on `close`.
+        child.on('error', (err) => {
+            finish({ ok: false, reason: 'spawn', error: err.message });
+        });
+        child.on('close', (code) => {
+            if (code !== 0) {
+                finish({ ok: false, reason: 'exit', code: code ?? 1, stdout });
+                return;
+            }
+            const parsed = parseChildEnvelope(stdout);
+            finish(parsed.ok
+                ? { ok: true, envelope: parsed.envelope, stdout }
+                : { ok: false, reason: 'contract', error: parsed.error, stdout });
+        });
+        // Deliver the StepContext and close stdin so a child reading to EOF proceeds.
+        child.stdin.write(JSON.stringify(params.input));
+        child.stdin.end();
+    });
+}
+// Parse the child's captured stdout into a validated envelope: JSON first (a
+// non-JSON stdout is out of contract, D46), then the envelope validator (which
+// carries the contract-mismatch hint). Kept private — `runAgent` is the only
+// caller and the verb reads the union, not this.
+function parseChildEnvelope(stdout) {
+    let raw;
+    try {
+        raw = JSON.parse(stdout);
+    }
+    catch {
+        return { ok: false, error: 'the agent wrote non-JSON to stdout — the envelope must be a single JSON object.' };
+    }
+    return parseEnvelope(raw);
+}