unitbob 0.2.3 → 0.2.6

package/dist/bin.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// The published executable (`package.json` bin). It exists only to start the
+// process and end it: no logic lives here, so nothing about how the CLI was
+// invoked can change what it does. npm installs a bin as a symlink, so this file
+// runs under a path that is not its own — an entry point that tried to detect
+// "am I the main module?" silently did nothing once installed.
+import { main } from "./cli.js";
+main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+    process.stderr.write(`${err.message}\n`);
+    process.exit(1);
+});

package/dist/cli.js

@@ -1,7 +1,8 @@
-#!/usr/bin/env node
-// The single entry point. Parse `unitbob <verb> [args]`, dispatch to a hands-verb,
-// and map any thrown error to a non-zero exit with an actionable message — never
-// a raw stack trace. This is the only place that decides process exit codes.
+// Verb dispatch. Parse `unitbob <verb> [args]`, dispatch to a hands-verb, and map
+// any thrown error to an exit code with an actionable message — never a raw stack
+// trace. This module decides exit codes but never acts on them: importing it must
+// stay free of side effects so tests can drive `main` directly. `bin.ts` is the
+// executable that owns process startup and exit.
 import { ensureLinked } from "./link.js";
 import { recipe } from "./verbs/recipe.js";
 import { show } from "./verbs/show.js";
@@ -13,6 +14,7 @@ import { suitePrepare } from "./verbs/suitePrepare.js";
 import { putSuiteBuild } from "./verbs/putSuiteBuild.js";
 import { fixPrepare } from "./verbs/fixPrepare.js";
 import { contractPrompt } from "./verbs/contractPrompt.js";
+import { suiteReviewPrepare } from "./verbs/suiteReviewPrepare.js";
 const USAGE = `unitbob — thin local hands for the Unitbob server.
 
 Usage: unitbob <verb> [args]
@@ -24,6 +26,7 @@ Verbs:
   map-prepare          Internal: keylessly update the graph (no API key) and write the host map-build request.
   put-map-build        Internal: upload the host-built map and graph.
   suite-prepare        Internal: fetch the recipe and capability assignment, write the host suite-build request.
+  suite-review-prepare Internal: bind an independent BDD quality review to the built behavioral candidate.
   put-suite-build      Internal: upload the host-built guardrail suite (whole spec file + test_metadata).
   fix-prepare <id>     Internal: fetch the per-capability repair packet for one red guard (by interface_id).
   contract-prompt <digest> <test_id> [fix|accept]
@@ -40,7 +43,7 @@ host-LLM's job; any semantic graph enrichment is host-LLM work (the /graphify sk
 
 Config: .unitbob.json at your project root, created automatically: the first
 run registers the project on the server by its folder name (spec 28).`;
-async function main(argv) {
+export async function main(argv, deps = { ensureLinked }) {
     const [verb, ...args] = argv;
     if (!verb || verb === '--help' || verb === '-h' || verb === 'help') {
         process.stdout.write(`${USAGE}\n`);
@@ -52,32 +55,35 @@ async function main(argv) {
                 await init(args);
                 return 0;
             case 'recipe':
-                await recipe(await ensureLinked(), args);
+                await recipe(await deps.ensureLinked(), args);
                 return 0;
             case 'show':
-                await show(await ensureLinked());
+                await show(await deps.ensureLinked());
                 return 0;
             case 'map-prepare':
-                await mapPrepare(await ensureLinked(), args);
+                await mapPrepare(await deps.ensureLinked(), args);
                 return 0;
             case 'put-map-build':
-                await putMapBuild(await ensureLinked(), args);
+                await putMapBuild(await deps.ensureLinked(), args);
                 return 0;
             case 'suite-prepare':
-                await suitePrepare(await ensureLinked(), args);
+                await suitePrepare(await deps.ensureLinked(), args);
+                return 0;
+            case 'suite-review-prepare':
+                await suiteReviewPrepare(await deps.ensureLinked(), args);
                 return 0;
             case 'put-suite-build':
-                await putSuiteBuild(await ensureLinked(), args);
+                await putSuiteBuild(await deps.ensureLinked(), args);
                 return 0;
             case 'fix-prepare':
-                await fixPrepare(await ensureLinked(), args);
+                await fixPrepare(await deps.ensureLinked(), args);
                 return 0;
             case 'contract-prompt':
-                await contractPrompt(await ensureLinked(), args);
+                await contractPrompt(await deps.ensureLinked(), args);
                 return 0;
             case 'run':
             case 'check':
-                await run(await ensureLinked(), args);
+                await run(await deps.ensureLinked(), args);
                 return 0;
             default:
                 process.stderr.write(`Unknown verb "${verb}".\n\n${USAGE}\n`);
@@ -89,7 +95,3 @@ async function main(argv) {
         return 1;
     }
 }
-main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
-    process.stderr.write(`${err.message}\n`);
-    process.exit(1);
-});

package/dist/files/behavioral.js

@@ -1,4 +1,4 @@
-import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { assertUnitbobPath } from "./artifactPath.js";
 // The behavioral suite lives under its own root: the main `.feature` plus its
@@ -9,14 +9,21 @@ import { assertUnitbobPath } from "./artifactPath.js";
 // blob only so `check` can execute it locally.
 export const BEHAVIORAL_DIR = '.unitbob/behavioral';
 // Write a behavioral artifact envelope (main file + support files) under the
-// behavioral root, after checking every path is safe. The root is wiped first
-// so a stale file from a previous version never lingers. Returns the absolute
-// path of the materialized main file.
-export function materializeBehavioral(projectRoot, artifact) {
+// behavioral root, after checking every path is safe. Stale suite artifacts are
+// removed while the separately provisioned runner environment is preserved.
+// Returns the absolute path of the materialized main file.
+export function materializeBehavioral(projectRoot, artifact, runner) {
     const files = [artifact, ...(artifact.support_files ?? [])];
     for (const file of files)
         assertUnitbobPath(file.path, BEHAVIORAL_DIR);
-    rmSync(join(projectRoot, BEHAVIORAL_DIR), { recursive: true, force: true });
+    const behavioralRoot = join(projectRoot, BEHAVIORAL_DIR);
+    const runnerEntries = RUNNER_ENVIRONMENT_ENTRIES[runner] ?? EMPTY_ENTRIES;
+    mkdirSync(behavioralRoot, { recursive: true });
+    for (const entry of readdirSync(behavioralRoot)) {
+        if (!runnerEntries.has(entry)) {
+            rmSync(join(behavioralRoot, entry), { recursive: true, force: true });
+        }
+    }
     let mainPath = '';
     for (const file of files) {
         const dest = join(projectRoot, file.path);
@@ -27,3 +34,20 @@ export function materializeBehavioral(projectRoot, artifact) {
     }
     return { mainPath };
 }
+export function copyBehavioralRunnerEnvironment(sourceRoot, targetRoot, runner) {
+    const entries = RUNNER_ENVIRONMENT_ENTRIES[runner] ?? EMPTY_ENTRIES;
+    for (const entry of entries) {
+        const source = join(sourceRoot, BEHAVIORAL_DIR, entry);
+        if (!existsSync(source))
+            continue;
+        const target = join(targetRoot, BEHAVIORAL_DIR, entry);
+        mkdirSync(dirname(target), { recursive: true });
+        cpSync(source, target, { recursive: true });
+    }
+}
+const EMPTY_ENTRIES = new Set();
+const RUNNER_ENVIRONMENT_ENTRIES = {
+    cucumber: new Set(['.bundle', 'Gemfile', 'Gemfile.lock']),
+    'cucumber-js': new Set(['node_modules', 'package.json', 'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock']),
+    'pytest-bdd': new Set(['.venv']),
+};

package/dist/files/suiteBuild.js

@@ -1,4 +1,5 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { dirname, join } from 'node:path';
 import { assertUnitbobPath } from "./artifactPath.js";
 export function requestPath(projectRoot) {
@@ -7,11 +8,112 @@ export function requestPath(projectRoot) {
 export function outputPath(projectRoot) {
     return join(projectRoot, '.unitbob', 'suite-build', 'suite_output.json');
 }
-export function writeSuiteBuildRequest(projectRoot, branches) {
+export function reviewOutputPath(projectRoot) {
+    return join(projectRoot, '.unitbob', 'suite-build', 'behavioral_review.json');
+}
+export function reviewRequestPath(projectRoot) {
+    return join(projectRoot, '.unitbob', 'suite-build', 'review-request.json');
+}
+export function writeBehavioralReviewRequest(projectRoot, output, candidateRun, knownDefectContext = { status: 'not_supplied' }, fixedCandidateRun) {
+    const metadata = output.test_metadata;
+    const candidateDigest = suiteCandidateDigest(output);
+    const request = {
+        candidate_digest: candidateDigest,
+        suite_file: output.suite_file,
+        capabilities: metadata?.capabilities,
+        output_path: reviewOutputPath(projectRoot),
+        known_defect_context: knownDefectContext,
+        candidate_run: { candidate_digest: candidateDigest, ...candidateRun },
+        ...(fixedCandidateRun ? {
+            fixed_candidate_run: { candidate_digest: candidateDigest, ...fixedCandidateRun },
+        } : {}),
+    };
+    const path = reviewRequestPath(projectRoot);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(request, null, 2)}\n`);
+    return request;
+}
+// The connector-owned runner strategy this branch selected. Reading it out of
+// the envelope is transport, like every other `runner_manifest` access in this
+// module — callers only ever get back the strategy name they dispatch on.
+export function branchRunner(output) {
+    const manifest = output.runner_manifest;
+    const runner = manifest?.runner;
+    if (typeof runner !== 'string' || !runner) {
+        throw new Error('The behavioral candidate names no runner strategy to execute.');
+    }
+    return runner;
+}
+export function suiteCandidateDigest(output) {
+    return createHash('sha256')
+        .update(stableJson({
+        suite_file: output.suite_file,
+        runner_manifest: output.runner_manifest,
+        test_metadata: output.test_metadata,
+    }))
+        .digest('hex');
+}
+// Everything the server strips back out before it recomputes the candidate
+// digest. The generator owns none of it, and if it writes any of these keys the
+// two sides hash different objects — which surfaces as "this review is about a
+// different candidate", blaming the reviewer for the generator's mistake. Refuse
+// it here, where the real cause can still be named.
+const POST_CANDIDATE_METADATA_KEYS = [
+    'bdd_quality_review',
+    'known_defect_probe',
+    'known_defect_context',
+    'candidate_run',
+    'fixed_candidate_run',
+];
+export function readBehavioralReview(projectRoot, output) {
+    const metadata = output.test_metadata;
+    const embedded = metadata ? POST_CANDIDATE_METADATA_KEYS.filter((key) => key in metadata) : [];
+    if (embedded.length > 0) {
+        throw new Error(`The behavioral suite generator must not embed its own review (found ${embedded.join(', ')} in test_metadata); run \`unitbob suite-review-prepare\` and provide the separate review artifact.`);
+    }
+    const path = reviewOutputPath(projectRoot);
+    if (!existsSync(path)) {
+        throw new Error(`${path} not found — run \`unitbob suite-review-prepare\` and have an independent reviewer write it.`);
+    }
+    const review = parseJson(readFileSync(path, 'utf8'), path);
+    if (!review || review.candidate_digest !== suiteCandidateDigest(output)) {
+        throw new Error(`${path} does not review the current behavioral suite candidate.`);
+    }
+    if (!('bdd_quality_review' in review) || !('known_defect_probe' in review)) {
+        throw new Error(`${path} must contain bdd_quality_review and known_defect_probe.`);
+    }
+    const request = readBehavioralReviewRequest(projectRoot, output);
+    return {
+        ...review,
+        candidate_run: request.candidate_run,
+        ...(request.fixed_candidate_run ? { fixed_candidate_run: request.fixed_candidate_run } : {}),
+    };
+}
+function readBehavioralReviewRequest(projectRoot, output) {
+    const path = reviewRequestPath(projectRoot);
+    const request = parseJson(readFileSync(path, 'utf8'), path);
+    const run = request?.candidate_run;
+    const digest = suiteCandidateDigest(output);
+    if (!request || request.candidate_digest !== digest || !run || run.candidate_digest !== digest ||
+        typeof run.revision !== 'string' || !run.revision || typeof run.run_result !== 'string' || !run.run_result) {
+        throw new Error(`${path} has no connector runner evidence for the current behavioral candidate.`);
+    }
+    const context = request.known_defect_context;
+    if (context?.status === 'supplied' && context.fixed_revision) {
+        const fixed = request.fixed_candidate_run;
+        if (!fixed || fixed.candidate_digest !== digest || fixed.revision !== context.fixed_revision ||
+            typeof fixed.run_result !== 'string' || !fixed.run_result) {
+            throw new Error(`${path} has no connector runner evidence for fixed revision ${context.fixed_revision}.`);
+        }
+    }
+    return request;
+}
+export function writeSuiteBuildRequest(projectRoot, branches, knownDefectContext = { status: 'not_supplied' }) {
     const request = {
         project_root: projectRoot,
         output_path: outputPath(projectRoot),
         branches,
+        known_defect_context: knownDefectContext,
     };
     const path = requestPath(projectRoot);
     mkdirSync(dirname(path), { recursive: true });
@@ -30,7 +132,31 @@ export function readSuiteBuildRequest(projectRoot) {
         !Array.isArray(request.branches)) {
         throw new Error(`${path} is malformed: expected project_root, output_path, and a branches array.`);
     }
-    return request;
+    return {
+        ...request,
+        known_defect_context: readKnownDefectContext(request.known_defect_context, path),
+    };
+}
+function readKnownDefectContext(value, path) {
+    if (value === undefined)
+        return { status: 'not_supplied' };
+    if (!value || typeof value !== 'object')
+        throw new Error(`${path}: known_defect_context must be an object.`);
+    const context = value;
+    if (context.status === 'not_supplied')
+        return { status: 'not_supplied' };
+    if (context.status !== 'supplied' || typeof context.defect !== 'string' || !context.defect.trim()) {
+        throw new Error(`${path}: supplied known_defect_context must name a defect.`);
+    }
+    if (context.fixed_revision !== undefined &&
+        (typeof context.fixed_revision !== 'string' || !context.fixed_revision.trim())) {
+        throw new Error(`${path}: fixed_revision must be a non-empty string.`);
+    }
+    return {
+        status: 'supplied',
+        defect: context.defect,
+        ...(context.fixed_revision ? { fixed_revision: context.fixed_revision } : {}),
+    };
 }
 // Read the host's answers, one per branch. The connector verifies each built
 // branch parses, carries a safe-path artifact envelope under its own root, and
@@ -110,6 +236,15 @@ function parseJson(raw, path) {
         throw new Error(`${path} is not valid JSON (${err.message})`);
     }
 }
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const object = value;
+        return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableJson(object[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
 // Turn a branch's assignment packet into its recipe name: structural uses the
 // unit-guardrail recipe, behavioral the Gherkin one.
 export function recipeNameFor(packet) {

package/dist/runner/bdd.js

@@ -34,20 +34,18 @@ export function runBddSuite(projectRoot, runner, mainPath) {
 async function runCucumberRuby(projectRoot) {
     const features = join(BEHAVIORAL_ROOT, 'features');
     const steps = join(BEHAVIORAL_ROOT, 'step_definitions');
-    const localBin = join(projectRoot, 'bin', 'cucumber');
     const sidecarGemfile = join(projectRoot, BEHAVIORAL_ROOT, 'Gemfile');
-    const hasSidecarGemfile = existsSync(sidecarGemfile);
-    const command = executable(localBin) ? localBin : 'bundle';
-    const base = executable(localBin) ? [] : ['exec', 'cucumber'];
-    const args = [...base, features, '--require', steps, '--format', 'message', '--out', CUCUMBER_REPORT];
+    if (!existsSync(sidecarGemfile)) {
+        throw missingRunner('Cucumber');
+    }
+    const command = 'bundle';
+    const args = ['exec', 'cucumber', features, '--require', steps, '--format', 'message', '--out', CUCUMBER_REPORT];
     const env = {
         ...process.env,
         RAILS_ENV: 'test',
         UNITBOB_REPO_ROOT: projectRoot,
     };
-    if (hasSidecarGemfile) {
-        env.BUNDLE_GEMFILE = join(BEHAVIORAL_ROOT, 'Gemfile');
-    }
+    env.BUNDLE_GEMFILE = join(BEHAVIORAL_ROOT, 'Gemfile');
     const result = await runProcess(command, args, {
         cwd: projectRoot,
         timeoutMs: BDD_TIMEOUT_MS,
@@ -55,16 +53,20 @@ async function runCucumberRuby(projectRoot) {
     });
     return finalize(result, command, args, projectRoot, CUCUMBER_REPORT);
 }
+function missingRunner(name) {
+    return new Error(`Behavioral runner missing (${name}). Run suite-prepare to provision it under ${BEHAVIORAL_ROOT}/, then run the checks again.`);
+}
 // JS/TS: `@cucumber/cucumber` (cucumber-js) with the message formatter written
 // to a file.
 async function runCucumberJs(projectRoot) {
     const features = join(BEHAVIORAL_ROOT, 'features');
     const steps = join(BEHAVIORAL_ROOT, 'step_definitions', '**', '*');
     const sidecarBin = join(projectRoot, BEHAVIORAL_ROOT, 'node_modules', '.bin', 'cucumber-js');
-    const command = executable(sidecarBin) ? sidecarBin : 'npx';
-    const baseArgs = executable(sidecarBin) ? [] : ['cucumber-js'];
+    if (!executable(sidecarBin)) {
+        throw missingRunner('Cucumber JS');
+    }
+    const command = sidecarBin;
     const args = [
-        ...baseArgs,
         features,
         '--require',
         steps,
@@ -122,11 +124,7 @@ async function pickPython(projectRoot) {
     if (executable(sidecarVenvPytest)) {
         return sidecarVenvPytest;
     }
-    const probe = await runProcess('python3', ['-m', 'pytest', '--version'], {
-        cwd: projectRoot,
-        timeoutMs: 10_000,
-    }).catch(() => ({ stdout: '', stderr: '', code: 1 }));
-    return probe.code === 0 ? 'python3' : 'python';
+    throw missingRunner('pytest-bdd');
 }
 function executable(path) {
     try {

package/dist/verbs/putSuiteBuild.js

@@ -1,4 +1,4 @@
-import { readHostSuiteOutputs, readSuiteBuildRequest } from "../files/suiteBuild.js";
+import { readBehavioralReview, readHostSuiteOutputs, readSuiteBuildRequest, } from "../files/suiteBuild.js";
 import { Wire } from "../wire.js";
 // Read the task and the host's answers, verify each branch parses and carries a
 // safe-path artifact envelope, then upload both peer branches in one batch
@@ -20,13 +20,36 @@ export async function putSuiteBuild(config, _args = [], deps) {
         if (output.build_error) {
             return { suite_kind: output.suite_kind, source_digest: sourceDigest, build_error: output.build_error };
         }
+        let testMetadata = output.test_metadata;
+        if (output.suite_kind === 'behavioral') {
+            const review = readBehavioralReview(config.projectRoot, output);
+            const probe = review.known_defect_probe;
+            const qualityReview = review.bdd_quality_review;
+            if (!qualityReview || typeof qualityReview !== 'object') {
+                throw new Error('The separate behavioral review must contain a bdd_quality_review object.');
+            }
+            if (request.known_defect_context.status === 'supplied' && probe?.status === 'not_supplied') {
+                throw new Error('A known defect was supplied to suite-prepare, but the behavioral review marked it not_supplied.');
+            }
+            testMetadata = {
+                ...output.test_metadata,
+                bdd_quality_review: {
+                    ...qualityReview,
+                    candidate_digest: review.candidate_digest,
+                },
+                known_defect_probe: review.known_defect_probe,
+                known_defect_context: request.known_defect_context,
+                candidate_run: review.candidate_run,
+                ...(review.fixed_candidate_run ? { fixed_candidate_run: review.fixed_candidate_run } : {}),
+            };
+        }
         return {
             suite_kind: output.suite_kind,
             source_digest: sourceDigest,
             artifacts: {
                 suite_file: output.suite_file,
                 runner_manifest: output.runner_manifest,
-                test_metadata: output.test_metadata,
+                test_metadata: testMetadata,
             },
         };
     });

package/dist/verbs/run.js

@@ -18,7 +18,7 @@ export async function run(config, _args, deps) {
             suite_file: { path: item.suite_file.path, content: item.suite_file.content },
             runner_manifest: item.runner_manifest,
         }),
-        materializeBehavioral: (projectRoot, item) => materializeBehavioral(projectRoot, item.suite_file).mainPath,
+        materializeBehavioral: (projectRoot, item) => materializeBehavioral(projectRoot, item.suite_file, item.runner_manifest.runner).mainPath,
         runStructural: runStructuralByRunner,
         runBehavioral: runBddSuite,
         validateStack,

package/dist/verbs/suitePrepare.js

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { materializeHelper } from "../files/guardrails.js";
-import { recipeNameFor, writeSuiteBuildRequest } from "../files/suiteBuild.js";
+import { recipeNameFor, writeSuiteBuildRequest, } from "../files/suiteBuild.js";
 import { anyStackPrecheck } from "../runner/precheck.js";
 import { ensureRunner } from "../runner/provision.js";
 import { Wire } from "../wire.js";
@@ -13,7 +13,8 @@ import { Wire } from "../wire.js";
 // unsupported project stops with one actionable message and writes nothing; a
 // no-current-map error from the server surfaces (via WireError) with guidance to
 // rebuild the map first.
-export async function suitePrepare(config, _args = [], deps) {
+export async function suitePrepare(config, args = [], deps) {
+    const defectContext = knownDefectContext(args);
     const wire = new Wire(config);
     const actual = {
         getRecipe: (name) => wire.getRecipe(name),
@@ -55,12 +56,15 @@ export async function suitePrepare(config, _args = [], deps) {
         recipe: await actual.getRecipe(recipeNameFor(packet)),
         assignment: packet.assignment,
     })));
-    const request = writeSuiteBuildRequest(config.projectRoot, branches);
+    const request = writeSuiteBuildRequest(config.projectRoot, branches, defectContext);
     const kinds = branches.map((branch) => branch.suite_kind).join(' and ');
+    const nextCommand = branches.some((branch) => branch.suite_kind === 'behavioral')
+        ? '`unitbob suite-review-prepare` before upload'
+        : '`unitbob put-suite-build`';
     actual.stdout.write(`Suite build request written to ${request.project_root}/.unitbob/suite-build/request.json\n`);
     actual.stdout.write(`Next: build ${branches.length === 1 ? 'the' : 'both'} peer ${branches.length === 1 ? 'suite' : 'suites'} (${kinds}) following each branch's \`recipe\` and \`assignment\`, ` +
-        `write your answer to ${request.output_path} as a branches array, run each locally to green, ` +
-        'then run `unitbob put-suite-build`.\n');
+        `write your answer to ${request.output_path} as a branches array, run each locally, repair broken harness steps while application failures remain red, ` +
+        `then run ${nextCommand}.\n`);
     // A fixable runner blocker is not a failure: the structural suite still builds this run. Tell the
     // vibecoder the one command that unblocks the behavioral peer, then re-run suite-prepare.
     if (fixableNotices.length > 0) {
@@ -70,6 +74,32 @@ export async function suitePrepare(config, _args = [], deps) {
             '\nFix the above, then re-run `unitbob suite-prepare` to build the behavioral peer.\n');
     }
 }
+function knownDefectContext(args) {
+    const defect = option(args, '--known-defect=');
+    const fixedRevision = option(args, '--fixed-revision=');
+    const explicitlyAbsent = args.includes('--no-known-defect');
+    if ((defect && explicitlyAbsent) || (!defect && !explicitlyAbsent)) {
+        throw new Error('Choose exactly one of --known-defect or --no-known-defect (use --known-defect=<description>).');
+    }
+    if (fixedRevision && !defect)
+        throw new Error('--fixed-revision requires --known-defect.');
+    if (explicitlyAbsent)
+        return { status: 'not_supplied' };
+    if (!defect)
+        throw new Error('--known-defect requires a value.');
+    return {
+        status: 'supplied',
+        defect,
+        ...(fixedRevision ? { fixed_revision: fixedRevision } : {}),
+    };
+}
+function option(args, prefix) {
+    const match = args.find((arg) => arg.startsWith(prefix));
+    const value = match?.slice(prefix.length).trim();
+    if (match && !value)
+        throw new Error(`${prefix.slice(0, -1)} requires a value.`);
+    return value || undefined;
+}
 function inferBddRunner(projectRoot) {
     if (existsSync(join(projectRoot, 'package.json')))
         return 'cucumber-js';

package/dist/verbs/suiteReviewPrepare.js

@@ -0,0 +1,101 @@
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { copyBehavioralRunnerEnvironment, materializeBehavioral } from "../files/behavioral.js";
+import { runBddSuite } from "../runner/bdd.js";
+import { boundReport } from "../runner/boundReport.js";
+import { branchRunner, readHostSuiteOutputs, readSuiteBuildRequest, reviewRequestPath, writeBehavioralReviewRequest, } from "../files/suiteBuild.js";
+export async function suiteReviewPrepare(config, _args = [], deps) {
+    const actual = {
+        runCandidate: runCandidate,
+        stdout: process.stdout,
+        ...deps,
+    };
+    const buildRequest = readSuiteBuildRequest(config.projectRoot);
+    const behavioral = readHostSuiteOutputs(buildRequest.output_path, buildRequest)
+        .find((branch) => branch.suite_kind === 'behavioral');
+    if (!behavioral)
+        throw new Error('The suite build has no behavioral candidate to review.');
+    if (behavioral.build_error) {
+        throw new Error(`The behavioral candidate could not be reviewed: ${behavioral.build_error.message}`);
+    }
+    const candidateRun = await actual.runCandidate(config.projectRoot, behavioral);
+    const fixedRevision = buildRequest.known_defect_context.status === 'supplied'
+        ? buildRequest.known_defect_context.fixed_revision
+        : undefined;
+    const fixedCandidateRun = fixedRevision
+        ? await actual.runCandidate(config.projectRoot, behavioral, fixedRevision)
+        : undefined;
+    const request = writeBehavioralReviewRequest(config.projectRoot, behavioral, candidateRun, buildRequest.known_defect_context, fixedCandidateRun);
+    actual.stdout.write(`Behavioral review request written to ${reviewRequestPath(config.projectRoot)}\n`);
+    actual.stdout.write(`Next: have an independent reviewer inspect this exact candidate and write bdd_quality_review and known_defect_probe to ${request.output_path}, then run \`unitbob put-suite-build\`.\n`);
+}
+async function runCandidate(projectRoot, output, revision) {
+    if (revision)
+        return runCandidateAtRevision(projectRoot, output, revision);
+    return runCandidateInProject(projectRoot, output, gitRevision(projectRoot));
+}
+async function runCandidateInProject(projectRoot, output, revision) {
+    const runner = branchRunner(output);
+    const suiteFile = output.suite_file;
+    const mainPath = materializeBehavioral(projectRoot, suiteFile, runner).mainPath;
+    const result = await runBddSuite(projectRoot, runner, mainPath);
+    const report = boundReport(runner, result);
+    if (report === null)
+        throw new Error('The behavioral candidate produced no machine-readable runner report.');
+    return { revision, run_result: report };
+}
+async function runCandidateAtRevision(projectRoot, output, revision) {
+    const resolved = execFileSync('git', ['rev-parse', '--verify', revision], {
+        cwd: projectRoot,
+        encoding: 'utf8',
+    }).trim();
+    const worktree = mkdtempSync(join(tmpdir(), 'unitbob-fixed-review-'));
+    let added = false;
+    try {
+        execFileSync('git', ['worktree', 'add', '--detach', worktree, resolved], { cwd: projectRoot, stdio: 'pipe' });
+        added = true;
+        const runner = branchRunner(output);
+        materializeBehavioral(worktree, output.suite_file, runner);
+        copyBehavioralRunnerEnvironment(projectRoot, worktree, runner);
+        return await runCandidateInProject(worktree, output, revision);
+    }
+    finally {
+        if (added) {
+            try {
+                execFileSync('git', ['worktree', 'remove', '--force', worktree], { cwd: projectRoot, stdio: 'pipe' });
+            }
+            catch {
+                // The temporary directory cleanup below is still safe and bounded.
+            }
+        }
+        rmSync(worktree, { recursive: true, force: true });
+        if (added) {
+            try {
+                // `remove` can fail while the directory still goes away just above,
+                // which leaves a dangling entry under .git/worktrees in the user's own
+                // checkout. Reviewing a suite must not litter the repository it reads.
+                execFileSync('git', ['worktree', 'prune'], { cwd: projectRoot, stdio: 'pipe' });
+            }
+            catch {
+                // Housekeeping only — never fail a finished review run over it.
+            }
+        }
+    }
+}
+function gitRevision(projectRoot) {
+    try {
+        const options = {
+            cwd: projectRoot,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        };
+        const head = execFileSync('git', ['rev-parse', 'HEAD'], options).trim();
+        const dirty = execFileSync('git', ['status', '--porcelain'], options).trim();
+        return dirty ? `${head}-dirty` : head;
+    }
+    catch {
+        return 'working-tree';
+    }
+}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "unitbob",
-  "version": "0.2.3",
+  "version": "0.2.6",
   "description": "Unitbob connector — thin local hands for the Unitbob Rails brain. Owns no domain logic: it runs tools, relays bytes over the wire, and prints what the server returns.",
   "type": "module",
   "bin": {
-    "unitbob": "dist/cli.js"
+    "unitbob": "dist/bin.js"
   },
   "files": [
     "dist"
@@ -13,7 +13,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.json && chmod +x dist/cli.js",
+    "build": "rm -rf dist && tsc -p tsconfig.json && chmod +x dist/bin.js",
     "prepublishOnly": "npm run build",
     "test": "node --test test/*.test.ts"
   },